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>

.dependency-cruiser.js

@@ -8,7 +8,7 @@
  *   tui            -> contracts
  *   runtime        -> contracts, llm   — llm facade only
  *   cli            -> contracts, runtime, tui, llm, toolchain-cpp
- *   workers        -> contracts        — WorkerRuntime IPC surface only
+ *   workers        -> contracts, runtime — WorkerRuntime IPC + shared utilities
  */
 module.exports = {
   forbidden: [
@@ -57,27 +57,27 @@ module.exports = {
       },
     },
 
-    /* ── Rule 4: runtime may only import from contracts & llm ── */
+    /* ── Rule 4: runtime may only import from contracts, llm & toolchain-cpp ── */
     {
       name: "runtime-boundary",
-      comment: "runtime may only depend on contracts and llm (facade)",
+      comment: "runtime may only depend on contracts, llm (facade), and toolchain-cpp (capability registration)",
       severity: "error",
       from: { path: "^packages/runtime/src/" },
       to:   {
-        path: "^packages/(tui|cli|workers|toolchain-cpp)/",
+        path: "^packages/(tui|cli|workers)/",
-        pathNot: "^packages/(contracts|llm)/",
+        pathNot: "^packages/(contracts|llm|toolchain-cpp)/",
       },
     },
 
-    /* ── Rule 5: workers may only import from contracts ── */
+    /* ── Rule 5: workers may import from contracts and runtime ── */
     {
       name: "workers-boundary",
-      comment: "workers may only depend on contracts (WorkerRuntime IPC surface)",
+      comment: "workers may depend on contracts (IPC surface) and runtime (shared utilities like CompressionValidator)",
       severity: "error",
       from: { path: "^packages/workers/src/" },
       to:   {
-        path: "^packages/(llm|runtime|tui|cli|toolchain-cpp)/",
+        path: "^packages/(llm|tui|cli|toolchain-cpp)/",
-        pathNot: "^packages/contracts/",
+        pathNot: "^packages/(contracts|runtime)/",
       },
     },
 

.gitignore

@@ -10,3 +10,5 @@ dist/
 
 # Turbo cache
 .turbo/
+.air
+.claude

.qoder/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(*)"
+    ]
+  }
+}

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.

AirPlan/docs/architecture/Qwen3.7开发阶段审计.md

@@ -0,0 +1,606 @@
+# Qwen3.7-Max 开发阶段全量审计报告
+
+**审计模型:** Qwen3.7-Max  
+**审计日期:** 2026-06-03  
+**审计范围:** V1.0.0 Alpha 全部代码实现 vs 原始需求/基线/设计文档/UML类图  
+**审计分支:** GLM5-Achieve  
+**代码规模:** 7 个包, 137 个 TypeScript/TSX 源文件, 4 个根配置文件
+
+---
+
+## 0. 审计总览
+
+| 严重程度 | 数量 | 说明 |
+|---|---|---|
+| CRITICAL | 31 | 架构性缺陷，阻塞核心不变量或导致运行时崩溃 |
+| HIGH | 22 | 功能性缺陷，子系统与设计断连或关键逻辑缺失 |
+| MEDIUM | 19 | 部分实现偏差，影响完整性但不阻塞骨架 |
+| LOW | 12 | 命名/结构偏差、多余类型、文档注释问题 |
+
+**总体评估:** 代码骨架覆盖了 V1.0.0 Alpha 的 8 个阶段目标，monorepo 结构、包分层、SQLite schema、事件注册表均存在。但实现与设计文档之间存在大量结构性偏差，核心子系统（Scheduler 状态机、IPC 协议、安全模型、上下文装配）与冻结基线的匹配度不足 40%。当前代码属于 **Phase 0-1 骨架 + Phase 2-7 桩代码** 状态，多数子系统有类无逻辑或有逻辑但语义不匹配。
+
+---
+
+## 1. 需求覆盖度审计 (requirements.md → 代码)
+
+### 1.1 功能需求 (FR) 覆盖矩阵
+
+| FR ID | 需求 | 覆盖状态 | 说明 |
+|---|---|---|---|
+| FR-001 | CLI 启动与项目初始化 | PARTIAL | CLI 命令齐全 (11 个)，但 `init` 不创建 17 个规范子目录 |
+| FR-002 | 项目本地状态 `.air/` | PARTIAL | ProjectInitializer 存在，但 `.air/shared/plan/docs/` 等子目录缺失 |
+| FR-003 | 会话持久化 SQLite | PASS | 17 表、38 索引、WAL/NORMAL/FK-OFF 全部正确 |
+| FR-004 | 事件驱动运行时 | PARTIAL | EventStore/EventBus/EventIngestor 存在，但事务边界违反 (F-04) |
+| FR-005 | 主代理对话 | PARTIAL | MainAgent 存在但缺 7/13 个状态，分类用正则而非 LLM |
+| FR-006 | 架构设计师 | PARTIAL | ArchitectureDesigner 存在但不产出 BlockerReport，不发事件 |
+| FR-007 | 调度器与 TaskGraph | FAIL | Scheduler 缺 BLOCKED/CANCELLED 状态，3 个方法缺失，接口不匹配 |
+| FR-008 | 独立 Worker 进程 | PARTIAL | 5 个角色均存在，但 WorkerResult 形状不匹配，IPC 协议偏差大 |
+| FR-009 | Claude Code 级执行原语 | FAIL | read-before-edit 未强制，工具 schema 字段名大量偏差 |
+| FR-010 | ToolRegistry 与内置工具 | FAIL | 28 个 MVP 工具中 16 个缺失 |
+| FR-011 | 权限与安全模型 | FAIL | 0/10 cut line 项完全满足；profile/action/grant_scope 类型不匹配 |
+| FR-012 | 插件与能力基础 | PARTIAL | CapabilityRegistry 存在但 manifest schema、trust level、依赖模型全部偏差 |
+| FR-013 | Provider 层 | PARTIAL | AnthropicAdapter 和 OpenAICompatibleAdapter 存在，能力矩阵仅实现 ~20% |
+| FR-014 | 上下文装配与压缩 | FAIL | L6-L9 层缺失，输出非 Anthropic canonical 格式，无冲突检测 |
+| FR-015 | 工件与证据管理 | PARTIAL | ArtifactStore 正确实现 temp-rename 流程，EvidenceStore 用内存 map |
+| FR-016 | TUI 与 HUD | PARTIAL | 9 个组件齐全，无 OpenTUI renderer，ProjectionStore.rebuild() 为桩 |
+| FR-017 | 完整 C++ 开发工作流 | FAIL | CppToolRegistrar 注册工具但 6 个 cpp.* 工具未注册到 ToolRegistry |
+| FR-018 | Doctor | PARTIAL | DoctorService 存在但无 provider 检查和平台检测 |
+| FR-019 | 日志与诊断 | PARTIAL | Logger 存在但与 DeveloperLogEncryptor 完全断连 |
+| FR-020 | 发布门禁 | FAIL | release 命令为桩，无 fixture 项目 |
+
+### 1.2 非功能需求 (NFR) 覆盖矩阵
+
+| NFR ID | 需求 | 覆盖状态 | 说明 |
+|---|---|---|---|
+| NFR-001 | 本地优先 | PASS | 所有状态在 `.air/` 下 |
+| NFR-002 | 可恢复性 | FAIL | Recovery 的 scanOrphanReferences 和 checkPidLiveness 均为桩 |
+| NFR-003 | 可扩展性 | PARTIAL | toolchain-* 包模式存在但能力注册不完整 |
+| NFR-004 | Provider 灵活性 | PARTIAL | 适配器模式存在但能力矩阵验证不完整 |
+| NFR-005 | UI 响应性 | PASS | ProjectionStore 架构正确隔离了 UI 与 DB |
+| NFR-006 | 基于证据的完成 | FAIL | 完成门禁未强制，验证桩代码 |
+| NFR-007 | Linux 优先 | PASS | 代码无平台特定障碍 |
+| NFR-008 | 安全边界保持 | FAIL | PathClassifier 类别错误，无 credential_store 检测 |
+
+---
+
+## 2. 契约包审计 (packages/contracts vs interface-contracts-v1.md)
+
+### 2.1 缺失的契约接口 (15 个)
+
+| # | 契约名 | 设计位置 | 严重程度 |
+|---|---|---|---|
+| 1 | `EventBus` | SS7 | CRITICAL |
+| 2 | `EventStore` | SS7 | CRITICAL |
+| 3 | `EventIngestor` | SS7 | CRITICAL |
+| 4 | `ContextAssembler` | SS16 | CRITICAL |
+| 5 | `EventSchemaRegistry` | SS7 | HIGH |
+| 6 | `EventAppendOptions` | SS7 | HIGH |
+| 7 | `SessionRecord` | SS6 | HIGH |
+| 8 | `MessageRecord` | SS6 | HIGH |
+| 9 | `PersistedEventRecord` | SS6 | HIGH |
+| 10 | `PersistedEventInsert` | SS6 | HIGH |
+| 11 | `EventRepository` | SS6 | HIGH |
+| 12 | `ContextAssembleInput` | SS16 | HIGH |
+| 13 | `AssembledContext` | SS16 | HIGH |
+| 14 | `CompactionPolicy` | SS16 | HIGH |
+| 15 | `CompactionResult` | SS16 | HIGH |
+
+### 2.2 字段级偏差
+
+| 契约 | 字段 | 设计 | 代码 | 文件:行 |
+|---|---|---|---|---|
+| `ProviderCapabilityMatrix` | `supports` | `JsonObject` | `ProviderSupports` (强类型) | provider.ts:70 |
+| `ProviderCapabilityMatrix` | `conversion` | `JsonObject` | `ProviderConversion` (强类型) | provider.ts:71 |
+| `ProviderCapabilityMatrix` | (额外字段) | 不存在 | `display_name?`, `limits?`, `default_use?`, `notes?` | provider.ts:64,72-74 |
+| `ModelRequirement` | `required` | `JsonObject` | `Partial<ProviderSupports>` | provider.ts:146 |
+| `ProviderManager` | (额外方法) | 不存在 | `load_config(): Promise<void>` | provider.ts:277 |
+| `DoctorIssueSeverity` | (缺失值) | 包含 `"error"` | 缺少 `"error"` | platform.ts:41 |
+| `TaskGraph` | `dependencies` | `TaskDependencyRecord[]` | 内联结构等价物 | task.ts:147 |
+| `PromptLayerLoader` | 参数类型 | `ProjectContext`, `TaskSpec` | 内联结构子集 | runtime.ts:94-104 |
+
+### 2.3 多余契约 (需 ADR)
+
+`ProviderIdentity`, `ProviderConversionReport`, `ProviderLimits`, `ProviderDefaultUse`, `DoctorIssue`, `DoctorIssueCategory`, `ToolErrorOutput` (来自 error-taxonomy-v1.md 但未实现) 等均为代码中新增但设计文档中不存在的契约。
+
+---
+
+## 3. 存储层审计 (packages/runtime/src/storage/ vs db-schema-v1.md)
+
+### 3.1 会话 DB Schema: 完整 (PASS)
+
+17 个表、38 个索引、3 个 PRAGMA、5 个 schema_meta 种子键全部正确匹配。
+
+### 3.2 CRITICAL 发现
+
+**F-01: DebugKnowledgeStore schema 完全不匹配 db-schema-v1.md §20.1**
+- DB 路径: 代码 `.air/shared/debug-records.db` vs 设计 `.air/local/debug-records.db`
+- 7 个列名/语义不匹配: `failure_signature` → `signature`, `fix_ref` → `fix_applied`, 缺失 `summary`/`evidence_json`/`verification_json`/`updated_at`/`metadata_json`
+- 多余列: `session_id`, `error_kind`, `status`, `resolved_at`
+- 索引名不匹配
+
+**F-02: LearnedMemoryStore schema 完全不匹配 db-schema-v1.md §20.2**
+- DB 路径: 代码 `.air/shared/learned-memory.db` vs 设计 `.air/local/learned-memory.db`
+- 表名: 代码 `learned_memory` vs 设计 `learned_memories`
+- 6 个列名/语义不匹配
+- 枚举值完全不匹配: 设计 `project_rule|toolchain_rule|skill_update|debug_experience` vs 代码 `pattern|rule|skill|experience`
+- 状态枚举不匹配: 设计 `candidate|promoted|archived|rejected` vs 代码 `draft|promoted|archived`
+
+**F-04: EventStore.project() 未将事务句柄传递给仓库**
+- `append()` 正确开启事务，但 `project()` 方法接收 `_tx` 参数后从不传给仓库方法
+- 违反 db-schema-v1.md §1 规则 8: "持久事件插入与域表更新必须在同一事务中"
+- 影响: 域表写入失败时事件行仍会提交，造成不一致状态
+
+**F-05: EventStore 写入无效的 workspace status 值**
+- `workspace.created` 写入 `status: 'created'`，但有效枚举为 `active|merged|conflicted|abandoned|cleaned`
+- `workspace.merge.started` 写入 `status: 'merging'`，不在枚举中
+- 导致 `assertEnumValues` 抛出 AirError，**首次 workspace 创建即崩溃**
+
+**F-06: TaskAttemptRepository.update() 列映射 bug**
+- 检查 `patch.failure_signature` 但更新 `failure_summary` 列
+- 导致 `failure_signature` 永远不会被更新，`failure_summary` 被静默覆盖
+
+**F-07: EventRepository 路由前缀过滤器使用错误分隔符**
+- 过滤用 `.` 拼接，但存储用 `/` 分隔
+- 所有路由前缀查询返回零结果
+
+### 3.3 HIGH 发现
+
+**F-08: Recovery.scanOrphanReferences() 为桩** — FK-off 孤儿扫描未实现  
+**F-09: Recovery.checkPidLiveness() 为桩** — PID 存活检查未实现  
+**F-10: Workspace GC SQL 逻辑错误** — AND/OR 缺少括号，`session_id` 过滤被绕过  
+**F-11: EvidenceStore 使用内存 Map** — 重启后证据查询为空  
+**F-12: SessionManager.close_session() 不刷新 ui_state** — 违反退出时刷新不变量
+
+### 3.4 MEDIUM 发现
+
+**F-13:** `command.completed` 投影传递 `diagnostic_ids` 但 `command_runs` 表无此列  
+**F-14:** EventStore 单例用空 `DatabaseHandle` 初始化  
+**F-15/F-16:** 多个仓库在 insert 时硬编码 status，与 EventStore 传递值冲突
+
+---
+
+## 4. 安全模型审计 (packages/runtime/src/security/ vs security-model-v1.md)
+
+### 4.1 路径分类器 (CRITICAL 偏差)
+
+| 设计 PathRiskCategory | 实现 | 状态 |
+|---|---|---|
+| `project` | `project_source`, `project_config` | 拆分为二 |
+| `project_air_shared` | — | **缺失** |
+| `project_air_local` | — | **缺失** |
+| `credential_store` | — | **完全缺失** (`~/.ssh`, `~/.gnupg` 等均不检测) |
+| `unknown` | — | **缺失**; 默认为 `project_config` (过于宽松) |
+
+### 4.2 命令风险分析器 (CRITICAL 偏差)
+
+| 设计 CommandRisk | 实现 | 状态 |
+|---|---|---|
+| `build_or_test` | — | **缺失** |
+| `dependency_install` | — | **缺失** |
+| `privilege_escalation` | — | **缺失** |
+| `unknown` | — | **缺失** |
+
+**运行时 Bug:** `'sudo_likely' in trimmed` — `in` 操作符在字符串上检查 String 原型属性，永远为 `false`。
+
+### 4.3 权限引擎 (CRITICAL 偏差)
+
+| 设计要素 | 实现 | 状态 |
+|---|---|---|
+| 4 个 Profile (`low/normal/high/developer`) | 按 agent 类型的 profile | **完全不匹配** |
+| 6 个 Action (`allow/deny/ask_user/block/refuse/announce_then_run`) | 7 个 Action (3 个不同) | **缺失 `block/refuse/announce_then_run`** |
+| `PermissionGrantScope` (5 级) | **完全缺失** | 无授权范围追踪 |
+| `risk_level` 字段 | **缺失** | |
+| `backup_required` 字段 | **缺失** | 无写入前备份逻辑 |
+| 策略违规 `refuse` | **缺失** | 无拒绝检测 |
+
+**Cut line 合规: 0/10 项完全满足, 4 项部分满足, 6 项不满足。**
+
+### 4.4 SecretRedactor: 良好但有缺口
+
+14 个模式类别覆盖良好。缺失: `.env` 文件路径级检测、云凭证目录模式、`auth_ref` 引用系统、Provider 适配器集成。
+
+---
+
+## 5. 工具注册表审计 (ToolRegistry vs tool-registry-v1.md)
+
+### 5.1 MVP 工具缺失 (16/28 缺失)
+
+| 缺失工具 | 类别 |
+|---|---|
+| `fs.stat` | 文件系统 |
+| `process.kill` | 进程 |
+| `git.worktree.create` | Git |
+| `git.merge_workspace` | Git |
+| `project.scan` | 项目 |
+| `project.profile.write` | 项目 |
+| `cpp.detect` | C++ 工具链 |
+| `cpp.cmake.configure` | C++ 工具链 |
+| `cpp.build` | C++ 工具链 |
+| `cpp.test` | C++ 工具链 |
+| `cpp.static.cppcheck` | C++ 工具链 |
+| `cpp.clangd.query` | C++ 工具链 |
+| `debug.run` | 调试 |
+| `debug.parse_logs` | 调试 |
+| `gui.screenshot` | GUI 证据 |
+| `network.capture` | 网络证据 |
+
+### 5.2 多余工具 (10 个不在 MVP 索引中)
+
+`git.commit`, `git.branch`, `project.rules`, `project.context`, `artifact.read`, `context.compact`, `permission.check`, `permission.prompt`, `doctor.check`, `doctor.fix`
+
+### 5.3 工具 Schema 偏差 (主要工具)
+
+| 工具 | 设计字段 | 代码字段 | 偏差 |
+|---|---|---|---|
+| `fs.edit` | `old_string`, `new_string`, `expected_existing_sha256?` | `find`, `replace` | 字段名全部不同，缺安全校验和 |
+| `shell.run` | `cwd` (required), `timeout_ms?`, `stdin?`, `capture_mode?`, `purpose?` | `workdir` (optional), `timeout?`, `env?` | 名称/必需性/字段均不匹配 |
+| `artifact.create` | `type`, `original_name?`, `content?`, `source_path?`, `associated_entity_type?`, `associated_entity_id?`, `metadata?` | `name`, `type`, `content`, `metadata` | 缺 5 个字段 |
+| `context.assemble` | `purpose` (required enum), `refs?`, `token_budget?` | `max_tokens?` | 缺必需 `purpose` 枚举和 `refs` |
+
+### 5.4 ToolRegistry 运行时 Bug
+
+**CRITICAL:** `this.downgrade_to_readonly()` 和 `this.apply_sandbox_restrictions()` 在模块作用域 `ACTION_BRANCHES` 对象中被调用，`this` 不是 ToolRegistry 实例，运行时将抛出异常。
+
+---
+
+## 6. 能力系统审计 (CapabilityRegistry vs capability-trust-v1.md)
+
+### 6.1 Manifest Schema (CRITICAL 偏差)
+
+| 设计字段 | 实现 | 状态 |
+|---|---|---|
+| `capability_id` | `name` | 重命名 |
+| `display_name` | — | **缺失** |
+| `source` (CapabilitySource) | — | **完全缺失** |
+| `trust_level` (5 级) | `trust_level` (3 级) | **不匹配**: 设计 `built_in/project_local/user_installed/verified_publisher/untrusted` vs 代码 `core/trusted/untrusted` |
+| `publisher?` | — | **缺失** |
+| `events?` | — | **缺失** |
+| `config_schema?` | — | **缺失** |
+| `entrypoint?` | — | **缺失** |
+
+### 6.2 依赖模型
+
+设计: 富 `CapabilityDependency` 对象 (7 种 kind、检测器、安装器策略)。  
+实现: 简单 `string[]`。所有结构信息丢失。
+
+### 6.3 工具命名空间验证
+
+设计要求 `<capability-id>.<tool-name>` 命名空间，保留内置命名空间。`CapabilityManifestValidator` 无命名空间验证。
+
+---
+
+## 7. 调度器审计 (Scheduler vs scheduler-state-machine-v1.md)
+
+### 7.1 缺失状态 (CRITICAL)
+
+| 设计状态 | 实现 | 状态 |
+|---|---|---|
+| `BLOCKED` | — | **缺失** |
+| `CANCELLED` | — | **缺失** |
+| `TERMINATED` | — | **多余** (非设计规范) |
+
+### 7.2 Scheduler 接口不匹配
+
+| 设计方法 | 实现 | 状态 |
+|---|---|---|
+| `create_tasks(session_id, specs: TaskSpec[])` | `create_tasks({id,type,title,depends_on}[])` | 签名不匹配，缺 `session_id` |
+| `add_dependency(session_id, task_id, dep)` | — | **完全缺失** |
+| `load_graph(session_id)` | — | **完全缺失** |
+| `run_until_idle(session_id): SchedulerRunResult` | `run_until_idle(): SchedulerState` | 返回值类型不匹配 |
+| `cancel_task(task_id, reason)` | — | **完全缺失** |
+
+### 7.3 状态逻辑空洞
+
+| 状态 | 设计要求 | 实现 |
+|---|---|---|
+| DISPATCHING | 4 个动作 (workspace, events, control message, attempt) | 仅标记 running |
+| COLLECTING_RESULTS | 5 个动作 (validate, persist, terminal, classify, unblock) | 直通到 MERGING |
+| MERGING | 策略选择 (main/worktree/isolated_copy) | 直通到 REVIEWING_WAVE |
+| REVIEWING_WAVE | 调度 review 任务 | 直通到 REPAIRING_OR_CONTINUING |
+
+### 7.4 TaskGraph 偏差
+
+- 缺失 `serialization` 依赖类型 (4 种中缺 1 种)
+- `soft` 依赖对调度无任何影响
+- 冲突依赖不阻止同波次并发
+- TaskNode 缺少 `spec`, `assigned_agent_id`, `retry_count`, `workspace_id`
+
+### 7.5 WavePlanner 偏差
+
+- 所有任务分配到 `'default'` write area — write-area 串行化无效
+- `wave_id` 为 `number` (Date.now()) 而非设计要求的 `string`
+- 无 `workspace_assignments`, `model_assignments`, `reason` 字段
+- 8 条波次规划规则中仅 1 条部分实现
+
+### 7.6 RetryPlanner: 死代码
+
+逻辑正确 (重复失败签名升级)，但从未被 Scheduler 调用。
+
+---
+
+## 8. IPC 协议审计 (WorkerProtocol vs interface-contracts-v1.md §10)
+
+### 8.1 缺失 IPC 类型
+
+| 设计 IpcKind | 实现 | 状态 |
+|---|---|---|
+| `control` | — | **缺失** (个别控制消息存在但无 `control` 信封) |
+| `log` | — | **完全缺失** |
+| `tool.stream` | — | **完全缺失** |
+| `protocol.error` | — | **缺失** (用非标准 `worker.error` 替代) |
+
+### 8.2 信封形状不匹配
+
+设计 `IpcEnvelope` 有 9 个字段: `id, direction, kind, timestamp, session_id, agent_id, correlation_id?, protocol_version, payload`  
+实现 `WorkerMessage` 有 5 个字段: `id, type, direction, timestamp, payload`  
+**缺失:** `kind`, `session_id`, `agent_id`, `correlation_id`, `protocol_version`
+
+### 8.3 握手顺序反转
+
+设计: 父进程先发 `agent.start`，worker 回 `worker.ready`  
+实现: worker 先发 `worker.ready`，父进程后发 `agent.start` — **顺序相反**
+
+---
+
+## 9. 主代理状态机审计 (MainAgent vs main-agent-state-machine.md)
+
+### 9.1 缺失状态 (7/13)
+
+| 设计状态 | 实现 | 状态 |
+|---|---|---|
+| `CLASSIFYING` | — | **缺失** |
+| `SCHEDULING` | — | **缺失** |
+| `ARCHITECTURE_DESIGNING` | — | **缺失** |
+| `CONFIRMING` | — | **缺失** (用 `AWAITING_CONFIRMATION` 替代，语义不同) |
+| `EXECUTING` | — | **缺失** |
+| `INTERRUPTING` | — | **缺失** |
+| `ARCHITECTURE_REVISING` | — | **缺失** |
+
+### 9.2 其他偏差
+
+- 分类用正则而非 LLM
+- Direct Mode `/direct`/`/done` 不完整
+- SUMMARIZING 不触发 ExperienceMiner
+- 无 `requirement.changed` 处理
+
+---
+
+## 10. Worker 角色审计 (packages/workers/ vs 设计)
+
+### 10.1 结果形状不匹配
+
+所有 5 个角色均返回局部结果类型而非设计要求的 `WorkerResult<T>` 信封:
+
+| 角色 | 设计要求 | 实际返回 |
+|---|---|---|
+| Executor | `WorkerResult<ExecutorResult>` (12 字段) | `{status, changes?, verification?, error?}` (4 字段) |
+| Reviewer | `WorkerResult<ReviewerResult>` + `verdict` 枚举 | `{status, findings[], summary}` |
+| Debugger | `WorkerResult<DebuggerResult>` + `BlockerReport?` | `{status, root_cause, fix_applied?, evidence_refs}` |
+| Compactor | `WorkerResult<CompactorResult>` + `summary_id` | `{status, summary_content, tokens_freed}` |
+| ExperienceMiner | `WorkerResult<ExperienceMinerResult>` + `MemoryCandidate[]` | `{status, entries[], summary}` |
+
+### 10.2 执行纪律缺失
+
+- read-before-edit 未强制
+- 完成门禁 (verification pass or explicit skip) 未强制
+- DebuggerRole 不查 DebugKnowledgeStore
+- ExperienceMiner 触发路径未接入 Scheduler
+
+---
+
+## 11. LLM Provider 层审计 (packages/llm/ vs provider-capability-matrix-v1.md)
+
+### 11.1 能力矩阵覆盖度: ~20%
+
+缺失:
+- `quality_tier`, `cost_tier` 字段未在矩阵中使用
+- 17 个 `supports` 字段中仅 5 个实现
+- 整个 `conversion` 块、`limits` 块、`default_use` 块缺失
+- `ProviderKind` 分类未使用
+- Fallback 策略、调度器分配模式缺失
+
+### 11.2 Provider 配置安全
+
+代码直接存储 `api_key` 原始值，设计要求 `auth_ref` 间接引用，密钥永不进入 session DB/events/artifacts。
+
+### 11.3 LLM 包未引用 contracts
+
+`packages/llm` 在本地定义所有类型而非从 `packages/contracts` 导入，违反了基线 §4 依赖方向规则。
+
+---
+
+## 12. 上下文装配审计 (ContextAssembler vs prompt-layering-v1.md)
+
+### 12.1 层级缺失 (4/10)
+
+| 层 | 设计 | 实现 | 状态 |
+|---|---|---|---|
+| L0 System | 系统身份 | 硬编码字符串 | PARTIAL |
+| L1 Capability | 能力声明 | 存在 | PASS |
+| L2 Safety | 安全规则 | 硬编码 | PARTIAL |
+| L3 Project Rules | 项目规则 | 存在但路径错误 | PARTIAL |
+| L4 Architecture | 架构上下文 | 存在 | PASS |
+| L5 Plan/Task | 计划/任务 | 存在 | PASS |
+| L6 Evidence | 证据上下文 | — | **缺失** (TODO) |
+| L7 Conversation | 对话历史 | — | **缺失** (TODO) |
+| L8 Tool Output | 工具输出 | — | **缺失** (TODO) |
+| L9 Immediate | 即时指令 | — | **缺失** (TODO) |
+
+### 12.2 输出格式
+
+设计要求输出 Anthropic canonical messages。实现输出自定义 `PromptLayer[]` 结构，未转换为 canonical 格式。
+
+### 12.3 冲突检测: 缺失
+
+设计要求层间冲突报告 (如安全规则与项目规则矛盾)。实现无任何冲突检测。
+
+### 12.4 CompactionPolicy: 无 copy-on-write
+
+设计要求 copy-on-write 压缩，保留回溯引用。实现仅有阈值检查，无工件持久化，无回溯保留。
+
+---
+
+## 13. TUI/HUD 审计 (packages/tui/ vs 设计)
+
+### 13.1 组件覆盖: 完整
+
+9 个视图组件全部存在: SessionView, TaskListView, AgentStatusView, ToolRunView, DiffView, PermissionPrompt, BlockerReport, HudView + TuiApp。
+
+### 13.2 缺口
+
+- 无 OpenTUI renderer 集成 (组件定义但无渲染引擎)
+- 无对话消息渲染表面
+- PermissionPrompt/BlockerReport 无路由连接
+- ProjectionStore.rebuild() 为桩 — 仅处理 5 种事件类型
+- HUD 预设 (Full/Essential/Minimal) 未实现
+
+---
+
+## 14. C++ 工具链审计 (packages/toolchain-cpp/ vs FR-017)
+
+### 14.1 组件存在但断连
+
+- `CppProjectDetector`, `CppBuilder`, `CMakeConfigurator`, `CppTestRunner`, `DiagnosticParser`, `ClangdClient`, `CppcheckRunner` 均存在
+- `CppToolRegistrar` 注册了工具定义但 **未注册到 ToolRegistry** (与 FR-010 的 16 个缺失工具一致)
+- `ClangdClient` 方法全部为桩
+- 源文件发现返回空数组
+
+### 14.2 安全风险
+
+`CppBuilder.build()` 和 `CppTestRunner.run()` 使用 `execSync` 字符串拼接，存在命令注入风险。
+
+---
+
+## 15. CLI 命令审计 (packages/cli/ vs 设计)
+
+### 15.1 命令覆盖: 完整 (PASS)
+
+所有 11 个必需命令存在: `init`, `run`, `doctor`, `provider`, `resume`, `compact`, `history`, `session`, `restore`, `e2e`, `release`。
+
+### 15.2 init 命令偏差
+
+- 不创建 17 个规范 `.air/` 子目录
+- 直接写文件系统，绕过 ToolRegistry/PermissionEngine (违反 INV-3)
+
+### 15.3 额外包
+
+代码中存在 `packages/workers/` 包，不在基线 §4 的规范包列表中。这是一个合理的分离 (worker 入口点独立于 runtime)，但需要 ADR 记录。
+
+---
+
+## 16. 运行时语义合规审计 (vs runtime-semantics-v1.md)
+
+| 不变量 | 合规 | 说明 |
+|---|---|---|
+| INV-1: 持久事件+域表同事务 | FAIL | F-04: EventStore.project() 不传事务 |
+| INV-2: EventIngestor 不创建调度任务 | PASS | |
+| INV-3: 副作用经 ToolRegistry/PermissionEngine | FAIL | init 直接写 FS |
+| INV-4: EventBus handler 错误不中断订阅 | PASS | |
+| INV-5: 临时事件合并 | PASS | 5 秒窗口正确 |
+| INV-6: 工件 temp-rename 原子写 | PASS | |
+| INV-7: Workspace GC 策略 | PARTIAL | GC 逻辑正确但 SQL 有 bug (F-10) |
+| INV-8: Agent heartbeat 持久化 | FAIL | 仅内存，不写 DB |
+| INV-9: ExperienceMiner 4 种触发路径 | FAIL | 0 种实现 |
+| INV-10: read-before-edit 强制 | FAIL | 未实现 |
+| INV-11: 完成门禁强制 | FAIL | 未实现 |
+
+---
+
+## 17. 正面发现 (代码与设计匹配的部分)
+
+1. **Monorepo 结构正确:** Bun workspace + Turborepo，7 个包分层清晰
+2. **SQLite Schema 完整:** 17 表、38 索引、PRAGMA、schema_meta 完全匹配
+3. **事件注册表完整:** 54 个持久事件 + 7 个临时事件全部注册
+4. **Enum 验证完整:** 18 个闭枚举全部覆盖
+5. **ArtifactStore 原子写入正确:** temp → sha256 → rename → event 流程完整
+6. **EventBus 错误隔离正确:** handler 异常不中断订阅
+7. **临时事件合并正确:** 7 种临时事件类型全部识别，5 秒窗口
+8. **EventIngestor 分离正确:** 持久/临时路径分离，不创建调度任务
+9. **SecretRedactor 覆盖良好:** 14 种凭证模式
+10. **CLI 命令完整:** 11/11 必需命令
+11. **WorkspaceManager GC 保留策略正确:** merged 7 天, abandoned 3 天
+12. **Heartbeat 合并窗口正确:** 5 秒
+13. **RetryPlanner 失败签名升级逻辑正确:** (但未接入)
+14. **所有 16 个仓库 CRUD 操作完整:** get/insert/update + 领域查询方法
+
+---
+
+## 18. 修复优先级建议
+
+### P0 (立即修复 — 阻塞核心不变量)
+
+1. **F-04: EventStore 事务边界** — 将 `_tx` 传递给所有仓库方法
+2. **F-05: Workspace status 枚举值** — `'created'` → `'active'`, `'merging'` → metadata
+3. **F-06: TaskAttemptRepository 列映射** — `failure_summary` → `failure_signature`
+4. **F-07: EventRepository 路由分隔符** — `.` → `/`
+5. **ToolRegistry `this` 绑定 bug** — 重构 ACTION_BRANCHES 为方法调用
+6. **CommandRiskAnalyzer `in` 操作符 bug** — `'sudo_likely' in trimmed` → `trimmed.includes('sudo')`
+
+### P1 (短期修复 — 功能性缺陷)
+
+7. **F-01/F-02: 项目级 DB schema** — 对齐 DebugKnowledgeStore 和 LearnedMemoryStore
+8. **补全 15 个缺失契约接口** — EventBus/EventStore/EventIngestor/ContextAssembler 等
+9. **PathClassifier 类别对齐** — 添加 `credential_store`, `project_air_shared/local`, `unknown`
+10. **PermissionEngine 类型对齐** — 4 profile, 6 action, grant scope
+11. **Scheduler 状态机补全** — BLOCKED/CANCELLED 状态, cancel_task, load_graph
+12. **IPC 信封补全** — 添加 5 个缺失字段, 修正握手顺序
+13. **注册 16 个缺失 MVP 工具** — fs.stat, process.kill, cpp.*, debug.*, gui.*, network.*
+14. **Main Agent 状态机补全** — 7 个缺失状态
+
+### P2 (中期修复 — 完整性)
+
+15. **ContextAssembler L6-L9** — 补全 4 个缺失层
+16. **Provider 能力矩阵** — 补全 ~80% 缺失字段
+17. **Worker 结果形状对齐** — 统一为 `WorkerResult<T>` 信封
+18. **Capability manifest 对齐** — 5 级 trust, 富依赖模型, 命名空间验证
+19. **Recovery 实现** — 孤儿扫描、PID 存活检查
+20. **EvidenceStore 持久化** — 从 EvidenceRepository 查询而非内存 Map
+
+### P3 (长期 — 质量与文档)
+
+21. **ADR 记录** — workers 包、Provider 类型强化、Doctor 扩展等设计偏差
+22. **DoctorIssueSeverity** — 添加缺失的 `"error"` 值
+23. **工具 Schema 对齐** — fs.edit, shell.run, artifact.create 等字段名/类型
+24. **Scope Escalation 实现** — ScopeImpactLevel, BlockerReport 集成
+25. **TUI renderer 集成** — OpenTUI/Solid 渲染引擎接入
+
+---
+
+## 19. 与设计文档冻结基线的一致性总结
+
+| 基线文档 | 一致性 | 主要偏差 |
+|---|---|---|
+| interface-contracts-v1.md | 65% | 15 个契约缺失，Provider 字段偏差 |
+| db-schema-v1.md | 85% | 2 个项目级 DB 完全不匹配，事务边界违反 |
+| event-registry-v1.md | 95% | 事件计数注释偏差 1，其余完整 |
+| tool-registry-v1.md | 40% | 16/28 MVP 工具缺失，schema 字段名偏差 |
+| security-model-v1.md | 20% | 分类器/权限/Profile 类型全面偏差 |
+| capability-trust-v1.md | 30% | Manifest schema、trust level、依赖模型不匹配 |
+| scheduler-state-machine-v1.md | 35% | 缺 2 状态、3 方法、3 空状态、依赖类型缺失 |
+| main-agent-state-machine.md | 45% | 缺 7/13 状态 |
+| prompt-layering-v1.md | 50% | L6-L9 缺失，输出格式不匹配 |
+| provider-capability-matrix-v1.md | 20% | 能力矩阵仅实现 ~20% |
+| runtime-semantics-v1.md | 40% | 11 个不变量中 5 个违反 |
+| error-taxonomy-v1.md | 90% | ErrorKind/AirError 匹配，ToolErrorOutput 缺失 |
+| artifact-naming-v1.md | 80% | ArtifactStore 路径正确，命名规范部分偏差 |
+| scope-escalation-v1.md | 10% | ScopeImpactLevel/BlockerReport 未实现 |
+| cross-platform-matrix-v1.md | 80% | 平台检测类型存在但 Doctor 未使用 |
+| C4 module.md | 85% | 包结构匹配，workers 包为额外添加 |
+| C4 code-view.md | 90% | contracts 文件结构匹配 |
+| solution-architecture.md | 55% | 分层架构存在，Agent 交互链不完整 |
+| system-overview-design.md | 50% | 子系统存在但连接断 |
+| system-detailed-design.md | 45% | 类存在但方法签名/状态机偏差大 |
+
+---
+
+## 20. 结论
+
+当前 V1.0.0 Alpha 代码实现处于 **骨架基本就位、语义大面积偏差** 的状态。monorepo 结构、SQLite schema、事件注册表等基础设施质量较高，但核心运行时子系统（Scheduler、IPC、Security、Context）与冻结基线之间存在结构性分歧。
+
+**最高风险项** 是 EventStore 事务边界违反 (F-04)，它会导致每个持久事件的域表更新在事务外执行，破坏数据一致性不变量。其次是 workspace status 枚举错误 (F-05) 会导致首次 workspace 创建即崩溃。
+
+建议在继续 Phase 2-8 实现之前，先完成 P0 和 P1 修复，确保核心不变量和接口契约与设计文档对齐。
+
+---
+
+*审计完毕。本报告由 Qwen3.7-Max 独立生成，可与其他模型审计报告进行交叉比对。*

AirPlan/docs/architecture/event-registry-v1.md

@@ -397,6 +397,35 @@ interface TaskInterruptedPayload {
 }
 ```
 
+#### `task.removed` v1
+
+Persistence: durable.
+
+Domain update: delete `tasks` row (only for pending status); insert event record.
+
+```ts
+interface TaskRemovedPayload {
+  task_id: string
+  reason: string
+  removed_by: string
+}
+```
+
+#### `task.invalidated` v1
+
+Persistence: durable.
+
+Domain update: update `tasks.status = invalidated`; insert event record.
+
+```ts
+interface TaskInvalidatedPayload {
+  task_id: string
+  adr_id: string
+  reason: string
+  rollback_ref?: string
+}
+```
+
 ### 3.5 Tool Events
 
 #### `tool.started` v1

AirPlan/docs/round4-AUDIT-FINAL.md

@@ -0,0 +1,232 @@
+# 全代码 code-to-design 审计 — 最终报告
+
+> 14 子系统 code-to-design 比对汇总 (round4 Stage 3)
+> 源: 14 份 agent 子系统审计报告 (A-N) → 合并去重 + 严重度再评估 + 影响链标注
+
+## 0. 元信息
+
+- 14 子系统全部完成 (A: Contracts, B: Storage, C: Event, D: Lifecycle, E: Scheduler, F: Worker/IPC, G: Tool/Perm, H: Context, I: Artifact, J: Provider, K: Projection+TUI, L: Agents, M: Toolchain, N: Doctor)
+- 合并后共 **97 条发现** (CRITICAL 18 / DEVIATION 32 / GAP 27 / EXCESS 20)
+- 报告期: round4 plan §3 格式逐项对齐, INV-1/INV-2/INV-3/INV-5 多子系统重复违反
+
+---
+
+## 1. CRITICAL (必须修) — 共 18 条
+
+| id | 子系统 | 标题 | 违反约束 | 触发场景 | 影响链 |
+|---|---|---|---|---|---|
+| round4-C-1 | A,B,D,J,K,L | **架构旁路: 多子系统自研 SessionManager/ProjectStore/ProviderManager 而旁路设计契约类** | DD §6.1-§6.2, §12, INV-2 single-writer | 启动任意 session, `RuntimeApp` / `init` / `ProviderManager` 全部跳过契约类, 直接 fs.write/SQLite/JSON.parse | 触发 C-2,C-4,C-5,C-8,C-11 |
+| round4-C-2 | C | **EventStore 单例 + 事后注入, SessionManager 创建的 EventStore 实例从未被消费** | DD §5.1 §22.2 构造注入 | 任何 session 打开后 `session.created` 写入空 db 或被抛弃, domain projection 变 no-op | C-3, C-6, C-15, G-C1 |
+| round4-C-3 | C | **`EventIngestor.ingest()` 走 fallback 无 tx 路径, 违反 `BEGIN/insert/project/COMMIT` 单事务** | runtime-semantics §3 | 同上事件路径, project() 与 event insert 不在同一事务 | C-2, I-C1 |
+| round4-C-4 | C | **`project()` switch 跳过 `context.compaction.*`/`permission.*`/`doctor.*`/`memory.*`/`debug.*` 20+ 事件类型** | DD §5.4 Table A+B | 上述事件全部不更新 domain table, 但 `events` 表行仍写 → 审计日志与 domain 永久不一致 | C-2, C-3, G-C2, N-D1 |
+| round4-C-5 | E | **失败/阻塞任务被路由到设计无的 `TERMINATED` 终态** | scheduler-state-machine §10 (仅 COMPLETED/BLOCKED/CANCELLED) | 任何 task 失败 → `run_until_idle` 退出但 API 不暴露 TERMINATED, 调度死锁 | E-2, E-7 |
+| round4-C-6 | E | **`PLANNING_WAVE → MONITORING` 跳过 `DISPATCHING`, 旁路 spawn** | scheduler-state-machine §4 | 任何非空 running task, 调度直接进入监控态, worker 永不被 spawn | E-3, E-5, F-C1 |
+| round4-C-7 | E | **Scheduler 公开 API `add_dependency` / `load_graph` / `cancel_task` 完全缺失** | DD §7.1, contracts task.ts:194-200 | DAG 编辑与取消无法调用, CLI/TUI 失去图编辑能力 | E-5, E-8 |
+| round4-C-8 | E,F | **`agent.start` IPC 控制消息未按设计携带 `context_pack`/`runtime`/`AgentRuntimeContext`, `WorkerRole.run` 单参** | DD §8.2 handshake, contracts §10 | worker 启动后拿不到 permission_template / ContextPack, 权限与上下文全空 | F-C2, F-D3, G-C3 |
+| round4-C-9 | F | **`WorkerRuntime` 自加 `call_llm`, 凭据路径走 `process.env.AIRCODING_MODEL` fallback 'glm-5.1', 绕过 TaskSpec.constraints.model_id** | DD §18 INV-3, interface-contracts §10 | worker 直连 LLM 风险 + 模型 ID 决定顺序错乱 (env > spec) | F-C1, J-C1, C-2 |
+| round4-C-10 | G | **ToolRegistry.call / PermissionEngine.record 完全不发射 `tool.*` / `permission.decision.recorded` 事件** | DD §9.1 §9.2, INV-1 | 任意 tool 调用与权限决策不入 `tool_runs` / 决策审计, 投影与追责链断 | C-4, G-C2, K-D1 |
+| round4-C-11 | G | **`execute_branch` 在 allow/announce_then_run 跳过 grant_scope 持久化与 backup_before_write** | DD §9.3, 安全模型 §11 | 同一 scope 每次 call 重复 prompt, 写操作无备份 | G-C1, G-D1 |
+| round4-C-12 | I | **CppToolRegistrar `write_artifacts` 完全旁路 ArtifactStore, 用 `file://` URI, 不算 sha256** | DD §994-1002, naming §8 | `cpp.build/test` 失败时写出的产物既不在 artifacts 表, 也无法回链 evidence | I-C3, I-G2, M-E1 |
+| round4-C-13 | I | **EvidenceStore.create 在 ingest event 后又重复插 `evidence_refs`, 打破 single-writer** | DD §18.4, runtime-semantics §6.3 | 每次 evidence 创建产 2 行 DB, 触发 FK-off 检测假阳 | C-3, B-C3 |
+| round4-C-14 | J | **ProviderManager 硬编码 `provider_id || 'anthropic'`, 多 provider 路由坍缩为单 provider fallback** | DD §12.1 §12.2 adapter_for(provider_id) | 任一 OpenAI/GLM 路径静默回落 anthropic 或抛 "No adapter selected" | J-D4, J-D5, J-G1, F-C1 |
+| round4-C-15 | L | **`CONFIRMING → confirm` 路由到 `DELEGATING` 而非 `EXECUTING` (Opus 报告"已修"未验证)** | DD §20.1 state machine | 用户确认后任务被 re-delegated 而非直接执行, 卡死 | L-2, L-3, E-7 |
+| round4-C-16 | L | **ArchitectureDesigner 放在 simple/plan 分支前, 强制所有 task-path 走 Architect 评估** | DD §20.1 §14.1 | 每个 task 请求都做 impact_assess, 性能与设计意图双重偏离 | L-3, L-4 |
+| round4-C-17 | N | **`DoctorService --fix` 裸跑 `sudo apt install`, 绕过 PermissionEngine** | DD §16.1, INV-3 | `--fix` 自动修复触发高危命令, 任何用户/任务权限配置被跳过 | N-D1, G-C3 |
+| round4-C-18 | B,C,I,N | **`Recovery.scanOrphanReferences` FK-off 8 不变量只覆盖 session_id 一类, 实际只查 5/8, 标修复但无 UPDATE/DELETE** | DD §18.3 §16.3, runtime-semantics §14 | 孤儿 task/agent/tool_run/command_run 不被检测/修复, 累积 → 重启后状态漂移 | C-6, I-C1, I-G2 |
+
+---
+
+## 2. DEVIATION (高优) — 共 32 条 (节选要点, 完整 32 条见附录)
+
+| id | 子系统 | 偏离 | 影响 |
+|---|---|---|---|
+| D-A-1..6 | A | ProviderCapabilityMatrix / ProviderCompletionInput / ProviderManager.load_config / PromptLayerLoader / FollowUpTask.type 等 6 处与 contracts §15 §16 字段类型不一致 | type 漂移累积 → runtime/contracts 边界失真 |
+| D-B-1..6 | B | `list_active(project_id)` 必传参, `insert` 硬写 status='active', `update` 接受 patch.status 无守卫, `DatabaseHandle` 返回 `{path}` 不含 db, 类型在 MigrationRunner | INV-1 守卫仅靠注释, 模块边界混乱 |
+| D-C-1..7 | C | `EventSchemaRegistry.validate` 只查 type, `EventBus.publish` 内存泄漏, `append_many` 共享 tx, `project()` 跳过 20+ 事件, `ingest_batch` 不在 contract, `assistant.message.created` 投影顺序, `agent.started` 丢失 starting 分支 | 事件管道不严, 大量 corner case 未覆盖 |
+| D-D-1..4 | D | `ProjectionStore.rebuild` 一致 ✓, 但 `RuntimeApp` 启动序列命名/编号与 §22.2 不一致, migrate 走 ad-hoc dbHandle | 启动行为可观察但语义不清 |
+| D-E-1..8 | E | `SchedulerState` 多 TERMINATED, `WavePlanner` 字段名错, `record_heartbeat` 签名错且不写 domain, `WorkspaceManager` 不发事件, `RetryPlanner.decide` 永不被调, `TaskGraph.get_runnable_tasks` 忽略 soft/serialization, MONITORING 收 WorkerResult, `create_tasks` 跳过 LOADING_GRAPH | 调度可用但状态机闭包破坏 |
+| D-F-1..4 | F | IpcKind 双重协议 (IpcKind + WorkerMessageType), ExitCode 5 永未触发, NDJSON 编码只校验 4 字段, 父进程全量继承 process.env | 协议冗余, 凭据泄漏风险面 |
+| D-G-1..4 | G | `PermissionAction` 6 个但 block 不抛 task.blocked, `PermissionEngine.evaluate` 3 参, `BuiltInToolRegistrar` 18 vs 28 缺 cpp.*6/fs.stat 等, `call_streaming` 不处理 ask_user/block/refuse | 决策 schema 漂移, V1 工具面残缺 1/3 |
+| D-H-1..5 | H | L8 用 `message_repo` 替代 `tool_runs`/`command_runs`, `AssembledContext` 缺 `canonical_format:"anthropic"`, L6 Evidence 第一参错 (传 'task_id' 而非 'task'), `messages_artifact_id` 溢出路径未触发, CompactorRole 行为一致 ✓ | ArchitectureDesigner L4 失效, L6/L8 数据源错 |
+| D-I-1..4 | I | `artifact_id` 用 UUID 截 24 hex 不用 ULID, DebugKnowledgeStore/LearnedMemoryStore 自定 schema 不同步 contracts, ArtifactStore 不 gzip, `get` 暴力 readdir 不用 DB | 命名不匹配触发 Recovery 假阳, 性能浪费 |
+| D-J-1..5 | J | Adapter 缺 `count_tokens`, `complete` 非流式 (等待整响应再 yield), `ProviderConversionReport.status` 缺, `ModelConfigLoader` 不解析嵌套 YAML, `select_model` 忽略 ModelRequirement | capability-based selection 与流式语义失效 |
+| D-K-1..2 | K | `ProjectionStore.apply` 在生产路径是死代码 (RuntimeApp 用 snapshot push), `TuiApp.start` 返回 Promise | 路径与设计意图分裂 |
+| D-L-1..3 | L | MainAgent 状态多 ERROR+TERMINATED, AWAITING 状态无转换, `handle_user_message` 不返回 y/n 循环 | 状态爆炸但未连通 |
+| D-M-1..4 | M | `DiagnosticParser.semantic_signature` 名字/签名错, `ClangdClient` 拆 query_symbol/query_diagnostics, `CppProjectDetector` 实例化用构造参数, `CppTestRunner.parse_ctest_output` 不在设计 | 工具链接口小幅漂移, 可互通 |
+| D-N-1..6 | N | Doctor 8 类 (含 project/runtime 多), `run_diagnostics(scope)` 签名不符, 7-day retention 缺失, MigrationRunner 17 表 OK, Recovery 8 步只 3 步, FK 检查 5/8, SecretRedactor 未共享 | 运维数据积累无清理, 恢复路径不完整 |
+
+---
+
+## 3. GAP (设计有、实现无) — 共 27 条
+
+**事件/存储契约层 (影响 4 子系统)**
+- G-1 缺失 §7 全部契约 `EventBus/EventStore/EventIngestor/EventSchemaRegistry/Subscription/EventAppendOptions` (A)
+- G-2 缺失 §6 持久化记录 `PersistedEventRecord/PersistedEventInsert/SessionRecord/MessageRecord/EventRepository` (A)
+- G-3 缺失 §16 Context 核心接口 `ContextAssembler/ContextAssembleInput/AssembledContext/CompactionPolicy/CompactionResult` (A)
+- G-4 `SessionStore` 聚合类缺失, 15 repos 散落 (B) — **触发 C-18**
+- G-5 Outbox 模型未实现 (B) — **触发 C-2, C-13, I-C1**
+- G-6 `EventIngestorFactory.createForSession` 无实现 (C)
+
+**工具/能力层 (影响 3 子系统)**
+- G-7 BuiltIn 28 工具仅 18 注册, `cpp.*6`/`fs.stat`/`git.worktree`/`process.kill` 全部缺 (G) — **触发 C-12, M-E1**
+- G-8 `artifact.create/read` 工具是 stub 不调 ArtifactStore (I) — **触发 C-12**
+- G-9 `Recovery.open()` 无 bootstrap 调用点 (N) — **触发 C-18**
+- G-10 `check_capability()` private helper 缺失 (N)
+- G-11 `doctor --bundle` 命令模式缺失 (N)
+- G-12 `context.compaction.requested` 事件从未由 Scheduler 发出 (H) — **触发 C-4**
+- G-13 copy-on-write compaction 缺失 (H)
+- G-14 L4 Architecture 层未实现 plan/ADR/C4 文档加载 (H)
+- G-15 L2 Safety 层是硬编码 placeholder (H)
+- G-16 L7 omission/conflict 路由未实现 (H)
+- G-17 `EventSchemaRegistry` 无 version 升级路径 (C)
+- G-18 `assistant.message.failed` 失败 artifact 创建缺失 (C)
+- G-19 FK-off 一致性 enforcement 缺失 (C) — **触发 C-18**
+
+**UI/Agent 层**
+- G-20 TUI `theme/` 与 `keymap/` 目录缺失 (K)
+- G-21 ProjectionStore 未与 SessionStore 仓库连接, `rebuild()` 生产未调 (K) — **触发 C-18**
+- G-22 HUD 未挂载主界面 (K)
+- G-23 缺失 ephemeral 事件处理 (assistant.message.delta 等) (K)
+- G-24 Regex 分类器替代 CLASSIFYING LLM 步骤 (L)
+- G-25 `requirement.changed` 发射路径缺失 (L)
+- G-26 INTERRUPTING/ARCHITECTURE_REVISING 分支不可达 (L)
+- G-27 main-agent-state-machine 7-day retention / Bundle 模式 (N)
+
+---
+
+## 4. EXCESS (实现有、设计无) — 共 20 条
+
+- E-1 `ProviderIdentity/ProviderConversionReport/ToolCall/DoctorIssue/CapabilityTrustLevel` 等类型别名抽取, 扩大 contracts 导出表面 (A) — **触发 C-14**
+- E-2 Repository 基类重复样板 ~800 行 (B)
+- E-3 `EventIngestor.ingest_batch/EventIngestorFactory/NullEventIngestor` (C) — **触发 C-2**
+- E-4 `EventStore.setTransactionManager/setRepositories` 事后注入 setter (C) — **触发 C-2**
+- E-5 `EventBus.getSubscriptionCount` (C)
+- E-6 `EventStore` 手写 UUID 生成器 (C) — **触发 G-17**
+- E-7 `EventStore` repository 字段类型 `any` (C) — **触发 C-4**
+- E-8 `createRuntime.ts` / `loadConfig.ts` 自实现 project_id 加载 (D) — **触发 C-1**
+- E-9 `WorkerRuntime` 多 4 个方法 (call_llm/report_result/heartbeat/send_*) (F) — **触发 C-9**
+- E-10 `WorkerProtocol` 多 5 种消息类型 (F) — **触发 C-8**
+- E-11 `WorkerHandle.state` 元数据多余 (F)
+- E-12 `find_bun()` / `worker.error` 私有通道 (F)
+- E-13 `ToolRegistry.execute_branch` 多 `downgrade_to_readonly`/`apply_sandbox_restrictions` dead code (G)
+- E-14 `ToolRegistry.global_tool_registry` 单例 (G)
+- E-15 `CapabilityManifestValidator` trust_level enum 校验未决策 (G) — **触发 G-7**
+- E-16 `PermissionEngine` LAYER_ORDER + decision_log (G)
+- E-17 `SkillLoader` trust_root bypass 旁路 (G)
+- E-18 `ContextAssembler` L3 `project_files` 非设计层 (H)
+- E-19 TUI 端重复定义 `ProjectionClient` 与投影类型 (K) — **触发 K-D1**
+- E-20 CppToolRegistrar `write_artifacts` 写文件, 重复 runtime EventSink (M) — **触发 C-12**
+
+---
+
+## 5. 影响链分析
+
+**核心根因 (修这个能解多个症状)**:
+
+1. **根因-A: 设计契约类被实现旁路** (C-1, C-2, D-C1, D-C2, F-C1, J-C1, N-C1)
+   → SessionManager / ProjectStore / ProviderManager / PermissionEngine 在 7 个子系统中实现完整但被 RuntimeApp / WorkerRuntime / ProviderManager / DoctorService 旁路
+   → 修一个 RuntimeApp 启动路径让其走 SessionManager.open_session, 7 个 CRITICAL 同步关闭
+
+2. **根因-B: INV-1 事件链整体失效** (C-2, C-3, C-4, G-C1, G-C2, H-G1, I-C1)
+   → event → projection → domain table 这条链上 5+ 子系统不发射或不投影关键事件
+   → 修 `EventStore.project()` switch 覆盖 55 个事件 + 移除单例, 8 个症状同时解
+
+3. **根因-C: 状态机闭包破坏** (E-1, E-2, E-6, L-1, L-2)
+   → Scheduler 5 个 CRITICAL + MainAgent 2 个 CRITICAL 都是状态转换路由错
+   → 统一从 state machine 重写主控循环
+
+4. **根因-D: outbox/INV-2 缺失** (B-G2, C-2, I-C1, I-C3, I-G2)
+   → external write → ingest event 同事务模式未实施, 导致 4 个子系统重复插入/孤儿文件
+   → 修 G-5 outbox 模型一处, 4 个症状同步解
+
+5. **根因-E: 设计类 vs 实现类双轨** (A-G1, A-G2, A-G3)
+   → contracts 设计了 §6 §7 §16 全部接口但实现未映射到任何 .ts 文件
+   → 修 contracts package index 重新映射, 3 个 GAP 关闭
+
+**症状层 (依赖根因)**:
+- K-D1, H-D1, H-D2 全部因 C-2/C-3 投影失效
+- M-D1-D4 因 G-7 工具面残缺间接暴露
+- L-D2, L-D3 因 E-5/E-6 调度状态错
+
+**CRITICAL 互相触发关系图 (简化)**:
+```
+C-1 (架构旁路) ─┬─→ C-2 (EventStore 单例) ─→ C-3 (no-tx) ─→ C-4 (project switch 缺) ─→ C-13
+                ├─→ C-5/C-6 (Scheduler 状态) ─→ C-7 (API 缺)
+                ├─→ C-9 (call_llm) ─→ C-14 (Provider 硬编码)
+                ├─→ C-10 (Tool 不发事件) ─→ C-11 (execute_branch)
+                ├─→ C-12 (Artifact 旁路) ─→ C-13
+                ├─→ C-15/L-1 (CONFIRMING 错) ─→ C-5
+                └─→ C-17 (Doctor 裸 sudo)
+C-18 (Recovery FK 5/8) ←─ C-3, C-4, I-C1
+```
+
+---
+
+## 6. 建议修复顺序
+
+**P0 - 必须先修 (5 条根因)**
+1. C-1 + D-C1 + D-C2: RuntimeApp 启动路径改走 SessionManager / ProjectStore — 解 7 个子系统症状 (估 1-2 天)
+2. C-2 + C-3: 撤销 EventStore/eventIngestor 模块单例, 改回 SessionManager 构造注入, 恢复 txManager/repos 在构造时绑定 — 解 C-13/C-15/I-C1 等 (估 1 天)
+3. C-4: `EventStore.project()` switch 覆盖 55 个事件类型 + Table B cross-DB 占位 — 解 C-13/C-10/G-C2 (估 1-2 天)
+4. C-5 + C-6 + C-7 + E-D1: 重写 Scheduler 状态机主循环 (terminal_state 去掉 TERMINATED, PLANNING_WAVE→DISPATCHING→MONITORING, 补齐 add_dependency/load_graph/cancel_task) — 解 E-2/L-1 (估 2-3 天)
+5. C-18 + B-G1 + B-G3: Recovery 8 步全部实现 + FK-off 8 invariant 全覆盖 + 实际 archive/reparent 动作 — (估 1 天)
+
+**P1 - 高优 (症状层, 根因修后自动解或独立修)**
+6. C-9 + C-14 + J-C1: WorkerRuntime 移除 call_llm, ProviderManager 走 adapter_for 路由 — (估 1 天)
+7. C-10 + C-11 + G-D1: Tool/Permission 事件链修复 + PermissionDecision schema 对齐 contracts — (估 1-2 天)
+8. C-12 + I-G1 + I-G2: CppToolRegistrar 走 ArtifactStore + tool 包装 — (估 1 天)
+9. L-1 + L-2 + L-3: MainAgent CONFIRMING→EXECUTING + ArchitectureDesigner 仅 plan 分支 + architecture.plan.updated 发射 — (估 1 天)
+10. N-C1 + N-C2: Doctor --fix 走 PermissionEngine, 双份日志连通 DeveloperLogEncryptor — (估 0.5 天)
+11. K-D1 + K-G2: ProjectionStore.apply 走真实事件流 + 注入 SessionStore 仓库 — (估 0.5 天)
+
+**P2 - 可后修 (设计 polish)**
+12. A-G1/G2/G3: contracts §6/§7/§16 接口映射 .ts 文件 (估 0.5 天)
+13. D-D4 + D-G1: RuntimeApp 启动序列命名/编号与 §22.2 对齐 (估 0.5 天)
+14. F-D1/D2/D4: IpcKind 单一协议 + ExitCode 5 触发路径 + 父进程 env 白名单 (估 1 天)
+15. J-D1-D5 + J-G1-G4: Provider 5 DEVIATION + 4 GAP (估 2 天)
+16. H-D1/D2/D3/D4 + H-G2/G3/G4: Context 6 处偏离 (估 1 天)
+17. M-D1-D4: Toolchain 4 处 API 漂移 (估 0.5 天)
+18. N-D2 + N-G1-G3: Doctor 7-day retention + Recovery bootstrap + bundle (估 1 天)
+19. K-G1/G3/G4 + K-E1/E2/E3: TUI 主题/键位/HUD/ephemeral/类型镜像 (估 1-2 天)
+20. EXCESS 全部 (20 条): 死代码清理 (估 0.5-1 天)
+
+**总工作量估算**:
+- P0: 6-9 天 (1 个工程师)
+- P1: 5-7 天
+- P2: 8-12 天
+- 合计: 19-28 工作日 (4-6 周)
+
+---
+
+## 7. 附录: 子系统审计发现数
+
+| 子系统 | CRITICAL | DEVIATION | GAP | EXCESS | 合计 |
+|---|---|---|---|---|---|
+| A Contracts | 4 | 6 | 3 | 4 | **17** |
+| B Storage | 3 | 6 | 5 | 4 | **18** |
+| C Event | 3 | 7 | 6 | 5 | **21** |
+| D Lifecycle | 3 | 4 | 2 | 1 | **10** |
+| E Scheduler | 5 | 8 | 4 | 0 | **17** |
+| F Worker/IPC | 2 | 4 | 3 | 4 | **13** |
+| G Tool/Perm | 3 | 4 | 5 | 5 | **17** |
+| H Context | 1 | 5 | 4 | 2 | **12** |
+| I Artifact | 3 | 4 | 3 | 1 | **11** |
+| J Provider | 1 | 5 | 4 | 3 | **13** |
+| K Projection+TUI | 1 | 2 | 5 | 3 | **11** |
+| L Agents | 4 | 3 | 3 | 2 | **12** |
+| M Toolchain | 0 | 4 | 0 | 2 | **6** |
+| N Doctor | 2 | 6 | 3 | 2 | **13** |
+| **合计 (去重前)** | **35** | **68** | **50** | **38** | **191** |
+| **合并去重后** | **18** | **32** | **27** | **20** | **97** |
+
+**去重说明**:
+- 多 agent 报告同一条 (如 C-2/C-3/C-4/C-10 都是 INV-1 事件链断裂的不同切面) 合并为 1 条
+- 工具缺注册 (G-D3) 与 contracts 缺接口 (A-G1) 因根因不同保留
+- 影响范围扩到 3+ 子系统的偏离被升级评估, 18 条 CRITICAL 包含 5 条根因型 (影响 7+ 子系统)
+
+---
+
+**审计范围**: 14 个子系统 + 0 个遗漏
+**报告字数**: ~1500 字 (含表格)
+**未修代码**: 严格遵守
+**Stage 3 汇总完成**

AirPlan/docs/spec/AirPlan-ParaV2/.agents/plugins/marketplace.json

@@ -0,0 +1,92 @@
+{
+  "name": "local-airarc",
+  "interface": {
+    "displayName": "Local AirArc Plugins"
+  },
+  "plugins": [
+    {
+      "name": "airarc",
+      "source": {
+        "source": "local",
+        "path": "./plugins/airarc"
+      },
+      "policy": {
+        "installation": "INSTALLED_BY_DEFAULT",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    },
+    {
+      "name": "aireng",
+      "source": {
+        "source": "local",
+        "path": "./plugins/aireng"
+      },
+      "policy": {
+        "installation": "INSTALLED_BY_DEFAULT",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    },
+    {
+      "name": "airdo",
+      "source": {
+        "source": "local",
+        "path": "./plugins/airdo"
+      },
+      "policy": {
+        "installation": "INSTALLED_BY_DEFAULT",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    },
+    {
+      "name": "airdbg",
+      "source": {
+        "source": "local",
+        "path": "./plugins/airdbg"
+      },
+      "policy": {
+        "installation": "INSTALLED_BY_DEFAULT",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    },
+    {
+      "name": "airndb",
+      "source": {
+        "source": "local",
+        "path": "./plugins/airndb"
+      },
+      "policy": {
+        "installation": "INSTALLED_BY_DEFAULT",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    },
+    {
+      "name": "airxdb",
+      "source": {
+        "source": "local",
+        "path": "./plugins/airxdb"
+      },
+      "policy": {
+        "installation": "INSTALLED_BY_DEFAULT",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    },
+    {
+      "name": "airsdb",
+      "source": {
+        "source": "local",
+        "path": "./plugins/airsdb"
+      },
+      "policy": {
+        "installation": "INSTALLED_BY_DEFAULT",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity"
+    }
+  ]
+}

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airarc/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: airarc
+description: Architecture-first workflow with built-in post-plan parallelization review. Use when planning should emit dependency edges, parallel groups, write-set conflicts, and serialization points for Air Engine. AirArc plans and edits planning docs only; it does not write code.
+---
+
+# AirArc
+
+## Upgrade Notes
+
+- Keep the original architecture-first planning role.
+- AirArc is an architect-only workflow: it may plan tasks and edit architecture or planning documents, but it must not implement code changes.
+- Add built-in post-plan review instead of a separate review-only plugin.
+- Emit engine-consumable execution artifacts after planning.
+
+## Outputs
+
+- `AirPlan/state/airarc/state.json`
+- `AirPlan/state/airarc/reviews/parallel-review.json`
+- `AirPlan/state/airarc/reviews/parallel-review.md`
+- `AirPlan/state/airarc/reviews/execution-plan.json`
+- `AirPlan/state/airarc/reviews/execution-plan.md`
+
+## Review Responsibilities
+
+- Compute dependency edges.
+- Compute parallel-safe groups.
+- Detect shared write-set conflicts.
+- Mark serialization points for global docs and merge boundaries.
+- Produce an execution plan that Air Engine can prefer directly.
+
+## Commands
+
+```bash
+python "$HOME/plugins/airarc/scripts/airarc_mode.py" --mode enter --project <project-root>
+python "$HOME/plugins/airarc/scripts/airarc_mode.py" --mode status --project <project-root>
+python "$HOME/plugins/airarc/scripts/airarc_mode.py" --mode parallel-review --project <project-root> --todo <todo-md>
+```

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdbg/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: airdbg
+description: Debug-first repair workflow. Use when the user invokes /airdbg or explicitly asks for AirDbg mode to debug, reproduce, diagnose, or fix software errors, including GUI, visual, screenshot, browser UI, desktop UI, remote GUI/device debugging, canvas, layout, focus, popup, graphical operation, network, packet capture, remote packet capture, pcap, DNS, TCP, UDP, TLS, HTTP connectivity, proxy, firewall, port, retransmit, reset, latency, cppcheck, static analysis, code quality, or security-relevant C/C++ defects. Load or initialize AirPlan/AGENTS.md, AirPlan/docs/architecture/adr/ decision records, and AirPlan/docs/architecture/c4/module.md; discuss symptoms and constraints with the user; reproduce the issue; require AirXDB local or remote device helpers or equivalent GUI/screen evidence for every local or remote GUI validation instead of treating process liveness as success; call AirNDB local or remote device helpers when tcpdump/WinDump packet capture, pcap analysis, BPF filters, or network-layer evidence is needed; call AirSDB local or remote device helpers when static-analysis capability, cppcheck evidence, or AirPlan/docs/staticanalysis.md documentation is needed; identify root cause; apply a focused fix; verify with tests or equivalent checks; and update AirPlan/AGENTS.md, ADR, and C4 module docs when project behavior, module boundaries, dependencies, GUI automation boundaries, network boundaries, static-analysis boundaries, remote-device boundaries, or architecture decisions change.
+---
+
+# AirDbg
+
+## 核心约束
+
+- 全程使用中文与用户交流，代码、命令、日志、路径、异常名保持原文。
+- `/airdbg` 是主要触发入口。用户进入 AirDbg 后，围绕调试和修复错误推进。
+- 先加载项目上下文，再修复：`AirPlan/AGENTS.md`、`AirPlan/docs/architecture/adr/`、`AirPlan/docs/architecture/c4/module.md`。
+- 如果这些文件不存在，先分析当前项目并初始化它们；C4 module 要记录真实模块边界，不只放空模板。
+- 与用户交流症状、复现步骤、期望行为、实际行为、影响范围和修复约束。
+- 默认做最小可验证修复，避免顺手重构。
+- 每个修复都要验证。优先自动化测试，其次是可重复命令或明确的手工验证步骤。
+- 只要验证或复现涉及本地或远程 GUI，就不能只以进程存在、窗口拉起、命令退出成功、端口监听或日志无异常判定通过；必须辅以图像/GUI 检验和测试。
+- 调试中遇到图形对比、截图取证、GUI 操作、浏览器/桌面界面、Canvas、弹窗、焦点、布局、视觉回归或其他图形功能时，必须调用 `airxdb` 获取截图、探索界面、执行操作验证或收集视觉证据；如果是嵌入式屏幕、显示链路等截图无诊断价值的场景，可不强制截图，但必须补充等效的 GUI/屏幕状态证据和操作验证，并记录原因。
+- 如果 GUI 问题发生在远程设备、测试机、VM、服务器或 SSH 主机上，调用 AirXDB remote device helper，而不是默认使用本机 Computer MCP。
+- 调试中遇到抓包分析、pcap、tcpdump/WinDump、BPF、DNS、TCP、UDP、TLS、HTTP 连接、端口、代理、防火墙、丢包、重传、RST 或延迟问题时，可以调用 `airndb` 获取网络层调试证据。
+- 如果网络问题发生在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，调用 AirNDB remote device helper，而不是默认使用本机抓包工具。
+- 调试中遇到需要静态分析能力的检验、测试或定位场景，以及 C/C++ 静态分析、cppcheck、代码质量、安全性初筛、未初始化变量、空指针、越界、资源释放、危险转换或 CWE 线索需求时，可以调用 `airsdb` 获取 `AirPlan/docs/staticanalysis.md`、XML/JSON 报告等静态分析证据和辅助调试文档。
+- 如果静态分析目标在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，调用 AirSDB remote device helper，而不是默认使用本机 cppcheck。
+- 一定要根据项目变化维护 `AirPlan/AGENTS.md`、ADR 和 C4 module。
+- ADR 是给 AI 作为上下文的决策记录，短、准、可检索即可，不写冗长修饰。
+
+## 启动与初始化
+
+进入 `/airdbg` 时运行：
+
+```bash
+python "$HOME/plugins/airdbg/scripts/airdbg_mode.py" --mode enter --project .
+```
+
+如果当前环境没有 `python`，尝试 `py` 或 `python3`。脚本不可用时，手动确保以下结构存在：
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/docs/debug/debug-log.md`
+- `AirPlan/state/airdbg/state.json`
+
+初始化后读取已有内容作为上下文。不要覆盖用户已有正文；只补齐缺失结构或更新 AirDbg 标记块。
+
+## 图形调试与 AirXDB 协作
+
+AirDbg 负责根因分析、代码层修复和验证收尾；AirXDB 负责图形界面的取证和操作层复现。遇到以下情况时，必须调用 AirXDB 或补充等效 GUI/屏幕证据：
+
+- 需要截图或图形对比来理解错误现场、视觉回归、布局错位、颜色/尺寸/遮挡差异。
+- 需要操作浏览器 UI、桌面 UI、Electron/Qt/WPF 等应用、Canvas、菜单、弹窗、托盘、任务栏或多显示器界面。
+- 需要 `/airxdb screenshot` 保存错误现场，再把截图交给 AirDbg 做代码层诊断。
+- 目标 GUI 在远程设备、测试机、VM、服务器或 SSH 主机上，需要 `/airxdb remote-screenshot` 或 `airxdb_remote_device.py` 保存远程错误现场。
+- 需要用 AirXDB 执行最小 GUI 操作，确认按钮、表单、导航、窗口切换、焦点或图形流程是否真的失败。
+- 需要把 GUI 证据沉淀到 `AirPlan/docs/debug/gui-debug-log.md`、`AirPlan/docs/debug/airxdb-artifacts/` 或 AirDbg 的 `AirPlan/docs/debug/debug-log.md`。
+
+协作规则：
+
+- 先用 AirXDB 收集最小必要证据，再回到 AirDbg 分析代码根因；不要把视觉症状直接当作根因。
+- 任何本地或远程 GUI 测试/验证都不能仅以进程存活、窗口创建成功、命令返回成功或日志无异常视为通过；默认至少保留 1 份截图/图像证据，并完成 1 次关键 GUI 操作或状态检查。
+- 如果是嵌入式屏幕、显示控制器、外接面板链路等截图无诊断价值的场景，可改用外部采集视频、framebuffer dump、串口/日志配合按键或触控操作记录、状态灯/OSD 观察记录等等效证据，但必须在 `debug-log.md` 记录为什么不截图以及替代证据是什么。
+- 截图模式可在没有 Midscene 语义模型配置时使用；语义视觉动作按 AirXDB 规则先检查模型配置。
+- 本机 GUI 证据使用 `/airxdb screenshot` 或 `airxdb_computer_mcp_smoke.py`；远程 GUI 证据使用 `airxdb_remote_device.py --action setup|screenshot`，由它探测 SSH、远端截图工具并在缺失时自动尝试配置。
+- 远程 helper 缺少 `AIRXDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；需要交互式 sudo、管理员确认或无支持包管理器时停止并说明。
+- AirDbg 的 `debug-log.md` 必须记录 AirXDB 命令、截图/报告路径、关键观察、与根因的关系、复验结果和剩余风险。
+- 如果 GUI 自动化、截图取证、视觉验收、浏览器桥接或桌面控制成为长期调试/测试边界，更新 C4 module 并创建或修订 ADR。
+- 如果发现稳定可复用的 GUI 调试命令、截图方式、远程设备配置或视觉验收步骤，更新 `AGENTS.md`。
+- 截图可能包含账号、密钥、客户数据或聊天内容时，先提醒用户脱敏，再外部分享或长期保留。
+
+## 抓包调试与 AirNDB 协作
+
+AirDbg 负责把网络证据和代码行为联系起来，定位根因并修复；AirNDB 负责 tcpdump/WinDump 抓包、pcap 摘要、BPF 过滤器和网络层证据。遇到以下情况时，调用 AirNDB：
+
+- 需要抓包判断请求是否发出、响应是否回来、连接是否被 RST/ICMP/防火墙/代理中断。
+- 需要分析 DNS 查询、TCP 三次握手、TLS 握手、HTTP 连接、UDP 流量、端口可达性、重传、丢包或延迟。
+- 需要读取已有 `.pcap` 或生成新的短时有界 pcap 给调试使用。
+- 需要确定问题在应用代码、系统网络栈、容器/WSL/VM/宿主机边界、代理、防火墙还是远端服务。
+- 目标流量发生在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，需要 `/airndb remote-interfaces`、`/airndb remote-capture` 或 `airndb_remote_device.py` 获取远程网络证据。
+
+协作规则：
+
+- 先让 AirNDB 明确授权范围、接口、BPF 过滤器、抓包窗口和 pcap 输出路径；不要进行无界抓包。
+- 本机网络证据使用 `airndb_capture.py`；远程网络证据使用 `airndb_remote_device.py --action setup|interfaces|command|capture`，由它探测 SSH、远端 `tcpdump` / `dumpcap` 并在缺失时自动尝试配置。
+- 远程 helper 缺少 `AIRNDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；需要交互式 sudo、管理员确认或无支持包管理器时停止并说明。
+- AirDbg 的 `debug-log.md` 必须记录 AirNDB 命令、pcap/summary/report 路径、关键包或时间线观察、与根因的关系、复验结果和剩余风险。
+- 如果抓包发现新的长期网络边界、端口、协议、DNS、代理、TLS、容器/WSL/VM/宿主机约束或观测方式，更新 C4 module 并创建或修订 ADR。
+- 如果发现稳定可复用的抓包命令、接口选择规则、BPF、远程设备配置或 pcap 读取方式，更新 `AGENTS.md`。
+- pcap 可能包含 token、cookie、payload、内网地址、主机名或个人信息；对外分享前必须提醒用户脱敏。
+
+## 静态分析与 AirSDB 协作
+
+AirDbg 负责把静态分析线索和代码根因联系起来；AirSDB 负责 cppcheck 检测/安装、本机或远程扫描、XML/JSON 产物和 `AirPlan/docs/staticanalysis.md` 简短报告。遇到以下情况时，可以调用 AirSDB：
+
+- 需要用 cppcheck 辅助定位 C/C++ bug、内存/资源/越界/空指针/未初始化变量/危险转换/CWE 线索。
+- 需要在修复前后比较静态分析结果。
+- 需要给 AirDbg 的根因分析提供短报告而不是长 XML。
+- 检验、测试或调试判断需要静态分析能力、质量门信息或可引用文档时，需要读取 `AirPlan/docs/staticanalysis.md` 或 AirSDB XML/JSON 报告辅助分析。
+- 目标代码在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，需要 `/airsdb remote-scan` 或 `airsdb_remote_device.py` 获取远端静态分析证据。
+
+协作规则：
+
+- 本机静态分析使用 `airsdb_cppcheck.py --action scan`；远程静态分析使用 `airsdb_remote_device.py --action setup|scan`，由它探测 SSH、远端 cppcheck 并在缺失时自动尝试配置。
+- AirDbg 的 `AirPlan/docs/debug/debug-log.md` 必须记录 AirSDB 命令、`AirPlan/docs/staticanalysis.md`、XML/JSON 报告路径、关键 findings、与根因的关系、复验结果和剩余风险。
+- 如果静态分析发现新的长期质量门槛、suppressions、远程设备配置或 cppcheck 命令，更新 `AGENTS.md`。
+- 如果静态分析成为长期测试/调试边界，更新 C4 module 并创建或修订 ADR。
+
+## 调试流程
+
+1. 确认问题边界：
+   - 用户看到的错误是什么。
+   - 期望行为和实际行为是什么。
+   - 复现步骤、输入数据、环境、版本、最近变更是什么。
+   - 有哪些不能破坏的兼容性或性能要求。
+2. 加载上下文：
+   - 读取 `AGENTS.md`。
+   - 读取 ADR 列表和相关 ADR。
+   - 读取 `docs/architecture/c4/module.md`。
+   - 查看测试、入口、依赖、配置和最近相关文件。
+3. 复现问题：
+   - 优先运行已有失败测试或用户给出的命令。
+   - 没有复现命令时，先构造最小复现或定位性测试。
+   - 如果复现依赖 GUI、截图或图形操作，必须调用 AirXDB 获取截图、执行最小界面操作或保存 GUI 报告；远程目标走 AirXDB remote device helper；嵌入式截图无效时改用等效 GUI/屏幕证据并记录原因。
+   - 如果复现依赖网络路径或抓包证据，调用 AirNDB 获取短时 pcap、摘要或网络层时间线；远程目标走 AirNDB remote device helper。
+- 如果复现或定位需要 C/C++ 静态分析，或当前检验需要静态分析能力辅助判断，调用 AirSDB 运行本机或远程 cppcheck，并读取 `AirPlan/docs/staticanalysis.md`。
+   - 记录复现命令和关键输出到 `docs/debug/debug-log.md`。
+4. 定位根因：
+   - 从错误栈、日志、测试断言、数据流和模块边界推断。
+   - 对 GUI 问题，结合 AirXDB 本机或远程截图/报告判断视觉症状、交互失败和代码根因之间的关系。
+   - 对网络问题，结合 AirNDB 本机或远程 pcap/摘要判断请求是否出站、响应是否入站、失败发生在 DNS/TCP/TLS/应用层哪一段。
+   - 对静态分析问题，结合 AirSDB findings 判断哪些是当前 bug 线索、哪些是既有质量债或误报。
+   - 必要时加临时日志或小范围探针，完成后清理。
+   - 区分根因、诱因和表面症状。
+5. 修复：
+   - 优先选择影响面小、能解释根因的修复。
+   - 不做无关格式化、批量重构或架构迁移。
+   - 如果修复会改变模块边界、依赖、接口、数据所有权或关键行为，先更新 C4/ADR。
+6. 验证：
+   - 运行失败用例、相关单元测试、集成测试、lint/typecheck。
+   - 如果修复涉及 GUI 或视觉行为，必须调用 AirXDB 截图、图形对比或操作验证关键路径；远程目标用远程 helper 复验；嵌入式截图无效时改用等效 GUI/屏幕证据并记录原因。
+   - 如果修复涉及网络行为，调用 AirNDB 复验关键网络路径或读取 pcap 摘要；远程目标用远程 helper 复验。
+- 如果修复涉及 C/C++ 风险、静态分析 findings，或验证需要静态分析能力辅助判断，调用 AirSDB 复跑 cppcheck 并更新 `AirPlan/docs/staticanalysis.md`。
+   - 如果不能运行，说明原因，并给出可复验的替代验证。
+   - 记录验证证据到 debug log。
+7. 收尾：
+   - 更新 `AGENTS.md` 中与调试、测试、运行方式相关的项目上下文。
+   - 更新或新增 ADR。
+   - 更新 C4 module。
+   - 向用户汇报根因、改动、验证结果、剩余风险。
+
+## AGENTS.md 维护
+
+在以下情况更新 `AGENTS.md`：
+
+- 发现新的运行、测试、构建、调试命令。
+- 发现新的 AirXDB 截图、GUI 操作验证、图形对比、远程设备配置或视觉验收命令。
+- 发现新的 AirNDB 抓包命令、BPF 过滤器、接口选择规则、远程设备配置、pcap 读取方式或网络复验步骤。
+- 发现新的 AirSDB cppcheck 命令、suppressions、质量门槛、远程设备配置或静态分析复验步骤。
+- 发现影响后续 AI 会话的重要项目约束。
+- 修复改变了模块职责、关键流程或错误处理策略。
+- 发现常见坑、环境要求或验证方式。
+
+保持内容可执行、可复用，不写调试过程流水账。
+
+## ADR 维护
+
+目录：`docs/architecture/adr/`。
+
+需要 ADR 的情况：
+
+- 修复选择了一个会影响长期架构或行为兼容性的方案。
+- 改变错误处理、重试、事务、缓存、一致性、安全边界。
+- 改变模块依赖、数据所有权、接口契约。
+- 将 GUI 自动化、截图取证、远程设备 GUI 取证、视觉验收或图形调试流程纳入长期测试/调试边界。
+- 将抓包、远程设备抓包、pcap 分析、网络观测、端口、协议、DNS、代理、TLS 或网络拓扑纳入长期调试/测试边界。
+- 将 cppcheck、staticanalysis.md、静态分析质量门槛或远程静态分析纳入长期调试/测试边界。
+- 拒绝了明显可选方案，需要给后续 AI 留下原因。
+
+ADR 模板：
+
+```markdown
+# ADR-000X: short-title
+
+- Status: Accepted
+- Date: YYYY-MM-DD
+
+## Context
+简述错误、约束和为什么需要决策。
+
+## Decision
+简述采用的修复或架构选择。
+
+## Consequences
+- 正面影响
+- 代价或风险
+
+## Alternatives
+- 方案 A：放弃原因
+```
+
+## C4 Module 维护
+
+文件：`docs/architecture/c4/module.md`。
+
+必须记录：
+
+- 模块名。
+- 职责。
+- 对外接口。
+- 依赖。
+- 数据所有权。
+- 与本次错误或修复相关的质量属性。
+
+新增模块、拆分模块、改变依赖、改变接口、改变数据边界、改变错误处理流时必须更新。
+
+引入或改变 GUI 自动化、浏览器桥接、桌面控制、截图取证、远程设备 GUI 取证、视觉验收或图形调试基础设施时，也必须更新。
+
+引入或改变 tcpdump/WinDump 抓包、远程设备抓包、pcap 分析、网络观测、端口、协议、DNS、代理、TLS、容器/WSL/VM/宿主机网络边界时，也必须更新。
+
+引入或改变 cppcheck、staticanalysis.md、静态分析质量门槛、suppressions 或远程静态分析边界时，也必须更新。
+
+## debug-log 维护
+
+文件：`docs/debug/debug-log.md`。
+
+每次 AirDbg 修复至少追加：
+
+- 问题摘要。
+- 复现命令或复现步骤。
+- 根因。
+- 修复摘要。
+- 验证命令和结果。
+- AirXDB 本机或远程截图/报告/操作验证证据及其结论（如适用）。
+- AirNDB 本机或远程 pcap/summary/report/抓包分析证据及其结论（如适用）。
+- AirSDB 本机或远程 staticanalysis.md/XML/JSON 静态分析证据及其结论（如适用）。
+- 相关 ADR/C4 更新。
+- 剩余风险。
+
+## 输出格式
+
+调试完成后用中文简洁汇报：
+
+- 根因。
+- 修复了什么。
+- 更新了哪些 `AGENTS.md` / ADR / C4 / debug log 上下文。
+- 运行了哪些验证；是否调用 AirXDB/AirNDB/AirSDB，截图、pcap、staticanalysis、报告或操作证据在哪里。
+- 仍然存在的风险或未验证项。

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdbg/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: airdbg
+short_description: Debug-first repair with local/remote AirXDB, AirNDB, and AirSDB evidence
+default_prompt: "使用 AirDbg 调试并修复当前项目错误；GUI 测试或验证必须保留 GUI 复验证据，嵌入式截图无效时改用等效屏幕证据；网络证据调用 AirNDB，需要静态分析能力时调用 AirSDB。"

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdo/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: airdo
+description: Public Air executor for one scoped todo slice. Use it standalone or as an isolated AirEng subagent and finalize the result into AirPlan.
+---
+
+# AirDo
+
+## Role
+
+- Execute one task or one very small implementation slice.
+- Keep AirDo execution guarantees for context loading, evidence, and validation.
+- Finalize one structured result package in `AirPlan/state/airdo/results/`.
+- Act as the standard AirEng child executor when work is delegated into isolated subagents.
+
+## Inputs
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/plan.md`
+- `AirPlan/todo.md`
+- `AirPlan/state/airdo/tasks/<task-id>/brief.md`
+- `AirPlan/state/airdo/tasks/<task-id>/subagent-handoff.md` when launched by AirEng
+
+## Result Rules
+
+- Finalize one `result.json` per task.
+- Treat `AirPlan/state/airdo/tasks/<task-id>/worker-state.json` `resultPath` as the canonical pointer to the latest result artifact. The task-local `result.json` is only the editable template before finalize.
+- Include validations, evidence, risks, blockers, and document updates when needed.
+- Do not edit global `AirPlan/todo.md`, `AirPlan/AGENTS.md`, ADR, or C4 files directly unless explicitly delegated through `documentUpdates`.
+- If the task changes execution planning or architecture reality, include concrete `documentUpdates` so AirEng can keep `todo`, `plan`, ADR, and C4 synchronized during merge.
+
+## Automatic Routing
+
+- On `blocked` results, auto-request AirDbg before finalize.
+- On GUI or visual work, auto-request AirXDB before finalize.
+- If AirEng queued an active repair attempt, continue repairing automatically instead of stopping at the first blocker.
+- Do not stop at implementation-prep or progress-only updates when the task is actionable. Continue until finalize unless a real blocker or explicit user decision is required.

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airdo/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: airdo
+short_description: Public Air executor for one scoped task, validation evidence, and AirPlan result finalization
+default_prompt: "Use AirDo to execute one task, gather validation evidence, auto-route GUI or debug work, and finalize a structured result in AirPlan for AirEng to merge."

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/aireng/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: aireng
+description: Sole public Air scheduler that reads AirArc execution artifacts, dispatches isolated AirDo subagents with bounded concurrency, monitors them on a 5-minute cadence, and merges structured results into AirPlan.
+---
+
+# AirEng
+
+## Role
+
+- Own the global execution contract in `AirPlan/`.
+- Read AirArc review output before falling back to local todo analysis.
+- Dispatch isolated AirDo subagents with `fork_context=false`.
+- Monitor active workers, merge structured worker results, and keep the scheduler moving unattended.
+- Own debug policy, XDB policy, repair policy, intervention policy, and global document convergence.
+- Default to no parent-thread coding; use parent-thread edits only for short unblock actions that restore the scheduler.
+
+## Planning Source Order
+
+1. `AirPlan/state/airarc/reviews/execution-plan.json`
+2. `AirPlan/state/airarc/reviews/parallel-review.json`
+3. Engine fallback analysis of `AirPlan/todo.md`
+
+## Dispatch Contract
+
+- Generate the dispatch manifest under `AirPlan/state/aireng/dispatch/`.
+- Respect `recommendedConcurrency`; do not flood the workspace with overlapping workers.
+- Spawn one isolated AirDo subagent per task handoff.
+- After a worker finishes, read its `workerStatePath` and use the `resultPath` recorded there as the canonical finalized result location.
+- Pass only the task handoff and project path to each worker. Do not fork the full parent thread history.
+- Do not interrupt actionable workers for midpoint status updates; let them continue through implementation and finalize unless they surface a real blocker.
+- Keep parent-thread work limited to orchestration, monitoring, merge, repair, document convergence, and minimal unblock actions.
+- Refresh `AirPlan/todo.md` and the active dispatch block in `AirPlan/plan.md` when a wave starts so execution progress is visible during the run.
+
+## Monitoring Contract
+
+- Store scheduler state in `AirPlan/state/aireng/state.json`.
+- Track `engineMode`, `activeWaveId`, `activeDispatchPath`, `activeWorkers`, `monitoringPolicy`, `nextAction`, and `interventionHistory`.
+- Use `monitoringPolicy.checkIntervalSeconds = 300` as the default cadence for unattended monitoring.
+- Prefer re-dispatch, repair, debug, or other isolated recovery flows before direct intervention.
+- Escalate to user decision only when a worker remains hard-blocked after the allowed intervention budget.
+
+## Merge Guarantees
+
+- Update task status and merge log in `AirPlan/todo.md`.
+- Apply worker `documentUpdates`.
+- Refresh engine-managed sync blocks in `AirPlan/AGENTS.md` and `AirPlan/docs/architecture/c4/module.md`.
+- Track AirXDB sessions in `AirPlan/state/aireng/state.json`.
+- Track debug sessions in `AirPlan/state/aireng/state.json`.
+- Track repair attempts in `AirPlan/state/aireng/state.json`.
+- Refuse a `done` merge when required global document updates are missing.
+- Refuse a GUI-like `done` merge when successful AirXDB evidence is missing.
+- Apply worker `documentUpdates` promptly so plan, ADR, and C4 changes do not lag behind completed slices.
+
+## Commands
+
+```bash
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode enter --project <project-root>
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode status --project <project-root>
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode plan --project <project-root> --todo <airplan-todo-md>
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode dispatch --project <project-root> [--dispatch-group <wave-group-name>]
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode monitor --project <project-root>
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode run --project <project-root> [--todo <airplan-todo-md>]
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode intervene --project <project-root>
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode merge --project <project-root> --result <worker-result-json>
+```

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/aireng/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: aireng
+short_description: Public Air scheduler for isolated AirDo subagent dispatch and AirPlan merges
+default_prompt: "Use AirEng to read AirArc execution artifacts from AirPlan, dispatch isolated AirDo subagents with bounded concurrency, and merge structured worker results back into AirPlan."

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airndb/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: airndb
+description: Network-debug packet capture workflow. Use when the user invokes /airndb or asks to debug networking, packet loss, DNS, TCP, UDP, TLS handshakes, HTTP connectivity, ports, retransmits, resets, latency, firewall, proxy, service reachability, pcap files, tcpdump, WinDump, remote packet capture over SSH, or BPF filters. Load or initialize AirPlan/AGENTS.md, AirPlan/docs/architecture/adr/ decision records, AirPlan/docs/architecture/c4/module.md, AirPlan/docs/network/airndb-log.md, and AirPlan/docs/network/airndb-captures/; on first startup detect tcpdump/WinDump and on Windows auto-download official WinDump.exe when no capture tool is available; when remote debugging, call the AirNDB remote device helper and auto-configure remote tcpdump/dumpcap when missing; build safe bounded tcpdump/WinDump commands; capture or read pcap artifacts; summarize packet evidence; and maintain AirPlan/AGENTS.md, ADR, C4 module docs, and network debug logs when capture tooling, network boundaries, or debugging decisions change.
+---
+
+# AirNDB
+
+## 核心约束
+
+- 全程使用中文与用户交流，命令、接口名、BPF、日志、路径和协议名保持原文。
+- `/airndb` 专用于网络抓包、pcap 分析和网络层调试证据收集。
+- 只抓取用户授权的本机、项目、测试环境或明确允许的网络流量。
+- 默认不做无界抓包；必须使用包数、超时、时长或轮转上限。
+- 默认先列接口，再确认接口、目标 host/port/protocol/filter、抓包窗口和输出路径。
+- 初次启动必须检测 `tcpdump` / `windump` / `WinDump.exe` 是否可用；Windows 下如果不可用，自动从 WinDump 官方下载页获取 `WinDump.exe`，校验 SHA1 后写入 `AirPlan/state/airndb/tool.env`。
+- 远程设备、测试机、VM 或 SSH 主机上的网络调试，先调用 `$HOME/plugins/airndb/scripts/airndb_remote_device.py`；缺少远程 `tcpdump` / `dumpcap` 时允许脚本自动配置，无法无密码 `sudo` 或无包管理器时停止并提示用户。
+- 自动获取只下载 WinDump 用户态程序，不静默安装 WinPcap/Npcap 抓包驱动；如果接口列举失败，提示用户安装 Npcap 或 WinPcap 并用管理员权限重试。
+- 默认使用 `-nn` 避免 DNS/service-name 解析，使用 `-s 0` 写入完整 pcap。
+- pcap 可能包含凭据、cookie、token、payload、内网地址、主机名或个人信息；对外分享前必须提醒脱敏。
+- 网络证据要写入 `AirPlan/docs/network/airndb-log.md`，pcap/摘要/JSON 报告写入 `AirPlan/docs/network/airndb-captures/`。
+- 根据项目变化维护 `AirPlan/AGENTS.md`、ADR 和 C4 module。
+- 如果需要 WinDump/tcpdump 选项和 BPF 简表，读取 [references/windump-tcpdump-notes.md](references/windump-tcpdump-notes.md)。
+
+## 启动与初始化
+
+进入 `/airndb` 时运行：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_mode.py" --mode enter --project .
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。脚本不可用时，手动确保以下结构存在：
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/docs/network/airndb-log.md`
+- `AirPlan/docs/network/airndb-captures/`
+- `AirPlan/state/airndb/state.json`
+
+初始化后读取已有内容作为上下文。不要覆盖用户已有正文；只补齐缺失结构或更新 AirNDB 标记块。
+
+## 首次工具配置
+
+`airndb_mode.py --mode enter` 会执行工具自检：
+
+1. 查找显式配置、项目 `AirPlan/state/airndb/tool.env`、环境变量 `AIRNDB_TCPDUMP`、项目 `AirPlan/state/airndb/tools/WinDump.exe`、PATH 中的 `windump` / `WinDump.exe` / `tcpdump`。
+2. 如果找到可用工具，写入或刷新 `AirPlan/state/airndb/tool.env`，后续 `airndb_capture.py` 自动读取。
+3. 如果 Windows 上找不到工具，自动从 WinDump 官方下载地址获取 `WinDump.exe`，校验 SHA1 `d59bc54721951dec855cbb4bbc000f9a71ea4d95`，保存到 `AirPlan/state/airndb/tools/WinDump.exe`，然后写入 `AirPlan/state/airndb/tool.env`。
+4. 如果下载失败或校验失败，停止并提示用户手动安装 `tcpdump` / `WinDump.exe` 或设置 `AIRNDB_TCPDUMP`。
+
+`AirPlan/state/airndb/tool.env` 是本机路径配置，由 `AirPlan/state/airndb/.gitignore` 忽略，不应提交。
+
+注意：WinDump 仍需要抓包驱动。官方 WinDump 安装页要求先安装 WinPcap 3.1 或更新版本；WinPcap 主页提示项目已停止维护并建议 Windows 10 用户使用 Npcap。AirNDB 不静默安装驱动，只负责检测、下载 WinDump.exe 和配置本机路径。
+
+## 远程设备工具配置
+
+当用户说明目标流量发生在远程设备、测试机、服务器、VM、容器宿主机、SSH 主机，或本机抓包看不到目标流量时，不要先使用本机 `airndb_capture.py`。先运行远程设备 helper：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action setup
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。首次运行会生成 `AirPlan/state/airndb/remote-device.env.example`；把连接信息写入 `AirPlan/state/airndb/remote-device.env` 或当前环境变量：
+
+- `AIRNDB_REMOTE_SSH_TARGET=user@host`
+- `AIRNDB_REMOTE_SSH_PORT=22`
+- `AIRNDB_REMOTE_SSH_OPTIONS=`
+- `AIRNDB_REMOTE_WORKDIR=`
+- `AIRNDB_REMOTE_TCPDUMP=auto`
+- `AIRNDB_REMOTE_CAPTURE_PREFIX=sudo -n`
+
+远程 helper 行为：
+
+- 检查本机 `ssh`、远程连通性和远程工作目录。
+- 探测 `tcpdump`、`dumpcap`、`windump`、`WinDump.exe`。
+- 工具缺失时自动尝试用远端包管理器安装 `tcpdump`，只使用非交互式 `sudo -n`；需要密码、管理员确认或无支持的包管理器时停止并提示用户。
+- 将可复用配置写入 `AirPlan/state/airndb/remote-device.env`，该文件由 `AirPlan/state/airndb/.gitignore` 忽略。
+- 抓包产物拉回 `AirPlan/docs/network/airndb-captures/`，并追加 `AirPlan/docs/network/airndb-log.md`。
+
+常用远程命令：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action interfaces
+python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action command --iface <iface> --filter "<bpf>" --count 200
+python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action capture --iface <iface> --filter "<bpf>" --count 200 --timeout 30
+```
+
+远程抓包仍必须有明确授权、接口、BPF、包数或超时上限。`AIRNDB_REMOTE_CAPTURE_PREFIX` 默认是 `sudo -n`；如果远端已配置免 sudo 的 capture capability，可改为空或指定更合适的前缀。
+
+## 工作流
+
+1. 明确网络问题：
+   - 现象：连不上、超时、重置、DNS 异常、TLS 握手失败、丢包、延迟、端口不可达、代理/防火墙疑似问题。
+   - 目标：源/目的 host、端口、协议、服务名、容器/VM/WSL/宿主机边界。
+   - 抓包窗口：包数、超时、复现步骤和是否允许保存 payload。
+2. 发现接口：
+   - 本机调试运行 `airndb_capture.py --action interfaces`。
+   - 远程调试运行 `airndb_remote_device.py --action interfaces`。
+   - Windows 优先使用 `windump -D` 或 `WinDump.exe -D`；Linux/macOS 优先 `tcpdump -D`。
+3. 设计过滤器：
+   - 使用最窄可行 BPF：`host`、`src host`、`dst host`、`port`、`tcp`、`udp`、`icmp`、`net`。
+   - 不确定时先短时宽过滤，再根据结果收窄。
+4. 执行有界抓包：
+   - 使用 `airndb_capture.py --action capture --iface <iface> --filter "<bpf>" --count <n> --timeout <seconds>`。
+   - 产物写入 `AirPlan/docs/network/airndb-captures/`。
+5. 读取和分析：
+   - 使用 `airndb_capture.py --action read --read-file <pcap> --filter "<bpf>"` 生成文本摘要。
+   - 结合时间线、TCP flags、重传、RST、DNS 响应、ICMP、TLS ClientHello/ServerHello 迹象判断网络层事实。
+6. 记录证据：
+   - exact command
+   - interface
+   - BPF filter
+   - packet count or timeout
+   - pcap path
+   - summary/report path
+   - 观察结论、限制和剩余风险
+
+## 与 AirDbg 协作
+
+- AirNDB 负责抓包、pcap 摘要、网络层证据和过滤器。
+- AirDbg 负责代码层根因分析、修复和验证收尾。
+- AirDbg 调试中遇到 DNS、TCP、UDP、TLS、HTTP 连接、端口、代理、防火墙、丢包、重传或 pcap 证据需求时，可以调用 AirNDB。
+- AirNDB 收集到的证据必须能被 AirDbg 直接引用：命令、pcap 路径、摘要、关键包、时间线和结论要写清楚。
+
+## 常用命令
+
+列接口：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action interfaces
+```
+
+检查或初始化工具路径：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_mode.py" --project . --mode enter
+```
+
+只生成命令：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action command --iface 1 --filter "tcp and port 443" --count 200
+```
+
+短时抓包：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action capture --iface 1 --filter "tcp and port 443" --count 200 --timeout 30
+```
+
+读取 pcap：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_capture.py" --project . --action read --read-file AirPlan/docs/network/airndb-captures/example.pcap
+```
+
+## AGENTS.md 维护
+
+在以下情况更新 `AGENTS.md`：
+
+- 发现稳定可复用的 tcpdump/WinDump 命令、接口选择规则、BPF 过滤器或 pcap 读取方式。
+- 发现影响后续 AI 调试的网络边界：容器、WSL、VM、代理、防火墙、VPN、DNS、TLS、NAT、端口映射。
+- 发现抓包权限、驱动、管理员权限或平台差异。
+- 发现本机 tcpdump/WinDump 路径或 `AirPlan/state/airndb/tool.env` 配置方式。
+- 发现远程设备 SSH 入口、远程抓包工具、`AIRNDB_REMOTE_*` 配置方式或远端抓包权限限制。
+
+## ADR 维护
+
+目录：`docs/architecture/adr/`。
+
+需要 ADR 的情况：
+
+- 长期采用 tcpdump/WinDump 作为项目网络诊断方式。
+- 抓包流程改变了测试边界、网络观测边界、运行权限、数据留存或安全策略。
+- 发现需要保留的网络架构决策，例如代理、DNS、TLS、端口、服务发现或跨容器/宿主机边界。
+
+ADR 保持简洁：Context、Decision、Consequences、Alternatives。
+
+## C4 Module 维护
+
+文件：`docs/architecture/c4/module.md`。
+
+当网络调试发现或改变以下内容时，必须更新：
+
+- 模块间网络依赖。
+- 服务端口、协议、DNS、代理、TLS、队列、网关、容器/宿主机/WSL/VM 边界。
+- 抓包或观测基础设施成为长期模块或运行边界。
+- 网络错误处理、重试、超时、连接池或安全边界。
+
+## network log 维护
+
+文件：`AirPlan/docs/network/airndb-log.md`。
+
+每次 AirNDB 会话至少追加：
+
+- 问题摘要。
+- 授权范围和目标流量。
+- 接口、BPF、抓包窗口。
+- 是否使用远程设备 helper 以及远程目标、抓包工具和权限限制。
+- pcap/summary/report 路径。
+- 关键包或时间线观察。
+- 结论、限制和给 AirDbg 的线索。
+- ADR/C4/AGENTS 更新。
+
+## 完成输出
+
+本轮网络调试结束时，用中文简洁汇报：
+
+- 使用了哪个接口和过滤器。
+- 抓包是否成功，证据在哪里。
+- 关键观察和网络层结论。
+- 更新了哪些 `AGENTS.md` / ADR / C4 / network log。
+- 是否需要切给 AirDbg 做代码层修复。

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airndb/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: airndb
+short_description: Local and remote packet capture workflow with tcpdump and WinDump
+default_prompt: "使用 AirNDB 做安全有界抓包；远程设备优先调用 remote device helper 并自动配置 tcpdump。"

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airndb/references/windump-tcpdump-notes.md

@@ -0,0 +1,83 @@
+# WinDump / Tcpdump Notes
+
+Source: https://www.winpcap.org/windump/docs/manual.htm
+
+## AirNDB Summary
+
+- WinDump follows tcpdump-style packet capture usage on Windows.
+- `-D` lists available capture interfaces.
+- `-i <interface>` selects the capture interface. On Windows this is often the interface number from `-D`.
+- `-c <count>` stops after a bounded number of packets.
+- `-w <file>` writes raw packets to a pcap file.
+- `-r <file>` reads packets back from a pcap file.
+- `-n` avoids host name resolution; `-nn` also avoids service name resolution.
+- `-s <snaplen>` controls packet snapshot length. AirNDB uses `-s 0` for pcap captures so packets are not truncated.
+- Filter expressions use BPF primitives such as `host`, `net`, `port`, `src`, `dst`, `tcp`, `udp`, `icmp`, `arp`, `and`, `or`, and `not`.
+
+## Windows Notes
+
+- Prefer `WinDump.exe` or `windump` when `tcpdump` is unavailable on Windows.
+- WinDump normally requires a packet capture driver such as WinPcap/Npcap and may require an elevated terminal.
+- Interface names can be long adapter paths; the numeric index from `windump -D` is usually easier to use.
+- Store pcap artifacts in a project-local ignored directory such as `docs/network/airndb-captures/`.
+
+## AirNDB Auto Setup
+
+- On `/airndb enter`, AirNDB checks for `tcpdump`, `windump`, or `WinDump.exe`.
+- If no capture tool is available on Windows, AirNDB downloads the official `WinDump.exe` linked from the WinDump install page:
+
+```text
+https://www.winpcap.org/windump/install/bin/windump_3_9_5/WinDump.exe
+```
+
+- AirNDB verifies SHA1 before using the file:
+
+```text
+d59bc54721951dec855cbb4bbc000f9a71ea4d95
+```
+
+- AirNDB stores the binary at `AirPlan/state/airndb/tools/WinDump.exe` and writes `AirPlan/state/airndb/tool.env`:
+
+```text
+AIRNDB_TCPDUMP=<absolute path to WinDump.exe>
+```
+
+- AirNDB does not silently install WinPcap/Npcap drivers. If `WinDump.exe -D` fails after download, tell the user to install Npcap or WinPcap and retry from an elevated terminal.
+
+## Safe Defaults
+
+- Start with interface discovery before capture:
+
+```bash
+windump -D
+tcpdump -D
+```
+
+- Prefer short, bounded capture:
+
+```bash
+tcpdump -i <iface> -nn -s 0 -w <file>.pcap -c 200 '<bpf>'
+```
+
+- Read back a pcap summary:
+
+```bash
+tcpdump -nn -r <file>.pcap '<bpf>'
+```
+
+## BPF Examples
+
+```text
+host 192.0.2.10
+tcp and port 443
+udp and port 53
+src host 192.0.2.10 and dst port 443
+net 10.0.0.0/8 and not port 22
+icmp or icmp6
+```
+
+## Evidence Rules
+
+- Record exact command, interface, filter, packet count, capture window, pcap path, and summary path.
+- Keep pcap files private unless reviewed; they can contain tokens, cookies, payload, internal hostnames, and addresses.
+- If application payload is encrypted, use packet timing, DNS, TCP/TLS handshakes, retransmissions, resets, or connection failures as evidence instead of expecting plaintext.

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airsdb/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: airsdb
+description: Cppcheck static-analysis workflow for C/C++ projects. Use when the user invokes /airsdb, asks to run static analysis, evaluate code quality or security with cppcheck, generate a short AI-context static-analysis report for AirDbg or AirDo, diagnose issues that need static analysis, maintain AirPlan/docs/staticanalysis.md, or run local/remote cppcheck over SSH. On first startup detect cppcheck and auto-install or auto-configure it when missing; default local and remote scans to `--check-level=exhaustive` for maximum branch-analysis detail; and call the AirSDB remote device helper when remote cppcheck is needed.
+---
+
+# AirSDB
+
+## 核心约束
+
+- 全程使用中文与用户交流，命令、路径、工具名、告警 id、CWE 保持原文。
+- `/airsdb` 专用于 C/C++ 静态分析、代码质量/安全性初筛、cppcheck 证据收集，以及给 AirDbg/AirDo 提供简短 AI 上下文报告。
+- 第一次进入必须检测 `cppcheck`。本机缺失时自动尝试用包管理器安装或配置；无法自动安装时停止并提示官方下载页或 `AIRSDB_CPPCHECK`。
+- 必须创建或维护 `AirPlan/docs/staticanalysis.md`。它只写简短摘要，详细 XML/JSON 产物放在 `AirPlan/state/airsdb/reports/`。
+- 本机分析使用 `$HOME/plugins/airsdb/scripts/airsdb_cppcheck.py`。
+- 远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上的静态分析，先使用 `$HOME/plugins/airsdb/scripts/airsdb_remote_device.py`；远端缺少 `cppcheck` 时允许脚本自动配置，无法无密码 `sudo` 或无包管理器时停止并提示用户。
+- 优先使用 `compile_commands.json`；没有时只扫描最窄可行目录，并排除 `.git`、`AirPlan/state/airsdb`、`build`、`node_modules`、`vendor`、`third_party` 等常见噪声目录。
+- 默认使用 `--check-level=exhaustive`，尽可能提供详细分支分析信息，避免出现 `normalCheckLevelMaxBranches` 这类因分支分析深度受限造成的信息缺口；只有用户明确要求降级时才改。
+- Cppcheck 是静态分析，不等同于编译、测试或安全审计；结论要写成“证据/线索”，不要夸大。
+- 如果需要 cppcheck 安装和命令细节，读取 [references/cppcheck-notes.md](references/cppcheck-notes.md)。
+
+## 启动与环境检测
+
+进入 `/airsdb` 时运行：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_mode.py" --mode enter --project .
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。
+
+脚本会：
+
+- 初始化 `AirPlan/state/airsdb/`、`AirPlan/state/airsdb/tool.env.example`、`AirPlan/state/airsdb/.gitignore`。
+- 创建或维护 `AirPlan/docs/staticanalysis.md`。
+- 在 `AirPlan/AGENTS.md` 中维护 AirSDB 标记块。
+- 检测 `AIRSDB_CPPCHECK`、`AirPlan/state/airsdb/tool.env`、PATH 和常见 Windows 安装路径。
+- 找不到 `cppcheck` 时自动尝试安装：
+  - Windows：`winget`、`choco`、`scoop`
+  - Linux/macOS：`apt-get`、`dnf`、`yum`、`apk`、`pacman`、`brew`、`port`
+
+`AirPlan/state/airsdb/tool.env` 是本机路径配置，由 `AirPlan/state/airsdb/.gitignore` 忽略，不应提交。
+
+## 本机分析
+
+检查或安装 cppcheck：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_cppcheck.py" --project . --action setup
+```
+
+只生成命令：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_cppcheck.py" --project . --action command
+```
+
+执行扫描：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_cppcheck.py" --project . --action scan --timeout 900
+```
+
+常用参数：
+
+- `--project-file build/compile_commands.json`：指定编译数据库。
+- `--target src`：没有编译数据库时限制扫描目录。
+- `--enable warning,style,performance,portability,information`：默认检查集合。
+- `--check-level exhaustive`：默认详细分支分析级别。
+- `--std c++17`：指定 C/C++ 标准。
+- `--extra "--suppress=missingIncludeSystem"`：追加 cppcheck 参数。
+
+扫描后必须确认：
+
+- `AirPlan/state/airsdb/reports/<timestamp>-cppcheck.xml`
+- `AirPlan/state/airsdb/reports/<timestamp>-cppcheck.json`
+- `AirPlan/docs/staticanalysis.md` 已追加简短报告
+
+## 远程设备分析
+
+当目标代码或复现场景在远程设备上时，不要先跑本机 cppcheck。先运行：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action setup
+```
+
+首次运行会生成 `AirPlan/state/airsdb/remote-device.env.example`。将连接信息写入 `AirPlan/state/airsdb/remote-device.env` 或当前环境变量：
+
+- `AIRSDB_REMOTE_SSH_TARGET=user@host`
+- `AIRSDB_REMOTE_SSH_PORT=22`
+- `AIRSDB_REMOTE_SSH_OPTIONS=`
+- `AIRSDB_REMOTE_WORKDIR=`
+- `AIRSDB_REMOTE_PROJECT=/path/to/remote/project`
+- `AIRSDB_REMOTE_CPPCHECK=auto`
+
+远程 helper 行为：
+
+- 检查本机 `ssh`、远程连通性、远程工作目录。
+- 探测远端 `cppcheck`。
+- 缺失时自动尝试用远端包管理器安装 `cppcheck`，只使用非交互式 `sudo -n`；需要密码、管理员确认或无支持包管理器时停止并提示用户。
+- 在远端项目目录运行 cppcheck，把 XML 拉回本机 `AirPlan/state/airsdb/reports/` 并更新本机 `AirPlan/docs/staticanalysis.md`。
+
+远程命令：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action command
+python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action scan --timeout 900
+```
+
+## 与 AirDbg 协作
+
+AirDbg 调试中遇到以下情况时调用 AirSDB：
+
+- 需要用静态分析辅助定位崩溃、内存错误、未初始化变量、空指针、越界、危险转换、资源释放或 CWE 线索。
+- 需要在修复前后比较 cppcheck 结果。
+- 需要给根因分析提供短报告，而不是完整 XML 噪声。
+
+AirSDB 给 AirDbg 的交接必须写入 `AirPlan/docs/staticanalysis.md`：
+
+- 命令和目标
+- XML/JSON 报告路径
+- severity/id/CWE 计数
+- Top findings
+- 哪些 findings 与当前 bug 相关
+- 剩余风险
+
+## 与 AirDo 协作
+
+AirDo 执行 `AirPlan/todo.md` 时可以调用 AirSDB 做验收或排障：
+
+- todo 要求静态分析、质量检查、安全性初筛或 C/C++ 代码风险评估。
+- 验证失败但需要 cppcheck 辅助定位。
+- 远程设备上的实现需要远端 cppcheck 证据。
+
+AirDo 仍然拥有 `AirPlan/todo.md` 进度。调用 AirSDB 后，把命令、报告路径、结论和剩余风险写回当前 todo 项。
+
+## staticanalysis.md 维护
+
+每次 AirSDB 扫描至少追加：
+
+- Target：local 或 remote target
+- Tool：cppcheck 路径和版本
+- Command：实际命令
+- Result：ok / findings / failed
+- Counts：各 severity 数量
+- Reports：XML/JSON 路径
+- Top findings：最多 12 条，含 severity、id、CWE、文件行号、摘要
+- AirDbg/AirDo handoff：当前任务如何使用这些结果
+- Residual risk：静态分析未覆盖的风险
+
+不要把完整 XML、长日志或大段 cppcheck 输出塞进 `staticanalysis.md`。
+
+## AGENTS / ADR / C4
+
+- 发现稳定可复用的 AirSDB 命令、远程设备配置、过滤策略、suppressions 或质量门槛时，更新 `AGENTS.md`。
+- 如果静态分析成为长期测试/调试边界，或影响模块边界、质量策略、安全策略、CI 策略，更新 C4 module 并新增或修订 ADR。
+- 如果只是一次临时扫描，只维护 `staticanalysis.md` 即可。
+
+## 完成输出
+
+本轮结束时用中文简洁汇报：
+
+- 使用本机还是远程 cppcheck。
+- cppcheck 是否可用，是否发生自动配置。
+- 报告路径和 `staticanalysis.md` 是否更新。
+- 发现数量和最重要的 3-5 条线索。
+- 是否建议交给 AirDbg 修复，或交给 AirDo 写回 todo 验收。

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airsdb/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: airsdb
+short_description: Cppcheck static analysis with exhaustive local/remote reports
+default_prompt: "使用 AirSDB 运行本机或远程 cppcheck 静态分析，默认启用 --check-level=exhaustive，生成简短 staticanalysis.md 报告并交给 AirDbg/AirDo 使用。"

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airsdb/references/cppcheck-notes.md

@@ -0,0 +1,27 @@
+# Cppcheck Notes
+
+Use this only when AirSDB needs cppcheck install or command details.
+
+## Sources
+
+- Official open-source download page: https://cppcheck.sourceforge.io/
+- Official repository package notes: https://github.com/danmar/cppcheck
+- Official manual: https://cppcheck.sourceforge.io/manual.html
+- User-provided Chinese guide: https://www.zeeklog.com/cppcheckzhong-ji-zhi-nan-cong-ling-kai-shi-zhang-wo-c-c-jing-tai-dai-ma-fen-xi
+- User-provided download reference: http://cppcheck.net/#download
+
+## Install Notes
+
+- The official page lists current open-source releases and package-manager examples.
+- Windows official installer is linked from the Cppcheck open-source page.
+- Package managers can be convenient but may lag behind official releases.
+- AirSDB auto-configures with package managers first because it must be non-interactive for agent workflows.
+
+## Command Notes
+
+- Prefer `cppcheck --project=compile_commands.json` when the project has a compilation database.
+- Generate a CMake compilation database with `cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .` when appropriate.
+- Use `--xml --xml-version=2` for machine-readable reports.
+- Use `--cppcheck-build-dir=<path>` for incremental analysis and better whole-program analysis.
+- Use `-i<path>` to skip generated/vendor directories.
+- Use suppressions instead of deleting warnings when a finding is a known false positive.

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: airxdb
+description: Midscene-based GUI debugging workflow. Use when the user invokes /airxdb, asks to debug browser UI, desktop UI, canvas UI, visual regressions, flaky interface interactions, remote GUI/device debugging over SSH, or reproduce graphical issues with Midscene.js. Load or initialize AirPlan/AGENTS.md, AirPlan/docs/architecture/adr/ decision records, and AirPlan/docs/architecture/c4/module.md; collaborate with AirDbg for GUI issues; choose the right Midscene mode for Playwright, Chrome bridge mode, desktop computer automation, MCP, or the AirXDB remote device helper; auto-configure remote screenshot tooling when missing; generate visual reproduction steps and reports; and maintain AirPlan/AGENTS.md, ADR, C4 module, and GUI debug logs whenever GUI-debug tooling or interface behavior changes.
+---
+
+# AirXDB
+
+## 核心约束
+
+- 全程使用中文与用户交流，代码、命令、日志、路径、包名保持原文。
+- `/airxdb` 专用于图形界面和视觉交互层面的调试，不替代 `airdbg` 的通用根因分析职责。
+- 优先与 `airdbg` 配合：
+  - `airxdb` 负责界面复现、视觉定位、交互自动化、Midscene 报告与截图证据。
+  - `airdbg` 负责代码层根因、最小修复、测试验证和通用调试收尾。
+- 先加载或初始化上下文：`AirPlan/AGENTS.md`、`AirPlan/docs/architecture/adr/`、`AirPlan/docs/architecture/c4/module.md`、`AirPlan/docs/debug/gui-debug-log.md`。
+- 如果这些文件不存在，先分析当前项目并初始化它们；C4 module 要反映真实模块边界，尤其是前端、UI、桌面桥接、自动化测试相关边界。
+- Midscene 路线优先使用视觉复现和 HTML 报告收集证据，不把 GUI 调试退化成纯日志猜测。
+- 截图取证是 AirXDB 的一等能力：即使没有语义模型配置，也可以连接 Computer MCP 截图，为 `airdbg` 提供错误现场、布局状态、弹窗、焦点和多显示器信息。
+- 远程设备、测试机、VM 或 SSH 主机上的 GUI 调试，先调用 `$HOME/plugins/airxdb/scripts/airxdb_remote_device.py`；缺少远程截图工具时允许脚本自动配置，无法无密码 `sudo` 或无包管理器时停止并提示用户。
+- 优先做最小可验证复现和最小必要修复，不顺手大改界面架构。
+- GUI 调试过程中，一定要维护 `AirPlan/AGENTS.md`、ADR、C4 module 和 `AirPlan/docs/debug/gui-debug-log.md`。
+- 如果需要 Midscene 包名、桥接/MCP 配置、常用命令，读取 [references/midscene-official-notes.md](references/midscene-official-notes.md)。
+
+## 启动与初始化
+
+进入 `/airxdb` 时运行：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_mode.py" --mode enter --project .
+```
+
+如果当前环境没有 `python`，尝试 `py` 或 `python3`。脚本不可用时，手动确保以下结构存在：
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/docs/debug/gui-debug-log.md`
+- `AirPlan/state/airxdb/state.json`
+
+初始化后读取已有内容作为上下文。不要覆盖用户已有正文；只补齐缺失结构或更新 AirXDB 标记块。
+
+## 首次模型配置
+
+AirXDB 第一次进入项目时必须检查 Midscene 模型配置。`airxdb_mode.py` 会输出 `midscene_config`，如果出现 `midscene_config_required=true` 或 `midscene_config=missing:...`：
+
+- 暂停执行 `act`、`Tap`、`Input`、`KeyboardPress`、视觉定位等语义动作。
+- 用中文向用户索取配置：
+  - `MIDSCENE_MODEL_NAME`
+  - `MIDSCENE_MODEL_BASE_URL`
+  - `MIDSCENE_MODEL_API_KEY`
+  - `MIDSCENE_MODEL_FAMILY`
+  - 可选：`MCP_SERVER_REQUEST_TIMEOUT`
+- 告知用户可以只在当前会话设置环境变量，或写入 `AirPlan/state/airxdb/midscene.local.env` 方便后续复用。
+- `AirPlan/state/airxdb/midscene.local.env` 只保存本机密钥，默认由 `AirPlan/state/airxdb/.gitignore` 忽略；不要把真实 API key 写入 `AirPlan/AGENTS.md`、ADR、C4 或 debug log。
+- 如果用户暂时不提供模型配置，仍然可以做截图、MCP 连接、显示器枚举、环境探测等非语义取证操作；不能声称完成了 Midscene 视觉语义操作。
+- `MIDSCENE_MODEL_FAMILY` 是语义视觉动作必填项。`gpt-5.4` 这类 GPT-5.x 视觉模型使用 `gpt-5`。
+- 常见合法 family：`gpt-5`、`qwen2.5-vl`、`qwen3-vl`、`gemini`、`doubao-seed`、`vlm-ui-tars`。
+
+## 截图取证模式
+
+当用户需要给 `airdbg` 提供错误诊断信息、GUI 现场、弹窗、焦点状态、布局错位或多显示器证据时，优先使用截图取证模式：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_computer_mcp_smoke.py" --project . --action screenshot
+```
+
+截图取证模式不要求 `MIDSCENE_MODEL_NAME`、`MIDSCENE_MODEL_BASE_URL`、`MIDSCENE_MODEL_API_KEY` 或 `MIDSCENE_MODEL_FAMILY`。它只验证 Computer MCP 桌面连接和截图能力，并将截图/JSON 报告写入 `AirPlan/docs/debug/airxdb-artifacts/`。
+
+截图后必须在 `AirPlan/docs/debug/gui-debug-log.md` 追加：
+
+- 截图目标和平台
+- 截图文件路径
+- 当前界面关键观察
+- 给 `airdbg` 的诊断线索
+- 是否还需要语义视觉动作或代码层修复
+
+如果截图可能包含密钥、聊天内容、账号、客户数据或隐私信息，在对外分享前提醒用户脱敏。
+
+## 远程设备截图模式
+
+当用户说明目标在远程设备、测试机、服务器、VM、SSH 主机，或当前桌面不是目标 GUI 所在机器时，不要先使用本机 Computer MCP。先运行远程设备 helper：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_remote_device.py" --project . --action setup
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。首次运行会生成 `AirPlan/state/airxdb/remote-device.env.example`；把连接信息写入 `AirPlan/state/airxdb/remote-device.env` 或当前环境变量：
+
+- `AIRXDB_REMOTE_SSH_TARGET=user@host`
+- `AIRXDB_REMOTE_SSH_PORT=22`
+- `AIRXDB_REMOTE_SSH_OPTIONS=`
+- `AIRXDB_REMOTE_WORKDIR=`
+- `AIRXDB_REMOTE_SCREENSHOT_TOOL=auto`
+- `AIRXDB_REMOTE_DISPLAY=`
+
+远程 helper 行为：
+
+- 检查本机 `ssh`、远程连通性和远程工作目录。
+- 探测 `gnome-screenshot`、`spectacle`、`scrot`、`grim`、`import`、`screencapture`。
+- 工具缺失时自动尝试用远端包管理器安装 `scrot`，只使用非交互式 `sudo -n`；需要密码、管理员确认或无支持的包管理器时停止并提示用户。
+- 将可复用配置写入 `AirPlan/state/airxdb/remote-device.env`，该文件由 `AirPlan/state/airxdb/.gitignore` 忽略。
+
+远程截图：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_remote_device.py" --project . --action screenshot
+```
+
+远程截图和 JSON 报告写入 `AirPlan/docs/debug/airxdb-artifacts/`，并追加 `AirPlan/docs/debug/gui-debug-log.md`。远程截图只能证明远端截图链路和当前 GUI 现场；如果需要 Midscene 语义视觉动作，仍需单独确认远端或本机可用的 Midscene 接入方式。
+
+## Computer MCP 快速验证
+
+验证桌面 GUI 能力时优先运行 smoke test 脚本，而不是临时拼 MCP 客户端：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_computer_mcp_smoke.py" --project . --action mousemove --prompt "Windows taskbar Start button"
+```
+
+如果当前环境没有 `python`，尝试 `py`、`python3` 或用户提供的 Python 绝对路径。
+
+脚本行为：
+
+- 加载 `AirPlan/state/airxdb/midscene.local.env`，但输出和 JSON 报告会屏蔽 API key；`--action screenshot` 不要求模型配置。
+- 启动 `@midscene/computer-mcp` HTTP 服务。
+- Windows 下自动检查并修复 `screenCapture_1.3.2.bat` / `app.manifest` 缺失问题；修复来源是 `screenshot-desktop@1.15.3` 官方 npm 包。
+- 执行 `computer_connect`、可选语义动作、`take_screenshot`、`computer_disconnect`。
+- 证据写入 `docs/debug/airxdb-artifacts/`，包括截图和 `airxdb-smoke.json` 报告。
+
+结果判断：
+
+- `airxdb_smoke=ok` 才能说明 Computer MCP 视觉链路通过。
+- 如果只完成截图，没有完成 `MouseMove` / `act` / `Tap` 等语义动作，只能说“截图/连接可用”，不能说“视觉语义操作已通过”。
+- 如果报 `MIDSCENE_MODEL_FAMILY is not set to a visual language model`，先补 family；`gpt-5.4` 用 `gpt-5`。
+- Windows 开始菜单 + 中文输入法场景下，输入查询词后可能需要双回车：第一次提交输入法，第二次执行启动。
+
+## Midscene 模式选择
+
+先判断目标界面和现有技术栈，再选 Midscene 模式：
+
+1. Web + 已有 Playwright：
+   - 优先使用 Midscene 的 Playwright 集成。
+   - 适合已有 E2E、页面复现、交互不稳定、视觉断言场景。
+2. Web + 需要复用本地 Chrome 状态：
+   - 使用 Chrome Bridge Mode。
+   - 适合需要复用 cookies、扩展、已登录会话、人工介入浏览器态的场景。
+3. 桌面应用 GUI：
+   - 使用 Midscene Computer / Playground。
+   - 适合 Electron、Qt、WPF、原生应用和跨应用流程。
+4. 远程设备 GUI：
+   - 先使用 AirXDB remote device helper 取证和自动配置远端截图工具。
+   - 适合 SSH 可达的测试机、VM、服务器桌面或远程 Linux/macOS GUI。
+5. 需要把 GUI 操作暴露给上层 Agent 或工具链：
+   - 使用 Midscene MCP。
+   - 浏览器优先 Web Bridge MCP，桌面优先 Computer MCP。
+
+不确定时，一次只问一个关键问题：
+
+- 这是浏览器页面还是桌面应用？
+- 项目里是否已有 Playwright？
+- 是否必须复用本机浏览器登录态？
+- 是要快速复现，还是要沉淀成长期自动化脚本？
+
+## GUI 调试流程
+
+1. 明确问题边界：
+   - 哪个界面、哪条交互链路、什么平台。
+   - 期望行为和实际行为。
+   - 是否涉及视觉错位、点击不到、浮层遮挡、Canvas、焦点问题、窗口切换、多显示器等。
+2. 加载上下文：
+   - 读取 `AGENTS.md`。
+   - 读取相关 ADR。
+   - 读取 `docs/architecture/c4/module.md`。
+   - 查看前端/桌面自动化相关代码、测试、构建配置。
+3. 选择 Midscene 模式并做最小复现：
+   - Playwright
+   - Chrome Bridge
+   - Computer / Playground
+   - MCP
+4. 生成可回放证据：
+   - Midscene HTML 报告
+   - 关键截图
+   - 复现命令
+   - 相关日志和报错
+5. 将证据和观察写入 `AirPlan/docs/debug/gui-debug-log.md`。
+6. 如果问题只是界面复现层，继续用 `airxdb` 深挖。
+7. 如果已定位到代码层根因，转入或并行配合 `airdbg` 做修复。
+8. 修复后再次用 Midscene 复跑关键 GUI 路径，确认问题关闭。
+
+## 与 AirDbg 的协作
+
+- `airxdb` 先做：
+  - GUI 复现
+  - 视觉定位
+  - 界面交互脚本/桥接/MCP 配置
+  - 报告与截图证据
+- `airdbg` 再做：
+  - 根因代码分析
+  - 修复实现
+  - 测试验证
+  - 风险收尾
+
+如果当前问题同时包含“界面复现难”和“代码根因不明”，先用 `airxdb` 稳定复现，再把复现结论和报告交给 `airdbg`。
+
+## AGENTS.md 维护
+
+在以下情况更新 `AGENTS.md`：
+
+- 发现新的 GUI 调试命令、Playwright 命令、Midscene 运行方式。
+- 发现系统权限要求，例如桌面自动化权限、屏幕录制权限、多显示器限制。
+- 发现影响后续 GUI 调试的重要约束，如浏览器桥接、登录态、测试环境、显示缩放。
+- 发现远程设备 SSH 入口、远程截图工具、`AIRXDB_REMOTE_*` 配置方式或远端显示环境限制。
+- 引入了新的 GUI 自动化脚本、报告目录或运行前置条件。
+
+内容保持可执行、可复用，不写流水账。
+
+## ADR 维护
+
+目录：`docs/architecture/adr/`。
+
+需要 ADR 的情况：
+
+- 决定长期采用某种 Midscene 接入方式，例如 Playwright 集成、Bridge Mode、Computer、MCP。
+- GUI 调试方案改变了测试边界、前端交互契约、浏览器控制方式、桌面自动化权限模型。
+- 为了稳定复现而新增长期保留的自动化脚本、报告流程或辅助基础设施。
+
+ADR 保持简洁：Context、Decision、Consequences、Alternatives。
+
+## C4 Module 维护
+
+文件：`docs/architecture/c4/module.md`。
+
+当 GUI 调试或修复改变以下内容时，必须更新：
+
+- 前端模块边界
+- 自动化测试边界
+- 浏览器桥接/桌面控制边界
+- 报告和调试基础设施
+- UI 层和服务层之间的数据所有权或依赖
+
+## GUI Debug Log 维护
+
+文件：`AirPlan/docs/debug/gui-debug-log.md`。
+
+每次 AirXDB 会话至少追加：
+
+- 问题摘要
+- 目标平台和界面
+- Midscene 模式（Playwright / Bridge / Computer / MCP）
+- 是否使用远程设备 helper 以及远程目标、截图工具和限制
+- 复现步骤或命令
+- 报告文件路径
+- 截图或关键观察
+- 转交给 `airdbg` 的结论，或已完成的修复验证
+- 剩余风险
+
+## 输出格式
+
+本轮 GUI 调试结束时，用中文简洁汇报：
+
+- 选择了哪种 Midscene 模式，为什么。
+- 复现是否成功，证据在哪里。
+- 更新了哪些 `AGENTS.md` / ADR / C4 / GUI debug log。
+- 是否需要切给 `airdbg` 继续做代码层修复。

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: airxdb
+short_description: Midscene GUI debug workflow with local and remote screenshot evidence
+default_prompt: "使用 AirXDB 配合 AirDbg 做图形界面调试；远程设备优先调用 remote device helper 并自动配置截图工具。"

AirPlan/docs/spec/AirPlan-ParaV2/.agents/skills/airxdb/references/midscene-official-notes.md

@@ -0,0 +1,159 @@
+# Midscene Official Notes
+
+用于 `airxdb` 的轻量参考，不替代官方文档。
+
+## 选择模式
+
+- Web + 现有 Playwright 项目：
+  - 优先 Midscene Playwright 集成
+  - 适合浏览器页面复现、E2E、界面交互不稳定问题
+- Web + 需要复用本机 Chrome 的 cookies / 已登录状态 / 扩展：
+  - 使用 Chrome Bridge Mode
+- 桌面应用 GUI：
+  - 使用 Midscene Computer 或 Playground
+- 需要给上层 Agent / MCP 客户端暴露 GUI 操作：
+  - 浏览器用 Web Bridge MCP
+  - 桌面用 Computer MCP
+
+## 关键能力
+
+- Midscene 的 UI 操作以纯视觉为主，可用于 Web、移动端、桌面端和 Canvas。
+- Midscene 支持生成 HTML 报告，适合作为 GUI debug 证据。
+- Midscene 可通过 MCP 暴露截图和动作空间操作。
+
+## 首次模型配置
+
+AirXDB 第一次进入项目时先检查这些变量：
+
+```bash
+MIDSCENE_MODEL_NAME
+MIDSCENE_MODEL_BASE_URL
+MIDSCENE_MODEL_API_KEY
+MIDSCENE_MODEL_FAMILY
+MCP_SERVER_REQUEST_TIMEOUT
+```
+
+前三个是连接模型服务的基本配置。`MIDSCENE_MODEL_FAMILY` 是视觉语义动作必填项，`MCP_SERVER_REQUEST_TIMEOUT` 按模型服务情况补充。
+
+常见 `MIDSCENE_MODEL_FAMILY`：
+
+- `gpt-5`：GPT-5.x 视觉模型，例如 `gpt-5.4`
+- `qwen2.5-vl`
+- `qwen3-vl`
+- `gemini`
+- `doubao-seed`
+- `vlm-ui-tars`
+
+不要把真实 API key 写入 ADR、C4、debug log 或可提交文档。需要本机持久化时优先使用 `AirPlan/state/airxdb/midscene.local.env`。
+
+## Chrome Bridge Mode
+
+- 官方说明：
+  - 需要 Midscene Chrome 插件
+  - 终端侧配置模型环境变量
+  - 适合复用本地浏览器登录态和页面状态
+- 常用依赖：
+
+```bash
+npm install @midscene/web tsx --save-dev
+```
+
+- 常见入口：
+
+```ts
+import { AgentOverChromeBridge } from "@midscene/web/bridge-mode";
+```
+
+- 常见运行方式：
+
+```bash
+tsx demo-new-tab.ts
+```
+
+- 常见模型环境变量：
+
+```bash
+MIDSCENE_MODEL_BASE_URL
+MIDSCENE_MODEL_API_KEY
+MIDSCENE_MODEL_NAME
+MIDSCENE_MODEL_FAMILY
+```
+
+## MCP
+
+- 浏览器桥接 MCP：
+
+```text
+@midscene/web-bridge-mcp
+```
+
+- 桌面 MCP：
+
+```text
+@midscene/computer-mcp
+```
+
+- Computer MCP 常见配置核心：
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@midscene/computer-mcp"]
+}
+```
+
+- 常见 MCP 模型环境变量：
+
+```bash
+MIDSCENE_MODEL_BASE_URL
+MIDSCENE_MODEL_API_KEY
+MIDSCENE_MODEL_NAME
+MIDSCENE_MODEL_FAMILY
+MCP_SERVER_REQUEST_TIMEOUT
+```
+
+## 桌面自动化
+
+- Midscene 支持 Windows、macOS、Linux 桌面自动化。
+- 桌面控制包括鼠标、键盘、截图、多显示器。
+- Linux 可在 Xvfb 下做无头执行。
+- Windows 下 `@midscene/computer-mcp` 的 npx 缓存包可能缺 `dist/screenCapture_1.3.2.bat` 和 `dist/app.manifest`。AirXDB smoke test 会从 `screenshot-desktop@1.15.3` npm 包自动补齐。
+- 桌面 GUI 调试可优先考虑：
+  - 快速试用：Playground
+  - 持续脚本化：Computer SDK / MCP
+
+## AirXDB Smoke Test
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_computer_mcp_smoke.py" --project . --action mousemove --prompt "Windows taskbar Start button"
+```
+
+输出：
+
+- `airxdb_smoke=ok`：Computer MCP 连接、截图、语义动作完成。
+- `airxdb_smoke=blocked`：缺模型配置或 family 不合法。
+- `asset_repair=repaired`：已补齐 Windows 截图脚本。
+- `report=<path>`：JSON 报告，API key 已脱敏。
+
+## AirXDB Screenshot Evidence
+
+截图取证不需要模型配置：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_computer_mcp_smoke.py" --project . --action screenshot
+```
+
+用于：
+
+- 给 `airdbg` 提供 GUI 错误现场
+- 捕获弹窗、遮挡、焦点、布局错位、任务栏/托盘状态
+- 记录多显示器和当前桌面状态
+
+截图可能包含敏感信息。写入 ADR/C4/debug log 时记录路径和观察，不复制密钥或隐私内容。
+
+## GUI Debug 推荐策略
+
+1. 先选模式，不要一上来混用多种接入。
+2. 先做最小复现，再考虑长期自动化。
+3. 保留 HTML 报告、截图和复现命令。
+4. 若问题已定位到代码层，把证据交给 `airdbg` 做修复。

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "aircontext-mkt",
+  "owner": {
+    "name": "AirContext"
+  },
+  "plugins": [
+    {
+      "name": "aircontext",
+      "source": "./",
+      "description": "Rule-driven, automated context compaction with auto-resume. Replaces Claude Code's auto-compact."
+    }
+  ]
+}

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/.claude-plugin/plugin.json

@@ -0,0 +1,53 @@
+{
+  "name": "aircontext",
+  "version": "0.1.0",
+  "description": "User-controlled periodic context compaction with auto-resume. Replaces Claude Code's auto-compact with rule-driven external LLM compression.",
+  "author": {
+    "name": "AirContext"
+  },
+  "keywords": ["context", "compaction", "automation"],
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python ${CLAUDE_PLUGIN_ROOT}/scripts/on_session_start.py"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python ${CLAUDE_PLUGIN_ROOT}/scripts/on_user_prompt.py"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python ${CLAUDE_PLUGIN_ROOT}/scripts/on_tool_use.py"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python ${CLAUDE_PLUGIN_ROOT}/scripts/on_pre_compact.py"
+          }
+        ]
+      }
+    ]
+  }
+}

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/README.md

@@ -0,0 +1,94 @@
+# AirContext
+
+A Claude Code plugin that **replaces auto-compact with rule-driven, automated, externally-summarised compaction**, then **auto-resumes** the session so long-running agent loops never break.
+
+## Why
+
+Claude Code's built-in auto-compact triggers on context pressure and uses a generic strategy. In a large project, frequent generic compaction degrades subsequent generation quality. AirContext lets you:
+
+1. Disable Claude's auto-compact (via PreCompact hook).
+2. Trigger compaction on **your** schedule (token-ratio threshold + cooldown).
+3. Run compaction in **your** LLM (any OpenAI-compatible endpoint — DeepSeek, Ollama, vLLM, LM Studio, etc.) using **your** rules (`AirContext/rules.md`).
+4. Apply the result by appending an isolated summary chain (`parentUuid: null`) to the session JSONL, then automatically restart `claude --resume <id>` and inject a continuation prompt so an in-flight agent loop picks back up unattended.
+
+## How it works
+
+```
+$ aircontext               # wrapper around `claude`
+        │
+        ▼
+   (loops)  ← spawns claude → user works as normal
+                   │
+                   │  PostToolUse hook (every tool call):
+                   │    • estimate active-chain tokens
+                   │    • if > threshold and cooldown elapsed:
+                   │        fork compactor.py (background, non-blocking)
+                   │
+                   │  compactor.py:
+                   │    • read JSONL → render head as plain text
+                   │    • call LLM with rules.md as system prompt
+                   │    • backup JSONL → snapshots/<ts>-<sid>.jsonl
+                   │    • append [summary, continuation] with parentUuid=null
+                   │    • set state.compaction_ready = true
+                   │
+        ◄──────────┘
+   wrapper watcher sees ready → SIGTERM claude → spawn `claude --resume <id>`
+        │
+        ▼
+   new claude loads JSONL: latest leaf is the continuation prompt → auto-replies
+   the in-flight task continues with ~10× smaller context.
+```
+
+## Install
+
+```bash
+# from the marketplace once published
+/plugin install aircontext@<your-marketplace>
+
+# or directly via settings.json
+{
+  "extraKnownMarketplaces": {
+    "aircontext-mkt": { "source": { "source": "github", "repo": "<you>/aircontext-plugin" } }
+  },
+  "enabledPlugins": { "aircontext@aircontext-mkt": true }
+}
+```
+
+Requires Python ≥ 3.10 and `pyyaml`. The wrapper assumes `claude` is on PATH.
+
+## Use
+
+```bash
+cd <your-project>
+aircontext                 # instead of `claude`
+```
+
+First run creates `<project>/AirContext/` with `config.yaml`, `rules.md`, and a per-project README. Edit `config.yaml` (especially `backend.api_key`), then re-run.
+
+## Per-project files (`AirContext/`)
+
+| File              | Purpose                                                       |
+| ----------------- | ------------------------------------------------------------- |
+| `config.yaml`     | Backend, trigger threshold, cooldown, continuation prompt     |
+| `rules.md`        | What to keep / drop — sent to LLM as system prompt            |
+| `state.json`      | Runtime state (managed by plugin, do not edit by hand)        |
+| `snapshots/`      | JSONL backup before each compaction (rotate via `max_snapshots`) |
+
+## Slash commands
+
+| Command                | Purpose                                                  |
+| ---------------------- | -------------------------------------------------------- |
+| `/aircontext-init`     | (Re)install templates into the current project           |
+| `/aircontext-now`      | Force a compaction immediately (bypasses cooldown)       |
+| `/aircontext-status`   | Show config, last compaction, snapshot count             |
+| `/aircontext-pause`    | Toggle (or `on`/`off`) automatic compaction              |
+
+## Caveats
+
+- **You must launch via `aircontext`, not `claude`, for auto-resume to work.** Without the wrapper, the compactor still prepares the snapshot but you must `claude --resume <id>` manually for it to take effect.
+- The JSONL transcript format is **not a stable public API**. AirContext logs the observed `version` field; if it sees an unfamiliar version, it warns and you may want to enable `safety.dry_run: true` until you've verified compatibility on your side.
+- A small fixed cost (system prompt, CLAUDE.md, tool definitions, skills) is reloaded into context every session — this is a Claude Code property, not something AirContext can shrink.
+
+## License
+
+MIT

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/bin/aircontext

@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""
+aircontext — wrapper around `claude` providing automatic context compaction loop.
+
+Usage:
+    aircontext [args passed through to claude]
+
+Behaviour:
+    1. Verify ./AirContext/ exists and config.yaml is valid (create from templates if missing).
+    2. Spawn `claude` as a child process (stdio inherited so UX matches running claude directly).
+    3. A watcher thread polls AirContext/state.json; when compaction_ready=true, it:
+         - terminates the running claude gracefully
+         - re-spawns `claude --resume <session_id>` so the new isolated-summary chain takes effect
+    4. Loop exits when the user closes claude without a pending compaction.
+"""
+from __future__ import annotations
+import os
+import sys
+import signal
+import subprocess
+import threading
+import time
+from pathlib import Path
+
+# Ensure plugin's scripts/ is importable regardless of how the wrapper is invoked.
+_PLUGIN_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_PLUGIN_ROOT / "scripts"))
+
+from core.auto_init import (  # noqa: E402
+    auto_configure,
+    propagate_settings_env,
+    required_fields_missing,
+)
+from core.config_loader import ensure_aircontext_dir, validate_config  # noqa: E402
+from core.state import StateFile  # noqa: E402
+
+
+WATCH_INTERVAL_SECONDS = 2.0
+TERMINATE_TIMEOUT_SECONDS = 10
+
+
+def terminate_gracefully(proc: subprocess.Popen) -> None:
+    """Send a platform-appropriate stop signal, then SIGKILL after timeout."""
+    try:
+        if os.name == "nt":
+            proc.send_signal(signal.CTRL_BREAK_EVENT)
+        else:
+            proc.send_signal(signal.SIGTERM)
+    except (ProcessLookupError, OSError):
+        return
+    try:
+        proc.wait(timeout=TERMINATE_TIMEOUT_SECONDS)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            pass
+
+
+def spawn_claude(resume_id: str | None, passthrough_args: list[str]) -> subprocess.Popen:
+    cmd = ["claude"]
+    if resume_id:
+        cmd += ["--resume", resume_id]
+    cmd += passthrough_args
+    env = {**os.environ, "AIRCONTEXT_ACTIVE": "1"}
+    creationflags = 0
+    if os.name == "nt":
+        creationflags = subprocess.CREATE_NEW_PROCESS_GROUP  # type: ignore[attr-defined]
+    return subprocess.Popen(cmd, env=env, creationflags=creationflags)
+
+
+def main() -> int:
+    project_root = Path.cwd()
+    air = project_root / "AirContext"
+
+    # Make ~/.claude/settings.json `env` block visible in os.environ so the
+    # validate_config call below resolves ${env:VAR} placeholders the same way
+    # claude/hooks/compactor will at runtime.
+    propagate_settings_env()
+
+    created = ensure_aircontext_dir(air, plugin_root=_PLUGIN_ROOT)
+    config_path = air / "config.yaml"
+    if created:
+        cfg = auto_configure(config_path)
+        window = cfg.get("trigger", {}).get("model_context_window", 200000)
+        print(
+            f"[aircontext] AirContext/ initialised at {air}",
+            file=sys.stderr,
+        )
+        print(
+            f"[aircontext] Auto-configured: model_context_window={window}, "
+            f"backend.type={cfg.get('backend', {}).get('type')}",
+            file=sys.stderr,
+        )
+
+    missing = required_fields_missing(config_path)
+    if missing:
+        print(
+            "[aircontext] Please fill these REQUIRED fields in "
+            f"{config_path}:",
+            file=sys.stderr,
+        )
+        for m in missing:
+            print(f"[aircontext]   - {m}", file=sys.stderr)
+        print(
+            "[aircontext] Then re-run `aircontext` and you'll go straight into claude.",
+            file=sys.stderr,
+        )
+        return 1
+
+    err = validate_config(config_path)
+    if err:
+        print(f"[aircontext] Invalid config: {err}", file=sys.stderr)
+        return 1
+
+    state = StateFile(air / "state.json")
+    state.reset_for_new_session()
+
+    passthrough = sys.argv[1:]
+    resume_id = state.last_session_id
+
+    while True:
+        proc = spawn_claude(resume_id, passthrough)
+        pending_resume_id: list[str | None] = [None]
+        stop_watcher = threading.Event()
+
+        def watcher() -> None:
+            while not stop_watcher.is_set():
+                snap = state.read()
+                if snap.get("compaction_ready"):
+                    rid = snap.get("pending_resume_session_id")
+                    if rid:
+                        pending_resume_id[0] = rid
+                        terminate_gracefully(proc)
+                        return
+                if stop_watcher.wait(WATCH_INTERVAL_SECONDS):
+                    return
+
+        t = threading.Thread(target=watcher, daemon=True)
+        t.start()
+        try:
+            proc.wait()
+        except KeyboardInterrupt:
+            terminate_gracefully(proc)
+        finally:
+            stop_watcher.set()
+            t.join(timeout=3)
+
+        if pending_resume_id[0]:
+            resume_id = pending_resume_id[0]
+            state.clear_ready()
+            print(
+                f"[aircontext] Compaction applied, resuming session {resume_id}",
+                file=sys.stderr,
+            )
+            continue
+
+        # User exited without a pending compaction — finish.
+        return proc.returncode or 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/bin/aircontext.cmd

@@ -0,0 +1,4 @@
+@echo off
+REM Windows launcher for the AirContext wrapper.
+REM Forwards all args to the Python script next to this file.
+python "%~dp0aircontext" %*

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/commands/aircontext-init.md

@@ -0,0 +1,12 @@
+---
+description: Install AirContext templates into the current project
+allowed-tools: Bash
+---
+
+Run the initialiser to create or repair `AirContext/` in the current project root.
+After it completes, tell the user to edit `AirContext/config.yaml` (specifically
+`backend.api_key` and `backend.endpoint`) before relying on automatic compaction.
+
+```!
+python "${CLAUDE_PLUGIN_ROOT}/scripts/cmd_init.py"
+```

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/commands/aircontext-now.md

@@ -0,0 +1,14 @@
+---
+description: Force an immediate compaction (ignores cooldown and threshold)
+allowed-tools: Bash
+---
+
+Spawn the compactor in the foreground for the current session and report the
+outcome. After it succeeds, the wrapper will detect `compaction_ready` within
+a few seconds and restart claude with `--resume`. If you launched claude
+directly without the `aircontext` wrapper, you must exit and run
+`claude --resume <session-id>` yourself for the new chain to take effect.
+
+```!
+python "${CLAUDE_PLUGIN_ROOT}/scripts/cmd_now.py" --session-id "${CLAUDE_SESSION_ID}"
+```

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/commands/aircontext-pause.md

@@ -0,0 +1,13 @@
+---
+description: Pause or resume AirContext automatic compaction (toggle)
+argument-hint: "[on|off]"
+allowed-tools: Bash
+---
+
+Toggle (or explicitly set) the automatic-compaction switch. While paused, the
+PostToolUse ticker still runs but skips firing the compactor. Manual
+`/aircontext-now` is unaffected.
+
+```!
+python "${CLAUDE_PLUGIN_ROOT}/scripts/cmd_pause.py" $ARGUMENTS
+```

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/commands/aircontext-status.md

@@ -0,0 +1,8 @@
+---
+description: Show current AirContext state, last compaction, and pending actions
+allowed-tools: Bash
+---
+
+```!
+python "${CLAUDE_PLUGIN_ROOT}/scripts/cmd_status.py"
+```

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/pyproject.toml

@@ -0,0 +1,11 @@
+[project]
+name = "aircontext-plugin"
+version = "0.1.0"
+description = "Claude Code plugin for rule-driven, automated context compaction with auto-resume."
+requires-python = ">=3.10"
+dependencies = [
+    "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/cmd_init.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Backend for /aircontext-init."""
+from __future__ import annotations
+import os
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE))
+
+from core.config_loader import ensure_aircontext_dir, validate_config  # noqa: E402
+
+
+def main() -> int:
+    plugin_root = Path(os.environ.get("CLAUDE_PLUGIN_ROOT", _HERE.parent))
+    project = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+    air = project / "AirContext"
+    created = ensure_aircontext_dir(air, plugin_root=plugin_root)
+    print(f"AirContext directory: {air}")
+    print("Templates installed." if created else "Templates already present (no overwrite).")
+    err = validate_config(air / "config.yaml")
+    if err:
+        print(f"Config status: needs attention — {err}")
+    else:
+        print("Config status: OK (compaction will activate on next session).")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/cmd_now.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Backend for /aircontext-now — force a compaction synchronously."""
+from __future__ import annotations
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE))
+
+from core.compactor import run as run_compactor  # noqa: E402
+from core.state import StateFile  # noqa: E402
+
+
+def _find_transcript(project: Path, session_id: str) -> Path | None:
+    """Locate the JSONL transcript for the given session.
+
+    Claude Code stores transcripts under
+        ~/.claude/projects/<encoded-cwd>/sessions/<session-id>.jsonl
+    The cwd encoding replaces path separators with `-`. We search defensively.
+    """
+    home = Path.home() / ".claude" / "projects"
+    if not home.exists():
+        return None
+    encoded = str(project).replace(os.sep, "-").replace(":", "")
+    # Try direct match first
+    candidate = home / encoded / "sessions" / f"{session_id}.jsonl"
+    if candidate.exists():
+        return candidate
+    # Fall back: scan for the session id under any project directory
+    for p in home.glob(f"*/sessions/{session_id}.jsonl"):
+        return p
+    return None
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--session-id", required=True)
+    args = p.parse_args()
+
+    project = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+    air = project / "AirContext"
+    if not (air / "config.yaml").exists():
+        print("AirContext not initialised. Run /aircontext-init first.")
+        return 1
+
+    transcript = _find_transcript(project, args.session_id)
+    if not transcript:
+        print(f"Could not locate transcript for session {args.session_id}.")
+        return 1
+
+    state = StateFile(air / "state.json")
+    # Force one-shot regardless of cooldown
+    state.update(last_compaction_unix=0)
+    print(f"Compacting transcript: {transcript}")
+    rc = run_compactor(project, transcript, args.session_id)
+    snap = state.read()
+    if rc == 0 and snap.get("compaction_ready"):
+        print("Compaction prepared. The wrapper will restart claude shortly.")
+        print("If you launched claude directly (without `aircontext`), exit and "
+              f"run: claude --resume {args.session_id}")
+    elif rc == 0:
+        print("Compactor returned success but no compaction was applied "
+              "(see compactor.log for reason — likely chain too short or paused).")
+    else:
+        print(f"Compactor failed with exit code {rc}. See AirContext/snapshots/compactor.log")
+    return rc
+
+
+if __name__ == "__main__":
+    sys.exit(main())

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/cmd_pause.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Backend for /aircontext-pause [on|off]."""
+from __future__ import annotations
+import os
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE))
+
+from core.state import StateFile  # noqa: E402
+
+
+def main() -> int:
+    project = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+    air = project / "AirContext"
+    if not air.exists():
+        print("AirContext not initialised. Run /aircontext-init first.")
+        return 1
+
+    state = StateFile(air / "state.json")
+    arg = (sys.argv[1].lower() if len(sys.argv) > 1 else "").strip()
+
+    cur = bool(state.read().get("paused"))
+    if arg in ("on", "pause", "true", "1"):
+        new = True
+    elif arg in ("off", "resume", "false", "0"):
+        new = False
+    else:
+        new = not cur  # toggle
+
+    state.update(paused=new)
+    print(f"AirContext automatic compaction: {'PAUSED' if new else 'ACTIVE'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/cmd_status.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Backend for /aircontext-status."""
+from __future__ import annotations
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE))
+
+from core.config_loader import load_config, validate_config  # noqa: E402
+from core.state import StateFile  # noqa: E402
+
+
+def main() -> int:
+    project = Path(os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd()))
+    air = project / "AirContext"
+    cfg_path = air / "config.yaml"
+    print(f"Project root:    {project}")
+    print(f"AirContext dir:  {air} {'(present)' if air.exists() else '(MISSING)'}")
+    if not cfg_path.exists():
+        print("Status: not initialised. Run /aircontext-init.")
+        return 0
+    err = validate_config(cfg_path)
+    if err:
+        print(f"Config: invalid — {err}")
+    else:
+        cfg = load_config(cfg_path)
+        b = cfg.get("backend", {})
+        t = cfg.get("trigger", {})
+        print(f"Backend:         {b.get('endpoint')} (model={b.get('model')})")
+        print(
+            f"Trigger:         strategy={t.get('strategy')} "
+            f"threshold={t.get('threshold')} window={t.get('model_context_window')}"
+        )
+
+    state = StateFile(air / "state.json").read()
+    print(f"Paused:          {state.get('paused')}")
+    print(f"Compacting now:  {state.get('compaction_in_progress')}")
+    print(f"Ready to apply:  {state.get('compaction_ready')}")
+    last = state.get("last_compaction_unix") or 0
+    if last:
+        ago = int(time.time() - last)
+        print(f"Last compaction: {ago}s ago")
+    else:
+        print("Last compaction: never")
+    snapshots = air / "snapshots"
+    if snapshots.exists():
+        files = [p for p in snapshots.iterdir() if p.suffix == ".jsonl"]
+        print(f"Snapshots:       {len(files)} stored under {snapshots}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/core/auto_init.py

@@ -0,0 +1,149 @@
+"""Auto-fill non-private fields when AirContext/ is freshly created.
+
+Privacy boundary:
+  - backend.api_key and backend.endpoint are left for the USER to fill.
+  - Everything else (model_context_window, threshold, cooldown, compaction
+    rules, etc.) is auto-configured here using the host machine's environment.
+
+Inputs we read:
+  - ~/.claude/settings.json (specifically `model` and `env` sections)
+  - os.environ (overrides settings.json env when both set)
+
+Outputs:
+  - Mutated AirContext/config.yaml on disk
+  - Side-effect: settings.json's `env` keys are copied into os.environ so the
+    wrapper's own validate_config call resolves ${env:VAR} placeholders
+    consistently with what claude (and thus its hooks/compactor) will see.
+"""
+from __future__ import annotations
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml  # type: ignore
+except ImportError:  # pragma: no cover — pyyaml is a hard dep declared in pyproject
+    yaml = None
+
+
+# Approximate context windows for known Claude model IDs / aliases.
+_MODEL_WINDOWS = {
+    "opus[1m]": 1_000_000,
+    "claude-opus-4-7[1m]": 1_000_000,
+    "claude-opus-4-7": 200_000,
+    "claude-sonnet-4-6": 200_000,
+    "claude-sonnet-4-5": 200_000,
+    "claude-haiku-4-5": 200_000,
+    "claude-haiku-4-5-20251001": 200_000,
+}
+
+
+def _read_user_settings() -> dict:
+    p = Path.home() / ".claude" / "settings.json"
+    if not p.exists():
+        return {}
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+
+
+def propagate_settings_env() -> dict[str, str]:
+    """Copy ~/.claude/settings.json `env` block into os.environ if not already set.
+
+    Claude Code injects these into its own subprocess environment, but the
+    wrapper itself is launched from the user's shell and doesn't inherit them.
+    Without this propagation, the wrapper's validate_config sees empty
+    ${env:ANTHROPIC_AUTH_TOKEN} and bails out, even though the env var WILL be
+    set when the compactor actually runs (since it's a child of claude).
+
+    Returns the env dict that was applied.
+    """
+    settings = _read_user_settings()
+    env_block = settings.get("env") or {}
+    if not isinstance(env_block, dict):
+        return {}
+    for k, v in env_block.items():
+        if isinstance(v, str):
+            os.environ.setdefault(k, v)
+    return env_block
+
+
+def detect_claude_context_window() -> int | None:
+    """Infer the active claude model's context window from settings.json."""
+    settings = _read_user_settings()
+    model = settings.get("model")
+    if not isinstance(model, str):
+        return None
+    if model in _MODEL_WINDOWS:
+        return _MODEL_WINDOWS[model]
+    if "[1m]" in model.lower():
+        return 1_000_000
+    return 200_000  # safe default for any modern Claude model
+
+
+def auto_configure(config_path: Path) -> dict[str, Any]:
+    """Fill non-private fields in the freshly-created config.
+
+    Returns the merged config dict (also written back to disk).
+    Raises RuntimeError if PyYAML is missing.
+    """
+    if yaml is None:
+        raise RuntimeError("PyYAML required (pip install pyyaml)")
+
+    propagate_settings_env()
+
+    cfg = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    cfg.setdefault("backend", {})
+    cfg.setdefault("trigger", {})
+    cfg.setdefault("compaction", {})
+    cfg.setdefault("safety", {})
+
+    window = detect_claude_context_window()
+    if window:
+        cfg["trigger"]["model_context_window"] = window
+
+    # If user has ANTHROPIC_AUTH_TOKEN in settings.json/env, prefer
+    # anthropic_native as the default backend type (most likely match).
+    # api_key/endpoint themselves stay user-fillable.
+    has_anthropic = bool(
+        os.environ.get("ANTHROPIC_AUTH_TOKEN")
+        or os.environ.get("ANTHROPIC_API_KEY")
+    )
+    has_openai = bool(os.environ.get("OPENAI_API_KEY"))
+    if has_anthropic and not has_openai:
+        cfg["backend"].setdefault("type", "anthropic_native")
+    elif has_openai and not has_anthropic:
+        cfg["backend"].setdefault("type", "openai_compat")
+    # Otherwise leave whatever the template specified.
+
+    config_path.write_text(
+        yaml.safe_dump(cfg, allow_unicode=True, sort_keys=False),
+        encoding="utf-8",
+    )
+    return cfg
+
+
+def required_fields_missing(config_path: Path) -> list[str]:
+    """Return the names of REQUIRED-USER-FILL fields that are still empty.
+
+    These are the privacy-boundary fields: endpoint and api_key. Any
+    auto-configurable field is NOT in this list.
+    """
+    if yaml is None:
+        return ["[pyyaml not installed]"]
+    cfg = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+    backend = cfg.get("backend") or {}
+    missing: list[str] = []
+    endpoint = (backend.get("endpoint") or "").strip()
+    if not endpoint:
+        missing.append("backend.endpoint")
+
+    api_key_raw = backend.get("api_key") or ""
+    # api_key may be a ${env:VAR} placeholder. Resolve via current env.
+    from .config_loader import resolve_env_placeholders
+    resolved = resolve_env_placeholders(api_key_raw)
+    if isinstance(resolved, str) and not resolved.strip():
+        missing.append("backend.api_key")
+    return missing

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/core/backends/anthropic_native.py

@@ -0,0 +1,91 @@
+"""Anthropic-native /v1/messages backend.
+
+For endpoints that speak the Anthropic Messages API (api.anthropic.com or any
+proxy compatible with it). Uses x-api-key + anthropic-version headers.
+"""
+from __future__ import annotations
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+
+DEFAULT_ANTHROPIC_VERSION = "2023-06-01"
+
+
+@dataclass
+class AnthropicNativeBackend:
+    cfg: dict
+
+    @property
+    def endpoint(self) -> str:
+        return self.cfg["endpoint"].rstrip("/")
+
+    @property
+    def model(self) -> str:
+        return self.cfg["model"]
+
+    @property
+    def api_key(self) -> str:
+        return self.cfg.get("api_key") or "missing-key"
+
+    @property
+    def max_output_tokens(self) -> int:
+        return int(self.cfg.get("max_output_tokens", 4000))
+
+    @property
+    def timeout(self) -> int:
+        return int(self.cfg.get("timeout_seconds", 60))
+
+    @property
+    def anthropic_version(self) -> str:
+        return self.cfg.get("anthropic_version", DEFAULT_ANTHROPIC_VERSION)
+
+    def summarise(self, system_prompt: str, conversation_text: str) -> str:
+        url = f"{self.endpoint}/v1/messages"
+        body = {
+            "model": self.model,
+            "max_tokens": self.max_output_tokens,
+            "temperature": 0.2,
+            "system": system_prompt,
+            "messages": [
+                {"role": "user", "content": conversation_text},
+            ],
+        }
+        data = json.dumps(body).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "x-api-key": self.api_key,
+            "anthropic-version": self.anthropic_version,
+        }
+        # Some proxies (e.g. wolfai.top) accept Bearer tokens too — send both
+        # so we work whether the upstream wants x-api-key or Authorization.
+        if self.api_key.startswith("sk-"):
+            headers["Authorization"] = f"Bearer {self.api_key}"
+
+        req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                payload = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", errors="replace")[:500]
+            raise RuntimeError(f"LLM HTTP {e.code}: {detail}") from e
+        except urllib.error.URLError as e:
+            raise RuntimeError(f"LLM connection failed: {e.reason}") from e
+
+        # Anthropic format: {"content": [{"type":"text","text":"..."}], ...}
+        content = payload.get("content")
+        if isinstance(content, list):
+            for block in content:
+                if isinstance(block, dict) and block.get("type") == "text":
+                    text = block.get("text", "")
+                    if text.strip():
+                        return text.strip()
+        # Some proxies pass through OpenAI shape — fall back gracefully.
+        choices = payload.get("choices") or []
+        if choices:
+            msg = choices[0].get("message") or {}
+            content = msg.get("content")
+            if isinstance(content, str) and content.strip():
+                return content.strip()
+        raise RuntimeError(f"LLM returned unexpected payload shape: {payload}")

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/core/backends/base.py

@@ -0,0 +1,19 @@
+"""Backend interface used by compactor.py."""
+from __future__ import annotations
+from typing import Protocol
+
+
+class CompressionBackend(Protocol):
+    def summarise(self, system_prompt: str, conversation_text: str) -> str: ...
+
+
+def build_backend(cfg: dict) -> CompressionBackend:
+    backend_cfg = cfg.get("backend") or {}
+    btype = backend_cfg.get("type", "openai_compat")
+    if btype == "openai_compat":
+        from .openai_compat import OpenAICompatibleBackend
+        return OpenAICompatibleBackend(backend_cfg)
+    if btype == "anthropic_native":
+        from .anthropic_native import AnthropicNativeBackend
+        return AnthropicNativeBackend(backend_cfg)
+    raise ValueError(f"Unsupported backend.type: {btype!r}")

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/core/backends/openai_compat.py

@@ -0,0 +1,77 @@
+"""OpenAI-compatible chat-completions backend.
+
+Covers OpenAI / Azure OpenAI / DeepSeek / Moonshot / Qwen-cloud / Ollama /
+vLLM / LM Studio — anything that exposes `POST {endpoint}/chat/completions`.
+
+We avoid the openai SDK to keep the plugin's dependency surface to stdlib +
+pyyaml. Uses urllib so even environments without `requests` work.
+"""
+from __future__ import annotations
+import json
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+
+
+@dataclass
+class OpenAICompatibleBackend:
+    cfg: dict
+
+    @property
+    def endpoint(self) -> str:
+        return self.cfg["endpoint"].rstrip("/")
+
+    @property
+    def model(self) -> str:
+        return self.cfg["model"]
+
+    @property
+    def api_key(self) -> str:
+        return self.cfg.get("api_key") or "missing-key"
+
+    @property
+    def max_output_tokens(self) -> int:
+        return int(self.cfg.get("max_output_tokens", 4000))
+
+    @property
+    def timeout(self) -> int:
+        return int(self.cfg.get("timeout_seconds", 60))
+
+    def summarise(self, system_prompt: str, conversation_text: str) -> str:
+        url = f"{self.endpoint}/chat/completions"
+        body = {
+            "model": self.model,
+            "max_tokens": self.max_output_tokens,
+            "temperature": 0.2,
+            "messages": [
+                {"role": "system", "content": system_prompt},
+                {"role": "user", "content": conversation_text},
+            ],
+        }
+        data = json.dumps(body).encode("utf-8")
+        req = urllib.request.Request(
+            url,
+            data=data,
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                payload = json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", errors="replace")[:500]
+            raise RuntimeError(f"LLM HTTP {e.code}: {detail}") from e
+        except urllib.error.URLError as e:
+            raise RuntimeError(f"LLM connection failed: {e.reason}") from e
+
+        choices = payload.get("choices") or []
+        if not choices:
+            raise RuntimeError(f"LLM returned no choices: {payload}")
+        msg = choices[0].get("message") or {}
+        content = msg.get("content")
+        if not isinstance(content, str) or not content.strip():
+            raise RuntimeError(f"LLM returned empty content: {payload}")
+        return content.strip()

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/core/compactor.py

@@ -0,0 +1,260 @@
+"""Compactor — runs out-of-band, mutates JSONL, signals wrapper to resume.
+
+Invocation (by on_tool_use.py or /aircontext-now):
+    python compactor.py --project <root> --transcript <jsonl> --session-id <sid>
+
+Lifecycle:
+    1. Acquire single-instance lock (compactor.lock).
+    2. Mark state.compaction_in_progress=true (already set by hook, idempotent).
+    3. Load active chain. If too short, abort.
+    4. Backup JSONL.
+    5. Slice tail (preserved) vs head (to compress).
+    6. Build conversation text + system prompt (rules.md).
+    7. Call LLM backend.
+    8. Append [summary, continuation] messages with parentUuid=null chain head.
+    9. Write state.compaction_ready=true so wrapper restarts claude.
+"""
+from __future__ import annotations
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+_HERE = Path(__file__).resolve().parent.parent
+if str(_HERE) not in sys.path:
+    sys.path.insert(0, str(_HERE))
+
+from core.backends.base import build_backend  # noqa: E402
+from core.config_loader import load_config  # noqa: E402
+from core.jsonl_ops import (  # noqa: E402
+    append_isolated_summary,
+    backup_jsonl,
+    find_active_chain,
+    load_messages,
+    rotate_snapshots,
+)
+from core.state import StateFile  # noqa: E402
+
+
+MIN_CHAIN_TO_COMPACT = 6
+
+
+def _serialise_message_for_llm(msg: dict[str, Any]) -> str | None:
+    """Reduce a JSONL message to plain text the LLM can read.
+
+    Returns None for messages that should be skipped entirely
+    (file-history-snapshot, queue-operation, etc.).
+    """
+    t = msg.get("type")
+    inner = msg.get("message") or {}
+    if t == "user":
+        content = inner.get("content")
+        if isinstance(content, str):
+            return f"USER: {content}"
+        if isinstance(content, list):
+            parts = [p.get("text", "") if isinstance(p, dict) else str(p) for p in content]
+            return "USER: " + " ".join(p for p in parts if p)
+    if t == "assistant":
+        content = inner.get("content")
+        if isinstance(content, str):
+            return f"ASSISTANT: {content}"
+        if isinstance(content, list):
+            parts: list[str] = []
+            for p in content:
+                if not isinstance(p, dict):
+                    continue
+                if p.get("type") == "text":
+                    parts.append(p.get("text", ""))
+                elif p.get("type") == "tool_use":
+                    parts.append(
+                        f"[tool_use {p.get('name')}({json.dumps(p.get('input', {}), ensure_ascii=False)[:300]})]"
+                    )
+                elif p.get("type") == "thinking":
+                    pass  # drop
+            return "ASSISTANT: " + " ".join(s for s in parts if s)
+    if t == "tool_result":
+        # `message.content` for tool_result is the result text
+        content = inner.get("content") if isinstance(inner, dict) else msg.get("content")
+        if isinstance(content, list):
+            content = " ".join(
+                (p.get("text", "") if isinstance(p, dict) else str(p)) for p in content
+            )
+        if not isinstance(content, str):
+            return None
+        return f"TOOL_RESULT: {content}"
+    if t in ("system",):
+        content = inner.get("content")
+        if isinstance(content, str):
+            return f"SYSTEM: {content}"
+    return None
+
+
+def _truncate_long_tool_results(rendered: list[str], max_lines: int) -> list[str]:
+    out: list[str] = []
+    for r in rendered:
+        if not r.startswith("TOOL_RESULT: "):
+            out.append(r)
+            continue
+        body = r[len("TOOL_RESULT: "):]
+        lines = body.splitlines()
+        if len(lines) <= max_lines:
+            out.append(r)
+            continue
+        head = "\n".join(lines[:50])
+        tail = "\n".join(lines[-50:])
+        out.append(
+            "TOOL_RESULT: "
+            + head
+            + f"\n... [{len(lines) - 100} lines omitted by AirContext pre-truncation] ...\n"
+            + tail
+        )
+    return out
+
+
+def run(project: Path, transcript: Path, session_id: str) -> int:
+    air = project / "AirContext"
+    cfg_path = air / "config.yaml"
+    state = StateFile(air / "state.json")
+
+    try:
+        cfg = load_config(cfg_path)
+    except Exception as e:
+        print(f"[compactor] config load failed: {e}", file=sys.stderr)
+        state.update(compaction_in_progress=False)
+        return 2
+
+    if state.read().get("paused"):
+        state.update(compaction_in_progress=False)
+        return 0
+
+    # Single-instance lock (best-effort; sufficient for single-user dev environment).
+    lock = air / "compactor.lock"
+    try:
+        fd = os.open(str(lock), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        os.write(fd, str(os.getpid()).encode())
+        os.close(fd)
+    except FileExistsError:
+        print("[compactor] another compactor is already running; exiting", file=sys.stderr)
+        return 0
+
+    try:
+        return _run_locked(project, transcript, session_id, cfg, state, air)
+    finally:
+        try:
+            os.unlink(lock)
+        except OSError:
+            pass
+
+
+def _run_locked(
+    project: Path,
+    transcript: Path,
+    session_id: str,
+    cfg: dict,
+    state: StateFile,
+    air: Path,
+) -> int:
+    state.update(compaction_in_progress=True, last_session_id=session_id)
+    msgs = load_messages(transcript)
+    chain = find_active_chain(msgs)
+    if len(chain) < MIN_CHAIN_TO_COMPACT:
+        print(
+            f"[compactor] chain too short ({len(chain)}); skipping",
+            file=sys.stderr,
+        )
+        state.update(compaction_in_progress=False)
+        return 0
+
+    comp_cfg = cfg.get("compaction") or {}
+    safety = cfg.get("safety") or {}
+    preserve_tail = int(comp_cfg.get("preserve_tail_messages", 10))
+    drop_lines = int(comp_cfg.get("drop_tool_results_over_lines", 1000))
+    rules_file = comp_cfg.get("rules_file", "rules.md")
+    continuation_prompt = comp_cfg.get("continuation_prompt", "") or ""
+
+    rules_path = air / rules_file
+    rules_text = rules_path.read_text(encoding="utf-8") if rules_path.exists() else ""
+
+    head = chain[:-preserve_tail] if preserve_tail > 0 else chain
+    tail = chain[-preserve_tail:] if preserve_tail > 0 else []
+
+    rendered = [r for r in (_serialise_message_for_llm(m) for m in head) if r]
+    rendered = _truncate_long_tool_results(rendered, drop_lines)
+    conversation_text = "\n\n".join(rendered)
+    if not conversation_text.strip():
+        print("[compactor] nothing to summarise", file=sys.stderr)
+        state.update(compaction_in_progress=False)
+        return 0
+
+    system_prompt = (
+        "You are a context-compression engine for a Claude Code session. "
+        "Apply the user-supplied compression rules below to the conversation "
+        "transcript that follows. Output ONLY the compressed summary text. "
+        "Do not add preamble, headers, or apologies.\n\n"
+        "=== USER COMPRESSION RULES ===\n"
+        f"{rules_text}\n"
+        "=== END RULES ==="
+    )
+
+    backend = build_backend(cfg)
+    print(
+        f"[compactor] calling {cfg['backend']['endpoint']} model={cfg['backend']['model']} "
+        f"head_msgs={len(head)} tail_preserved={len(tail)}",
+        file=sys.stderr,
+    )
+    try:
+        summary_text = backend.summarise(system_prompt, conversation_text)
+    except Exception as e:
+        print(f"[compactor] LLM call failed: {e}", file=sys.stderr)
+        state.update(compaction_in_progress=False)
+        return 3
+
+    if safety.get("dry_run"):
+        print(
+            f"[compactor] dry_run=true; summary length={len(summary_text)}; "
+            "JSONL not modified",
+            file=sys.stderr,
+        )
+        state.update(compaction_in_progress=False, last_compaction_unix=int(time.time()))
+        return 0
+
+    if safety.get("backup", True):
+        backup_jsonl(transcript, air / "snapshots", session_id)
+
+    template = chain[-1]  # use the latest message's metadata as template
+    summary_uuid, cont_uuid = append_isolated_summary(
+        transcript,
+        summary_text=summary_text,
+        continuation_text=continuation_prompt or None,
+        template_message=template,
+    )
+    print(
+        f"[compactor] appended summary={summary_uuid} continuation={cont_uuid}",
+        file=sys.stderr,
+    )
+
+    rotate_snapshots(air / "snapshots", int(safety.get("max_snapshots", 50)))
+
+    state.update(
+        compaction_in_progress=False,
+        compaction_ready=True,
+        pending_resume_session_id=session_id,
+        last_compaction_unix=int(time.time()),
+    )
+    return 0
+
+
+def main() -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--project", required=True)
+    p.add_argument("--transcript", required=True)
+    p.add_argument("--session-id", required=True)
+    args = p.parse_args()
+    return run(Path(args.project), Path(args.transcript), args.session_id)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/core/config_loader.py

@@ -0,0 +1,97 @@
+"""AirContext/ self-check + template installation + config validation."""
+from __future__ import annotations
+import os
+import re
+import shutil
+from pathlib import Path
+from typing import Any
+
+try:
+    import yaml  # type: ignore
+except ImportError:
+    yaml = None  # validate_config will surface a clear error
+
+
+REQUIRED_FILES = ("config.yaml", "rules.md")
+
+
+def ensure_aircontext_dir(air: Path, plugin_root: Path) -> bool:
+    """Create AirContext/ from templates if missing.
+
+    Returns True if templates were just installed (caller should ask user to
+    edit config.yaml). Returns False if the dir already existed.
+    """
+    templates = plugin_root / "templates"
+    if air.exists() and (air / "config.yaml").exists():
+        # Make sure subdirs exist even on partial installs.
+        (air / "snapshots").mkdir(exist_ok=True)
+        return False
+
+    air.mkdir(parents=True, exist_ok=True)
+    (air / "snapshots").mkdir(exist_ok=True)
+    for name in REQUIRED_FILES:
+        src = templates / name
+        dst = air / name
+        if not dst.exists() and src.exists():
+            shutil.copyfile(src, dst)
+    # README is optional but nice
+    readme_src = templates / "README.md"
+    readme_dst = air / "README.md"
+    if not readme_dst.exists() and readme_src.exists():
+        shutil.copyfile(readme_src, readme_dst)
+    return True
+
+
+_ENV_RE = re.compile(r"\$\{env:([A-Z_][A-Z0-9_]*)\}")
+
+
+def resolve_env_placeholders(value: Any) -> Any:
+    """Replace ${env:VAR} placeholders inside string values, recursively."""
+    if isinstance(value, str):
+        def _sub(m: re.Match[str]) -> str:
+            return os.environ.get(m.group(1), "")
+        return _ENV_RE.sub(_sub, value)
+    if isinstance(value, dict):
+        return {k: resolve_env_placeholders(v) for k, v in value.items()}
+    if isinstance(value, list):
+        return [resolve_env_placeholders(v) for v in value]
+    return value
+
+
+def load_config(path: Path) -> dict[str, Any]:
+    if yaml is None:
+        raise RuntimeError("PyYAML not installed. `pip install pyyaml` and retry.")
+    with path.open("r", encoding="utf-8") as f:
+        raw = yaml.safe_load(f) or {}
+    return resolve_env_placeholders(raw)
+
+
+def validate_config(path: Path) -> str | None:
+    """Return None on success, or a human-readable error string."""
+    if not path.exists():
+        return f"{path} not found"
+    try:
+        cfg = load_config(path)
+    except Exception as e:  # pragma: no cover
+        return f"failed to parse {path.name}: {e}"
+
+    backend = cfg.get("backend") or {}
+    if not backend.get("endpoint"):
+        return "backend.endpoint is required"
+    if not backend.get("model"):
+        return "backend.model is required"
+    api_key = backend.get("api_key", "")
+    if not api_key:
+        return "backend.api_key is empty (set AIRCONTEXT_API_KEY env var or fill config.yaml)"
+
+    trig = cfg.get("trigger") or {}
+    threshold = trig.get("threshold")
+    if not isinstance(threshold, (int, float)) or not 0 < float(threshold) < 1:
+        return "trigger.threshold must be a number between 0 and 1"
+
+    comp = cfg.get("compaction") or {}
+    rules_file = comp.get("rules_file", "rules.md")
+    if not (path.parent / rules_file).exists():
+        return f"rules file not found: {rules_file}"
+
+    return None

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/core/jsonl_ops.py

@@ -0,0 +1,158 @@
+"""JSONL transcript parsing + isolated-summary append.
+
+The Claude Code transcript is a JSON-Lines file where each line is a message.
+Messages form a DAG via `parentUuid`; the "active chain" is the path from the
+latest leaf back to the first message with parentUuid==null.
+
+We append a NEW chain by writing two `user` messages at the tail of the file:
+  1. summary    (parentUuid: null) — becomes a fresh chain root
+  2. continuation (parentUuid: summary.uuid) — becomes the latest leaf
+
+On `claude --resume <id>` the leaf-selection algorithm picks the continuation
+message (newest leaf) and walks back to the summary, so the loaded context is
+exactly those two messages plus the system/CLAUDE.md/etc. fixed cost.
+"""
+from __future__ import annotations
+import datetime as _dt
+import json
+import shutil
+import uuid as _uuid
+from pathlib import Path
+from typing import Any, Iterator
+
+
+def iter_messages(path: Path) -> Iterator[dict[str, Any]]:
+    with path.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                yield json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+
+def load_messages(path: Path) -> list[dict[str, Any]]:
+    return list(iter_messages(path))
+
+
+def find_active_chain(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Return messages on the active chain, ordered from root to leaf.
+
+    Mirrors `claude --resume` behaviour:
+      1. Build uuid -> message map.
+      2. Find leaves: uuids not referenced as a parentUuid by any other message.
+      3. Pick leaf with latest timestamp.
+      4. Walk parentUuid pointers back until parentUuid is null.
+    """
+    by_uuid = {m["uuid"]: m for m in messages if "uuid" in m}
+    referenced = {m.get("parentUuid") for m in messages if m.get("parentUuid")}
+    leaves = [m for m in messages if m.get("uuid") and m["uuid"] not in referenced]
+    if not leaves:
+        return []
+
+    def _ts(m: dict[str, Any]) -> str:
+        return m.get("timestamp", "")
+
+    leaf = max(leaves, key=_ts)
+
+    chain: list[dict[str, Any]] = []
+    cur: dict[str, Any] | None = leaf
+    seen: set[str] = set()
+    while cur is not None and cur.get("uuid") not in seen:
+        chain.append(cur)
+        seen.add(cur["uuid"])
+        parent_uuid = cur.get("parentUuid")
+        if not parent_uuid:
+            break
+        cur = by_uuid.get(parent_uuid)
+    chain.reverse()
+    return chain
+
+
+def _meta_from(reference: dict[str, Any]) -> dict[str, Any]:
+    """Copy non-content metadata fields from a reference message.
+
+    We deliberately only copy metadata fields, never the content/message field,
+    so callers control what payload the new message carries.
+    """
+    keep = ("sessionId", "cwd", "version", "gitBranch", "userType")
+    return {k: reference[k] for k in keep if k in reference}
+
+
+def _now_iso() -> str:
+    return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="milliseconds").replace(
+        "+00:00", "Z"
+    )
+
+
+def build_user_message(
+    *,
+    parent_uuid: str | None,
+    content: str,
+    template: dict[str, Any],
+) -> dict[str, Any]:
+    msg: dict[str, Any] = {
+        "type": "user",
+        "uuid": str(_uuid.uuid4()),
+        "parentUuid": parent_uuid,
+        "timestamp": _now_iso(),
+        "isSidechain": False,
+        **_meta_from(template),
+        "message": {"role": "user", "content": content},
+    }
+    msg.setdefault("userType", "external")
+    return msg
+
+
+def backup_jsonl(path: Path, snapshots_dir: Path, session_id: str) -> Path:
+    snapshots_dir.mkdir(parents=True, exist_ok=True)
+    ts = _dt.datetime.now().strftime("%Y%m%d-%H%M%S")
+    dst = snapshots_dir / f"{ts}-{session_id}.jsonl"
+    shutil.copyfile(path, dst)
+    return dst
+
+
+def append_isolated_summary(
+    path: Path,
+    *,
+    summary_text: str,
+    continuation_text: str | None,
+    template_message: dict[str, Any],
+) -> tuple[str, str | None]:
+    """Append summary (parentUuid=null) and optional continuation.
+
+    Returns (summary_uuid, continuation_uuid_or_None).
+    """
+    summary = build_user_message(
+        parent_uuid=None, content=summary_text, template=template_message
+    )
+    lines: list[str] = [json.dumps(summary, ensure_ascii=False) + "\n"]
+    cont_uuid: str | None = None
+    if continuation_text:
+        cont = build_user_message(
+            parent_uuid=summary["uuid"],
+            content=continuation_text,
+            template=template_message,
+        )
+        cont_uuid = cont["uuid"]
+        lines.append(json.dumps(cont, ensure_ascii=False) + "\n")
+    with path.open("a", encoding="utf-8") as f:
+        f.writelines(lines)
+    return summary["uuid"], cont_uuid
+
+
+def rotate_snapshots(snapshots_dir: Path, max_keep: int) -> None:
+    if not snapshots_dir.exists():
+        return
+    files = sorted(
+        (p for p in snapshots_dir.iterdir() if p.is_file() and p.suffix == ".jsonl"),
+        key=lambda p: p.stat().st_mtime,
+    )
+    excess = len(files) - max_keep
+    for p in files[:max(0, excess)]:
+        try:
+            p.unlink()
+        except OSError:
+            pass

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/core/state.py

@@ -0,0 +1,93 @@
+"""state.json read/write — shared between wrapper, hooks, and compactor.
+
+Schema:
+{
+  "config_missing": bool,                 # set by SessionStart hook when AirContext/ template was just created
+  "last_session_id": str | None,          # the most recent claude session id we observed
+  "pending_resume_session_id": str | null,# session id to resume after wrapper terminates claude
+  "compaction_ready": bool,               # compactor sets to true; wrapper consumes
+  "compaction_in_progress": bool,         # compactor sets to true while running, prevents re-entry
+  "last_compaction_unix": int,            # cooldown reference
+  "last_tool_count_at_compact": int,      # for tool_count strategy (reserved)
+  "paused": bool                          # /aircontext-pause toggle
+}
+"""
+from __future__ import annotations
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+_DEFAULT: dict[str, Any] = {
+    "config_missing": False,
+    "last_session_id": None,
+    "pending_resume_session_id": None,
+    "compaction_ready": False,
+    "compaction_in_progress": False,
+    "last_compaction_unix": 0,
+    "last_tool_count_at_compact": 0,
+    "paused": False,
+}
+
+
+class StateFile:
+    """Best-effort JSON state store. Writes are atomic via tmp-file rename.
+
+    Concurrency: hook scripts and the wrapper read/write concurrently. We accept
+    last-write-wins semantics for non-critical fields. The compactor uses a
+    separate lock file (see compactor.py) for the critical 'do not start two
+    compactions at once' invariant.
+    """
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        if not self.path.exists():
+            self._write_atomic(_DEFAULT.copy())
+
+    @property
+    def last_session_id(self) -> str | None:
+        return self.read().get("last_session_id")
+
+    def read(self) -> dict[str, Any]:
+        try:
+            with self.path.open("r", encoding="utf-8") as f:
+                data = json.load(f)
+        except (FileNotFoundError, json.JSONDecodeError):
+            data = _DEFAULT.copy()
+        # backfill defaults for forward-compat
+        for k, v in _DEFAULT.items():
+            data.setdefault(k, v)
+        return data
+
+    def update(self, **kwargs: Any) -> dict[str, Any]:
+        data = self.read()
+        data.update(kwargs)
+        self._write_atomic(data)
+        return data
+
+    def reset_for_new_session(self) -> None:
+        self.update(
+            compaction_ready=False,
+            compaction_in_progress=False,
+            pending_resume_session_id=None,
+        )
+
+    def clear_ready(self) -> None:
+        self.update(compaction_ready=False, pending_resume_session_id=None)
+
+    def _write_atomic(self, data: dict[str, Any]) -> None:
+        # tempfile in same dir so os.replace is atomic on the same filesystem
+        fd, tmp = tempfile.mkstemp(prefix=".state.", suffix=".tmp", dir=str(self.path.parent))
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                json.dump(data, f, indent=2)
+            os.replace(tmp, self.path)
+        except Exception:
+            try:
+                os.unlink(tmp)
+            except OSError:
+                pass
+            raise

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/core/token_estimator.py

@@ -0,0 +1,53 @@
+"""Token-usage estimation for the active chain of a JSONL transcript.
+
+v0.1 ships only `char_div_3_5` — count characters of the active chain's content
+fields and divide by 3.5. This is a rough but cheap heuristic; tiktoken-based
+estimation can be added later behind the same interface.
+"""
+from __future__ import annotations
+import json
+from pathlib import Path
+from typing import Any
+
+from .jsonl_ops import find_active_chain, load_messages
+
+
+def _char_count(content: Any) -> int:
+    if content is None:
+        return 0
+    if isinstance(content, str):
+        return len(content)
+    if isinstance(content, list):
+        total = 0
+        for item in content:
+            if isinstance(item, dict):
+                if "text" in item and isinstance(item["text"], str):
+                    total += len(item["text"])
+                elif "input" in item:
+                    total += len(json.dumps(item.get("input", {}), ensure_ascii=False))
+                elif "content" in item:
+                    total += _char_count(item["content"])
+            else:
+                total += len(str(item))
+        return total
+    if isinstance(content, dict):
+        return _char_count(content.get("content"))
+    return len(str(content))
+
+
+def _message_chars(msg: dict[str, Any]) -> int:
+    inner = msg.get("message")
+    if isinstance(inner, dict):
+        return _char_count(inner.get("content"))
+    if "tool_use_id" in msg and "content" in msg:
+        return _char_count(msg.get("content"))
+    return 0
+
+
+def estimate_active_chain_tokens(transcript: Path, *, method: str = "char_div_3_5") -> int:
+    if method != "char_div_3_5":
+        raise ValueError(f"Unsupported estimate_method: {method}")
+    msgs = load_messages(transcript)
+    chain = find_active_chain(msgs)
+    chars = sum(_message_chars(m) for m in chain)
+    return int(chars / 3.5)

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/on_pre_compact.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""PreCompact hook — block Claude Code's built-in auto-compact.
+
+Only active in projects that have opted in (AirContext/ exists). Otherwise
+Claude's default auto-compact behaviour is preserved untouched.
+
+Manual `/compact` is always allowed; auto-triggered compaction is rejected so
+AirContext's rule-driven compactor is the only thing that mutates the chain.
+"""
+from __future__ import annotations
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def main() -> int:
+    raw = sys.stdin.read() or "{}"
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        payload = {}
+
+    cwd = payload.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+    if not (Path(cwd) / "AirContext").exists():
+        return 0  # project hasn't opted in; let Claude do whatever it wants
+
+    trigger = payload.get("trigger") or payload.get("compact_trigger")
+    if trigger == "auto":
+        print(json.dumps({
+            "decision": "block",
+            "reason": (
+                "AirContext: auto-compact disabled by user policy. "
+                "Custom rule-driven compaction handles this out-of-band."
+            )
+        }))
+        return 0
+    return 0  # manual /compact passes through
+
+
+if __name__ == "__main__":
+    sys.exit(main())

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/on_session_start.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""SessionStart hook — verify AirContext/ presence and surface a friendly notice.
+
+Stage-2 implementation. For now we:
+  - look for AirContext/ in cwd
+  - if absent or invalid, set state.config_missing=true so UserPromptSubmit can block
+  - emit a SessionStart additionalContext message describing AirContext status
+"""
+from __future__ import annotations
+import json
+import os
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE))
+
+from core.config_loader import validate_config  # noqa: E402
+from core.state import StateFile  # noqa: E402
+
+
+def _find_project_root(stdin_payload: dict) -> Path:
+    cwd = stdin_payload.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+    return Path(cwd)
+
+
+def main() -> int:
+    raw = sys.stdin.read() or "{}"
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        payload = {}
+
+    project = _find_project_root(payload)
+    air = project / "AirContext"
+
+    # Project hasn't opted in — stay completely silent so AirContext doesn't
+    # pollute every Claude Code session globally.
+    if not air.exists():
+        return 0
+
+    config = air / "config.yaml"
+    state = StateFile(air / "state.json")
+
+    sid = payload.get("session_id")
+    if sid:
+        state.update(last_session_id=sid)
+
+    if not config.exists():
+        state.update(config_missing=True)
+        print(json.dumps({
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": (
+                    "AirContext: AirContext/ exists but config.yaml is missing. "
+                    "Run `/aircontext-init` to (re)install templates."
+                )
+            }
+        }))
+        return 0
+
+    err = validate_config(config)
+    if err:
+        state.update(config_missing=True)
+        print(json.dumps({
+            "hookSpecificOutput": {
+                "hookEventName": "SessionStart",
+                "additionalContext": f"AirContext config invalid: {err}"
+            }
+        }))
+        return 0
+
+    state.update(config_missing=False)
+    # Healthy — stay silent to keep prompt clean.
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/on_tool_use.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""PostToolUse hook — lightweight ticker.
+
+Responsibilities (all must complete in well under 100 ms):
+  1. Read AirContext/state.json. If paused, in-progress, or in cooldown, return.
+  2. Estimate active-chain token usage from transcript_path.
+  3. If usage / model_context_window >= trigger.threshold, fork compactor.py
+     in the background and return immediately.
+
+The compactor runs detached so it never blocks Claude's main loop.
+"""
+from __future__ import annotations
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE))
+
+from core.config_loader import load_config  # noqa: E402
+from core.state import StateFile  # noqa: E402
+from core.token_estimator import estimate_active_chain_tokens  # noqa: E402
+
+
+def _project_root(payload: dict) -> Path:
+    cwd = payload.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+    return Path(cwd)
+
+
+def _spawn_compactor(project: Path, transcript: Path, session_id: str) -> None:
+    """Detach compactor.py so the hook returns immediately."""
+    compactor = _HERE / "core" / "compactor.py"
+    args = [sys.executable, str(compactor),
+            "--project", str(project),
+            "--transcript", str(transcript),
+            "--session-id", session_id]
+    log_dir = project / "AirContext" / "snapshots"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / "compactor.log"
+
+    if os.name == "nt":
+        DETACHED = 0x00000008  # DETACHED_PROCESS
+        NEW_GROUP = 0x00000200
+        creationflags = DETACHED | NEW_GROUP
+        with log_file.open("ab") as lf:
+            subprocess.Popen(args, stdout=lf, stderr=lf, stdin=subprocess.DEVNULL,
+                             creationflags=creationflags, close_fds=True)
+    else:
+        with log_file.open("ab") as lf:
+            subprocess.Popen(args, stdout=lf, stderr=lf, stdin=subprocess.DEVNULL,
+                             start_new_session=True, close_fds=True)
+
+
+def main() -> int:
+    raw = sys.stdin.read() or "{}"
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        return 0
+
+    project = _project_root(payload)
+    air = project / "AirContext"
+    config_path = air / "config.yaml"
+    if not config_path.exists():
+        return 0  # uninitialised — nothing to do
+
+    state = StateFile(air / "state.json")
+    snap = state.read()
+    if snap.get("paused") or snap.get("compaction_in_progress") or snap.get("compaction_ready"):
+        return 0
+
+    try:
+        cfg = load_config(config_path)
+    except Exception:
+        return 0  # config broken — UserPromptSubmit will surface it
+
+    cooldown = int(cfg.get("trigger", {}).get("cooldown_seconds", 300))
+    if time.time() - snap.get("last_compaction_unix", 0) < cooldown:
+        return 0
+
+    transcript = payload.get("transcript_path")
+    if not transcript or not Path(transcript).exists():
+        return 0
+    session_id = payload.get("session_id") or snap.get("last_session_id")
+    if not session_id:
+        return 0
+
+    threshold = float(cfg.get("trigger", {}).get("threshold", 0.6))
+    window = int(cfg.get("trigger", {}).get("model_context_window", 200000))
+    method = cfg.get("trigger", {}).get("estimate_method", "char_div_3_5")
+
+    used = estimate_active_chain_tokens(Path(transcript), method=method)
+    if used / max(window, 1) < threshold:
+        return 0
+
+    # Mark in-progress immediately so successive PostToolUse calls don't double-fire.
+    state.update(compaction_in_progress=True, last_session_id=session_id)
+    _spawn_compactor(project, Path(transcript), session_id)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/scripts/on_user_prompt.py

@@ -0,0 +1,68 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook — block prompts until AirContext config is valid.
+
+When state.config_missing is true, refuse the prompt with a guidance message.
+Otherwise, pass through silently.
+"""
+from __future__ import annotations
+import json
+import os
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+sys.path.insert(0, str(_HERE))
+
+from core.config_loader import validate_config  # noqa: E402
+from core.state import StateFile  # noqa: E402
+
+
+def _project_root(payload: dict) -> Path:
+    cwd = payload.get("cwd") or os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
+    return Path(cwd)
+
+
+def main() -> int:
+    raw = sys.stdin.read() or "{}"
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError:
+        payload = {}
+
+    project = _project_root(payload)
+    air = project / "AirContext"
+
+    # Project hasn't opted in — silently allow. Users opt in by running
+    # `aircontext` (which installs templates) or `/aircontext-init`.
+    if not air.exists():
+        return 0
+
+    config = air / "config.yaml"
+    if not config.exists():
+        # Opted in but template install never completed.
+        msg = (
+            "AirContext: AirContext/ directory exists but config.yaml is missing. "
+            "Run `/aircontext-init` to reinstall templates, or remove the AirContext/ "
+            "directory if you no longer want compaction in this project."
+        )
+        print(json.dumps({"decision": "block", "reason": msg}))
+        return 0
+
+    err = validate_config(config)
+    if err:
+        msg = (
+            f"AirContext config is invalid: {err}\n"
+            "Edit AirContext/config.yaml and resubmit."
+        )
+        print(json.dumps({"decision": "block", "reason": msg}))
+        return 0
+
+    # Healthy — clear stale flag and pass through.
+    state = StateFile(air / "state.json")
+    if state.read().get("config_missing"):
+        state.update(config_missing=False)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/templates/README.md

@@ -0,0 +1,26 @@
+# AirContext (per-project)
+
+This directory configures AirContext for **this project**. It was created the
+first time you ran `aircontext` here.
+
+## Files
+
+- `config.yaml` — backend (LLM), trigger threshold, compaction options
+- `rules.md` — compression rules sent to the LLM as system prompt
+- `state.json` — runtime state (do not edit; managed by the plugin)
+- `snapshots/` — backup of each JSONL before compaction; keep or delete freely
+
+## Getting started
+
+1. Open `config.yaml`, set `backend.endpoint` / `backend.model` / `backend.api_key`.
+   The default targets DeepSeek; replace with Ollama or any OpenAI-compatible
+   server as needed. For Ollama set `endpoint: http://localhost:11434/v1` and
+   any non-empty `api_key`.
+2. Tune `trigger.threshold` (default 0.6 = compact at 60% of model context).
+3. Edit `rules.md` to bias summaries toward what your project considers important.
+4. Re-run `aircontext` from this directory.
+
+## Disabling auto compaction temporarily
+
+Run `/aircontext-pause` inside Claude Code, or set `safety.dry_run: true` in
+config.yaml.

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/templates/config.yaml

@@ -0,0 +1,44 @@
+# AirContext compaction config.
+#
+# YOU MUST FILL these two fields (privacy-sensitive, never auto-populated):
+#   - backend.endpoint   your LLM endpoint URL
+#   - backend.api_key    either a literal value, or the ${env:VAR} placeholder
+#                         pointing at an env var that holds the secret
+#
+# Everything else is auto-configured by `aircontext` on first run
+# (model_context_window inferred from your Claude model setting, etc.) and
+# you generally don't need to touch it. Edit freely if you want to override.
+# `${env:VAR}` placeholders are resolved at runtime against environment
+# variables (including those declared in ~/.claude/settings.json `env` block).
+
+backend:
+  type: anthropic_native                           # or openai_compat (auto-set by aircontext when possible)
+
+  # >>> REQUIRED — fill before re-running aircontext <<<
+  endpoint: ""                                     # e.g. https://api.anthropic.com  |  https://wolfai.top  |  http://localhost:11434/v1
+
+  # >>> REQUIRED — fill or set the env var <<<
+  api_key: ${env:ANTHROPIC_AUTH_TOKEN}             # change to ${env:OPENAI_API_KEY} or paste a literal value
+
+  model: claude-haiku-4-5-20251001                 # cheap+fast for compression; raise to claude-sonnet-4-6 if quality insufficient
+  max_output_tokens: 4000
+  timeout_seconds: 60
+  anthropic_version: "2023-06-01"                  # only used when type = anthropic_native
+
+trigger:
+  strategy: token_ratio
+  threshold: 0.6                                   # compact when active chain reaches 60% of model_context_window
+  cooldown_seconds: 300
+  estimate_method: char_div_3_5
+  model_context_window: 200000                     # auto-overridden on first aircontext run based on your claude model
+
+compaction:
+  preserve_tail_messages: 10
+  drop_tool_results_over_lines: 1000
+  rules_file: rules.md
+  continuation_prompt: "基于上面的压缩摘要继续之前的工作；如果没有进行中的任务则等待我的下一条指令。"
+
+safety:
+  backup: true
+  max_snapshots: 50
+  dry_run: false

AirPlan/docs/spec/AirPlan-ParaV2/AirContextServer/templates/rules.md

@@ -0,0 +1,30 @@
+# AirContext Compression Rules
+
+This file is fed to the compression LLM as part of its system prompt. Edit
+freely to bias what the summary keeps versus drops. The defaults below favour
+software-engineering sessions; rewrite them for your domain.
+
+## Always preserve verbatim
+
+- File paths read or modified, with the final intended state of each file
+- Architecture decisions and the reasoning behind them
+- Open TODOs, unresolved bugs, error messages still in scope
+- The user's stated goal for the current session
+- Any user-supplied facts that the model could not derive from the codebase
+  (credentials hints, deployment quirks, deadlines, "we tried X and it failed because Y")
+
+## Aggressively drop
+
+- Exploratory grep/glob results that did not lead anywhere
+- File contents that were superseded by later edits
+- Tool outputs over 1000 lines (keep first 50 lines and last 50 lines, summarise the middle)
+- Repeated similar searches and their near-identical outputs
+- Completed sub-steps whose only output was "looks good, moving on"
+
+## Output format
+
+- Plain prose, no markdown headers or bullet lists unless they materially aid recall
+- Reference files by `path:line` when relevant
+- One paragraph per topic; aim for under 3000 tokens total
+- Do NOT speculate beyond what the conversation contains
+- Do NOT apologise, summarise the act of summarising, or add meta-commentary

AirPlan/docs/spec/AirPlan-ParaV2/README.md

@@ -0,0 +1,49 @@
+# AirPlan-ParaV2 Deployment Bundle
+
+This bundle packages the Air workflow suite plus the standalone AirContext component for deployment on another computer.
+
+## Included components
+
+### Air workflow suite
+- plugins: airarc, aireng, airdo, airdbg, airxdb, airndb, airsdb
+- `lib/air_runtime`
+- `.agents/skills/*`
+- `.agents/plugins/marketplace.json`
+- `install_to_home.ps1`
+- `init_project_airplan.ps1`
+
+### AirContext
+- `AirContextServer/`
+- `install_aircontext_local.ps1`
+- `aircontext-settings-snippet.json`
+
+## Quick install
+
+### Install the Air workflow suite
+Run in PowerShell from this extracted folder:
+
+```powershell
+.\install_to_home.ps1
+```
+
+### Stage AirContext on the target machine
+Run:
+
+```powershell
+.\install_aircontext_local.ps1
+```
+
+This copies `AirContextServer` to `%USERPROFILE%\AirContextServer` and prints the settings snippet path to enable the plugin in Claude Code.
+
+### Install everything in one step
+Run:
+
+```powershell
+.\install_all.ps1
+```
+
+## Notes
+
+- `aireng` is packaged from the current updated implementation and no longer keeps `air-engine` as a public entrypoint.
+- AirContext is shipped as a separate component because it is not part of the `plugins/` development tree.
+- The bundled `aircontext-settings-snippet.json` shows the Claude settings shape needed to enable the local AirContext marketplace.

AirPlan/docs/spec/AirPlan-ParaV2/aircontext-settings-snippet.json

@@ -0,0 +1,13 @@
+{
+  "extraKnownMarketplaces": {
+    "aircontext-mkt": {
+      "source": {
+        "source": "directory",
+        "path": "C:\\Users\\<YourUser>\\AirContextServer"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "aircontext@aircontext-mkt": true
+  }
+}

AirPlan/docs/spec/AirPlan-ParaV2/bundle-manifest.json

@@ -0,0 +1,67 @@
+{
+  "bundleName": "AirPlan-ParaV2",
+  "generatedAt": "2026-04-30T11:50:37.519942+00:00",
+  "layout": "home-local-codex-plus-aircontext",
+  "includes": {
+    "plugins": [
+      {
+        "name": "airarc",
+        "version": "0.3.1",
+        "homepage": "https://airlongdian.fun/plugins/airarc"
+      },
+      {
+        "name": "aireng",
+        "version": "0.6.0",
+        "homepage": "https://airlongdian.fun/plugins/aireng"
+      },
+      {
+        "name": "airdo",
+        "version": "0.5.0",
+        "homepage": "https://airlongdian.fun/plugins/airdo"
+      },
+      {
+        "name": "airdbg",
+        "version": "0.1.4",
+        "homepage": "https://airlongdian.fun/plugins/airdbg"
+      },
+      {
+        "name": "airxdb",
+        "version": "0.2.2",
+        "homepage": "https://airlongdian.fun/plugins/airxdb"
+      },
+      {
+        "name": "airndb",
+        "version": "0.1.2",
+        "homepage": "https://airlongdian.fun/plugins/airndb"
+      },
+      {
+        "name": "airsdb",
+        "version": "0.1.1",
+        "homepage": "https://airlongdian.fun/plugins/airsdb"
+      }
+    ],
+    "skills": [
+      "airarc",
+      "aireng",
+      "airdo",
+      "airdbg",
+      "airxdb",
+      "airndb",
+      "airsdb"
+    ],
+    "sharedRuntime": [
+      "air_runtime"
+    ],
+    "marketplace": ".agents/plugins/marketplace.json",
+    "projectBootstrap": [
+      "install_to_home.ps1",
+      "init_project_airplan.ps1"
+    ],
+    "aircontext": {
+      "name": "aircontext",
+      "version": "0.1.0",
+      "root": "AirContextServer",
+      "installer": "install_aircontext_local.ps1"
+    }
+  }
+}

AirPlan/docs/spec/AirPlan-ParaV2/init_project_airplan.ps1

@@ -0,0 +1,262 @@
+param(
+    [string]$ProjectRoot = ".",
+    [switch]$Force
+)
+
+$ErrorActionPreference = "Stop"
+
+$resolvedProjectRoot = (Resolve-Path $ProjectRoot).Path
+$airPlanRoot = Join-Path $resolvedProjectRoot "AirPlan"
+
+function Ensure-Directory {
+    param([Parameter(Mandatory = $true)][string]$Path)
+    New-Item -ItemType Directory -Path $Path -Force | Out-Null
+}
+
+function Write-TextFile {
+    param(
+        [Parameter(Mandatory = $true)][string]$Path,
+        [Parameter(Mandatory = $true)][string]$Content
+    )
+
+    if ((Test-Path -LiteralPath $Path) -and (-not $Force)) {
+        Write-Output ("skipped=" + $Path)
+        return
+    }
+
+    $parent = Split-Path -Parent $Path
+    if ($parent) {
+        Ensure-Directory -Path $parent
+    }
+    [System.IO.File]::WriteAllText($Path, $Content.TrimStart("`n") + "`n", [System.Text.UTF8Encoding]::new($false))
+    Write-Output ("written=" + $Path)
+}
+
+$rootAgents = @'
+# AGENTS.md
+
+- Canonical workflow context for this repository lives in `AirPlan/AGENTS.md`.
+- Always load `AirPlan/AGENTS.md` first for project instructions, workflow rules, plan/todo state, ADR/C4 context, and current Air sync blocks.
+- Treat `AirPlan/plan.md`, `AirPlan/todo.md`, and `AirPlan/docs/` as the authoritative workflow documents.
+- Treat `AirPlan/state/` as the authoritative plugin and runtime state root.
+- This root file is only a bootstrap shim; keep real workflow context maintained inside `AirPlan/AGENTS.md`.
+'@
+
+$projectAgents = @'
+# AGENTS.md
+
+## Workflow Root
+
+- This project uses `AirPlan/` as the workflow root.
+- Keep planning, execution state, ADR, C4, validation, debug, and plugin runtime data under `AirPlan/`.
+- The repo-root `AGENTS.md` only bootstraps into this file.
+
+<!-- AIRARC:BEGIN -->
+## AirArc Workflow
+
+1. Use `AirPlan/AGENTS.md` as the canonical project context entry point.
+2. Load and maintain:
+   - `AirPlan/docs/analysis/requirements.md`
+   - `AirPlan/docs/architecture/solution-architecture.md`
+   - `AirPlan/docs/architecture/c4/module.md`
+   - `AirPlan/docs/architecture/adr/`
+3. Produce or refine `AirPlan/plan.md` and `AirPlan/todo.md`.
+4. Keep plans optimized for lower-cost follow-up sessions, including scope, validation, file targets, and parallelization boundaries.
+<!-- AIRARC:END -->
+
+<!-- AIRENG:BEGIN -->
+## AirEng Workflow
+
+1. Use `/aireng` as the scheduler for confirmed execution.
+2. Prefer `AirPlan/state/airarc/reviews/execution-plan.json`, then `AirPlan/state/airarc/reviews/parallel-review.json`, before falling back to local `AirPlan/todo.md`.
+3. Dispatch isolated `/airdo` subagents with bounded concurrency.
+4. Keep `AirPlan/todo.md`, `AirPlan/plan.md`, `AirPlan/AGENTS.md`, ADR, and C4 docs synchronized during dispatch and merge.
+5. AirEng owns global debug, XDB, repair, and document convergence.
+<!-- AIRENG:END -->
+
+<!-- AIRDO:BEGIN -->
+## AirDo Workflow
+
+1. Use `/airdo` for one narrow task slice from `AirPlan/todo.md`.
+2. Before editing, load:
+   - `AirPlan/AGENTS.md`
+   - `AirPlan/docs/architecture/adr/`
+   - `AirPlan/docs/architecture/c4/module.md`
+   - `AirPlan/plan.md`
+   - `AirPlan/todo.md`
+3. Keep task-local progress resumable in `AirPlan/state/airdo/`.
+4. When AirEng owns orchestration, return shared document changes through `documentUpdates`.
+5. Route GUI work through AirXDB, debugging through AirDbg, network evidence through AirNDB, and static analysis through AirSDB when needed.
+<!-- AIRDO:END -->
+'@
+
+$planMd = @'
+# Implementation Plan
+
+## Read First
+1. `AirPlan/AGENTS.md`
+2. `AirPlan/docs/analysis/requirements.md`
+3. `AirPlan/docs/architecture/solution-architecture.md`
+4. `AirPlan/docs/architecture/c4/module.md`
+5. `AirPlan/docs/architecture/adr/`
+6. `AirPlan/todo.md`
+
+## Goal
+- Replace this section with the concrete product or project goal.
+
+## Constraints
+- Record technical, organizational, legal, hardware, or platform constraints here.
+
+## Phases
+- Add implementation phases once AirArc planning is complete.
+
+## Validation Strategy
+- Record build, test, debug, GUI, network, and static-analysis validation commands here.
+'@
+
+$todoMd = @'
+# TODO
+
+Status values: TODO / DOING / DONE / BLOCKED
+
+| ID | Status | Module | Task | Files/Dirs | Done When | Validation | Static Analysis | ADR/C4 Update |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| T-001 | TODO | Planning | Replace with the first confirmed execution task | `AirPlan/plan.md`, `AirPlan/docs/` | Acceptance criteria are explicit and testable | Record the exact validation command | Record the static-analysis plan or why it is not applicable | Record required ADR or C4 updates |
+
+## Quality Gates
+- Run the validation command listed in `AirPlan/plan.md` before marking a task `DONE`.
+- Keep ADR and C4 docs synchronized whenever architecture, module boundaries, dependencies, or ownership change.
+- Record skipped validation, residual risk, and follow-up work explicitly.
+'@
+
+$requirementsMd = @'
+# Requirements
+
+## Product Intent
+- Replace with the user-visible outcome this repository should deliver.
+
+## Functional Requirements
+- Replace with numbered or grouped functional requirements.
+
+## Constraints
+- Replace with non-functional constraints, environmental limits, or safety rules.
+
+## Acceptance Notes
+- Replace with the most important acceptance criteria and evidence rules.
+'@
+
+$solutionArchitectureMd = @'
+# Solution Architecture
+
+## Overview
+- Replace with the top-level architecture summary.
+
+## Major Components
+- Replace with the main containers and their responsibilities.
+
+## Data And Control Flow
+- Replace with the major interaction paths between components.
+
+## Key Risks
+- Replace with the architecture risks, unknowns, and open decisions.
+'@
+
+$c4ModuleMd = @'
+# C4 Module
+
+## System Context
+- Replace with the project purpose and external actors or systems.
+
+## Containers
+- Replace with the main runtime or repository containers.
+
+## Modules
+
+| Module | Responsibility | Public Interfaces | Dependencies | Data Ownership | Quality Notes |
+| --- | --- | --- | --- | --- | --- |
+| `replace_me` | Replace with the first real module | Replace with interfaces | Replace with dependencies | Replace with owned data | Replace with testing or quality notes |
+'@
+
+$adrMd = @'
+# ADR-0001: Use AirPlan As The Workflow Root
+
+- Status: Accepted
+- Date: YYYY-MM-DD
+
+## Context
+This project needs a durable workflow root for planning, execution state, architecture context, validation evidence, and resumable AI sessions.
+
+## Decision
+Store project workflow artifacts under `AirPlan/`, use the repo-root `AGENTS.md` only as a bootstrap shim, and let `aireng` plus `airdo` maintain plan, todo, ADR, and C4 context there.
+
+## Consequences
+- Planning and execution context stay resumable across sessions.
+- Global workflow docs live in one predictable location.
+- Plugin runtime state does not clutter the main project tree.
+'@
+
+$debugLogMd = @'
+# Debug Log
+
+- Add reproducible bug investigations, root-cause notes, and validation outcomes here.
+'@
+
+$guiDebugLogMd = @'
+# GUI Debug Log
+
+- Add screenshots, GUI observations, Midscene evidence, and visual acceptance notes here.
+'@
+
+$networkLogMd = @'
+# AirNDB Log
+
+- Add packet-capture commands, pcap paths, network observations, and conclusions here.
+'@
+
+$staticAnalysisMd = @'
+# Static Analysis
+
+- Add cppcheck or other static-analysis summaries, report paths, and residual risks here.
+'@
+
+$validationReadme = @'
+# Validation Artifacts
+
+- Save build logs, flash logs, test logs, screenshots, and validation summaries under this directory.
+'@
+
+$artifactsReadme = @'
+# Artifact Output
+
+- Save generated evidence files in this directory.
+'@
+
+Ensure-Directory -Path $airPlanRoot
+Ensure-Directory -Path (Join-Path $airPlanRoot "docs\analysis")
+Ensure-Directory -Path (Join-Path $airPlanRoot "docs\architecture\adr")
+Ensure-Directory -Path (Join-Path $airPlanRoot "docs\architecture\c4")
+Ensure-Directory -Path (Join-Path $airPlanRoot "docs\debug\airxdb-artifacts")
+Ensure-Directory -Path (Join-Path $airPlanRoot "docs\network\airndb-captures")
+Ensure-Directory -Path (Join-Path $airPlanRoot "docs\validation\logs")
+Ensure-Directory -Path (Join-Path $airPlanRoot "state")
+
+Write-TextFile -Path (Join-Path $resolvedProjectRoot "AGENTS.md") -Content $rootAgents
+Write-TextFile -Path (Join-Path $airPlanRoot "AGENTS.md") -Content $projectAgents
+Write-TextFile -Path (Join-Path $airPlanRoot "plan.md") -Content $planMd
+Write-TextFile -Path (Join-Path $airPlanRoot "todo.md") -Content $todoMd
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\analysis\requirements.md") -Content $requirementsMd
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\architecture\solution-architecture.md") -Content $solutionArchitectureMd
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\architecture\c4\module.md") -Content $c4ModuleMd
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\architecture\adr\ADR-0001-use-airplan-as-the-workflow-root.md") -Content $adrMd
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\debug\debug-log.md") -Content $debugLogMd
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\debug\gui-debug-log.md") -Content $guiDebugLogMd
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\debug\airxdb-artifacts\README.md") -Content $artifactsReadme
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\network\airndb-log.md") -Content $networkLogMd
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\network\airndb-captures\README.md") -Content $artifactsReadme
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\validation\README.md") -Content $validationReadme
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\validation\logs\README.md") -Content $artifactsReadme
+Write-TextFile -Path (Join-Path $airPlanRoot "docs\staticanalysis.md") -Content $staticAnalysisMd
+
+Write-Output ("airplan_project_init=completed")
+Write-Output ("project_root=" + $resolvedProjectRoot)
+Write-Output ("airplan_root=" + $airPlanRoot)

AirPlan/docs/spec/AirPlan-ParaV2/install_aircontext_local.ps1

@@ -0,0 +1,52 @@
+$ErrorActionPreference = "Stop"
+
+$bundleRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+$homeRoot = [Environment]::GetFolderPath("UserProfile")
+$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
+$backupRoot = Join-Path $homeRoot "airplan-backups\$timestamp"
+$sourceRoot = Join-Path $bundleRoot "AirContextServer"
+$targetRoot = Join-Path $homeRoot "AirContextServer"
+$snippetPath = Join-Path $bundleRoot "aircontext-settings-snippet.json"
+
+function Backup-ItemIfExists {
+    param(
+        [Parameter(Mandatory = $true)][string]$SourcePath,
+        [Parameter(Mandatory = $true)][string]$BackupRelativePath
+    )
+
+    if (-not (Test-Path -LiteralPath $SourcePath)) {
+        return
+    }
+
+    $backupPath = Join-Path $backupRoot $BackupRelativePath
+    $backupParent = Split-Path -Parent $backupPath
+    if ($backupParent) {
+        New-Item -ItemType Directory -Path $backupParent -Force | Out-Null
+    }
+    Copy-Item -LiteralPath $SourcePath -Destination $backupPath -Recurse -Force
+}
+
+function Replace-Directory {
+    param(
+        [Parameter(Mandatory = $true)][string]$SourcePath,
+        [Parameter(Mandatory = $true)][string]$TargetPath
+    )
+
+    $targetParent = Split-Path -Parent $TargetPath
+    if ($targetParent) {
+        New-Item -ItemType Directory -Path $targetParent -Force | Out-Null
+    }
+    if (Test-Path -LiteralPath $TargetPath) {
+        Remove-Item -LiteralPath $TargetPath -Recurse -Force
+    }
+    Copy-Item -LiteralPath $SourcePath -Destination $TargetPath -Recurse -Force
+}
+
+New-Item -ItemType Directory -Path $backupRoot -Force | Out-Null
+Backup-ItemIfExists -SourcePath $targetRoot -BackupRelativePath "AirContextServer"
+Replace-Directory -SourcePath $sourceRoot -TargetPath $targetRoot
+
+Write-Output "aircontext_stage=completed"
+Write-Output ("aircontext_root=" + $targetRoot)
+Write-Output ("settings_snippet=" + $snippetPath)
+Write-Output "next_step=merge the snippet into %USERPROFILE%\.claude\settings.json or settings.local.json and enable aircontext@aircontext-mkt"

AirPlan/docs/spec/AirPlan-ParaV2/install_all.cmd

@@ -0,0 +1,2 @@
+@echo off
+

AirPlan/docs/spec/AirPlan-ParaV2/install_all.ps1

@@ -0,0 +1,8 @@
+$ErrorActionPreference = "Stop"
+
+$bundleRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+& (Join-Path $bundleRoot "install_to_home.ps1")
+& (Join-Path $bundleRoot "install_aircontext_local.ps1")
+
+Write-Output "airplan_parav2_install=completed"

AirPlan/docs/spec/AirPlan-ParaV2/install_to_home.cmd

@@ -0,0 +1,2 @@
+@echo off
+powershell -ExecutionPolicy Bypass -File "%~dp0install_to_home.ps1"

AirPlan/docs/spec/AirPlan-ParaV2/install_to_home.ps1

@@ -0,0 +1,172 @@
+$ErrorActionPreference = "Stop"
+
+$bundleRoot = Split-Path -Parent $MyInvocation.MyCommand.Path
+$homeRoot = [Environment]::GetFolderPath("UserProfile")
+$timestamp = Get-Date -Format "yyyyMMdd-HHmmss"
+$backupRoot = Join-Path $homeRoot "airplan-backups\$timestamp"
+
+$pluginNames = @(
+    "airarc",
+    "aireng",
+    "airdo",
+    "airdbg",
+    "airxdb",
+    "airndb",
+    "airsdb"
+)
+
+$skillNames = @(
+    "airarc",
+    "aireng",
+    "airdo",
+    "airdbg",
+    "airxdb",
+    "airndb",
+    "airsdb"
+)
+
+$legacyPluginNames = @("airdo-worker", "air-engine")
+$legacySkillNames = @("airdo-worker", "air-engine")
+
+function Backup-ItemIfExists {
+    param(
+        [Parameter(Mandatory = $true)][string]$SourcePath,
+        [Parameter(Mandatory = $true)][string]$BackupRelativePath
+    )
+
+    if (-not (Test-Path -LiteralPath $SourcePath)) {
+        return
+    }
+
+    $backupPath = Join-Path $backupRoot $BackupRelativePath
+    $backupParent = Split-Path -Parent $backupPath
+    if ($backupParent) {
+        New-Item -ItemType Directory -Path $backupParent -Force | Out-Null
+    }
+    Copy-Item -LiteralPath $SourcePath -Destination $backupPath -Recurse -Force
+}
+
+function Replace-Directory {
+    param(
+        [Parameter(Mandatory = $true)][string]$SourcePath,
+        [Parameter(Mandatory = $true)][string]$TargetPath
+    )
+
+    $targetParent = Split-Path -Parent $TargetPath
+    if ($targetParent) {
+        New-Item -ItemType Directory -Path $targetParent -Force | Out-Null
+    }
+    if (Test-Path -LiteralPath $TargetPath) {
+        Remove-Item -LiteralPath $TargetPath -Recurse -Force
+    }
+    Copy-Item -LiteralPath $SourcePath -Destination $TargetPath -Recurse -Force
+}
+
+function Resolve-SkillSourcePath {
+    param(
+        [Parameter(Mandatory = $true)][string]$BundleRoot,
+        [Parameter(Mandatory = $true)][string]$SkillName
+    )
+
+    $pluginSkillPath = Join-Path $BundleRoot ("plugins\" + $SkillName + "\skills\" + $SkillName)
+    if (Test-Path -LiteralPath $pluginSkillPath) {
+        return $pluginSkillPath
+    }
+
+    $legacySkillPath = Join-Path $BundleRoot (".agents\skills\" + $SkillName)
+    if (Test-Path -LiteralPath $legacySkillPath) {
+        return $legacySkillPath
+    }
+
+    throw "Skill source not found for $SkillName"
+}
+
+function Rewrite-SkillScriptReferences {
+    param(
+        [Parameter(Mandatory = $true)][string]$SkillRoot,
+        [Parameter(Mandatory = $true)][string]$PluginName
+    )
+
+    $skillMdPath = Join-Path $SkillRoot "SKILL.md"
+    if (-not (Test-Path -LiteralPath $skillMdPath)) {
+        return
+    }
+
+    $content = Get-Content -LiteralPath $skillMdPath -Raw -Encoding UTF8
+    $updated = [regex]::Replace(
+        $content,
+        'python\s+(?:\.\./\.\./scripts/|scripts/)([^\s`"]+)',
+        {
+            param($match)
+            'python "$HOME/plugins/{0}/scripts/{1}"' -f $PluginName, $match.Groups[1].Value
+        }
+    )
+
+    if ($updated -ne $content) {
+        [System.IO.File]::WriteAllText($skillMdPath, $updated, [System.Text.UTF8Encoding]::new($false))
+    }
+}
+
+New-Item -ItemType Directory -Path $backupRoot -Force | Out-Null
+
+$pluginsRoot = Join-Path $homeRoot "plugins"
+$skillsRoot = Join-Path $homeRoot ".agents\skills"
+$marketplaceRoot = Join-Path $homeRoot ".agents\plugins"
+$libRoot = Join-Path $homeRoot "lib"
+$marketplacePath = Join-Path $marketplaceRoot "marketplace.json"
+
+Backup-ItemIfExists -SourcePath $marketplacePath -BackupRelativePath ".agents\plugins\marketplace.json"
+Backup-ItemIfExists -SourcePath (Join-Path $libRoot "air_runtime") -BackupRelativePath "lib\air_runtime"
+
+foreach ($name in $pluginNames + $legacyPluginNames) {
+    Backup-ItemIfExists -SourcePath (Join-Path $pluginsRoot $name) -BackupRelativePath ("plugins\" + $name)
+}
+
+foreach ($name in $skillNames + $legacySkillNames) {
+    Backup-ItemIfExists -SourcePath (Join-Path $skillsRoot $name) -BackupRelativePath (".agents\skills\" + $name)
+}
+
+foreach ($name in $legacyPluginNames) {
+    $target = Join-Path $pluginsRoot $name
+    if (Test-Path -LiteralPath $target) {
+        Remove-Item -LiteralPath $target -Recurse -Force
+    }
+}
+
+foreach ($name in $legacySkillNames) {
+    $target = Join-Path $skillsRoot $name
+    if (Test-Path -LiteralPath $target) {
+        Remove-Item -LiteralPath $target -Recurse -Force
+    }
+}
+
+foreach ($name in $pluginNames) {
+    Replace-Directory `
+        -SourcePath (Join-Path $bundleRoot ("plugins\" + $name)) `
+        -TargetPath (Join-Path $pluginsRoot $name)
+}
+
+foreach ($name in $skillNames) {
+    Replace-Directory `
+        -SourcePath (Resolve-SkillSourcePath -BundleRoot $bundleRoot -SkillName $name) `
+        -TargetPath (Join-Path $skillsRoot $name)
+    Rewrite-SkillScriptReferences `
+        -SkillRoot (Join-Path $skillsRoot $name) `
+        -PluginName $name
+}
+
+Replace-Directory `
+    -SourcePath (Join-Path $bundleRoot "lib\air_runtime") `
+    -TargetPath (Join-Path $libRoot "air_runtime")
+
+New-Item -ItemType Directory -Path $marketplaceRoot -Force | Out-Null
+Copy-Item `
+    -LiteralPath (Join-Path $bundleRoot ".agents\plugins\marketplace.json") `
+    -Destination $marketplacePath `
+    -Force
+
+Write-Output "airplan_install=completed"
+Write-Output ("home_root=" + $homeRoot)
+Write-Output ("backup_root=" + $backupRoot)
+Write-Output ("plugins=" + ($pluginNames -join ","))
+Write-Output ("skills=" + ($skillNames -join ","))

AirPlan/docs/spec/AirPlan-ParaV2/lib/air_runtime/__init__.py

@@ -0,0 +1,103 @@
+from .contracts import (
+    DEFAULT_DEBUG_POLICY,
+    DEFAULT_XDB_POLICY,
+    DEFAULT_REPAIR_POLICY,
+    ParallelGroup,
+    ParallelReview,
+    RepairAttempt,
+    ReviewConflict,
+    TaskRecord,
+    ValidationRecord,
+    WorkerResult,
+    XdbSession,
+    default_worker_result,
+    now_iso,
+)
+from .airxdb_runtime import (
+    ensure_xdb_sessions_for_result,
+    list_xdb_sessions,
+    load_xdb_policy,
+    merge_xdb_sessions_into_state,
+    normalize_xdb_policy,
+    task_requires_xdb,
+)
+from .debug_runtime import (
+    ensure_debug_sessions_for_result,
+    list_debug_sessions,
+    load_debug_policy,
+    merge_debug_sessions_into_state,
+    normalize_debug_policy,
+)
+from .repair_runtime import (
+    ensure_repair_attempts_for_result,
+    list_repair_attempts,
+    load_active_repair_attempt,
+    load_repair_policy,
+    merge_repair_attempts_into_state,
+    normalize_repair_policy,
+    summarize_active_repairs,
+    write_repair_queue,
+)
+from .engine import (
+    artifact_health,
+    build_engine_plan,
+    enter_engine,
+    merge_worker_result,
+    status_engine,
+)
+from .doc_sync import (
+    apply_document_updates,
+    enforce_doc_sync_requirements,
+    sync_engine_managed_docs,
+    update_todo_after_merge,
+)
+from .review import build_parallel_review, render_review_markdown
+from .todo_parser import find_task, parse_tasks
+
+__all__ = [
+    "DEFAULT_DEBUG_POLICY",
+    "DEFAULT_XDB_POLICY",
+    "DEFAULT_REPAIR_POLICY",
+    "ParallelGroup",
+    "ParallelReview",
+    "RepairAttempt",
+    "ReviewConflict",
+    "TaskRecord",
+    "ValidationRecord",
+    "WorkerResult",
+    "XdbSession",
+    "artifact_health",
+    "apply_document_updates",
+    "build_engine_plan",
+    "build_parallel_review",
+    "default_worker_result",
+    "ensure_xdb_sessions_for_result",
+    "ensure_debug_sessions_for_result",
+    "enforce_doc_sync_requirements",
+    "enter_engine",
+    "find_task",
+    "list_xdb_sessions",
+    "list_debug_sessions",
+    "list_repair_attempts",
+    "load_active_repair_attempt",
+    "load_xdb_policy",
+    "load_debug_policy",
+    "load_repair_policy",
+    "merge_xdb_sessions_into_state",
+    "merge_debug_sessions_into_state",
+    "merge_repair_attempts_into_state",
+    "merge_worker_result",
+    "normalize_xdb_policy",
+    "normalize_debug_policy",
+    "normalize_repair_policy",
+    "now_iso",
+    "parse_tasks",
+    "render_review_markdown",
+    "summarize_active_repairs",
+    "sync_engine_managed_docs",
+    "task_requires_xdb",
+    "status_engine",
+    "update_todo_after_merge",
+    "write_repair_queue",
+    "ensure_repair_attempts_for_result",
+]

AirPlan/docs/spec/AirPlan-ParaV2/lib/air_runtime/airxdb_runtime.py

@@ -0,0 +1,817 @@
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+from typing import Dict, Iterable, List, Tuple
+
+from .contracts import (
+    DEFAULT_XDB_POLICY,
+    TaskRecord,
+    ValidationRecord,
+    WorkerResult,
+    XdbSession,
+    now_iso,
+)
+from .paths import (
+    agents_path,
+    aireng_root,
+    airxdb_artifacts_dir,
+    airxdb_root,
+    architecture_adr_dir,
+    architecture_c4_module_path,
+    gui_debug_log_path,
+    todo_path,
+)
+from .todo_parser import find_task, parse_tasks
+
+
+def _json_load(path: Path) -> Dict[str, object]:
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8-sig"))
+
+
+def _json_dump(path: Path, payload: Dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def _ordered_unique(items: Iterable[str]) -> List[str]:
+    seen = set()
+    ordered: List[str] = []
+    for item in items:
+        cleaned = str(item).strip()
+        if not cleaned or cleaned in seen:
+            continue
+        seen.add(cleaned)
+        ordered.append(cleaned)
+    return ordered
+
+
+def normalize_xdb_policy(policy: Dict[str, object] | None = None) -> Dict[str, object]:
+    merged = dict(DEFAULT_XDB_POLICY)
+    if policy:
+        merged.update(policy)
+
+    merged["enabled"] = bool(merged.get("enabled", True))
+    merged["requireForGuiTasks"] = bool(merged.get("requireForGuiTasks", True))
+    merged["captureOnBlocked"] = bool(merged.get("captureOnBlocked", True))
+    merged["captureOnDone"] = bool(merged.get("captureOnDone", True))
+    merged["preferOriginalAirXDB"] = bool(merged.get("preferOriginalAirXDB", True))
+    merged["remoteFirstIfConfigured"] = bool(merged.get("remoteFirstIfConfigured", True))
+    merged["triggerValidationStatuses"] = _ordered_unique(
+        str(item).lower() for item in list(merged.get("triggerValidationStatuses", []))
+    )
+    merged["taskKeywords"] = _ordered_unique(
+        str(item).lower() for item in list(merged.get("taskKeywords", []))
+    )
+    try:
+        max_sessions = int(merged.get("maxSessionsPerTask", 1) or 1)
+    except (TypeError, ValueError):
+        max_sessions = 1
+    merged["maxSessionsPerTask"] = max(1, max_sessions)
+    return merged
+
+
+def load_xdb_policy(project_root: Path) -> Dict[str, object]:
+    state_path = aireng_root(project_root) / "state.json"
+    state = _json_load(state_path)
+    return normalize_xdb_policy(state.get("xdbPolicy", {}))
+
+
+def merge_xdb_sessions_into_state(
+    state: Dict[str, object], xdb_sessions: List[XdbSession]
+) -> Dict[str, object]:
+    state["xdbPolicy"] = normalize_xdb_policy(dict(state.get("xdbPolicy", {})))
+
+    existing_items = list(state.get("xdbSessions", []))
+    seen_ids = {
+        str(item.get("sessionId", "")).strip()
+        for item in existing_items
+        if isinstance(item, dict)
+    }
+    for session in xdb_sessions:
+        if session.session_id in seen_ids:
+            continue
+        existing_items.append(session.to_dict())
+        seen_ids.add(session.session_id)
+
+    task_counts: Dict[str, int] = {}
+    for item in existing_items:
+        task_id = str(item.get("taskId", "")).strip()
+        if not task_id:
+            continue
+        task_counts[task_id] = task_counts.get(task_id, 0) + 1
+
+    state["xdbSessions"] = existing_items
+    state["taskXdbCounts"] = task_counts
+    if xdb_sessions:
+        latest = xdb_sessions[-1]
+        state["lastXdbSessionId"] = latest.session_id
+        state["lastXdbTaskId"] = latest.task_id
+        state["lastXdbAt"] = latest.created_at
+    return state
+
+
+def _xdb_paths(project_root: Path) -> Dict[str, Path]:
+    root = airxdb_root(project_root)
+    return {
+        "root": root,
+        "state": root / "state.json",
+        "requests": root / "requests",
+        "sessions": root / "sessions",
+        "artifacts": airxdb_artifacts_dir(project_root),
+        "gui_debug_log": gui_debug_log_path(project_root),
+    }
+
+
+def _airxdb_health(project_root: Path) -> Dict[str, bool]:
+    paths = _xdb_paths(project_root)
+    return {
+        "AirPlan/AGENTS.md": agents_path(project_root).exists(),
+        "AirPlan/docs/architecture/c4/module.md": architecture_c4_module_path(project_root).exists(),
+        "AirPlan/docs/architecture/adr": architecture_adr_dir(project_root).exists(),
+        "gui_debug_log": paths["gui_debug_log"].exists(),
+    }
+
+
+def _ensure_xdb_layout(project_root: Path) -> Dict[str, Path]:
+    paths = _xdb_paths(project_root)
+    paths["requests"].mkdir(parents=True, exist_ok=True)
+    paths["sessions"].mkdir(parents=True, exist_ok=True)
+    paths["artifacts"].mkdir(parents=True, exist_ok=True)
+    paths["gui_debug_log"].parent.mkdir(parents=True, exist_ok=True)
+    if not paths["gui_debug_log"].exists():
+        paths["gui_debug_log"].write_text("# GUI Debug Log\n\n", encoding="utf-8")
+    return paths
+
+
+def _resolve_original_airxdb_script(script_name: str) -> Path | None:
+    candidates = [
+        Path.home() / "plugins" / "airxdb" / "scripts" / script_name,
+        Path(r"C:\Users\20392\plugins\airxdb\scripts") / script_name,
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _bootstrap_airxdb(project_root: Path, prefer_original: bool) -> Tuple[str, str, str]:
+    mode = "runtime-bootstrap"
+    stdout = ""
+    error = ""
+    script_path = (
+        _resolve_original_airxdb_script("airxdb_mode.py") if prefer_original else None
+    )
+
+    if script_path is not None:
+        try:
+            completed = subprocess.run(
+                [
+                    sys.executable,
+                    str(script_path),
+                    "--mode",
+                    "enter",
+                    "--project",
+                    str(project_root),
+                ],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            mode = "original-airxdb"
+            stdout = completed.stdout.strip()
+        except subprocess.CalledProcessError as exc:
+            mode = "runtime-fallback"
+            stdout = exc.stdout.strip()
+            error = exc.stderr.strip() or str(exc)
+
+    paths = _ensure_xdb_layout(project_root)
+    state = _json_load(paths["state"])
+    state["enabled"] = True
+    state["updatedAt"] = now_iso()
+    state["projectRoot"] = str(project_root)
+    state["artifactHealth"] = _airxdb_health(project_root)
+    if stdout:
+        state["lastBootstrapStdout"] = stdout
+    if error:
+        state["lastBootstrapError"] = error
+    _json_dump(paths["state"], state)
+    return mode, stdout, error
+
+
+def list_xdb_sessions(project_root: Path, task_id: str = "") -> List[XdbSession]:
+    session_dir = _xdb_paths(project_root)["sessions"]
+    if not session_dir.exists():
+        return []
+
+    sessions: List[XdbSession] = []
+    for path in sorted(session_dir.glob("*.json")):
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8-sig"))
+            session_payload = payload.get("xdbSession", payload)
+            session = XdbSession.from_dict(session_payload)
+            session.validate()
+        except (json.JSONDecodeError, TypeError, ValueError):
+            continue
+        if task_id and session.task_id != task_id:
+            continue
+        sessions.append(session)
+
+    sessions.sort(key=lambda item: (item.created_at, item.session_id))
+    return sessions
+
+
+def _load_task(project_root: Path, task_id: str) -> TaskRecord | None:
+    current_todo_path = todo_path(project_root)
+    if not current_todo_path.exists():
+        return None
+    try:
+        return find_task(parse_tasks(current_todo_path), task_id)
+    except ValueError:
+        return None
+
+
+def _parse_env_file(path: Path) -> Dict[str, str]:
+    if not path.exists():
+        return {}
+    payload: Dict[str, str] = {}
+    for raw_line in path.read_text(encoding="utf-8-sig").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        value = value.strip().strip('"').strip("'")
+        if key and value:
+            payload[key] = value
+    return payload
+
+
+def _is_remote_configured(project_root: Path) -> bool:
+    if os.environ.get("AIRXDB_REMOTE_SSH_TARGET", "").strip():
+        return True
+    remote_env = airxdb_root(project_root) / "remote-device.env"
+    return bool(_parse_env_file(remote_env).get("AIRXDB_REMOTE_SSH_TARGET", "").strip())
+
+
+def task_requires_xdb(
+    task: TaskRecord | None,
+    result: WorkerResult | None,
+    policy: Dict[str, object] | None = None,
+) -> bool:
+    effective_policy = normalize_xdb_policy(policy)
+    if not bool(effective_policy.get("enabled", True)):
+        return False
+    if not bool(effective_policy.get("requireForGuiTasks", True)):
+        return False
+
+    keyword_set = {
+        str(item).lower().strip()
+        for item in list(effective_policy.get("taskKeywords", []))
+        if str(item).strip()
+    }
+    search_parts = []
+    if task is not None:
+        search_parts.extend(
+            [
+                task.module,
+                task.task,
+                task.files_dirs,
+                task.done_when,
+                task.validation,
+                task.adr_c4_update,
+            ]
+        )
+    if result is not None:
+        search_parts.extend(
+            [
+                result.summary,
+                " ".join(result.files_changed),
+                " ".join(result.evidence_paths),
+                " ".join(result.blockers),
+                " ".join(item.kind for item in result.validations),
+                " ".join(item.command for item in result.validations),
+            ]
+        )
+    blob = " ".join(search_parts).lower()
+    for keyword in keyword_set:
+        pattern = re.compile(rf"(?<![a-z0-9]){re.escape(keyword)}(?![a-z0-9])")
+        if pattern.search(blob):
+            return True
+    return False
+
+
+def _result_trigger_summary(
+    task: TaskRecord | None,
+    result: WorkerResult,
+    policy: Dict[str, object],
+) -> Tuple[bool, List[str], str]:
+    if not task_requires_xdb(task, result, policy):
+        return False, [], ""
+
+    triggers: List[str] = []
+    reasons: List[str] = []
+
+    if result.status == "done" and bool(policy.get("captureOnDone", True)):
+        triggers.append("done-acceptance")
+        reasons.append("GUI acceptance requires AirXDB evidence before closure")
+
+    if result.status == "blocked" and bool(policy.get("captureOnBlocked", True)):
+        triggers.append("blocked-visual")
+        reasons.append("blocked GUI result should capture current screen evidence")
+
+    tracked_validation_statuses = {
+        str(item).lower() for item in list(policy.get("triggerValidationStatuses", []))
+    }
+    failed_validations = [
+        item
+        for item in result.validations
+        if item.status.lower() in tracked_validation_statuses
+    ]
+    if failed_validations:
+        triggers.append("validation-failure")
+        reasons.append(
+            "GUI-related validation failures: "
+            + ", ".join(f"{item.kind}:{item.status}" for item in failed_validations)
+        )
+
+    return bool(triggers), triggers, "; ".join(reasons)
+
+
+def _session_stamp() -> str:
+    return now_iso().replace(":", "-").replace(".", "-").replace("+", "-")
+
+
+def _session_trigger_set(session: XdbSession) -> set[str]:
+    return {
+        item.strip()
+        for item in session.trigger.split(",")
+        if item.strip()
+    }
+
+
+def _session_matches_triggers(session: XdbSession, triggers: List[str]) -> bool:
+    if not triggers:
+        return False
+    trigger_set = set(triggers)
+    return trigger_set.issubset(_session_trigger_set(session))
+
+
+def _parse_kv_output(stdout: str) -> Dict[str, str]:
+    payload: Dict[str, str] = {}
+    for raw_line in stdout.splitlines():
+        line = raw_line.strip()
+        if not line or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        payload[key.strip()] = value.strip()
+    return payload
+
+
+def _load_report_payload(report_path: Path) -> Dict[str, object]:
+    if not report_path or not report_path.exists() or not report_path.is_file():
+        return {}
+    try:
+        return json.loads(report_path.read_text(encoding="utf-8-sig"))
+    except json.JSONDecodeError:
+        return {}
+
+
+def _extract_report_images(report_payload: Dict[str, object]) -> List[str]:
+    images: List[str] = []
+    screenshot = str(report_payload.get("screenshot", "")).strip()
+    if screenshot:
+        images.append(screenshot)
+    for step in list(report_payload.get("steps", [])):
+        if not isinstance(step, dict):
+            continue
+        for image in list(step.get("images", [])):
+            cleaned = str(image).strip()
+            if cleaned:
+                images.append(cleaned)
+    return _ordered_unique(images)
+
+
+def _capture_airxdb(
+    project_root: Path, policy: Dict[str, object]
+) -> Tuple[str, str, Dict[str, str], str, str]:
+    prefer_original = bool(policy.get("preferOriginalAirXDB", True))
+    output_dir = _xdb_paths(project_root)["artifacts"]
+
+    remote_first = bool(policy.get("remoteFirstIfConfigured", True)) and _is_remote_configured(
+        project_root
+    )
+    def run_capture(script_name: str, mode: str, remote_mode: bool) -> Tuple[str, str, Dict[str, str], str, str]:
+        script_path = _resolve_original_airxdb_script(script_name) if prefer_original else None
+        if script_path is None:
+            return (
+                mode,
+                "failed",
+                {},
+                "",
+                f"AirXDB helper script not found: {script_name}",
+            )
+
+        command = [
+            sys.executable,
+            str(script_path),
+            "--project",
+            str(project_root),
+            "--output-dir",
+            str(output_dir),
+            "--action",
+            "screenshot",
+        ]
+        completed = subprocess.run(
+            command,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        stdout = completed.stdout.strip()
+        stderr = completed.stderr.strip()
+        parsed = _parse_kv_output(stdout)
+        status_key = "airxdb_remote_status" if remote_mode else "airxdb_smoke"
+        status = parsed.get(status_key, "")
+        if not status:
+            status = "ok" if completed.returncode == 0 else "failed"
+        if completed.returncode != 0 and status == "ok":
+            status = "failed"
+        return mode, status, parsed, stdout, stderr
+
+    if not remote_first:
+        return run_capture("airxdb_computer_mcp_smoke.py", "local-screenshot", False)
+
+    remote_attempt = run_capture("airxdb_remote_device.py", "remote-screenshot", True)
+    if remote_attempt[1] == "ok":
+        return remote_attempt
+
+    local_attempt = run_capture("airxdb_computer_mcp_smoke.py", "local-screenshot", False)
+    if local_attempt[1] == "ok":
+        parsed = dict(local_attempt[2])
+        parsed["fallbackFrom"] = remote_attempt[0]
+        parsed["fallbackRemoteStdout"] = remote_attempt[3]
+        parsed["fallbackRemoteError"] = remote_attempt[4]
+        return (
+            "remote-fallback-local",
+            local_attempt[1],
+            parsed,
+            "\n".join(
+                part
+                for part in [
+                    f"[remote-attempt]\n{remote_attempt[3]}",
+                    f"[local-attempt]\n{local_attempt[3]}",
+                ]
+                if part.strip()
+            ),
+            "\n".join(
+                part
+                for part in [
+                    f"[remote-attempt]\n{remote_attempt[4]}",
+                    f"[local-attempt]\n{local_attempt[4]}",
+                ]
+                if part.strip()
+            ),
+        )
+
+    parsed = dict(remote_attempt[2])
+    parsed["fallbackLocalStdout"] = local_attempt[3]
+    parsed["fallbackLocalError"] = local_attempt[4]
+    return (
+        "remote-fallback-local",
+        "failed",
+        parsed,
+        "\n".join(
+            part
+            for part in [
+                f"[remote-attempt]\n{remote_attempt[3]}",
+                f"[local-attempt]\n{local_attempt[3]}",
+            ]
+            if part.strip()
+        ),
+        "\n".join(
+            part
+            for part in [
+                f"[remote-attempt]\n{remote_attempt[4]}",
+                f"[local-attempt]\n{local_attempt[4]}",
+            ]
+            if part.strip()
+        ),
+    )
+
+
+def _append_gui_debug_log(
+    gui_debug_log_path: Path,
+    task: TaskRecord | None,
+    result: WorkerResult,
+    session: XdbSession,
+    bootstrap_mode: str,
+) -> None:
+    target_surface = task.module if task is not None else "unknown"
+    screenshot_text = ", ".join(f"`{item}`" for item in session.screenshots) or "`none`"
+    entry_lines = [
+        f"### {session.created_at}: auto-xdb capture for {result.task_id}",
+        "",
+        f"- Target surface: {target_surface}",
+        f"- Task: `{result.task_id}`",
+        f"- Source: `{session.source}`",
+        f"- Trigger: `{session.trigger}`",
+        f"- Midscene mode: `{session.mode}`",
+        f"- Symptom: {result.summary}",
+        "- Expected: GUI acceptance evidence should exist before closure, and blocked GUI paths should keep reproducible screen evidence.",
+        f"- Actual: worker status `{result.status}`; blockers={', '.join(result.blockers) or 'none'}",
+        f"- Report path: `{session.report_path or 'n/a'}`",
+        f"- Screenshots: {screenshot_text}",
+        f"- AirDbg handoff: linked debug sessions={', '.join(f'`{item.session_id}`' for item in result.debug_sessions) or '`none`'}",
+        f"- Validation after fix: pending runtime merge; bootstrap mode `{bootstrap_mode}`; xdb status `{session.status}`",
+        f"- ADR/C4 updates: {'required' if task and task.global_doc_paths else 'none'}",
+        f"- Residual risk: {'GUI acceptance is not complete until XDB evidence is successful.' if session.status != 'captured' else 'none'}",
+        "",
+    ]
+    existing = (
+        gui_debug_log_path.read_text(encoding="utf-8")
+        if gui_debug_log_path.exists()
+        else "# GUI Debug Log\n\n"
+    )
+    gui_debug_log_path.write_text(
+        existing.rstrip() + "\n\n" + "\n".join(entry_lines),
+        encoding="utf-8",
+    )
+
+
+def _update_airxdb_state(
+    project_root: Path,
+    session: XdbSession,
+    bootstrap_mode: str,
+    bootstrap_stdout: str,
+    bootstrap_error: str,
+    capture_stdout: str,
+    capture_error: str,
+) -> None:
+    paths = _ensure_xdb_layout(project_root)
+    state = _json_load(paths["state"])
+    sessions = list(state.get("autoXdbSessions", []))
+    known_ids = {
+        str(item.get("sessionId", "")).strip()
+        for item in sessions
+        if isinstance(item, dict)
+    }
+    if session.session_id not in known_ids:
+        sessions.append(
+            {
+                "sessionId": session.session_id,
+                "taskId": session.task_id,
+                "source": session.source,
+                "trigger": session.trigger,
+                "status": session.status,
+                "createdAt": session.created_at,
+                "requestPath": session.request_path,
+                "reportPath": session.report_path,
+            }
+        )
+
+    state["enabled"] = True
+    state["updatedAt"] = now_iso()
+    state["projectRoot"] = str(project_root)
+    state["artifactHealth"] = _airxdb_health(project_root)
+    state["autoXdbSessions"] = sessions
+    state["autoXdbSessionCount"] = len(sessions)
+    state["lastAutoXdbAt"] = session.created_at
+    state["lastAutoXdbSessionId"] = session.session_id
+    state["lastBootstrapMode"] = bootstrap_mode
+    if bootstrap_stdout:
+        state["lastBootstrapStdout"] = bootstrap_stdout
+    if bootstrap_error:
+        state["lastBootstrapError"] = bootstrap_error
+    if capture_stdout:
+        state["lastCaptureStdout"] = capture_stdout
+    if capture_error:
+        state["lastCaptureError"] = capture_error
+    _json_dump(paths["state"], state)
+
+
+def _attach_session_to_result(result: WorkerResult, session: XdbSession, note: str) -> None:
+    if not any(item.session_id == session.session_id for item in result.xdb_sessions):
+        result.xdb_sessions.append(session)
+    for path in [session.request_path, session.gui_debug_log_path, session.state_path, session.report_path]:
+        if path and path not in result.evidence_paths:
+            result.evidence_paths.append(path)
+    for path in session.screenshots:
+        if path and path not in result.evidence_paths:
+            result.evidence_paths.append(path)
+    if note not in result.notes:
+        result.notes.append(note)
+
+
+def _session_linked_to_result(result: WorkerResult, session: XdbSession) -> bool:
+    linked_paths = set(result.evidence_paths)
+    session_paths = {
+        session.request_path,
+        session.report_path,
+        session.gui_debug_log_path,
+        session.state_path,
+        *session.screenshots,
+    }
+    return bool(linked_paths.intersection(path for path in session_paths if path))
+
+
+def _mark_xdb_capture_blocker(result: WorkerResult, reason: str, session: XdbSession | None = None) -> None:
+    result.status = "blocked"
+    if reason not in result.blockers:
+        result.blockers.append(reason)
+
+    evidence = []
+    if session is not None:
+        evidence.extend(
+            [
+                session.request_path,
+                session.report_path,
+                session.gui_debug_log_path,
+                *session.screenshots,
+            ]
+        )
+    evidence = [item for item in evidence if item]
+    if not any(
+        item.kind == "airxdb-acceptance" and item.status == "failed"
+        for item in result.validations
+    ):
+        result.validations.append(
+            ValidationRecord(
+                kind="airxdb-acceptance",
+                status="failed",
+                command="automatic AirXDB capture",
+                evidence=evidence,
+            )
+        )
+    note = f"AirXDB acceptance was downgraded to blocked: {reason}"
+    if note not in result.notes:
+        result.notes.append(note)
+
+
+def _latest_successful_session(sessions: List[XdbSession]) -> XdbSession | None:
+    for session in reversed(sessions):
+        if session.status == "captured":
+            return session
+    return None
+
+
+def ensure_xdb_sessions_for_result(
+    project_root: Path,
+    result: WorkerResult,
+    source: str,
+    strict_done: bool = True,
+) -> List[XdbSession]:
+    policy = load_xdb_policy(project_root)
+    task = _load_task(project_root, result.task_id)
+    needs_capture, triggers, reason = _result_trigger_summary(task, result, policy)
+    if not needs_capture:
+        return result.xdb_sessions
+
+    current_matching = [
+        item for item in result.xdb_sessions if _session_matches_triggers(item, triggers)
+    ]
+    successful_current = _latest_successful_session(current_matching)
+    if successful_current is not None:
+        _attach_session_to_result(
+            result,
+            successful_current,
+            f"Reused current AirXDB session for {result.task_id}: {successful_current.session_id}",
+        )
+        return result.xdb_sessions
+
+    existing_sessions = list_xdb_sessions(project_root, result.task_id)
+    matching_existing = [
+        item for item in existing_sessions if _session_matches_triggers(item, triggers)
+    ]
+    successful_existing = _latest_successful_session(matching_existing)
+    if (
+        source != "worker-finish"
+        and successful_existing is not None
+        and _session_linked_to_result(result, successful_existing)
+    ):
+        _attach_session_to_result(
+            result,
+            successful_existing,
+            f"Reused existing AirXDB session for {result.task_id}: {successful_existing.session_id}",
+        )
+        return result.xdb_sessions
+
+    session_limit = int(policy.get("maxSessionsPerTask", 1) or 1)
+    if source != "worker-finish" and len(matching_existing) >= session_limit:
+        latest_matching = matching_existing[-1] if matching_existing else None
+        if latest_matching is not None:
+            if _session_linked_to_result(result, latest_matching):
+                _attach_session_to_result(
+                    result,
+                    latest_matching,
+                    f"Reused latest matching AirXDB session for {result.task_id}: {latest_matching.session_id}",
+                )
+            else:
+                latest_matching = None
+        if strict_done and result.status == "done":
+            _mark_xdb_capture_blocker(
+                result,
+                f"AirXDB acceptance evidence is stale or exhausted for {result.task_id}",
+                latest_matching,
+            )
+        return result.xdb_sessions
+
+    paths = _ensure_xdb_layout(project_root)
+    bootstrap_mode, bootstrap_stdout, bootstrap_error = _bootstrap_airxdb(
+        project_root, bool(policy.get("preferOriginalAirXDB", True))
+    )
+    mode, capture_status, parsed, capture_stdout, capture_error = _capture_airxdb(
+        project_root, policy
+    )
+
+    created_at = now_iso()
+    session_id = f"{result.task_id}-{_session_stamp()}"
+    request_path = paths["requests"] / f"{session_id}.json"
+    session_path = paths["sessions"] / f"{session_id}.json"
+    report_path = (
+        Path(str(parsed.get("report", "")).strip()).resolve()
+        if str(parsed.get("report", "")).strip()
+        else None
+    )
+    report_payload = _load_report_payload(report_path)
+    screenshots = _extract_report_images(report_payload)
+    remote_target = parsed.get("target", "")
+    status = "captured" if capture_status == "ok" else "failed"
+    session = XdbSession(
+        session_id=session_id,
+        task_id=result.task_id,
+        source=source,
+        trigger=",".join(triggers),
+        reason=reason,
+        request_path=str(request_path),
+        gui_debug_log_path=str(paths["gui_debug_log"]),
+        report_path=str(report_path) if report_path is not None else "",
+        state_path=str(paths["state"]),
+        mode=mode,
+        status=status,
+        screenshots=screenshots,
+        created_at=created_at,
+        remote_target=remote_target,
+    )
+
+    _json_dump(
+        request_path,
+        {
+            "taskId": result.task_id,
+            "source": source,
+            "trigger": triggers,
+            "reason": reason,
+            "requestedAt": created_at,
+            "bootstrapMode": bootstrap_mode,
+            "captureMode": mode,
+            "captureStatus": capture_status,
+            "captureParsedOutput": parsed,
+            "bootstrapStdout": bootstrap_stdout,
+            "bootstrapError": bootstrap_error,
+            "captureStdout": capture_stdout,
+            "captureError": capture_error,
+            "resultSummary": result.summary,
+            "validationStatuses": [item.to_dict() for item in result.validations],
+        },
+    )
+    _json_dump(
+        session_path,
+        {
+            "xdbSession": session.to_dict(),
+            "captureReport": report_payload,
+        },
+    )
+
+    _append_gui_debug_log(paths["gui_debug_log"], task, result, session, bootstrap_mode)
+    _update_airxdb_state(
+        project_root,
+        session,
+        bootstrap_mode,
+        bootstrap_stdout,
+        bootstrap_error,
+        capture_stdout,
+        capture_error,
+    )
+    _attach_session_to_result(
+        result,
+        session,
+        (
+            f"AirXDB evidence captured for {result.task_id}: {session.session_id}"
+            if session.status == "captured"
+            else f"AirXDB capture failed for {result.task_id}: {session.session_id}"
+        ),
+    )
+
+    if strict_done and result.status == "done" and session.status != "captured":
+        _mark_xdb_capture_blocker(
+            result,
+            f"AirXDB acceptance capture failed for {result.task_id}",
+            session,
+        )
+    return result.xdb_sessions

AirPlan/docs/spec/AirPlan-ParaV2/lib/air_runtime/contracts.py

@@ -0,0 +1,617 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List
+
+from .paths import required_project_artifacts
+
+KNOWN_TASK_STATUSES = {"TODO", "DOING", "DONE", "BLOCKED"}
+ACTIVE_TASK_STATUSES = {"TODO", "DOING"}
+FINAL_WORKER_STATUSES = {"done", "blocked", "skipped"}
+DOCUMENT_UPDATE_ACTIONS = {"replace_block", "append_lines", "create_file"}
+DEFAULT_WORKER_RESULT_NOTE = (
+    "Do not merge this result until summary, filesChanged, validations, and risks are reviewed."
+)
+DEFAULT_DEBUG_POLICY = {
+    "enabled": True,
+    "triggerOnBlocked": True,
+    "triggerValidationStatuses": ["failed", "error"],
+    "maxSessionsPerTask": 1,
+    "preferOriginalAirDbg": True,
+}
+DEFAULT_XDB_POLICY = {
+    "enabled": True,
+    "requireForGuiTasks": True,
+    "captureOnBlocked": True,
+    "captureOnDone": True,
+    "triggerValidationStatuses": ["failed", "error"],
+    "maxSessionsPerTask": 1,
+    "preferOriginalAirXDB": True,
+    "remoteFirstIfConfigured": True,
+    "taskKeywords": [
+        "gui",
+        "ui",
+        "desktop",
+        "browser",
+        "screen",
+        "screenshot",
+        "visual",
+        "layout",
+        "popup",
+        "focus",
+        "canvas",
+        "acceptance",
+        "midscene",
+        "airxdb",
+        "lvgl",
+        "lcd",
+        "qt-app",
+    ],
+}
+DEFAULT_REPAIR_POLICY = {
+    "enabled": True,
+    "triggerOnBlocked": True,
+    "triggerValidationStatuses": ["failed", "error"],
+    "maxAttemptsPerTask": 2,
+    "requeueTodoStatus": "DOING",
+    "autoPrepareWorker": True,
+}
+REQUIRED_PROJECT_ARTIFACTS = required_project_artifacts()
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _dedupe(items: List[str]) -> List[str]:
+    seen = set()
+    ordered: List[str] = []
+    for item in items:
+        cleaned = str(item).strip()
+        if not cleaned or cleaned in seen:
+            continue
+        seen.add(cleaned)
+        ordered.append(cleaned)
+    return ordered
+
+
+def _ensure_str_list(value: Any) -> List[str]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return _dedupe([str(item) for item in value])
+    return _dedupe([str(value)])
+
+
+@dataclass
+class ValidationRecord:
+    kind: str
+    status: str
+    command: str = ""
+    evidence: List[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "ValidationRecord":
+        return cls(
+            kind=str(payload.get("kind", "")).strip(),
+            status=str(payload.get("status", "")).strip(),
+            command=str(payload.get("command", "")).strip(),
+            evidence=_ensure_str_list(payload.get("evidence")),
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class TaskRecord:
+    task_id: str
+    status: str
+    module: str
+    task: str
+    files_dirs: str
+    done_when: str
+    validation: str
+    adr_c4_update: str
+    line_number: int
+    dependencies: List[str] = field(default_factory=list)
+    write_paths: List[str] = field(default_factory=list)
+    global_doc_paths: List[str] = field(default_factory=list)
+
+    def normalized_write_set(self) -> List[str]:
+        return _dedupe(self.write_paths + self.global_doc_paths)
+
+    def touches_global_docs(self) -> bool:
+        return bool(self.global_doc_paths)
+
+    def to_dict(self) -> Dict[str, Any]:
+        payload = asdict(self)
+        payload["taskId"] = payload.pop("task_id")
+        payload["filesDirs"] = payload.pop("files_dirs")
+        payload["doneWhen"] = payload.pop("done_when")
+        payload["adrC4Update"] = payload.pop("adr_c4_update")
+        payload["lineNumber"] = payload.pop("line_number")
+        payload["writeSet"] = payload.pop("write_paths")
+        payload["globalDocPaths"] = payload.pop("global_doc_paths")
+        return payload
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "TaskRecord":
+        return cls(
+            task_id=str(payload.get("taskId", "")).strip(),
+            status=str(payload.get("status", "")).strip().upper(),
+            module=str(payload.get("module", "")).strip(),
+            task=str(payload.get("task", "")).strip(),
+            files_dirs=str(payload.get("filesDirs", "")).strip(),
+            done_when=str(payload.get("doneWhen", "")).strip(),
+            validation=str(payload.get("validation", "")).strip(),
+            adr_c4_update=str(payload.get("adrC4Update", "")).strip(),
+            line_number=int(payload.get("lineNumber", 0) or 0),
+            dependencies=_ensure_str_list(payload.get("dependencies")),
+            write_paths=_ensure_str_list(payload.get("writeSet")),
+            global_doc_paths=_ensure_str_list(payload.get("globalDocPaths")),
+        )
+
+
+@dataclass
+class WorkerResult:
+    task_id: str
+    status: str
+    summary: str
+    files_changed: List[str] = field(default_factory=list)
+    validations: List[ValidationRecord] = field(default_factory=list)
+    evidence_paths: List[str] = field(default_factory=list)
+    risks: List[str] = field(default_factory=list)
+    blockers: List[str] = field(default_factory=list)
+    recommend_global_doc_updates: List[str] = field(default_factory=list)
+    global_doc_paths: List[str] = field(default_factory=list)
+    document_updates: List["DocumentUpdate"] = field(default_factory=list)
+    debug_sessions: List["DebugSession"] = field(default_factory=list)
+    xdb_sessions: List["XdbSession"] = field(default_factory=list)
+    repair_attempts: List["RepairAttempt"] = field(default_factory=list)
+    notes: List[str] = field(default_factory=list)
+    finalized_at: str = ""
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "WorkerResult":
+        return cls(
+            task_id=str(payload.get("taskId", "")).strip(),
+            status=str(payload.get("status", "")).strip().lower(),
+            summary=str(payload.get("summary", "")).strip(),
+            files_changed=_ensure_str_list(payload.get("filesChanged")),
+            validations=[
+                ValidationRecord.from_dict(item)
+                for item in payload.get("validations", [])
+            ],
+            evidence_paths=_ensure_str_list(payload.get("evidencePaths")),
+            risks=_ensure_str_list(payload.get("risks")),
+            blockers=_ensure_str_list(payload.get("blockers")),
+            recommend_global_doc_updates=_ensure_str_list(
+                payload.get("recommendGlobalDocUpdates")
+            ),
+            global_doc_paths=_ensure_str_list(payload.get("globalDocPaths")),
+            document_updates=[
+                DocumentUpdate.from_dict(item)
+                for item in payload.get("documentUpdates", [])
+            ],
+            debug_sessions=[
+                DebugSession.from_dict(item)
+                for item in payload.get("debugSessions", [])
+            ],
+            xdb_sessions=[
+                XdbSession.from_dict(item)
+                for item in payload.get("xdbSessions", [])
+            ],
+            repair_attempts=[
+                RepairAttempt.from_dict(item)
+                for item in payload.get("repairAttempts", [])
+            ],
+            notes=_ensure_str_list(payload.get("notes")),
+            finalized_at=str(payload.get("finalizedAt", "")).strip(),
+        )
+
+    def validate(self) -> None:
+        if not self.task_id:
+            raise ValueError("worker result missing taskId")
+        if self.status not in FINAL_WORKER_STATUSES:
+            raise ValueError(
+                f"worker result status must be one of {sorted(FINAL_WORKER_STATUSES)}"
+            )
+        if not self.summary:
+            raise ValueError("worker result summary must not be empty")
+        if self.status == "blocked" and not self.blockers:
+            raise ValueError("blocked worker result must include blockers")
+        for item in self.document_updates:
+            item.validate()
+        for item in self.debug_sessions:
+            item.validate()
+        for item in self.xdb_sessions:
+            item.validate()
+        for item in self.repair_attempts:
+            item.validate()
+
+    def has_meaningful_done_payload(self) -> bool:
+        return bool(
+            self.files_changed
+            or self.validations
+            or self.evidence_paths
+            or self.document_updates
+            or self.debug_sessions
+            or self.xdb_sessions
+        )
+
+    def validate_for_finalize(self) -> None:
+        self.validate()
+        if self.status == "done" and not self.has_meaningful_done_payload():
+            raise ValueError(
+                "done worker result must include filesChanged, validations, evidencePaths, "
+                "documentUpdates, debugSessions, or xdbSessions before finalize"
+            )
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "taskId": self.task_id,
+            "status": self.status,
+            "summary": self.summary,
+            "filesChanged": self.files_changed,
+            "validations": [item.to_dict() for item in self.validations],
+            "evidencePaths": self.evidence_paths,
+            "risks": self.risks,
+            "blockers": self.blockers,
+            "recommendGlobalDocUpdates": self.recommend_global_doc_updates,
+            "globalDocPaths": self.global_doc_paths,
+            "documentUpdates": [item.to_dict() for item in self.document_updates],
+            "debugSessions": [item.to_dict() for item in self.debug_sessions],
+            "xdbSessions": [item.to_dict() for item in self.xdb_sessions],
+            "repairAttempts": [item.to_dict() for item in self.repair_attempts],
+            "notes": self.notes,
+            "finalizedAt": self.finalized_at,
+        }
+
+
+def default_worker_result(task_id: str, summary: str = "") -> WorkerResult:
+    return WorkerResult(
+        task_id=task_id,
+        status="done",
+        summary=summary,
+        files_changed=[],
+        validations=[],
+        evidence_paths=[],
+        risks=[],
+        blockers=[],
+        recommend_global_doc_updates=[],
+        global_doc_paths=[],
+        document_updates=[],
+        debug_sessions=[],
+        xdb_sessions=[],
+        repair_attempts=[],
+        notes=[
+            DEFAULT_WORKER_RESULT_NOTE
+        ],
+        finalized_at="",
+    )
+
+
+@dataclass
+class DebugSession:
+    session_id: str
+    task_id: str
+    source: str
+    trigger: str
+    reason: str
+    request_path: str
+    debug_log_path: str
+    state_path: str = ""
+    mode: str = "original-airdbg"
+    status: str = "requested"
+    created_at: str = ""
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "DebugSession":
+        return cls(
+            session_id=str(payload.get("sessionId", "")).strip(),
+            task_id=str(payload.get("taskId", "")).strip(),
+            source=str(payload.get("source", "")).strip(),
+            trigger=str(payload.get("trigger", "")).strip(),
+            reason=str(payload.get("reason", "")).strip(),
+            request_path=str(payload.get("requestPath", "")).strip(),
+            debug_log_path=str(payload.get("debugLogPath", "")).strip(),
+            state_path=str(payload.get("statePath", "")).strip(),
+            mode=str(payload.get("mode", "original-airdbg")).strip(),
+            status=str(payload.get("status", "requested")).strip(),
+            created_at=str(payload.get("createdAt", "")).strip(),
+        )
+
+    def validate(self) -> None:
+        if not self.session_id:
+            raise ValueError("debug session missing sessionId")
+        if not self.task_id:
+            raise ValueError("debug session missing taskId")
+        if not self.request_path:
+            raise ValueError("debug session missing requestPath")
+        if not self.debug_log_path:
+            raise ValueError("debug session missing debugLogPath")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "sessionId": self.session_id,
+            "taskId": self.task_id,
+            "source": self.source,
+            "trigger": self.trigger,
+            "reason": self.reason,
+            "requestPath": self.request_path,
+            "debugLogPath": self.debug_log_path,
+            "statePath": self.state_path,
+            "mode": self.mode,
+            "status": self.status,
+            "createdAt": self.created_at,
+        }
+
+
+@dataclass
+class XdbSession:
+    session_id: str
+    task_id: str
+    source: str
+    trigger: str
+    reason: str
+    request_path: str
+    gui_debug_log_path: str
+    report_path: str = ""
+    state_path: str = ""
+    mode: str = "local-screenshot"
+    status: str = "captured"
+    screenshots: List[str] = field(default_factory=list)
+    created_at: str = ""
+    remote_target: str = ""
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "XdbSession":
+        return cls(
+            session_id=str(payload.get("sessionId", "")).strip(),
+            task_id=str(payload.get("taskId", "")).strip(),
+            source=str(payload.get("source", "")).strip(),
+            trigger=str(payload.get("trigger", "")).strip(),
+            reason=str(payload.get("reason", "")).strip(),
+            request_path=str(payload.get("requestPath", "")).strip(),
+            gui_debug_log_path=str(payload.get("guiDebugLogPath", "")).strip(),
+            report_path=str(payload.get("reportPath", "")).strip(),
+            state_path=str(payload.get("statePath", "")).strip(),
+            mode=str(payload.get("mode", "local-screenshot")).strip(),
+            status=str(payload.get("status", "captured")).strip(),
+            screenshots=_ensure_str_list(payload.get("screenshots")),
+            created_at=str(payload.get("createdAt", "")).strip(),
+            remote_target=str(payload.get("remoteTarget", "")).strip(),
+        )
+
+    def validate(self) -> None:
+        if not self.session_id:
+            raise ValueError("xdb session missing sessionId")
+        if not self.task_id:
+            raise ValueError("xdb session missing taskId")
+        if not self.request_path:
+            raise ValueError("xdb session missing requestPath")
+        if not self.gui_debug_log_path:
+            raise ValueError("xdb session missing guiDebugLogPath")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "sessionId": self.session_id,
+            "taskId": self.task_id,
+            "source": self.source,
+            "trigger": self.trigger,
+            "reason": self.reason,
+            "requestPath": self.request_path,
+            "guiDebugLogPath": self.gui_debug_log_path,
+            "reportPath": self.report_path,
+            "statePath": self.state_path,
+            "mode": self.mode,
+            "status": self.status,
+            "screenshots": self.screenshots,
+            "createdAt": self.created_at,
+            "remoteTarget": self.remote_target,
+        }
+
+
+@dataclass
+class RepairAttempt:
+    repair_id: str
+    task_id: str
+    attempt_index: int
+    source_status: str
+    source_result_path: str
+    reason: str
+    repair_brief_path: str
+    state_path: str = ""
+    worker_brief_path: str = ""
+    debug_session_ids: List[str] = field(default_factory=list)
+    status: str = "queued"
+    created_at: str = ""
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "RepairAttempt":
+        return cls(
+            repair_id=str(payload.get("repairId", "")).strip(),
+            task_id=str(payload.get("taskId", "")).strip(),
+            attempt_index=int(payload.get("attemptIndex", 0) or 0),
+            source_status=str(payload.get("sourceStatus", "")).strip(),
+            source_result_path=str(payload.get("sourceResultPath", "")).strip(),
+            reason=str(payload.get("reason", "")).strip(),
+            repair_brief_path=str(payload.get("repairBriefPath", "")).strip(),
+            state_path=str(payload.get("statePath", "")).strip(),
+            worker_brief_path=str(payload.get("workerBriefPath", "")).strip(),
+            debug_session_ids=_ensure_str_list(payload.get("debugSessionIds")),
+            status=str(payload.get("status", "queued")).strip(),
+            created_at=str(payload.get("createdAt", "")).strip(),
+        )
+
+    def validate(self) -> None:
+        if not self.repair_id:
+            raise ValueError("repair attempt missing repairId")
+        if not self.task_id:
+            raise ValueError("repair attempt missing taskId")
+        if self.attempt_index <= 0:
+            raise ValueError("repair attempt must have positive attemptIndex")
+        if not self.repair_brief_path:
+            raise ValueError("repair attempt missing repairBriefPath")
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "repairId": self.repair_id,
+            "taskId": self.task_id,
+            "attemptIndex": self.attempt_index,
+            "sourceStatus": self.source_status,
+            "sourceResultPath": self.source_result_path,
+            "reason": self.reason,
+            "repairBriefPath": self.repair_brief_path,
+            "statePath": self.state_path,
+            "workerBriefPath": self.worker_brief_path,
+            "debugSessionIds": self.debug_session_ids,
+            "status": self.status,
+            "createdAt": self.created_at,
+        }
+
+
+@dataclass
+class DocumentUpdate:
+    path: str
+    action: str
+    content: str = ""
+    marker: str = ""
+    append_lines: List[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "DocumentUpdate":
+        return cls(
+            path=str(payload.get("path", "")).strip(),
+            action=str(payload.get("action", "")).strip(),
+            content=str(payload.get("content", "")).rstrip(),
+            marker=str(payload.get("marker", "")).strip(),
+            append_lines=_ensure_str_list(payload.get("appendLines")),
+        )
+
+    def validate(self) -> None:
+        if not self.path:
+            raise ValueError("document update missing path")
+        if self.action not in DOCUMENT_UPDATE_ACTIONS:
+            raise ValueError(
+                f"document update action must be one of {sorted(DOCUMENT_UPDATE_ACTIONS)}"
+            )
+        if self.action == "replace_block" and not self.marker:
+            raise ValueError("replace_block document update requires marker")
+        if self.action == "append_lines" and not self.append_lines:
+            raise ValueError("append_lines document update requires appendLines")
+        if self.action in {"replace_block", "create_file"} and not self.content:
+            raise ValueError(f"{self.action} document update requires content")
+        if self.action in {"replace_block", "create_file"} and "TODO" in self.content:
+            raise ValueError(
+                f"{self.action} document update for {self.path} still contains TODO placeholders"
+            )
+        if self.action == "append_lines" and any("TODO" in line for line in self.append_lines):
+            raise ValueError(
+                f"append_lines document update for {self.path} still contains TODO placeholders"
+            )
+
+    def to_dict(self) -> Dict[str, Any]:
+        payload = {
+            "path": self.path,
+            "action": self.action,
+        }
+        if self.content:
+            payload["content"] = self.content
+        if self.marker:
+            payload["marker"] = self.marker
+        if self.append_lines:
+            payload["appendLines"] = self.append_lines
+        return payload
+
+
+@dataclass
+class ReviewConflict:
+    task_ids: List[str]
+    reason: str
+    overlap_paths: List[str] = field(default_factory=list)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "taskIds": self.task_ids,
+            "reason": self.reason,
+            "overlapPaths": self.overlap_paths,
+        }
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "ReviewConflict":
+        return cls(
+            task_ids=_ensure_str_list(payload.get("taskIds")),
+            reason=str(payload.get("reason", "")).strip(),
+            overlap_paths=_ensure_str_list(payload.get("overlapPaths")),
+        )
+
+
+@dataclass
+class ParallelGroup:
+    name: str
+    task_ids: List[str]
+    reason: str
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "name": self.name,
+            "taskIds": self.task_ids,
+            "reason": self.reason,
+        }
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "ParallelGroup":
+        return cls(
+            name=str(payload.get("name", "")).strip(),
+            task_ids=_ensure_str_list(payload.get("taskIds")),
+            reason=str(payload.get("reason", "")).strip(),
+        )
+
+
+@dataclass
+class ParallelReview:
+    source_todo: str
+    generated_at: str
+    tasks_considered: List[TaskRecord]
+    dependency_edges: List[Dict[str, str]]
+    parallel_groups: List[ParallelGroup]
+    conflicts: List[ReviewConflict]
+    serialization_points: List[Dict[str, Any]]
+    notes: List[str]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "sourceTodo": self.source_todo,
+            "generatedAt": self.generated_at,
+            "tasksConsidered": [task.to_dict() for task in self.tasks_considered],
+            "dependencyEdges": self.dependency_edges,
+            "parallelGroups": [group.to_dict() for group in self.parallel_groups],
+            "conflicts": [conflict.to_dict() for conflict in self.conflicts],
+            "serializationPoints": self.serialization_points,
+            "notes": self.notes,
+        }
+
+    @classmethod
+    def from_dict(cls, payload: Dict[str, Any]) -> "ParallelReview":
+        return cls(
+            source_todo=str(payload.get("sourceTodo", "")).strip(),
+            generated_at=str(payload.get("generatedAt", "")).strip(),
+            tasks_considered=[
+                TaskRecord.from_dict(item)
+                for item in payload.get("tasksConsidered", [])
+            ],
+            dependency_edges=list(payload.get("dependencyEdges", [])),
+            parallel_groups=[
+                ParallelGroup.from_dict(item)
+                for item in payload.get("parallelGroups", [])
+            ],
+            conflicts=[
+                ReviewConflict.from_dict(item)
+                for item in payload.get("conflicts", [])
+            ],
+            serialization_points=list(payload.get("serializationPoints", [])),
+            notes=_ensure_str_list(payload.get("notes")),
+        )

AirPlan/docs/spec/AirPlan-ParaV2/lib/air_runtime/debug_runtime.py

@@ -0,0 +1,413 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Dict, Iterable, List, Tuple
+
+from .contracts import DEFAULT_DEBUG_POLICY, DebugSession, WorkerResult, now_iso
+from .paths import airdbg_root, agents_path, aireng_root, architecture_adr_dir, architecture_c4_module_path, debug_log_path
+
+
+def _json_load(path: Path) -> Dict[str, object]:
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8-sig"))
+
+
+def _json_dump(path: Path, payload: Dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def _ordered_unique(items: Iterable[str]) -> List[str]:
+    seen = set()
+    ordered: List[str] = []
+    for item in items:
+        cleaned = str(item).strip()
+        if not cleaned or cleaned in seen:
+            continue
+        seen.add(cleaned)
+        ordered.append(cleaned)
+    return ordered
+
+
+def normalize_debug_policy(policy: Dict[str, object] | None = None) -> Dict[str, object]:
+    merged = dict(DEFAULT_DEBUG_POLICY)
+    if policy:
+        merged.update(policy)
+
+    merged["enabled"] = bool(merged.get("enabled", True))
+    merged["triggerOnBlocked"] = bool(merged.get("triggerOnBlocked", True))
+    merged["preferOriginalAirDbg"] = bool(merged.get("preferOriginalAirDbg", True))
+    merged["triggerValidationStatuses"] = _ordered_unique(
+        str(item).lower() for item in list(merged.get("triggerValidationStatuses", []))
+    )
+
+    try:
+        max_sessions = int(merged.get("maxSessionsPerTask", 1) or 1)
+    except (TypeError, ValueError):
+        max_sessions = 1
+    merged["maxSessionsPerTask"] = max(1, max_sessions)
+    return merged
+
+
+def load_debug_policy(project_root: Path) -> Dict[str, object]:
+    state_path = aireng_root(project_root) / "state.json"
+    state = _json_load(state_path)
+    return normalize_debug_policy(state.get("debugPolicy", {}))
+
+
+def merge_debug_sessions_into_state(
+    state: Dict[str, object], debug_sessions: List[DebugSession]
+) -> Dict[str, object]:
+    state["debugPolicy"] = normalize_debug_policy(dict(state.get("debugPolicy", {})))
+
+    existing_items = list(state.get("debugSessions", []))
+    seen_ids = {
+        str(item.get("sessionId", "")).strip()
+        for item in existing_items
+        if isinstance(item, dict)
+    }
+    for session in debug_sessions:
+        if session.session_id in seen_ids:
+            continue
+        existing_items.append(session.to_dict())
+        seen_ids.add(session.session_id)
+
+    task_counts: Dict[str, int] = {}
+    for item in existing_items:
+        task_id = str(item.get("taskId", "")).strip()
+        if not task_id:
+            continue
+        task_counts[task_id] = task_counts.get(task_id, 0) + 1
+
+    state["debugSessions"] = existing_items
+    state["taskDebugCounts"] = task_counts
+    if debug_sessions:
+        latest = debug_sessions[-1]
+        state["lastDebugSessionId"] = latest.session_id
+        state["lastDebugTaskId"] = latest.task_id
+        state["lastDebugAt"] = latest.created_at
+    return state
+
+
+def _debug_paths(project_root: Path) -> Dict[str, Path]:
+    root = airdbg_root(project_root)
+    return {
+        "root": root,
+        "state": root / "state.json",
+        "requests": root / "requests",
+        "sessions": root / "sessions",
+        "debug_log": debug_log_path(project_root),
+    }
+
+
+def _airdbg_health(project_root: Path) -> Dict[str, bool]:
+    paths = _debug_paths(project_root)
+    return {
+        "AirPlan/AGENTS.md": agents_path(project_root).exists(),
+        "AirPlan/docs/architecture/c4/module.md": architecture_c4_module_path(project_root).exists(),
+        "AirPlan/docs/architecture/adr": architecture_adr_dir(project_root).exists(),
+        "debug_log": paths["debug_log"].exists(),
+    }
+
+
+def _ensure_debug_layout(project_root: Path) -> Dict[str, Path]:
+    paths = _debug_paths(project_root)
+    paths["requests"].mkdir(parents=True, exist_ok=True)
+    paths["sessions"].mkdir(parents=True, exist_ok=True)
+    paths["debug_log"].parent.mkdir(parents=True, exist_ok=True)
+    if not paths["debug_log"].exists():
+        paths["debug_log"].write_text("# Debug Log\n\n", encoding="utf-8")
+    return paths
+
+
+def _resolve_original_airdbg_script() -> Path | None:
+    candidates = [
+        Path.home() / "plugins" / "airdbg" / "scripts" / "airdbg_mode.py",
+        Path(r"C:\Users\20392\plugins\airdbg\scripts\airdbg_mode.py"),
+    ]
+    for candidate in candidates:
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def _bootstrap_airdbg(project_root: Path, prefer_original: bool) -> Tuple[str, str, str]:
+    mode = "runtime-bootstrap"
+    stdout = ""
+    error = ""
+    script_path = _resolve_original_airdbg_script() if prefer_original else None
+
+    if script_path is not None:
+        try:
+            completed = subprocess.run(
+                [
+                    sys.executable,
+                    str(script_path),
+                    "--mode",
+                    "enter",
+                    "--project",
+                    str(project_root),
+                ],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            mode = "original-airdbg"
+            stdout = completed.stdout.strip()
+        except subprocess.CalledProcessError as exc:
+            mode = "runtime-fallback"
+            stdout = exc.stdout.strip()
+            error = exc.stderr.strip() or str(exc)
+
+    paths = _ensure_debug_layout(project_root)
+    state = _json_load(paths["state"])
+    state["enabled"] = True
+    state["updatedAt"] = now_iso()
+    state["projectRoot"] = str(project_root)
+    state["artifactHealth"] = _airdbg_health(project_root)
+    if stdout:
+        state["lastBootstrapStdout"] = stdout
+    if error:
+        state["lastBootstrapError"] = error
+    _json_dump(paths["state"], state)
+    return mode, stdout, error
+
+
+def list_debug_sessions(project_root: Path, task_id: str = "") -> List[DebugSession]:
+    session_dir = _debug_paths(project_root)["sessions"]
+    if not session_dir.exists():
+        return []
+
+    sessions: List[DebugSession] = []
+    for path in sorted(session_dir.glob("*.json")):
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8-sig"))
+            session_payload = payload.get("debugSession", payload)
+            session = DebugSession.from_dict(session_payload)
+            session.validate()
+        except (json.JSONDecodeError, TypeError, ValueError):
+            continue
+        if task_id and session.task_id != task_id:
+            continue
+        sessions.append(session)
+
+    sessions.sort(key=lambda item: (item.created_at, item.session_id))
+    return sessions
+
+
+def _result_trigger_summary(
+    result: WorkerResult, policy: Dict[str, object]
+) -> Tuple[List[str], str]:
+    triggers: List[str] = []
+    reasons: List[str] = []
+
+    if result.status == "blocked" and bool(policy.get("triggerOnBlocked", True)):
+        triggers.append("blocked-status")
+        blocker_text = ", ".join(result.blockers) if result.blockers else "worker returned blocked"
+        reasons.append(f"worker result is blocked: {blocker_text}")
+
+    tracked_validation_statuses = {
+        str(item).lower() for item in list(policy.get("triggerValidationStatuses", []))
+    }
+    failed_validations = [
+        item
+        for item in result.validations
+        if item.status.lower() in tracked_validation_statuses
+    ]
+    if failed_validations:
+        triggers.append("validation-failure")
+        reasons.append(
+            "validation failures: "
+            + ", ".join(f"{item.kind}:{item.status}" for item in failed_validations)
+        )
+
+    return triggers, "; ".join(reasons)
+
+
+def _session_stamp() -> str:
+    return now_iso().replace(":", "-").replace(".", "-").replace("+", "-")
+
+
+def _append_debug_log(
+    debug_log_path: Path,
+    result: WorkerResult,
+    session: DebugSession,
+    bootstrap_mode: str,
+) -> None:
+    section_lines = [
+        f"### {session.created_at}: auto-debug request for {result.task_id}",
+        "",
+        f"- Task: `{result.task_id}`",
+        f"- Source: `{session.source}`",
+        f"- Trigger: `{session.trigger}`",
+        f"- Symptom: {result.summary}",
+        "- Expected: Task validations should pass, or the task should complete without blockers.",
+        f"- Actual: worker status `{result.status}`; blockers={', '.join(result.blockers) or 'none'}",
+        "- Reproduction: finalize the worker result and let the runtime auto-route the failure into AirDbg.",
+        "- Root cause: pending AirDbg investigation.",
+        f"- Fix: pending AirDbg session `{session.session_id}`",
+        (
+            "- Validation: debug request stored at "
+            f"`{session.request_path}`; log appended automatically; bootstrap mode `{bootstrap_mode}`"
+        ),
+        f"- Evidence: {', '.join(f'`{item}`' for item in result.evidence_paths) or '`none`'}",
+        "- ADR/C4 updates: none yet",
+        "- Residual risk: the underlying blocker is unresolved until the debug session is completed.",
+        "",
+    ]
+    existing = debug_log_path.read_text(encoding="utf-8") if debug_log_path.exists() else "# Debug Log\n\n"
+    debug_log_path.write_text(existing.rstrip() + "\n\n" + "\n".join(section_lines), encoding="utf-8")
+
+
+def _update_airdbg_state(
+    project_root: Path,
+    session: DebugSession,
+    bootstrap_mode: str,
+    bootstrap_stdout: str,
+    bootstrap_error: str,
+) -> None:
+    paths = _ensure_debug_layout(project_root)
+    state = _json_load(paths["state"])
+    sessions = list(state.get("autoDebugSessions", []))
+    known_ids = {
+        str(item.get("sessionId", "")).strip()
+        for item in sessions
+        if isinstance(item, dict)
+    }
+    if session.session_id not in known_ids:
+        sessions.append(
+            {
+                "sessionId": session.session_id,
+                "taskId": session.task_id,
+                "source": session.source,
+                "trigger": session.trigger,
+                "status": session.status,
+                "createdAt": session.created_at,
+                "requestPath": session.request_path,
+            }
+        )
+
+    state["enabled"] = True
+    state["updatedAt"] = now_iso()
+    state["projectRoot"] = str(project_root)
+    state["artifactHealth"] = _airdbg_health(project_root)
+    state["autoDebugSessions"] = sessions
+    state["autoDebugSessionCount"] = len(sessions)
+    state["lastAutoDebugAt"] = session.created_at
+    state["lastAutoDebugSessionId"] = session.session_id
+    state["lastBootstrapMode"] = bootstrap_mode
+    if bootstrap_stdout:
+        state["lastBootstrapStdout"] = bootstrap_stdout
+    if bootstrap_error:
+        state["lastBootstrapError"] = bootstrap_error
+    _json_dump(paths["state"], state)
+
+
+def _attach_session_to_result(result: WorkerResult, session: DebugSession, note: str) -> None:
+    if not any(item.session_id == session.session_id for item in result.debug_sessions):
+        result.debug_sessions.append(session)
+    for path in [session.request_path, session.debug_log_path, session.state_path]:
+        if path and path not in result.evidence_paths:
+            result.evidence_paths.append(path)
+    if note not in result.notes:
+        result.notes.append(note)
+
+
+def ensure_debug_sessions_for_result(
+    project_root: Path, result: WorkerResult, source: str
+) -> List[DebugSession]:
+    policy = load_debug_policy(project_root)
+    if not bool(policy.get("enabled", True)):
+        return result.debug_sessions
+
+    triggers, reason = _result_trigger_summary(result, policy)
+    if not triggers:
+        return result.debug_sessions
+
+    existing_sessions = list_debug_sessions(project_root, result.task_id)
+    if result.debug_sessions:
+        for session in result.debug_sessions:
+            _attach_session_to_result(
+                result,
+                session,
+                f"Debug session already linked for {result.task_id}: {session.session_id}",
+            )
+        return result.debug_sessions
+
+    if existing_sessions:
+        latest = existing_sessions[-1]
+        _attach_session_to_result(
+            result,
+            latest,
+            f"Reused existing debug session for {result.task_id}: {latest.session_id}",
+        )
+        return result.debug_sessions
+
+    session_limit = int(policy.get("maxSessionsPerTask", 1) or 1)
+    if len(existing_sessions) >= session_limit:
+        return result.debug_sessions
+
+    paths = _ensure_debug_layout(project_root)
+    bootstrap_mode, bootstrap_stdout, bootstrap_error = _bootstrap_airdbg(
+        project_root, bool(policy.get("preferOriginalAirDbg", True))
+    )
+
+    created_at = now_iso()
+    session_id = f"{result.task_id}-{_session_stamp()}"
+    request_path = paths["requests"] / f"{session_id}.json"
+    session_path = paths["sessions"] / f"{session_id}.json"
+    trigger = ",".join(triggers)
+
+    request_payload = {
+        "sessionId": session_id,
+        "taskId": result.task_id,
+        "source": source,
+        "trigger": trigger,
+        "reason": reason or result.summary,
+        "workerStatus": result.status,
+        "summary": result.summary,
+        "filesChanged": result.files_changed,
+        "validations": [item.to_dict() for item in result.validations],
+        "evidencePaths": result.evidence_paths,
+        "risks": result.risks,
+        "blockers": result.blockers,
+        "createdAt": created_at,
+        "bootstrapMode": bootstrap_mode,
+        "bootstrapStdout": bootstrap_stdout,
+        "bootstrapError": bootstrap_error,
+    }
+    _json_dump(request_path, request_payload)
+
+    session = DebugSession(
+        session_id=session_id,
+        task_id=result.task_id,
+        source=source,
+        trigger=trigger,
+        reason=reason or result.summary,
+        request_path=str(request_path),
+        debug_log_path=str(paths["debug_log"]),
+        state_path=str(paths["state"]),
+        mode=bootstrap_mode,
+        status="requested",
+        created_at=created_at,
+    )
+    _json_dump(
+        session_path,
+        {
+            "debugSession": session.to_dict(),
+            "request": request_payload,
+        },
+    )
+
+    _append_debug_log(paths["debug_log"], result, session, bootstrap_mode)
+    _update_airdbg_state(project_root, session, bootstrap_mode, bootstrap_stdout, bootstrap_error)
+    _attach_session_to_result(
+        result,
+        session,
+        f"Auto-requested debug session for {result.task_id}: {session.session_id}",
+    )
+    return result.debug_sessions

AirPlan/docs/spec/AirPlan-ParaV2/lib/air_runtime/doc_sync.py

@@ -0,0 +1,350 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, Iterable, List
+
+from .contracts import DocumentUpdate, ValidationRecord, WorkerResult, now_iso
+from .paths import (
+    agents_path,
+    architecture_c4_module_path,
+    plan_path as workflow_plan_path,
+    todo_path as workflow_todo_path,
+)
+from .todo_parser import parse_tasks
+
+
+def _project_relative(project_root: Path, raw_path: str) -> Path:
+    candidate = Path(raw_path)
+    if candidate.is_absolute():
+        resolved = candidate.resolve()
+    else:
+        resolved = (project_root / candidate).resolve()
+
+    project_root_resolved = project_root.resolve()
+    try:
+        resolved.relative_to(project_root_resolved)
+    except ValueError as exc:
+        raise ValueError(f"document update path escapes project root: {raw_path}") from exc
+    return resolved
+
+
+def _replace_marker_block(text: str, marker: str, content: str) -> str:
+    begin = f"<!-- AIR-ENGINE:{marker}:BEGIN -->"
+    end = f"<!-- AIR-ENGINE:{marker}:END -->"
+    block = f"{begin}\n{content.rstrip()}\n{end}\n"
+    start_index = text.find(begin)
+    end_index = text.find(end)
+    if start_index >= 0 and end_index > start_index:
+        end_index += len(end)
+        return text[:start_index].rstrip() + "\n\n" + block + text[end_index:].lstrip()
+    return text.rstrip() + "\n\n" + block
+
+
+def _extract_marker_block(text: str, marker: str) -> str:
+    begin = f"<!-- AIR-ENGINE:{marker}:BEGIN -->"
+    end = f"<!-- AIR-ENGINE:{marker}:END -->"
+    start_index = text.find(begin)
+    end_index = text.find(end)
+    if start_index < 0 or end_index <= start_index:
+        return ""
+    content_start = start_index + len(begin)
+    return text[content_start:end_index].strip()
+
+
+def _apply_document_update(project_root: Path, update: DocumentUpdate) -> str:
+    target_path = _project_relative(project_root, update.path)
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    existing = target_path.read_text(encoding="utf-8") if target_path.exists() else ""
+
+    if update.action == "create_file":
+        target_path.write_text(update.content.rstrip() + "\n", encoding="utf-8")
+    elif update.action == "append_lines":
+        joined = "\n".join(update.append_lines).rstrip()
+        if existing.strip():
+            target_path.write_text(existing.rstrip() + "\n" + joined + "\n", encoding="utf-8")
+        else:
+            target_path.write_text(joined + "\n", encoding="utf-8")
+    elif update.action == "replace_block":
+        updated = _replace_marker_block(existing, update.marker, update.content)
+        target_path.write_text(updated, encoding="utf-8")
+    else:
+        raise ValueError(f"unsupported document update action: {update.action}")
+
+    return str(target_path)
+
+
+def apply_document_updates(project_root: Path, result: WorkerResult) -> List[str]:
+    applied: List[str] = []
+    for update in result.document_updates:
+        applied.append(_apply_document_update(project_root, update))
+    return applied
+
+
+def _validation_summary(validations: List[ValidationRecord]) -> str:
+    if not validations:
+        return "No explicit validation recorded"
+    return "; ".join(
+        f"{item.kind}:{item.status}" + (f" ({item.command})" if item.command else "")
+        for item in validations
+    )
+
+
+def _debug_summary(result: WorkerResult) -> str:
+    if not result.debug_sessions:
+        return "none"
+    return ", ".join(
+        f"{item.session_id} [{item.trigger}]"
+        for item in result.debug_sessions
+    )
+
+
+def _xdb_summary(result: WorkerResult) -> str:
+    if not result.xdb_sessions:
+        return "none"
+    return ", ".join(
+        f"{item.session_id} [{item.mode}:{item.status}]"
+        for item in result.xdb_sessions
+    )
+
+
+def _repair_summary(result: WorkerResult) -> str:
+    if not result.repair_attempts:
+        return "none"
+    return ", ".join(
+        f"{item.repair_id} [{item.status}]"
+        for item in result.repair_attempts
+    )
+
+
+def _todo_status_from_worker_status(worker_status: str) -> str:
+    if worker_status == "done":
+        return "DONE"
+    return "BLOCKED"
+
+
+def _todo_status_from_result(result: WorkerResult) -> str:
+    if result.status == "done":
+        return "DONE"
+    if result.repair_attempts:
+        return "DOING"
+    return "BLOCKED"
+
+
+def _rebuild_table_row(cells: List[str]) -> str:
+    return "| " + " | ".join(cells) + " |"
+
+
+def update_todo_after_merge(
+    project_root: Path,
+    result: WorkerResult,
+    applied_doc_paths: List[str],
+    sync_paths: List[str],
+) -> Path:
+    todo_path = workflow_todo_path(project_root)
+    original_text = todo_path.read_text(encoding="utf-8")
+    lines = original_text.splitlines()
+    updated_lines: List[str] = []
+    task_found = False
+
+    unique_applied_doc_paths = list(dict.fromkeys(applied_doc_paths))
+    unique_sync_paths = list(dict.fromkeys(sync_paths))
+    for raw_line in lines:
+        if raw_line.startswith(f"| {result.task_id} "):
+            cells = [cell.strip() for cell in raw_line.strip().strip("|").split("|")]
+            if len(cells) > 8:
+                cells = cells[:7] + ["; ".join(cell for cell in cells[7:] if cell)]
+            if len(cells) >= 8:
+                cells[1] = _todo_status_from_result(result)
+                validation_cell = _validation_summary(result.validations)
+                if result.evidence_paths:
+                    validation_cell += f"; evidence={len(result.evidence_paths)}"
+                if result.blockers:
+                    validation_cell += "; blockers=" + ", ".join(result.blockers)
+                if result.xdb_sessions:
+                    validation_cell += f"; xdb={len(result.xdb_sessions)}"
+                if result.debug_sessions:
+                    validation_cell += f"; debug={len(result.debug_sessions)}"
+                if result.repair_attempts:
+                    validation_cell += f"; repair={len(result.repair_attempts)}"
+                cells[6] = validation_cell
+                if unique_applied_doc_paths:
+                    cells[7] = "Merged by engine: " + ", ".join(
+                        Path(path).name for path in unique_applied_doc_paths
+                    )
+                updated_lines.append(_rebuild_table_row(cells))
+                task_found = True
+                continue
+        updated_lines.append(raw_line)
+
+    if not task_found:
+        raise ValueError(f"task row not found in todo.md for {result.task_id}")
+
+    log_lines = [
+        f"- `{now_iso()}` task `{result.task_id}` merged with status `{result.status}`",
+        f"  Summary: {result.summary}",
+        f"  Files Changed: {', '.join(f'`{item}`' for item in result.files_changed) or '`none`'}",
+        f"  Validations: {_validation_summary(result.validations)}",
+        f"  Evidence: {', '.join(f'`{item}`' for item in result.evidence_paths) or '`none`'}",
+        f"  XDB Sessions: {_xdb_summary(result)}",
+        f"  Debug Sessions: {_debug_summary(result)}",
+        f"  Repair Attempts: {_repair_summary(result)}",
+        f"  Risks: {', '.join(result.risks) or 'none'}",
+        f"  Blockers: {', '.join(result.blockers) or 'none'}",
+        f"  Applied Doc Paths: {', '.join(f'`{item}`' for item in unique_applied_doc_paths) or '`none`'}",
+        f"  Engine Sync Paths: {', '.join(f'`{item}`' for item in unique_sync_paths) or '`none`'}",
+    ]
+    existing_log = _extract_marker_block(original_text, "TODO-RUN-LOG")
+    existing_body = ""
+    if existing_log:
+        existing_lines = existing_log.splitlines()
+        if existing_lines and existing_lines[0].strip() in {"# Air Engine Merge Log", "# AirEng Merge Log"}:
+            existing_body = "\n".join(existing_lines[1:]).strip()
+        else:
+            existing_body = existing_log.strip()
+
+    merged_log_content = "# AirEng Merge Log\n\n" + "\n".join(log_lines)
+    if existing_body:
+        merged_log_content += "\n\n" + existing_body
+
+    text = "\n".join(updated_lines).rstrip() + "\n"
+    text = _replace_marker_block(
+        text,
+        "TODO-RUN-LOG",
+        merged_log_content,
+    )
+    todo_path.write_text(text, encoding="utf-8")
+    return todo_path
+
+
+def mark_tasks_dispatched(
+    project_root: Path,
+    group_name: str,
+    dispatched_tasks: List[Dict[str, object]],
+    recommended_concurrency: int,
+) -> List[str]:
+    updated_paths: List[str] = []
+    current_todo_path = workflow_todo_path(project_root)
+    current_plan_path = workflow_plan_path(project_root)
+    task_ids = {str(item.get("taskId", "")).strip() for item in dispatched_tasks if str(item.get("taskId", "")).strip()}
+
+    if current_todo_path.exists() and task_ids:
+        lines = current_todo_path.read_text(encoding="utf-8").splitlines()
+        rewritten: List[str] = []
+        for raw_line in lines:
+            if raw_line.startswith("| "):
+                cells = [cell.strip() for cell in raw_line.strip().strip("|").split("|")]
+                if cells and cells[0] in task_ids and len(cells) >= 2:
+                    cells[1] = "DOING"
+                    raw_line = _rebuild_table_row(cells)
+            rewritten.append(raw_line)
+        current_todo_path.write_text("\n".join(rewritten).rstrip() + "\n", encoding="utf-8")
+        updated_paths.append(str(current_todo_path))
+
+    if current_plan_path.exists():
+        plan_text = current_plan_path.read_text(encoding="utf-8")
+        lines = [
+            "## AirEng Active Dispatch",
+            "",
+            f"- Updated At: `{now_iso()}`",
+            f"- Group: `{group_name or 'default'}`",
+            f"- Recommended Concurrency: `{recommended_concurrency}`",
+            "- Tasks:",
+        ]
+        if dispatched_tasks:
+            for item in dispatched_tasks:
+                lines.append(
+                    f"  - `{item.get('taskId', '')}` handoff=`{item.get('handoffPath', '')}` brief=`{item.get('briefPath', '')}`"
+                )
+        else:
+            lines.append("  - none")
+        plan_text = _replace_marker_block(plan_text, "DISPATCH-STATUS", "\n".join(lines))
+        current_plan_path.write_text(plan_text, encoding="utf-8")
+        updated_paths.append(str(current_plan_path))
+
+    return updated_paths
+
+
+def _sync_block_content(result: WorkerResult, applied_doc_paths: List[str], title: str) -> str:
+    unique_applied_doc_paths = list(dict.fromkeys(applied_doc_paths))
+    lines = [
+        title,
+        "",
+        f"- Last Synced At: `{now_iso()}`",
+        f"- Task: `{result.task_id}`",
+        f"- Status: `{result.status}`",
+        f"- Summary: {result.summary}",
+        f"- Files Changed: {', '.join(f'`{item}`' for item in result.files_changed) or '`none`'}",
+        f"- Validations: {_validation_summary(result.validations)}",
+        f"- XDB Sessions: {_xdb_summary(result)}",
+        f"- Debug Sessions: {_debug_summary(result)}",
+        f"- Repair Attempts: {_repair_summary(result)}",
+        f"- Applied Doc Paths: {', '.join(f'`{item}`' for item in unique_applied_doc_paths) or '`none`'}",
+        f"- Risks: {', '.join(result.risks) or 'none'}",
+        f"- Blockers: {', '.join(result.blockers) or 'none'}",
+    ]
+    return "\n".join(lines)
+
+
+def sync_engine_managed_docs(project_root: Path, result: WorkerResult, applied_doc_paths: List[str]) -> List[str]:
+    updated_paths: List[str] = []
+    current_agents_path = agents_path(project_root)
+    if current_agents_path.exists():
+        agents_text = current_agents_path.read_text(encoding="utf-8")
+        agents_text = _replace_marker_block(
+            agents_text,
+            "AGENTS-SYNC",
+            _sync_block_content(result, applied_doc_paths, "## AirEng Sync"),
+        )
+        current_agents_path.write_text(agents_text, encoding="utf-8")
+        updated_paths.append(str(current_agents_path))
+
+    c4_path = architecture_c4_module_path(project_root)
+    if c4_path.exists():
+        c4_text = c4_path.read_text(encoding="utf-8")
+        c4_text = _replace_marker_block(
+            c4_text,
+            "C4-SYNC",
+            _sync_block_content(result, applied_doc_paths, "## AirEng Sync"),
+        )
+        c4_path.write_text(c4_text, encoding="utf-8")
+        updated_paths.append(str(c4_path))
+
+    return updated_paths
+
+
+def enforce_doc_sync_requirements(project_root: Path, result: WorkerResult) -> None:
+    task = None
+    todo_path = workflow_todo_path(project_root)
+    if todo_path.exists():
+        task = next((item for item in parse_tasks(todo_path) if item.task_id == result.task_id), None)
+
+    required_doc_paths = set(result.global_doc_paths)
+    if task is not None:
+        required_doc_paths.update(task.global_doc_paths)
+
+    if result.status != "done":
+        return
+
+    if not required_doc_paths:
+        return
+
+    covered_paths = set()
+    for update in result.document_updates:
+        covered_paths.add(update.path)
+
+    missing_paths = []
+    for required in sorted(required_doc_paths):
+        if required == "AirPlan/docs/architecture/adr/":
+            if not any("AirPlan/docs/architecture/adr/" in path.replace("\\", "/") for path in covered_paths):
+                missing_paths.append(required)
+            continue
+        if required not in covered_paths:
+            missing_paths.append(required)
+
+    if missing_paths:
+        raise ValueError(
+            "document sync is incomplete for task "
+            + result.task_id
+            + ": missing updates for "
+            + ", ".join(missing_paths)
+        )

AirPlan/docs/spec/AirPlan-ParaV2/lib/air_runtime/paths.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+AIRPLAN_DIRNAME = "AirPlan"
+
+
+def airplan_root(project_root: Path) -> Path:
+    return project_root / AIRPLAN_DIRNAME
+
+
+def docs_root(project_root: Path) -> Path:
+    return airplan_root(project_root) / "docs"
+
+
+def state_root(project_root: Path) -> Path:
+    return airplan_root(project_root) / "state"
+
+
+def agents_path(project_root: Path) -> Path:
+    return airplan_root(project_root) / "AGENTS.md"
+
+
+def root_agents_bootstrap_path(project_root: Path) -> Path:
+    return project_root / "AGENTS.md"
+
+
+def plan_path(project_root: Path) -> Path:
+    return airplan_root(project_root) / "plan.md"
+
+
+def todo_path(project_root: Path) -> Path:
+    return airplan_root(project_root) / "todo.md"
+
+
+def analysis_requirements_path(project_root: Path) -> Path:
+    return docs_root(project_root) / "analysis" / "requirements.md"
+
+
+def architecture_root(project_root: Path) -> Path:
+    return docs_root(project_root) / "architecture"
+
+
+def architecture_solution_path(project_root: Path) -> Path:
+    return architecture_root(project_root) / "solution-architecture.md"
+
+
+def architecture_adr_dir(project_root: Path) -> Path:
+    return architecture_root(project_root) / "adr"
+
+
+def architecture_c4_module_path(project_root: Path) -> Path:
+    return architecture_root(project_root) / "c4" / "module.md"
+
+
+def debug_root(project_root: Path) -> Path:
+    return docs_root(project_root) / "debug"
+
+
+def debug_log_path(project_root: Path) -> Path:
+    return debug_root(project_root) / "debug-log.md"
+
+
+def gui_debug_log_path(project_root: Path) -> Path:
+    return debug_root(project_root) / "gui-debug-log.md"
+
+
+def airxdb_artifacts_dir(project_root: Path) -> Path:
+    return debug_root(project_root) / "airxdb-artifacts"
+
+
+def network_root(project_root: Path) -> Path:
+    return docs_root(project_root) / "network"
+
+
+def airndb_log_path(project_root: Path) -> Path:
+    return network_root(project_root) / "airndb-log.md"
+
+
+def airndb_captures_dir(project_root: Path) -> Path:
+    return network_root(project_root) / "airndb-captures"
+
+
+def validation_root(project_root: Path) -> Path:
+    return docs_root(project_root) / "validation"
+
+
+def staticanalysis_path(project_root: Path) -> Path:
+    return docs_root(project_root) / "staticanalysis.md"
+
+
+def plugin_state_root(project_root: Path, plugin_name: str) -> Path:
+    return state_root(project_root) / plugin_name
+
+
+def airarc_root(project_root: Path) -> Path:
+    return plugin_state_root(project_root, "airarc")
+
+
+def aireng_root(project_root: Path) -> Path:
+    return plugin_state_root(project_root, "aireng")
+
+
+def airdo_root(project_root: Path) -> Path:
+    return plugin_state_root(project_root, "airdo")
+
+
+def airdbg_root(project_root: Path) -> Path:
+    return plugin_state_root(project_root, "airdbg")
+
+
+def airndb_root(project_root: Path) -> Path:
+    return plugin_state_root(project_root, "airndb")
+
+
+def airsdb_root(project_root: Path) -> Path:
+    return plugin_state_root(project_root, "airsdb")
+
+
+def airxdb_root(project_root: Path) -> Path:
+    return plugin_state_root(project_root, "airxdb")
+
+
+def required_project_artifacts() -> tuple[str, ...]:
+    return (
+        "AirPlan/AGENTS.md",
+        "AirPlan/docs/architecture/adr",
+        "AirPlan/docs/architecture/c4/module.md",
+        "AirPlan/plan.md",
+        "AirPlan/todo.md",
+    )

AirPlan/docs/spec/AirPlan-ParaV2/lib/air_runtime/project_bootstrap.py

@@ -0,0 +1,342 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Dict, Tuple
+
+from .paths import (
+    agents_path,
+    airplan_root,
+    analysis_requirements_path,
+    architecture_adr_dir,
+    architecture_c4_module_path,
+    architecture_solution_path,
+    debug_log_path,
+    gui_debug_log_path,
+    root_agents_bootstrap_path,
+    state_root,
+    staticanalysis_path,
+    validation_root,
+)
+
+AIRARC_BEGIN = "<!-- AIRARC:BEGIN -->"
+AIRARC_END = "<!-- AIRARC:END -->"
+AIRENG_BEGIN = "<!-- AIRENG:BEGIN -->"
+AIRENG_END = "<!-- AIRENG:END -->"
+AIRDO_BEGIN = "<!-- AIRDO:BEGIN -->"
+AIRDO_END = "<!-- AIRDO:END -->"
+
+ROOT_AGENTS_TEMPLATE = """# AGENTS.md
+
+- Canonical workflow context for this repository lives in `AirPlan/AGENTS.md`.
+- Always load `AirPlan/AGENTS.md` first for project instructions, workflow rules, plan/todo state, ADR/C4 context, and current Air sync blocks.
+- Treat `AirPlan/plan.md`, `AirPlan/todo.md`, and `AirPlan/docs/` as the authoritative workflow documents.
+- Treat `AirPlan/state/` as the authoritative plugin and runtime state root.
+- This root file is only a bootstrap shim; keep real workflow context maintained inside `AirPlan/AGENTS.md`.
+"""
+
+PROJECT_AGENTS_TEMPLATE = f"""# AGENTS.md
+
+## Workflow Root
+
+- This project uses `AirPlan/` as the workflow root.
+- Keep planning, execution state, ADR, C4, validation, debug, and plugin runtime data under `AirPlan/`.
+- The repo-root `AGENTS.md` only bootstraps into this file.
+
+{AIRARC_BEGIN}
+## AirArc Workflow
+
+1. Use `AirPlan/AGENTS.md` as the canonical project context entry point.
+2. Load and maintain:
+   - `AirPlan/docs/analysis/requirements.md`
+   - `AirPlan/docs/architecture/solution-architecture.md`
+   - `AirPlan/docs/architecture/c4/module.md`
+   - `AirPlan/docs/architecture/adr/`
+3. Produce or refine `AirPlan/plan.md` and `AirPlan/todo.md`.
+4. Keep plans optimized for lower-cost follow-up sessions, including scope, validation, file targets, and parallelization boundaries.
+5. AirArc is architecture-only: it may plan tasks and edit planning or architecture documents, but it must not write code or implement tasks directly.
+{AIRARC_END}
+
+{AIRENG_BEGIN}
+## AirEng Workflow
+
+1. Use `/aireng` as the sole scheduler for confirmed execution.
+2. Prefer `AirPlan/state/airarc/reviews/execution-plan.json`, then `AirPlan/state/airarc/reviews/parallel-review.json`, before falling back to local `AirPlan/todo.md`.
+3. Dispatch isolated `/airdo` subagents with bounded concurrency instead of defaulting to parent-thread coding.
+4. Monitor active workers on a 5-minute cadence, merge ready results, and continue later waves automatically when work remains.
+5. Keep `AirPlan/todo.md`, `AirPlan/plan.md`, `AirPlan/AGENTS.md`, ADR, and C4 docs synchronized during dispatch, monitoring, repair, and merge.
+6. AirEng owns global debug, XDB, repair, intervention, and document convergence, but it should only intervene directly for hard blockers and must return to scheduler mode immediately afterward.
+{AIRENG_END}
+
+{AIRDO_BEGIN}
+## AirDo Workflow
+
+1. Use `/airdo` for one narrow task slice from `AirPlan/todo.md`.
+2. Before editing, load:
+   - `AirPlan/AGENTS.md`
+   - `AirPlan/docs/architecture/adr/`
+   - `AirPlan/docs/architecture/c4/module.md`
+   - `AirPlan/plan.md`
+   - `AirPlan/todo.md`
+3. Keep task-local progress resumable in `AirPlan/state/airdo/`.
+4. When AirEng owns orchestration, return shared document changes through `documentUpdates`.
+5. Route GUI work through AirXDB, debugging through AirDbg, network evidence through AirNDB, and static analysis through AirSDB when needed.
+{AIRDO_END}
+"""
+
+PLAN_TEMPLATE = """# Implementation Plan
+
+## Read First
+1. `AirPlan/AGENTS.md`
+2. `AirPlan/docs/analysis/requirements.md`
+3. `AirPlan/docs/architecture/solution-architecture.md`
+4. `AirPlan/docs/architecture/c4/module.md`
+5. `AirPlan/docs/architecture/adr/`
+6. `AirPlan/todo.md`
+
+## Goal
+- Replace this section with the concrete product or project goal.
+
+## Constraints
+- Record technical, organizational, legal, hardware, or platform constraints here.
+
+## Phases
+- Add implementation phases once AirArc planning is complete.
+
+## Validation Strategy
+- Record build, test, debug, GUI, network, and static-analysis validation commands here.
+"""
+
+TODO_TEMPLATE = """# TODO
+
+Status values: TODO / DOING / DONE / BLOCKED
+
+| ID | Status | Module | Task | Files/Dirs | Done When | Validation | Static Analysis | ADR/C4 Update |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| T-001 | TODO | Planning | Replace with the first confirmed execution task | `AirPlan/plan.md`, `AirPlan/docs/` | Acceptance criteria are explicit and testable | Record the exact validation command | Record the static-analysis plan or why it is not applicable | Record required ADR or C4 updates |
+
+## Quality Gates
+- Run the validation command listed in `AirPlan/plan.md` before marking a task `DONE`.
+- Keep ADR and C4 docs synchronized whenever architecture, module boundaries, dependencies, or ownership change.
+- Record skipped validation, residual risk, and follow-up work explicitly.
+"""
+
+REQUIREMENTS_TEMPLATE = """# Requirements
+
+## Product Intent
+- Replace with the user-visible outcome this repository should deliver.
+
+## Functional Requirements
+- Replace with numbered or grouped functional requirements.
+
+## Constraints
+- Replace with non-functional constraints, environmental limits, or safety rules.
+
+## Acceptance Notes
+- Replace with the most important acceptance criteria and evidence rules.
+"""
+
+SOLUTION_ARCHITECTURE_TEMPLATE = """# Solution Architecture
+
+## Overview
+- Replace with the top-level architecture summary.
+
+## Major Components
+- Replace with the main containers and their responsibilities.
+
+## Data And Control Flow
+- Replace with the major interaction paths between components.
+
+## Key Risks
+- Replace with the architecture risks, unknowns, and open decisions.
+"""
+
+C4_MODULE_TEMPLATE = """# C4 Module
+
+## System Context
+- Replace with the project purpose and external actors or systems.
+
+## Containers
+- Replace with the main runtime or repository containers.
+
+## Modules
+
+| Module | Responsibility | Public Interfaces | Dependencies | Data Ownership | Quality Notes |
+| --- | --- | --- | --- | --- | --- |
+| `replace_me` | Replace with the first real module | Replace with interfaces | Replace with dependencies | Replace with owned data | Replace with testing or quality notes |
+"""
+
+ADR_TEMPLATE = """# ADR-0001: Use AirPlan As The Workflow Root
+
+- Status: Accepted
+- Date: YYYY-MM-DD
+
+## Context
+This project needs a durable workflow root for planning, execution state, architecture context, validation evidence, and resumable AI sessions.
+
+## Decision
+Store project workflow artifacts under `AirPlan/`, use the repo-root `AGENTS.md` only as a bootstrap shim, and let `aireng` plus `airdo` maintain plan, todo, ADR, and C4 context there.
+
+## Consequences
+- Planning and execution context stay resumable across sessions.
+- Global workflow docs live in one predictable location.
+- Plugin runtime state does not clutter the main project tree.
+"""
+
+DEBUG_LOG_TEMPLATE = """# Debug Log
+
+- Add reproducible bug investigations, root-cause notes, and validation outcomes here.
+"""
+
+GUI_DEBUG_LOG_TEMPLATE = """# GUI Debug Log
+
+- Add screenshots, GUI observations, Midscene evidence, and visual acceptance notes here.
+"""
+
+NETWORK_LOG_TEMPLATE = """# AirNDB Log
+
+- Add packet-capture commands, pcap paths, network observations, and conclusions here.
+"""
+
+STATIC_ANALYSIS_TEMPLATE = """# Static Analysis
+
+- Add cppcheck or other static-analysis summaries, report paths, and residual risks here.
+"""
+
+VALIDATION_README_TEMPLATE = """# Validation Artifacts
+
+- Save build logs, flash logs, test logs, screenshots, and validation summaries under this directory.
+"""
+
+ARTIFACTS_README_TEMPLATE = """# Artifact Output
+
+- Save generated evidence files in this directory.
+"""
+
+
+def _write_if_missing(path: Path, content: str) -> str:
+    if path.exists():
+        return "exists"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content.rstrip() + "\n", encoding="utf-8", newline="\n")
+    return "created"
+
+
+def _upsert_marked_block(existing: str, begin: str, end: str, block: str) -> Tuple[str, bool]:
+    begin_index = existing.find(begin)
+    end_index = existing.find(end)
+    normalized_block = block.rstrip() + "\n"
+    if begin_index >= 0 and end_index > begin_index:
+        end_index += len(end)
+        updated = existing[:begin_index].rstrip() + "\n\n" + normalized_block + existing[end_index:].lstrip()
+        return updated, updated != existing
+    updated = existing.rstrip() + "\n\n" + normalized_block
+    return updated, True
+
+
+def _ensure_project_agents(path: Path) -> str:
+    if not path.exists():
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(PROJECT_AGENTS_TEMPLATE.rstrip() + "\n", encoding="utf-8", newline="\n")
+        return "created"
+
+    original = path.read_text(encoding="utf-8-sig")
+    updated = original
+    changed = False
+    for begin, end, block in [
+        (
+            AIRARC_BEGIN,
+            AIRARC_END,
+            PROJECT_AGENTS_TEMPLATE[
+                PROJECT_AGENTS_TEMPLATE.index(AIRARC_BEGIN) : PROJECT_AGENTS_TEMPLATE.index(AIRARC_END) + len(AIRARC_END)
+            ],
+        ),
+        (
+            AIRENG_BEGIN,
+            AIRENG_END,
+            PROJECT_AGENTS_TEMPLATE[
+                PROJECT_AGENTS_TEMPLATE.index(AIRENG_BEGIN) : PROJECT_AGENTS_TEMPLATE.index(AIRENG_END) + len(AIRENG_END)
+            ],
+        ),
+        (
+            AIRDO_BEGIN,
+            AIRDO_END,
+            PROJECT_AGENTS_TEMPLATE[
+                PROJECT_AGENTS_TEMPLATE.index(AIRDO_BEGIN) : PROJECT_AGENTS_TEMPLATE.index(AIRDO_END) + len(AIRDO_END)
+            ],
+        ),
+    ]:
+        updated, block_changed = _upsert_marked_block(updated, begin, end, block)
+        changed = changed or block_changed
+
+    if not changed:
+        return "exists"
+
+    path.write_text(updated.rstrip() + "\n", encoding="utf-8", newline="\n")
+    return "updated"
+
+
+def ensure_project_bootstrap(project_root: Path) -> Dict[str, str]:
+    airplan_root(project_root).mkdir(parents=True, exist_ok=True)
+    architecture_adr_dir(project_root).mkdir(parents=True, exist_ok=True)
+    architecture_c4_module_path(project_root).parent.mkdir(parents=True, exist_ok=True)
+    analysis_requirements_path(project_root).parent.mkdir(parents=True, exist_ok=True)
+    debug_log_path(project_root).parent.mkdir(parents=True, exist_ok=True)
+    gui_debug_log_path(project_root).parent.mkdir(parents=True, exist_ok=True)
+    (debug_log_path(project_root).parent / "airxdb-artifacts").mkdir(parents=True, exist_ok=True)
+    (airplan_root(project_root) / "docs" / "network" / "airndb-captures").mkdir(parents=True, exist_ok=True)
+    (validation_root(project_root) / "logs").mkdir(parents=True, exist_ok=True)
+    state_root(project_root).mkdir(parents=True, exist_ok=True)
+
+    results = {
+        str(root_agents_bootstrap_path(project_root)): _write_if_missing(
+            root_agents_bootstrap_path(project_root), ROOT_AGENTS_TEMPLATE
+        ),
+        str(agents_path(project_root)): _ensure_project_agents(agents_path(project_root)),
+        str(airplan_root(project_root) / "plan.md"): _write_if_missing(
+            airplan_root(project_root) / "plan.md", PLAN_TEMPLATE
+        ),
+        str(airplan_root(project_root) / "todo.md"): _write_if_missing(
+            airplan_root(project_root) / "todo.md", TODO_TEMPLATE
+        ),
+        str(analysis_requirements_path(project_root)): _write_if_missing(
+            analysis_requirements_path(project_root), REQUIREMENTS_TEMPLATE
+        ),
+        str(architecture_solution_path(project_root)): _write_if_missing(
+            architecture_solution_path(project_root), SOLUTION_ARCHITECTURE_TEMPLATE
+        ),
+        str(architecture_c4_module_path(project_root)): _write_if_missing(
+            architecture_c4_module_path(project_root), C4_MODULE_TEMPLATE
+        ),
+        str(architecture_adr_dir(project_root) / "ADR-0001-use-airplan-as-the-workflow-root.md"): _write_if_missing(
+            architecture_adr_dir(project_root) / "ADR-0001-use-airplan-as-the-workflow-root.md",
+            ADR_TEMPLATE,
+        ),
+        str(debug_log_path(project_root)): _write_if_missing(
+            debug_log_path(project_root), DEBUG_LOG_TEMPLATE
+        ),
+        str(gui_debug_log_path(project_root)): _write_if_missing(
+            gui_debug_log_path(project_root), GUI_DEBUG_LOG_TEMPLATE
+        ),
+        str(debug_log_path(project_root).parent / "airxdb-artifacts" / "README.md"): _write_if_missing(
+            debug_log_path(project_root).parent / "airxdb-artifacts" / "README.md",
+            ARTIFACTS_README_TEMPLATE,
+        ),
+        str(airplan_root(project_root) / "docs" / "network" / "airndb-log.md"): _write_if_missing(
+            airplan_root(project_root) / "docs" / "network" / "airndb-log.md",
+            NETWORK_LOG_TEMPLATE,
+        ),
+        str(airplan_root(project_root) / "docs" / "network" / "airndb-captures" / "README.md"): _write_if_missing(
+            airplan_root(project_root) / "docs" / "network" / "airndb-captures" / "README.md",
+            ARTIFACTS_README_TEMPLATE,
+        ),
+        str(validation_root(project_root) / "README.md"): _write_if_missing(
+            validation_root(project_root) / "README.md", VALIDATION_README_TEMPLATE
+        ),
+        str(validation_root(project_root) / "logs" / "README.md"): _write_if_missing(
+            validation_root(project_root) / "logs" / "README.md", ARTIFACTS_README_TEMPLATE
+        ),
+        str(staticanalysis_path(project_root)): _write_if_missing(
+            staticanalysis_path(project_root), STATIC_ANALYSIS_TEMPLATE
+        ),
+    }
+    return results

AirPlan/docs/spec/AirPlan-ParaV2/lib/air_runtime/repair_runtime.py

@@ -0,0 +1,373 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, Iterable, List
+
+from .contracts import DEFAULT_REPAIR_POLICY, RepairAttempt, WorkerResult, now_iso
+from .paths import (
+    airdo_root,
+    aireng_root,
+    debug_log_path,
+    gui_debug_log_path,
+    plan_path,
+    todo_path,
+)
+
+
+def _json_load(path: Path) -> Dict[str, object]:
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8-sig"))
+
+
+def _json_dump(path: Path, payload: Dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def _ordered_unique(items: Iterable[str]) -> List[str]:
+    seen = set()
+    ordered: List[str] = []
+    for item in items:
+        cleaned = str(item).strip()
+        if not cleaned or cleaned in seen:
+            continue
+        seen.add(cleaned)
+        ordered.append(cleaned)
+    return ordered
+
+
+def normalize_repair_policy(policy: Dict[str, object] | None = None) -> Dict[str, object]:
+    merged = dict(DEFAULT_REPAIR_POLICY)
+    if policy:
+        merged.update(policy)
+
+    merged["enabled"] = bool(merged.get("enabled", True))
+    merged["triggerOnBlocked"] = bool(merged.get("triggerOnBlocked", True))
+    merged["autoPrepareWorker"] = bool(merged.get("autoPrepareWorker", True))
+    merged["triggerValidationStatuses"] = _ordered_unique(
+        str(item).lower() for item in list(merged.get("triggerValidationStatuses", []))
+    )
+    try:
+        max_attempts = int(merged.get("maxAttemptsPerTask", 2) or 2)
+    except (TypeError, ValueError):
+        max_attempts = 2
+    merged["maxAttemptsPerTask"] = max(1, max_attempts)
+
+    requeue_status = str(merged.get("requeueTodoStatus", "DOING")).strip().upper()
+    if requeue_status not in {"TODO", "DOING"}:
+        requeue_status = "DOING"
+    merged["requeueTodoStatus"] = requeue_status
+    return merged
+
+
+def load_repair_policy(project_root: Path) -> Dict[str, object]:
+    state_path = aireng_root(project_root) / "state.json"
+    state = _json_load(state_path)
+    return normalize_repair_policy(state.get("repairPolicy", {}))
+
+
+def _repair_root(project_root: Path) -> Path:
+    return aireng_root(project_root) / "repairs"
+
+
+def _repair_queue_path(project_root: Path) -> Path:
+    return aireng_root(project_root) / "repair-queue.md"
+
+
+def _repair_attempt_path(project_root: Path, task_id: str, repair_id: str) -> Path:
+    return _repair_root(project_root) / task_id / repair_id / "attempt.json"
+
+
+def _repair_brief_path(project_root: Path, task_id: str, repair_id: str) -> Path:
+    return _repair_root(project_root) / task_id / repair_id / "repair-brief.md"
+
+
+def _worker_repair_brief_path(project_root: Path, task_id: str) -> Path:
+    return airdo_root(project_root) / "tasks" / task_id / "repair-brief.md"
+
+
+def _repair_reasons(result: WorkerResult, policy: Dict[str, object]) -> List[str]:
+    reasons: List[str] = []
+    if result.status == "blocked" and bool(policy.get("triggerOnBlocked", True)):
+        reasons.append("blocked worker result requires automatic repair")
+    tracked_statuses = {
+        str(item).lower() for item in list(policy.get("triggerValidationStatuses", []))
+    }
+    failed_validations = [
+        item for item in result.validations if item.status.lower() in tracked_statuses
+    ]
+    if failed_validations:
+        reasons.append(
+            "validation failures: "
+            + ", ".join(f"{item.kind}:{item.status}" for item in failed_validations)
+        )
+    return reasons
+
+
+def _build_repair_brief(project_root: Path, result: WorkerResult, attempt: RepairAttempt) -> str:
+    debug_session_ids = ", ".join(f"`{item}`" for item in attempt.debug_session_ids) or "`none`"
+    xdb_session_ids = ", ".join(f"`{item.session_id}`" for item in result.xdb_sessions) or "`none`"
+    validations = (
+        "; ".join(
+            f"{item.kind}:{item.status}" + (f" ({item.command})" if item.command else "")
+            for item in result.validations
+        )
+        or "none"
+    )
+    evidence = ", ".join(f"`{item}`" for item in result.evidence_paths) or "`none`"
+    blockers = ", ".join(result.blockers) or "none"
+    risks = ", ".join(result.risks) or "none"
+    return "\n".join(
+        [
+            f"# Auto Repair Brief: {attempt.repair_id}",
+            "",
+            f"- Task ID: `{result.task_id}`",
+            f"- Attempt Index: `{attempt.attempt_index}`",
+            f"- Source Status: `{result.status}`",
+            f"- Reason: {attempt.reason}",
+            f"- Debug Sessions: {debug_session_ids}",
+            f"- Source Result Path: `{attempt.source_result_path}`",
+            "",
+            "## Required Context",
+            "",
+            f"- Load `{project_root / 'AirPlan' / 'AGENTS.md'}`, `{project_root / 'AirPlan' / 'docs' / 'architecture' / 'adr'}`, `{project_root / 'AirPlan' / 'docs' / 'architecture' / 'c4' / 'module.md'}`, `{plan_path(project_root)}`, `{todo_path(project_root)}`, `{debug_log_path(project_root)}`, and `{gui_debug_log_path(project_root)}` when present.",
+            "- Read the referenced AirDbg request/session artifacts before changing code.",
+            "- If this task has AirXDB evidence, read the GUI screenshots and report before changing code.",
+            "- Continue repairing automatically. Do not stop at the existence of a debug request.",
+            "- Only return `blocked` again when the repair budget is exhausted or a real user decision is required.",
+            "",
+            "## Failure Snapshot",
+            "",
+            f"- Summary: {result.summary}",
+            f"- Validations: {validations}",
+            f"- Blockers: {blockers}",
+            f"- Evidence: {evidence}",
+            f"- XDB Sessions: {xdb_session_ids}",
+            f"- Risks: {risks}",
+            "",
+            "## Repair Goal",
+            "",
+            "- Modify the scoped code until the original validation path passes again.",
+            "- Keep the same task id and reuse the existing debug session id in the final repaired result.",
+            "- Update document sync content if the final fix changes architecture or execution rules.",
+            "",
+            f"- Project Root: `{project_root}`",
+        ]
+    ) + "\n"
+
+
+def _write_repair_attempt_artifacts(
+    project_root: Path, result: WorkerResult, attempt: RepairAttempt
+) -> RepairAttempt:
+    attempt_path = Path(attempt.state_path)
+    brief_path = Path(attempt.repair_brief_path)
+    worker_brief_path = Path(attempt.worker_brief_path)
+
+    brief_content = _build_repair_brief(project_root, result, attempt)
+    brief_path.parent.mkdir(parents=True, exist_ok=True)
+    brief_path.write_text(brief_content, encoding="utf-8")
+
+    worker_brief_path.parent.mkdir(parents=True, exist_ok=True)
+    worker_brief_path.write_text(brief_content, encoding="utf-8")
+
+    _json_dump(
+        attempt_path,
+        {
+            "repairAttempt": attempt.to_dict(),
+            "sourceSummary": result.summary,
+            "sourceBlockers": result.blockers,
+            "sourceValidations": [item.to_dict() for item in result.validations],
+            "sourceEvidencePaths": result.evidence_paths,
+        },
+    )
+    return attempt
+
+
+def list_repair_attempts(project_root: Path, task_id: str = "") -> List[RepairAttempt]:
+    repair_root = _repair_root(project_root)
+    if not repair_root.exists():
+        return []
+
+    attempts: List[RepairAttempt] = []
+    search_root = repair_root / task_id if task_id else repair_root
+    if not search_root.exists():
+        return []
+
+    for path in sorted(search_root.rglob("attempt.json")):
+        try:
+            payload = json.loads(path.read_text(encoding="utf-8-sig"))
+            attempt_payload = payload.get("repairAttempt", payload)
+            attempt = RepairAttempt.from_dict(attempt_payload)
+            attempt.validate()
+        except (json.JSONDecodeError, TypeError, ValueError):
+            continue
+        if task_id and attempt.task_id != task_id:
+            continue
+        attempts.append(attempt)
+
+    attempts.sort(key=lambda item: (item.created_at, item.repair_id))
+    return attempts
+
+
+def load_active_repair_attempt(project_root: Path, task_id: str) -> RepairAttempt | None:
+    for attempt in reversed(list_repair_attempts(project_root, task_id)):
+        if attempt.status in {"queued", "active"}:
+            return attempt
+    return None
+
+
+def _set_attempt_status(attempt: RepairAttempt, status: str) -> RepairAttempt:
+    attempt.status = status
+    attempt_path = Path(attempt.state_path)
+    if attempt_path.exists():
+        payload = json.loads(attempt_path.read_text(encoding="utf-8-sig"))
+        payload["repairAttempt"] = attempt.to_dict()
+        _json_dump(attempt_path, payload)
+    return attempt
+
+
+def ensure_repair_attempts_for_result(
+    project_root: Path, result: WorkerResult, source_result_path: str = ""
+) -> List[RepairAttempt]:
+    policy = load_repair_policy(project_root)
+    if not bool(policy.get("enabled", True)):
+        return result.repair_attempts
+
+    if result.repair_attempts:
+        return result.repair_attempts
+
+    existing_attempts = list_repair_attempts(project_root, result.task_id)
+    active_attempts = [
+        item for item in existing_attempts if item.status in {"queued", "active"}
+    ]
+
+    if result.status == "done":
+        if active_attempts:
+            resolved_attempts = []
+            for attempt in active_attempts:
+                resolved_attempts.append(_set_attempt_status(attempt, "resolved"))
+            result.repair_attempts = resolved_attempts
+        return result.repair_attempts
+
+    reasons = _repair_reasons(result, policy)
+    if not reasons:
+        return result.repair_attempts
+
+    if active_attempts:
+        result.repair_attempts = active_attempts
+        return result.repair_attempts
+
+    if len(existing_attempts) >= int(policy.get("maxAttemptsPerTask", 2) or 2):
+        result.notes.append(
+            f"Automatic repair budget exhausted for {result.task_id}; user decision may be required."
+        )
+        return result.repair_attempts
+
+    attempt_index = len(existing_attempts) + 1
+    repair_id = f"{result.task_id}-repair-{attempt_index:03d}"
+    created_at = now_iso()
+    attempt = RepairAttempt(
+        repair_id=repair_id,
+        task_id=result.task_id,
+        attempt_index=attempt_index,
+        source_status=result.status,
+        source_result_path=source_result_path or "",
+        reason="; ".join(reasons),
+        repair_brief_path=str(_repair_brief_path(project_root, result.task_id, repair_id)),
+        state_path=str(_repair_attempt_path(project_root, result.task_id, repair_id)),
+        worker_brief_path=str(_worker_repair_brief_path(project_root, result.task_id)),
+        debug_session_ids=_ordered_unique(
+            item.session_id for item in result.debug_sessions if item.session_id
+        ),
+        status="queued",
+        created_at=created_at,
+    )
+    _write_repair_attempt_artifacts(project_root, result, attempt)
+    result.repair_attempts = [attempt]
+    result.notes.append(
+        f"Automatic repair attempt queued for {result.task_id}: {attempt.repair_id}"
+    )
+    return result.repair_attempts
+
+
+def mark_repair_attempts_active(project_root: Path, task_id: str) -> List[RepairAttempt]:
+    updated: List[RepairAttempt] = []
+    for attempt in list_repair_attempts(project_root, task_id):
+        if attempt.status == "queued":
+            updated.append(_set_attempt_status(attempt, "active"))
+    return updated
+
+
+def merge_repair_attempts_into_state(
+    state: Dict[str, object], repair_attempts: List[RepairAttempt]
+) -> Dict[str, object]:
+    state["repairPolicy"] = normalize_repair_policy(dict(state.get("repairPolicy", {})))
+
+    existing_items = list(state.get("repairAttempts", []))
+    items_by_id = {}
+    for item in existing_items:
+        if not isinstance(item, dict):
+            continue
+        repair_id = str(item.get("repairId", "")).strip()
+        if repair_id:
+            items_by_id[repair_id] = item
+
+    for attempt in repair_attempts:
+        items_by_id[attempt.repair_id] = attempt.to_dict()
+
+    merged_items = [items_by_id[key] for key in sorted(items_by_id)]
+    state["repairAttempts"] = merged_items
+    state["activeRepairCount"] = sum(
+        1 for item in merged_items if str(item.get("status", "")).strip() in {"queued", "active"}
+    )
+    if repair_attempts:
+        latest = repair_attempts[-1]
+        state["lastRepairAttemptId"] = latest.repair_id
+        state["lastRepairTaskId"] = latest.task_id
+        state["lastRepairAt"] = latest.created_at
+    return state
+
+
+def summarize_active_repairs(state: Dict[str, object]) -> List[Dict[str, str]]:
+    summary: List[Dict[str, str]] = []
+    for item in list(state.get("repairAttempts", [])):
+        if not isinstance(item, dict):
+            continue
+        status = str(item.get("status", "")).strip()
+        if status not in {"queued", "active"}:
+            continue
+        summary.append(
+            {
+                "repairId": str(item.get("repairId", "")).strip(),
+                "taskId": str(item.get("taskId", "")).strip(),
+                "status": status,
+                "reason": str(item.get("reason", "")).strip(),
+                "repairBriefPath": str(item.get("repairBriefPath", "")).strip(),
+            }
+        )
+    return summary
+
+
+def write_repair_queue(project_root: Path, state: Dict[str, object]) -> Path:
+    queue_path = _repair_queue_path(project_root)
+    active_items = summarize_active_repairs(state)
+    lines = [
+        "# Air Engine Auto Repair Queue",
+        "",
+        "This file lists repair attempts that were automatically queued from blocked or failed worker results.",
+        "",
+    ]
+    if active_items:
+        for item in active_items:
+            lines.append(f"- Repair: `{item['repairId']}`")
+            lines.append(f"  Task: `{item['taskId']}`")
+            lines.append(f"  Status: `{item['status']}`")
+            lines.append(f"  Reason: {item['reason'] or 'n/a'}")
+            lines.append(f"  Brief: `{item['repairBriefPath']}`")
+    else:
+        lines.append("- No active auto repair attempts.")
+
+    queue_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return queue_path

AirPlan/docs/spec/AirPlan-ParaV2/lib/air_runtime/review.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+from itertools import combinations
+from pathlib import Path
+from typing import Dict, Iterable, List, Set
+
+from .contracts import (
+    ACTIVE_TASK_STATUSES,
+    ParallelGroup,
+    ParallelReview,
+    ReviewConflict,
+    TaskRecord,
+    now_iso,
+)
+from .todo_parser import parse_tasks
+
+
+def _overlap_paths(left: Iterable[str], right: Iterable[str]) -> List[str]:
+    overlap: Set[str] = set()
+    left_items = list(left)
+    right_items = list(right)
+
+    for left_path in left_items:
+        for right_path in right_items:
+            left_clean = left_path.rstrip("/\\")
+            right_clean = right_path.rstrip("/\\")
+            if left_clean == right_clean:
+                overlap.add(left_path)
+                continue
+            if left_clean.startswith(right_clean):
+                overlap.add(right_path)
+            elif right_clean.startswith(left_clean):
+                overlap.add(left_path)
+
+    return sorted(overlap)
+
+
+def _task_conflict(left: TaskRecord, right: TaskRecord) -> ReviewConflict | None:
+    overlap = _overlap_paths(left.normalized_write_set(), right.normalized_write_set())
+    if overlap:
+        return ReviewConflict(
+            task_ids=[left.task_id, right.task_id],
+            reason="shared write set overlap",
+            overlap_paths=overlap,
+        )
+
+    if left.touches_global_docs() and right.touches_global_docs():
+        return ReviewConflict(
+            task_ids=[left.task_id, right.task_id],
+            reason="both tasks touch global planning or architecture documents",
+            overlap_paths=sorted(set(left.global_doc_paths + right.global_doc_paths)),
+        )
+
+    return None
+
+
+def _greedy_parallel_groups(tasks: List[TaskRecord]) -> List[ParallelGroup]:
+    groups: List[List[TaskRecord]] = []
+    for task in tasks:
+        placed = False
+        for group in groups:
+            if all(_task_conflict(task, existing) is None for existing in group):
+                group.append(task)
+                placed = True
+                break
+        if not placed:
+            groups.append([task])
+
+    output: List[ParallelGroup] = []
+    for index, group in enumerate(groups, start=1):
+        output.append(
+            ParallelGroup(
+                name=f"group-{index}",
+                task_ids=[task.task_id for task in group],
+                reason="no detected write-set conflict inside this group",
+            )
+        )
+    return output
+
+
+def _build_dependency_edges(tasks: List[TaskRecord]) -> List[Dict[str, str]]:
+    task_ids = {task.task_id for task in tasks}
+    edges: List[Dict[str, str]] = []
+    for task in tasks:
+        for dependency in task.dependencies:
+            if dependency in task_ids:
+                edges.append({"from": dependency, "to": task.task_id})
+    return edges
+
+
+def build_parallel_review(todo_path: Path) -> ParallelReview:
+    all_tasks = parse_tasks(todo_path)
+    active_tasks = [task for task in all_tasks if task.status in ACTIVE_TASK_STATUSES]
+    active_task_ids = {task.task_id for task in active_tasks}
+    task_map = {task.task_id: task for task in active_tasks}
+    edges = _build_dependency_edges(active_tasks)
+
+    in_degree = {task.task_id: 0 for task in active_tasks}
+    children: Dict[str, List[str]] = {task.task_id: [] for task in active_tasks}
+    for edge in edges:
+        parent = edge["from"]
+        child = edge["to"]
+        if parent not in active_task_ids or child not in active_task_ids:
+            continue
+        in_degree[child] += 1
+        children[parent].append(child)
+
+    ready = sorted(
+        [task.task_id for task in active_tasks if in_degree[task.task_id] == 0],
+        key=lambda task_id: task_map[task_id].line_number,
+    )
+    scheduled = set()
+    parallel_groups: List[ParallelGroup] = []
+    wave_index = 1
+
+    while ready:
+        current_wave_ids = ready
+        ready = []
+        current_tasks = [task_map[task_id] for task_id in current_wave_ids]
+        wave_groups = _greedy_parallel_groups(current_tasks)
+        for group in wave_groups:
+            group.name = f"wave-{wave_index}-{group.name}"
+        parallel_groups.extend(wave_groups)
+        wave_index += 1
+
+        for task_id in current_wave_ids:
+            scheduled.add(task_id)
+            for child in children.get(task_id, []):
+                in_degree[child] -= 1
+                if in_degree[child] == 0:
+                    ready.append(child)
+        ready.sort(key=lambda task_id: task_map[task_id].line_number)
+
+    notes: List[str] = []
+    unscheduled = sorted(active_task_ids - scheduled)
+    if unscheduled:
+        notes.append(
+            "Some active tasks could not be layered. Check for cyclic or missing dependencies: "
+            + ", ".join(unscheduled)
+        )
+
+    if all(not task.dependencies for task in active_tasks) and len(active_tasks) > 1:
+        notes.append(
+            "No explicit dependency hints were found. Parallel grouping relies on write-set isolation and global-doc serialization rules."
+        )
+
+    blocked_tasks = [task.task_id for task in all_tasks if task.status == "BLOCKED"]
+    if blocked_tasks:
+        notes.append("Blocked tasks were excluded from ready groups: " + ", ".join(blocked_tasks))
+
+    conflicts: List[ReviewConflict] = []
+    for left, right in combinations(active_tasks, 2):
+        conflict = _task_conflict(left, right)
+        if conflict is not None:
+            conflicts.append(conflict)
+
+    serialization_points: List[Dict[str, object]] = []
+    for task in active_tasks:
+        reasons: List[str] = []
+        if task.touches_global_docs():
+            reasons.append("touches global planning or architecture documents")
+        if any(task.task_id in conflict.task_ids for conflict in conflicts):
+            reasons.append("has shared write-set conflicts that need engine-level scheduling")
+        if reasons:
+            serialization_points.append(
+                {
+                    "taskId": task.task_id,
+                    "reasons": reasons,
+                    "paths": task.global_doc_paths or task.normalized_write_set(),
+                }
+            )
+
+    return ParallelReview(
+        source_todo=str(todo_path),
+        generated_at=now_iso(),
+        tasks_considered=active_tasks,
+        dependency_edges=edges,
+        parallel_groups=parallel_groups,
+        conflicts=conflicts,
+        serialization_points=serialization_points,
+        notes=notes,
+    )
+
+
+def render_review_markdown(review: ParallelReview) -> str:
+    lines = [
+        "# AirArc Parallel Review",
+        "",
+        f"- Source TODO: `{review.source_todo}`",
+        f"- Generated At: `{review.generated_at}`",
+        f"- Active Tasks: `{', '.join(task.task_id for task in review.tasks_considered) or 'none'}`",
+        "",
+        "## Parallel Groups",
+    ]
+
+    if review.parallel_groups:
+        for group in review.parallel_groups:
+            lines.append(f"- `{group.name}`: {', '.join(group.task_ids)}")
+            lines.append(f"  Reason: {group.reason}")
+    else:
+        lines.append("- No ready parallel groups were detected.")
+
+    lines.extend(["", "## Dependency Edges"])
+    if review.dependency_edges:
+        for edge in review.dependency_edges:
+            lines.append(f"- `{edge['from']}` -> `{edge['to']}`")
+    else:
+        lines.append("- No explicit dependency edges were detected.")
+
+    lines.extend(["", "## Shared-Write Conflicts"])
+    if review.conflicts:
+        for conflict in review.conflicts:
+            lines.append(
+                f"- `{conflict.task_ids[0]}` <-> `{conflict.task_ids[1]}`: {conflict.reason}"
+            )
+            if conflict.overlap_paths:
+                lines.append("  Paths: " + ", ".join(f"`{path}`" for path in conflict.overlap_paths))
+    else:
+        lines.append("- No shared-write conflicts were detected.")
+
+    lines.extend(["", "## Serialization Points"])
+    if review.serialization_points:
+        for point in review.serialization_points:
+            lines.append(f"- `{point['taskId']}`: {'; '.join(point['reasons'])}")
+            paths = point.get("paths", [])
+            if paths:
+                lines.append("  Paths: " + ", ".join(f"`{path}`" for path in paths))
+    else:
+        lines.append("- No serialization points were detected.")
+
+    lines.extend(["", "## Notes"])
+    if review.notes:
+        for note in review.notes:
+            lines.append(f"- {note}")
+    else:
+        lines.append("- No extra notes.")
+
+    return "\n".join(lines) + "\n"

AirPlan/docs/spec/AirPlan-ParaV2/lib/air_runtime/todo_parser.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from .contracts import TaskRecord
+
+TASK_ID_RE = re.compile(r"T-\d+")
+HEADER_RE = re.compile(r"^\|\s*ID\s*\|\s*Status\s*\|", re.IGNORECASE)
+SEPARATOR_RE = re.compile(r"^\|\s*:?-+:?\s*(\|\s*:?-+:?\s*)+\|?$")
+CODE_SPAN_RE = re.compile(r"`([^`]+)`")
+DEPENDENCY_HINT_RE = re.compile(r"\[(?:deps?|depends)\s*:\s*([^\]]+)\]", re.IGNORECASE)
+
+
+def _split_row(line: str) -> List[str]:
+    return [cell.strip() for cell in line.strip().strip("|").split("|")]
+
+
+def _normalize_paths(items: List[str]) -> List[str]:
+    seen = set()
+    ordered: List[str] = []
+    for item in items:
+        cleaned = item.strip().strip("`")
+        if not cleaned or cleaned.lower() == "planned":
+            continue
+        if cleaned in seen:
+            continue
+        seen.add(cleaned)
+        ordered.append(cleaned)
+    return ordered
+
+
+def extract_paths(cell_text: str) -> List[str]:
+    code_paths = CODE_SPAN_RE.findall(cell_text)
+    if code_paths:
+        return _normalize_paths(code_paths)
+
+    candidates = re.split(r"[,;+]", cell_text)
+    paths = [
+        token.strip()
+        for token in candidates
+        if "/" in token or "\\" in token or token.endswith((".md", ".py", ".json"))
+    ]
+    return _normalize_paths(paths)
+
+
+def extract_dependencies(*cells: str) -> List[str]:
+    found: List[str] = []
+    for cell in cells:
+        for match in DEPENDENCY_HINT_RE.finditer(cell):
+            found.extend(TASK_ID_RE.findall(match.group(1)))
+    return _normalize_paths(found)
+
+
+def extract_global_doc_paths(*cells: str) -> List[str]:
+    text = " ".join(cells)
+    candidates: List[str] = []
+    lowered = text.lower()
+
+    if "agents.md" in lowered or "agents" in text:
+        candidates.append("AirPlan/AGENTS.md")
+    if "airplan/docs/architecture/adr" in lowered or "docs/architecture/adr" in lowered or "adr" in text:
+        candidates.append("AirPlan/docs/architecture/adr/")
+    if "airplan/docs/architecture/c4/module.md" in lowered or "docs/architecture/c4/module.md" in lowered or "c4" in text:
+        candidates.append("AirPlan/docs/architecture/c4/module.md")
+    if "plan.md" in lowered:
+        candidates.append("AirPlan/plan.md")
+    if "todo.md" in lowered or "todo" in text:
+        candidates.append("AirPlan/todo.md")
+    if "staticanalysis.md" in lowered:
+        candidates.append("AirPlan/docs/staticanalysis.md")
+
+    for path in extract_paths(text):
+        normalized = path.replace("\\", "/")
+        if normalized in {"AGENTS.md", "AirPlan/AGENTS.md"}:
+            candidates.append("AirPlan/AGENTS.md")
+        elif "AirPlan/docs/architecture/adr" in normalized or "docs/architecture/adr" in normalized:
+            candidates.append("AirPlan/docs/architecture/adr/")
+        elif "AirPlan/docs/architecture/c4/module.md" in normalized or "docs/architecture/c4/module.md" in normalized:
+            candidates.append("AirPlan/docs/architecture/c4/module.md")
+        elif normalized in {"plan.md", "AirPlan/plan.md"}:
+            candidates.append("AirPlan/plan.md")
+        elif normalized in {"todo.md", "AirPlan/todo.md"}:
+            candidates.append("AirPlan/todo.md")
+        elif normalized in {"staticanalysis.md", "AirPlan/docs/staticanalysis.md"}:
+            candidates.append("AirPlan/docs/staticanalysis.md")
+
+    return _normalize_paths(candidates)
+
+
+def parse_tasks(todo_path: Path) -> List[TaskRecord]:
+    lines = todo_path.read_text(encoding="utf-8").splitlines()
+    header_index: Optional[int] = None
+
+    for idx, line in enumerate(lines):
+        if HEADER_RE.search(line):
+            header_index = idx
+            break
+
+    if header_index is None:
+        raise ValueError(f"no TODO task table found in {todo_path}")
+
+    header_cells = _split_row(lines[header_index])
+    tasks: List[TaskRecord] = []
+
+    for line_number in range(header_index + 1, len(lines)):
+        raw_line = lines[line_number]
+        if not raw_line.strip():
+            if tasks:
+                break
+            continue
+        if not raw_line.strip().startswith("|"):
+            if tasks:
+                break
+            continue
+        if SEPARATOR_RE.match(raw_line):
+            continue
+
+        row_cells = _split_row(raw_line)
+        if len(row_cells) < len(header_cells):
+            row_cells += [""] * (len(header_cells) - len(row_cells))
+
+        row: Dict[str, str] = dict(zip(header_cells, row_cells))
+        task_id = row.get("ID", "").strip()
+        if not task_id:
+            continue
+
+        files_dirs = row.get("Files/Dirs", "").strip()
+        adr_c4_update = row.get("ADR/C4 Update", "").strip()
+        task_text = row.get("Task", "").strip()
+        validation = row.get("Validation", "").strip()
+
+        tasks.append(
+            TaskRecord(
+                task_id=task_id,
+                status=row.get("Status", "").strip().upper(),
+                module=row.get("Module", "").strip(),
+                task=task_text,
+                files_dirs=files_dirs,
+                done_when=row.get("Done When", "").strip(),
+                validation=validation,
+                adr_c4_update=adr_c4_update,
+                line_number=line_number + 1,
+                dependencies=extract_dependencies(task_text, files_dirs, validation, adr_c4_update),
+                write_paths=extract_paths(files_dirs),
+                global_doc_paths=extract_global_doc_paths(
+                    files_dirs, adr_c4_update, task_text
+                ),
+            )
+        )
+
+    return tasks
+
+
+def find_task(tasks: List[TaskRecord], task_id: str) -> Optional[TaskRecord]:
+    for task in tasks:
+        if task.task_id == task_id:
+            return task
+    return None

AirPlan/docs/spec/AirPlan-ParaV2/lib/air_runtime/worker.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, List
+
+from .airxdb_runtime import ensure_xdb_sessions_for_result, task_requires_xdb
+from .contracts import (
+    DocumentUpdate,
+    WorkerResult,
+    default_worker_result,
+    now_iso,
+    required_project_artifacts,
+)
+from .debug_runtime import ensure_debug_sessions_for_result
+from .doc_sync import enforce_doc_sync_requirements
+from .paths import (
+    agents_path,
+    airdo_root,
+    architecture_adr_dir,
+    architecture_c4_module_path,
+    plan_path,
+    todo_path,
+)
+from .repair_runtime import load_active_repair_attempt
+from .todo_parser import find_task, parse_tasks
+
+
+def _json_dump(path: Path, payload: Dict[str, object]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def _artifact_health(project_root: Path) -> Dict[str, bool]:
+    return {
+        relative: (project_root / relative).exists()
+        for relative in required_project_artifacts()
+    }
+
+
+def _paths(project_root: Path) -> Dict[str, Path]:
+    worker_root = airdo_root(project_root)
+    return {
+        "root": worker_root,
+        "state": worker_root / "state.json",
+        "tasks": worker_root / "tasks",
+        "results": worker_root / "results",
+    }
+
+
+def _ensure_layout(project_root: Path) -> Dict[str, Path]:
+    paths = _paths(project_root)
+    paths["tasks"].mkdir(parents=True, exist_ok=True)
+    paths["results"].mkdir(parents=True, exist_ok=True)
+    return paths
+
+
+def _task_dir(project_root: Path, task_id: str) -> Path:
+    return _paths(project_root)["tasks"] / task_id
+
+
+def worker_state_path(project_root: Path, task_id: str) -> Path:
+    return _task_dir(project_root, task_id) / "worker-state.json"
+
+
+def _load_task_record(project_root: Path, task_id: str):
+    current_todo = todo_path(project_root)
+    if not current_todo.exists():
+        return None
+    try:
+        return find_task(parse_tasks(current_todo), task_id)
+    except ValueError:
+        return None
+
+
+def _worker_rules_block() -> List[str]:
+    return [
+        "## Worker Rules",
+        "",
+        "- Load `AirPlan/AGENTS.md`, `AirPlan/docs/architecture/adr/`, `AirPlan/docs/architecture/c4/module.md`, `AirPlan/plan.md`, and `AirPlan/todo.md` before doing work.",
+        "- Keep the task scoped to this brief.",
+        "- Preserve validation evidence on disk.",
+        "- Do not directly take ownership of global `AirPlan/todo.md`, `AirPlan/AGENTS.md`, ADR, or C4 updates unless explicitly delegated.",
+        "- If this task touches global docs, `result.json` must include executable `documentUpdates`, not just recommendations.",
+        "- If this task is GUI or visual acceptance related, `result.json` must end with successful AirXDB evidence before it can close as done.",
+        "- If the result is blocked, or a validation ends in failed/error, the worker auto-requests AirDbg before finalize.",
+        "- If the task is GUI-related, the worker auto-captures AirXDB evidence before finalize.",
+        "- If an active auto-repair attempt exists, continue repairing immediately instead of stopping at the debug request.",
+        "- Do not stop at an 'about to implement', 'implementation plan ready', or similar midpoint status. Continue editing, validating, and finalizing unless a real blocker or user decision is required.",
+        "- Do not return only a progress update when the task is actionable. Return only after finalize, or after recording a concrete blocked reason that needs intervention.",
+        "- Fill `result.json`, then finalize it for engine merge.",
+        "",
+    ]
+
+
+def _placeholder_result(project_root: Path, task_id: str) -> WorkerResult:
+    task_summary = ""
+    task = _load_task_record(project_root, task_id)
+    if task:
+        task_summary = task.task
+
+    result = default_worker_result(task_id, task_summary)
+    if task and task.global_doc_paths:
+        result.global_doc_paths = list(task.global_doc_paths)
+        result.recommend_global_doc_updates = list(task.global_doc_paths)
+        result.document_updates = []
+        for doc_path in task.global_doc_paths:
+            if doc_path == "AirPlan/docs/architecture/adr/":
+                result.document_updates.append(
+                    DocumentUpdate(
+                        path="AirPlan/docs/architecture/adr/ADR-XXXX-task-sync.md",
+                        action="create_file",
+                        content=(
+                            "# ADR-XXXX: task-sync\n\n"
+                            "- Status: Accepted\n"
+                            "- Date: YYYY-MM-DD\n\n"
+                            "## Context\n"
+                            "Replace with the concrete context introduced by this task.\n\n"
+                            "## Decision\n"
+                            "Replace with the concrete decision introduced by this task.\n\n"
+                            "## Consequences\n"
+                            "- Replace with the concrete consequences introduced by this task.\n"
+                        ),
+                    )
+                )
+            else:
+                result.document_updates.append(
+                    DocumentUpdate(
+                        path=doc_path,
+                        action="replace_block",
+                        marker=f"{task_id}-{Path(doc_path).name}".replace(".", "-").upper(),
+                        content=(
+                            f"## Sync For {task_id}\n\n"
+                            "- Summary: Replace with a concrete summary.\n"
+                            "- Code Reality: Replace with the actual code outcome.\n"
+                            "- Validation: Replace with the actual validation result.\n"
+                        ),
+                    )
+                )
+    return result
+
+
+def _is_untouched_placeholder_result(project_root: Path, result: WorkerResult) -> bool:
+    placeholder = _placeholder_result(project_root, result.task_id)
+    return result.to_dict() == placeholder.to_dict()
+
+
+def resolve_worker_result_path(project_root: Path, task_id: str) -> Path:
+    state_path = worker_state_path(project_root, task_id)
+    if state_path.exists():
+        payload = json.loads(state_path.read_text(encoding="utf-8-sig"))
+        raw_path = str(payload.get("resultPath", "")).strip()
+        if raw_path:
+            candidate = Path(raw_path).expanduser()
+            if not candidate.is_absolute():
+                candidate = (project_root / candidate).resolve()
+            return candidate
+    return _task_dir(project_root, task_id) / "result.json"
+
+
+def _write_brief(project_root: Path, task_id: str) -> Path:
+    task_folder = _task_dir(project_root, task_id)
+    task_folder.mkdir(parents=True, exist_ok=True)
+    task = _load_task_record(project_root, task_id)
+    active_repair = load_active_repair_attempt(project_root, task_id)
+
+    lines: List[str] = [f"# Worker Brief: {task_id}", ""]
+    if task:
+        requires_xdb = task_requires_xdb(task, None)
+        lines.extend(
+            [
+                f"- Module: `{task.module}`",
+                f"- Status In TODO: `{task.status}`",
+                f"- Task: {task.task}",
+                f"- Write Scope: {', '.join(f'`{path}`' for path in task.write_paths) or '`(not declared)`'}",
+                f"- Global Doc Paths: {', '.join(f'`{path}`' for path in task.global_doc_paths) or '`none`'}",
+                f"- Validation: {task.validation or '(not declared)'}",
+                f"- Document Sync Required: {'yes' if task.global_doc_paths else 'no'}",
+                f"- AirXDB Required: {'yes' if requires_xdb else 'no'}",
+                "",
+            ]
+        )
+
+    if active_repair:
+        lines.extend(
+            [
+                "## Active Auto Repair",
+                "",
+                f"- Repair ID: `{active_repair.repair_id}`",
+                f"- Attempt Index: `{active_repair.attempt_index}`",
+                f"- Status: `{active_repair.status}`",
+                f"- Reason: {active_repair.reason}",
+                f"- Repair Brief: `{active_repair.repair_brief_path}`",
+                f"- Debug Sessions: {', '.join(f'`{item}`' for item in active_repair.debug_session_ids) or '`none`'}",
+                "",
+            ]
+        )
+
+    lines.extend(_worker_rules_block())
+    brief_path = task_folder / "brief.md"
+    brief_path.write_text("\n".join(lines), encoding="utf-8")
+    return brief_path
+
+
+def _write_handoff(project_root: Path, task_id: str, brief_path: Path, result_path: Path) -> Path:
+    task = _load_task_record(project_root, task_id)
+    current_worker_state_path = worker_state_path(project_root, task_id)
+    handoff_path = _task_dir(project_root, task_id) / "subagent-handoff.md"
+    lines = [
+        f"# AirDo Subagent Handoff: {task_id}",
+        "",
+        "You are an isolated AirDo execution subagent launched by AirEng.",
+        "",
+        f"- Task ID: `{task_id}`",
+        f"- Project Root: `{project_root}`",
+        f"- Brief Path: `{brief_path}`",
+        f"- Worker State Path: `{current_worker_state_path}`",
+        f"- Template Result Path: `{result_path}`",
+        f"- Task Summary: {task.task if task else '(load from brief)'}",
+        f"- Write Scope: {', '.join(f'`{path}`' for path in (task.write_paths if task else [])) or '`(load from brief)`'}",
+        "",
+        "## Required Reads",
+        "",
+        f"- `{agents_path(project_root)}`",
+        f"- `{architecture_adr_dir(project_root)}`",
+        f"- `{architecture_c4_module_path(project_root)}`",
+        f"- `{plan_path(project_root)}`",
+        f"- `{todo_path(project_root)}`",
+        f"- `{brief_path}`",
+        "",
+        "## Execution Contract",
+        "",
+        "- Stay inside this task scope and its declared write set.",
+        "- Do not assume the parent thread history is available; build context from the files above.",
+        "- Execute the task, gather validation evidence, and update `result.json` with honest status, files changed, risks, blockers, and document updates when required.",
+        "- Run AirDbg or AirXDB automatically when the runtime rules require them.",
+        "- Do not pause for intermediate implementation-status replies. Keep going until the task is finalized unless you hit a real blocker that requires external input.",
+        "- Finalize the result before returning control to AirEng.",
+        "",
+        "## Finalize Command",
+        "",
+        f"`python \"$HOME/plugins/airdo/scripts/airdo_mode.py\" --mode finish --project . --task-id {task_id}`",
+        "",
+        "## Return Contract",
+        "",
+        "- Report the final status and the finalized result path.",
+        "- After `finish`, treat `worker-state.json` `resultPath` as the canonical result location instead of re-reading the template `result.json`.",
+        "- Do not merge global docs yourself unless the task explicitly delegated document updates through `result.json`.",
+        "",
+    ]
+    handoff_path.write_text("\n".join(lines), encoding="utf-8")
+    return handoff_path
+
+
+def enter_worker(project_root: Path, task_id: str) -> Dict[str, object]:
+    paths = _ensure_layout(project_root)
+    task_folder = _task_dir(project_root, task_id)
+    task_folder.mkdir(parents=True, exist_ok=True)
+
+    result_path = task_folder / "result.json"
+    if not result_path.exists():
+        result = _placeholder_result(project_root, task_id)
+        _json_dump(result_path, result.to_dict())
+
+    brief_path = _write_brief(project_root, task_id)
+    handoff_path = _write_handoff(project_root, task_id, brief_path, result_path)
+    state_path = worker_state_path(project_root, task_id)
+    state = {
+        "enabled": True,
+        "updatedAt": now_iso(),
+        "projectRoot": str(project_root),
+        "artifactHealth": _artifact_health(project_root),
+        "activeTaskId": task_id,
+    }
+    _json_dump(paths["state"], state)
+    _json_dump(
+        state_path,
+        {
+            "taskId": task_id,
+            "status": "entered",
+            "enteredAt": now_iso(),
+            "templateResultPath": str(result_path),
+            "resultPath": str(result_path),
+            "briefPath": str(brief_path),
+            "handoffPath": str(handoff_path),
+        },
+    )
+    return {
+        "taskId": task_id,
+        "briefPath": str(brief_path),
+        "handoffPath": str(handoff_path),
+        "resultPath": str(result_path),
+        "workerStatePath": str(state_path),
+    }
+
+
+def handoff_worker(project_root: Path, task_id: str) -> Dict[str, object]:
+    entered = enter_worker(project_root, task_id)
+    return {
+        "taskId": task_id,
+        "briefPath": entered["briefPath"],
+        "handoffPath": entered["handoffPath"],
+        "resultPath": entered["resultPath"],
+        "workerStatePath": entered["workerStatePath"],
+    }
+
+
+def finish_worker(project_root: Path, task_id: str, result_path: Path | None) -> Dict[str, object]:
+    _ensure_layout(project_root)
+    task_folder = _task_dir(project_root, task_id)
+    if result_path is None:
+        result_path = task_folder / "result.json"
+
+    result = WorkerResult.from_dict(json.loads(result_path.read_text(encoding="utf-8-sig")))
+    if _is_untouched_placeholder_result(project_root, result):
+        raise ValueError(
+            "worker result is still the untouched default template; update result.json before finalize"
+        )
+    result.validate_for_finalize()
+    ensure_xdb_sessions_for_result(project_root, result, "worker-finish")
+    ensure_debug_sessions_for_result(project_root, result, "worker-finish")
+    result.validate_for_finalize()
+    enforce_doc_sync_requirements(project_root, result)
+    if result.task_id != task_id:
+        raise ValueError("result taskId does not match --task-id")
+    if not result.finalized_at:
+        result.finalized_at = now_iso()
+
+    finalized_path = _paths(project_root)["results"] / f"{task_id}.json"
+    _json_dump(finalized_path, result.to_dict())
+    previous_state: Dict[str, object] = {}
+    current_state_path = worker_state_path(project_root, task_id)
+    if current_state_path.exists():
+        previous_state = json.loads(current_state_path.read_text(encoding="utf-8-sig"))
+    _json_dump(
+        current_state_path,
+        {
+            "taskId": task_id,
+            "status": "completed",
+            "enteredAt": previous_state.get("enteredAt", ""),
+            "briefPath": previous_state.get("briefPath", ""),
+            "handoffPath": previous_state.get("handoffPath", ""),
+            "templateResultPath": previous_state.get("templateResultPath", str(task_folder / "result.json")),
+            "finalizedAt": result.finalized_at,
+            "resultPath": str(finalized_path),
+        },
+    )
+    return {
+        "taskId": task_id,
+        "status": result.status,
+        "finalizedResultPath": str(finalized_path),
+        "workerStatePath": str(current_state_path),
+    }
+
+
+def status_worker(project_root: Path) -> Dict[str, object]:
+    paths = _ensure_layout(project_root)
+    state_path = paths["state"]
+    enabled = state_path.exists()
+    active_task_id = ""
+    if enabled:
+        payload = json.loads(state_path.read_text(encoding="utf-8-sig"))
+        active_task_id = str(payload.get("activeTaskId", ""))
+
+    task_ids = sorted(path.name for path in paths["tasks"].iterdir() if path.is_dir())
+    return {
+        "enabled": enabled,
+        "projectRoot": str(project_root),
+        "artifactHealth": _artifact_health(project_root),
+        "activeTaskId": active_task_id,
+        "taskIds": task_ids,
+    }

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airarc/.codex-plugin/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "airarc",
+  "version": "0.3.1",
+  "description": "Experimental upgraded AirArc prototype with built-in post-plan parallelization review support.",
+  "author": {
+    "name": "14816",
+    "email": "noreply@example.com",
+    "url": "https://airlongdian.fun"
+  },
+  "homepage": "https://airlongdian.fun/plugins/airarc",
+  "repository": "https://airlongdian.fun/plugins/airarc",
+  "license": "MIT",
+  "keywords": [
+    "airarc",
+    "architecture",
+    "planning",
+    "parallel",
+    "review"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "AirArc",
+    "shortDescription": "Architecture-first planning with built-in parallel review",
+    "longDescription": "This AirArc prototype keeps architecture-first planning and adds a built-in post-plan review step that emits dependency edges, parallel-safe groups, shared write-set conflicts, serialization points, and an execution plan for Air Engine.",
+    "developerName": "14816",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "websiteURL": "https://airlongdian.fun/plugins/airarc",
+    "privacyPolicyURL": "https://openai.com/policies/row-privacy-policy/",
+    "termsOfServiceURL": "https://openai.com/policies/row-terms-of-use/",
+    "defaultPrompt": [
+      "Use AirArc to initialize or inspect project planning context.",
+      "Use AirArc to produce a post-plan parallelization review from todo.md.",
+      "Use AirArc to identify dependency edges, shared-write conflicts, and serialization points before workers run."
+    ],
+    "brandColor": "#0D9488",
+    "screenshots": []
+  }
+}

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airarc/commands/airarc.md

@@ -0,0 +1,24 @@
+---
+description: Enter, inspect, or run the upgraded AirArc planning flow with built-in parallel review output. AirArc is architecture-only and must not write code.
+argument-hint: [enter|status|parallel-review]
+allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
+---
+
+# /airarc
+
+Use the upgraded AirArc plugin for architecture-first planning and post-plan parallel review. AirArc only does architecture planning, task decomposition, and document updates; it does not implement code changes.
+
+## Steps
+
+1. Parse `$ARGUMENTS`; default to `enter` when empty.
+2. Run the matching mode from the current project root:
+
+```bash
+python "$HOME/plugins/airarc/scripts/airarc_mode.py" --mode <enter|status|parallel-review> --project .
+```
+
+3. The runtime auto-bootstraps missing `AirPlan/` files on first startup and does not overwrite existing project artifacts.
+4. If the request is a planning or architecture-change task, keep `AirPlan/AGENTS.md`, ADRs, C4 module docs, `AirPlan/plan.md`, and `AirPlan/todo.md` aligned with the new AirArc output.
+5. Do not write code, apply patches, or implement tasks directly from AirArc; hand confirmed execution work off to AirEng or other execution workflows.
+6. When planning needs UI or visual evidence, hand off screenshots or minimal GUI exploration to AirXDB before finalizing the plan.
+7. When `parallel-review` runs, record the emitted dependency edges, shared-write conflicts, serialization points, and execution-plan artifacts.

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airarc/scripts/airarc_mode.py

@@ -0,0 +1,191 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def _add_lib_path() -> None:
+    root = Path(__file__).resolve().parents[3]
+    lib_path = root / "lib"
+    if str(lib_path) not in sys.path:
+        sys.path.insert(0, str(lib_path))
+
+
+_add_lib_path()
+
+from air_runtime.contracts import now_iso
+from air_runtime.paths import airarc_root, required_project_artifacts, todo_path as workflow_todo_path
+from air_runtime.project_bootstrap import ensure_project_bootstrap
+from air_runtime.review import build_parallel_review, render_review_markdown
+
+REQUIRED_ARTIFACTS = required_project_artifacts()
+
+
+def _paths(project_root: Path) -> dict[str, Path]:
+    root = airarc_root(project_root)
+    return {
+        "root": root,
+        "state": root / "state.json",
+        "reviews": root / "reviews",
+        "execution_plan_json": root / "reviews" / "execution-plan.json",
+        "execution_plan_md": root / "reviews" / "execution-plan.md",
+    }
+
+
+def _ensure_layout(project_root: Path) -> dict[str, Path]:
+    paths = _paths(project_root)
+    paths["reviews"].mkdir(parents=True, exist_ok=True)
+    return paths
+
+
+def _artifact_health(project_root: Path) -> dict[str, bool]:
+    return {
+        relative: (project_root / relative).exists()
+        for relative in REQUIRED_ARTIFACTS
+    }
+
+
+def _write_state(project_root: Path, enabled: bool) -> Path:
+    paths = _ensure_layout(project_root)
+    payload = {
+        "enabled": enabled,
+        "updatedAt": now_iso(),
+        "projectRoot": str(project_root),
+        "artifactHealth": _artifact_health(project_root),
+    }
+    paths["state"].write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+    return paths["state"]
+
+
+def enter_mode(project_root: Path) -> dict[str, object]:
+    state_path = _write_state(project_root, True)
+    return {
+        "statePath": str(state_path),
+        "artifactHealth": _artifact_health(project_root),
+    }
+
+
+def status_mode(project_root: Path) -> dict[str, object]:
+    paths = _ensure_layout(project_root)
+    if paths["state"].exists():
+        payload = json.loads(paths["state"].read_text(encoding="utf-8-sig"))
+    else:
+        payload = {
+            "enabled": False,
+            "projectRoot": str(project_root),
+            "artifactHealth": _artifact_health(project_root),
+        }
+    payload["artifactHealth"] = _artifact_health(project_root)
+    return payload
+
+
+def parallel_review_mode(project_root: Path, todo_path: Path) -> dict[str, object]:
+    paths = _ensure_layout(project_root)
+    review = build_parallel_review(todo_path)
+    json_path = paths["reviews"] / "parallel-review.json"
+    markdown_path = paths["reviews"] / "parallel-review.md"
+    json_path.write_text(json.dumps(review.to_dict(), indent=2) + "\n", encoding="utf-8")
+    markdown_path.write_text(render_review_markdown(review), encoding="utf-8")
+    selected_tasks = review.parallel_groups[0].task_ids if review.parallel_groups else []
+    execution_plan_payload = {
+        "generatedAt": now_iso(),
+        "projectRoot": str(project_root),
+        "todoPath": str(todo_path),
+        "planSource": "airarc-post-plan-review",
+        "parallelReview": review.to_dict(),
+        "selectedTasks": selected_tasks,
+        "parallelGroups": [group.to_dict() for group in review.parallel_groups],
+        "conflicts": [conflict.to_dict() for conflict in review.conflicts],
+        "serializationPoints": review.serialization_points,
+    }
+    paths["execution_plan_json"].write_text(
+        json.dumps(execution_plan_payload, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    execution_lines = [
+        "# AirArc Execution Plan",
+        "",
+        f"- Generated At: `{execution_plan_payload['generatedAt']}`",
+        f"- Todo Path: `{todo_path}`",
+        f"- Plan Source: `{execution_plan_payload['planSource']}`",
+        "",
+        "## Selected Tasks",
+    ]
+    if selected_tasks:
+        for task_id in selected_tasks:
+            execution_lines.append(f"- `{task_id}`")
+    else:
+        execution_lines.append("- No selected tasks.")
+    execution_lines.extend(["", "## Parallel Groups"])
+    if review.parallel_groups:
+        for group in review.parallel_groups:
+            execution_lines.append(f"- `{group.name}`: {', '.join(group.task_ids)}")
+            execution_lines.append(f"  Reason: {group.reason}")
+    else:
+        execution_lines.append("- No parallel groups.")
+    execution_lines.extend(["", "## Serialization Points"])
+    if review.serialization_points:
+        for item in review.serialization_points:
+            execution_lines.append(f"- `{item['taskId']}`: {'; '.join(item['reasons'])}")
+    else:
+        execution_lines.append("- No serialization points.")
+    paths["execution_plan_md"].write_text("\n".join(execution_lines) + "\n", encoding="utf-8")
+    _write_state(project_root, True)
+    return {
+        "jsonPath": str(json_path),
+        "markdownPath": str(markdown_path),
+        "executionPlanJsonPath": str(paths["execution_plan_json"]),
+        "executionPlanMarkdownPath": str(paths["execution_plan_md"]),
+        "parallelGroupCount": len(review.parallel_groups),
+        "conflictCount": len(review.conflicts),
+    }
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Upgraded AirArc prototype runtime")
+    parser.add_argument("--mode", choices=["enter", "status", "parallel-review"], default="status")
+    parser.add_argument("--project", default=".")
+    parser.add_argument("--todo", default="")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    project_root = Path(args.project).expanduser().resolve()
+    ensure_project_bootstrap(project_root)
+
+    if args.mode == "enter":
+        result = enter_mode(project_root)
+        print("airarc_mode=enabled")
+        print(f"project_root={project_root}")
+        print(f"state_path={result['statePath']}")
+        for key, value in result["artifactHealth"].items():
+            print(f"{key}={'ok' if value else 'missing'}")
+        return
+
+    if args.mode == "status":
+        result = status_mode(project_root)
+        print(f"airarc_mode={'enabled' if result.get('enabled') else 'disabled'}")
+        print(f"project_root={project_root}")
+        for key, value in result["artifactHealth"].items():
+            print(f"{key}={'ok' if value else 'missing'}")
+        return
+
+    current_todo_path = Path(args.todo).expanduser().resolve() if args.todo else workflow_todo_path(project_root)
+    result = parallel_review_mode(project_root, current_todo_path)
+    print("airarc_mode=parallel-reviewed")
+    print(f"project_root={project_root}")
+    print(f"todo_path={current_todo_path}")
+    print(f"json_path={result['jsonPath']}")
+    print(f"markdown_path={result['markdownPath']}")
+    print(f"execution_plan_json_path={result['executionPlanJsonPath']}")
+    print(f"execution_plan_markdown_path={result['executionPlanMarkdownPath']}")
+    print(f"parallel_group_count={result['parallelGroupCount']}")
+    print(f"conflict_count={result['conflictCount']}")
+
+
+if __name__ == "__main__":
+    main()

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airarc/skills/airarc/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: airarc
+description: Architecture-first workflow with built-in post-plan parallelization review. Use when planning should emit dependency edges, parallel groups, write-set conflicts, and serialization points for AirEng. AirArc plans and edits planning docs only; it does not write code.
+---
+
+# AirArc
+
+## Upgrade Notes
+
+- Keep the original architecture-first planning role.
+- AirArc is an architect-only workflow: it may plan tasks and edit architecture or planning documents, but it must not implement code changes.
+- Add built-in post-plan review instead of a separate review-only plugin.
+- Emit engine-consumable execution artifacts after planning.
+
+## Outputs
+
+- `AirPlan/state/airarc/state.json`
+- `AirPlan/state/airarc/reviews/parallel-review.json`
+- `AirPlan/state/airarc/reviews/parallel-review.md`
+- `AirPlan/state/airarc/reviews/execution-plan.json`
+- `AirPlan/state/airarc/reviews/execution-plan.md`
+
+## Review Responsibilities
+
+- Compute dependency edges.
+- Compute parallel-safe groups.
+- Detect shared write-set conflicts.
+- Mark serialization points for global docs and merge boundaries.
+- Produce an execution plan that AirEng can prefer directly.
+
+## Commands
+
+```bash
+python ../../scripts/airarc_mode.py --mode enter --project <project-root>
+python ../../scripts/airarc_mode.py --mode status --project <project-root>
+python ../../scripts/airarc_mode.py --mode parallel-review --project <project-root> --todo <todo-md>
+```

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airarc/skills/airarc/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: airarc
+short_description: Architecture-first planning with built-in parallel review and Air Engine handoff
+default_prompt: "Use AirArc to build or refresh architecture context, then emit a post-plan parallel review and execution plan for Air Engine."

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airdbg/.codex-plugin/plugin.json

@@ -0,0 +1,52 @@
+{
+  "name": "airdbg",
+  "version": "0.1.4",
+  "description": "Debug-first repair workflow for reproducing defects, requiring GUI evidence for local or remote GUI validation, using local or remote AirNDB for packet-capture evidence, and using local or remote AirSDB for static-analysis evidence when needed, while finding root causes, applying focused fixes, verifying behavior, and maintaining AGENTS.md, ADR, and C4 module context.",
+  "author": {
+    "name": "14816",
+    "email": "noreply@example.com",
+    "url": "https://airlongdian.fun/plugins/airdbg"
+  },
+  "homepage": "https://airlongdian.fun/plugins/airdbg",
+  "repository": "https://airlongdian.fun/plugins/airdbg",
+  "license": "MIT",
+  "keywords": [
+    "airdbg",
+    "debug",
+    "bugfix",
+    "root-cause",
+    "adr",
+    "c4",
+    "airxdb",
+    "airndb",
+    "gui-debug",
+    "screenshot",
+    "packet-capture",
+    "pcap",
+    "airsdb",
+    "cppcheck",
+    "static-analysis"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "AirDbg",
+    "shortDescription": "Debug-first repair with graphical, packet, and static-analysis evidence",
+    "longDescription": "AirDbg guides Codex through reproducible debugging: load project context, initialize missing AGENTS.md/ADR/C4 docs, discuss symptoms with the user, require AirXDB or equivalent GUI or screen evidence for every GUI validation instead of trusting process liveness, call local or remote AirNDB for tcpdump or WinDump packet capture, remote tcpdump or dumpcap capture, pcap summaries, BPF filters, DNS, TCP, UDP, TLS, HTTP connectivity and network evidence when needed, call local or remote AirSDB for cppcheck static analysis, staticanalysis.md summaries, and static-analysis documentation when needed, isolate root cause, apply focused fixes, verify behavior, and keep architecture context current.",
+    "developerName": "14816",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "websiteURL": "https://airlongdian.fun/plugins/airdbg",
+    "privacyPolicyURL": "https://openai.com/policies/row-privacy-policy/",
+    "termsOfServiceURL": "https://openai.com/policies/row-terms-of-use/",
+    "defaultPrompt": [
+      "Use AirDbg to reproduce the current bug, isolate the root cause, and apply the smallest safe fix.",
+      "Use AirDbg to repair a failing test and keep AGENTS.md, ADR, and C4 context in sync.",
+      "Use AirDbg to investigate a GUI, network, or C/C++ quality issue and collect the right evidence before changing code."
+    ],
+    "brandColor": "#D97706",
+    "screenshots": []
+  }
+}

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airdbg/commands/airdbg.md

@@ -0,0 +1,100 @@
+---
+description: Enter, exit, or inspect AirDbg mode for debugging and repair, with mandatory GUI evidence plus AirNDB and AirSDB evidence handoff
+argument-hint: [enter|exit|status]
+allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
+---
+
+# /airdbg
+
+控制当前工作区的 AirDbg 调试修复模式。
+
+用户传入参数：`$ARGUMENTS`
+
+- `enter` 或空参数：进入 AirDbg 模式并初始化调试上下文。
+- `status`：检查 AirDbg 状态和关键文件是否存在。
+- `exit`：退出 AirDbg 模式。
+
+## 执行步骤
+
+1. 解析 `$ARGUMENTS`，默认动作为 `enter`。
+2. 在当前项目根目录运行：
+
+```bash
+python "$HOME/plugins/airdbg/scripts/airdbg_mode.py" --mode <enter|exit|status> --project .
+```
+
+如果 `python` 不存在，尝试 `py` 或 `python3`。
+
+3. `enter` 后开始调试对话：
+   - 确认错误症状、期望行为、实际行为。
+   - 确认复现步骤、环境、最近变更和修复限制。
+   - 读取或初始化 `AGENTS.md`、ADR 和 C4 module。
+   - 复现、定位根因、最小修复、验证。
+
+4. 调试中遇到图形相关需求时，必须调用 `airxdb` 或补充等效 GUI/屏幕证据：
+   - 图形对比、截图取证、视觉回归、布局错位、弹窗、焦点、Canvas、浏览器/桌面 GUI：用 AirXDB 获取截图或报告。
+   - 如果目标 GUI 在远程设备、测试机、服务器、VM 或 SSH 主机上，使用 AirXDB 远程设备路径：
+
+```bash
+python "$HOME/plugins/airxdb/scripts/airxdb_remote_device.py" --project . --action setup
+python "$HOME/plugins/airxdb/scripts/airxdb_remote_device.py" --project . --action screenshot
+```
+
+   - 远程 helper 缺少 `AIRXDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；有目标后它会自动探测远端截图工具，缺失时自动尝试配置。
+   - 需要确认用户界面操作是否可用：用 AirXDB 执行最小 GUI 操作验证。
+   - 本地或远程 GUI 测试/验证不得只以进程存在、窗口拉起、命令退出成功或日志无异常视为通过。
+   - 如果是嵌入式屏幕、显示链路等截图无诊断价值的场景，可不强制截图，但必须补充等效的 GUI/屏幕状态证据和操作验证，并在 debug log 记录原因。
+   - AirDbg 继续负责根因分析、修复和最终验证，并把 AirXDB 证据写入 debug log。
+
+5. 调试中遇到抓包或网络层证据需求时，可调用 `airndb`：
+   - DNS、TCP、UDP、TLS、HTTP 连接、端口、代理、防火墙、丢包、重传、RST、延迟：用 AirNDB 设计 BPF 并抓取/读取 pcap。
+   - 需要判断请求是否发出、响应是否回来或失败发生在哪个网络阶段：用 AirNDB 生成 pcap、summary 和 JSON 报告。
+   - 如果目标流量在远程设备、测试机、服务器、VM、容器宿主机或 SSH 主机上，使用 AirNDB 远程设备路径：
+
+```bash
+python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action setup
+python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action interfaces
+python "$HOME/plugins/airndb/scripts/airndb_remote_device.py" --project . --action capture --iface <iface> --filter "<bpf>" --count 200 --timeout 30
+```
+
+   - 远程 helper 缺少 `AIRNDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；有目标后它会自动探测远端 `tcpdump` / `dumpcap`，缺失时自动尝试配置。
+   - AirDbg 继续负责代码层根因分析、修复和最终验证，并把 AirNDB 证据写入 debug log。
+
+6. 调试中遇到 C/C++ 静态分析或 cppcheck 证据需求时，可调用 `airsdb`：
+- 未初始化变量、空指针、越界、资源释放、危险转换、CWE、代码质量或安全性初筛：用 AirSDB 运行 cppcheck 并维护 `AirPlan/docs/staticanalysis.md`。
+- 当检验、测试或调试判断需要静态分析能力时，用 AirSDB 获取 `AirPlan/docs/staticanalysis.md`、XML/JSON 报告等静态分析信息和文档辅助调试。
+   - 如果目标代码在远程设备、测试机、服务器、VM、容器宿主机或 SSH 主机上，使用 AirSDB 远程设备路径：
+
+```bash
+python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action setup
+python "$HOME/plugins/airsdb/scripts/airsdb_remote_device.py" --project . --action scan
+```
+
+   - AirDbg 继续负责代码层根因分析、修复和最终验证，并把 AirSDB 证据写入 debug log。
+
+7. 修复过程中必须维护：
+   - `AGENTS.md`
+   - `docs/architecture/adr/`
+   - `docs/architecture/c4/module.md`
+   - `docs/debug/debug-log.md`
+
+## 输出文案
+
+进入模式：
+
+```text
+AirDbg 模式已开启：已初始化或检查 AGENTS.md、ADR、C4 module 和 debug log。请描述错误症状、复现步骤、期望行为和实际行为；如果涉及本机或远程 GUI 测试/验证，必须使用 AirXDB 或等效 GUI/屏幕证据做复验，不能只看进程是否存活；如果涉及抓包或网络层分析，可调用 AirNDB 获取本机或远程 pcap/summary 证据；如果涉及 C/C++ 静态分析或检验需要静态分析能力，可调用 AirSDB 获取本机或远程 cppcheck/staticanalysis 证据。
+```
+
+退出模式：
+
+```text
+AirDbg 模式已退出：已返回标准 Codex 流程。
+```
+
+状态检查：
+
+```text
+AirDbg 状态：<enabled|disabled>
+关键文件：逐项列出 ok/missing。
+```

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airdbg/scripts/airdbg_mode.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""Bootstrap AirDbg debugging context files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, Tuple
+
+MARKER_BEGIN = "<!-- AIRDBG:BEGIN -->"
+MARKER_END = "<!-- AIRDBG:END -->"
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def airdbg_agents_block() -> str:
+    return f"""{MARKER_BEGIN}
+## AirDbg Debug Workflow
+
+1. Use AirDbg for `/airdbg` debugging and repair sessions.
+2. Before fixing, load project context:
+   - `AirPlan/AGENTS.md`
+   - `AirPlan/docs/architecture/adr/`
+   - `AirPlan/docs/architecture/c4/module.md`
+   - `AirPlan/docs/debug/debug-log.md`
+3. Reproduce the issue before changing code whenever feasible.
+4. Identify root cause, then apply the smallest verifiable fix.
+5. Record reproduction, root cause, fix, validation, and residual risk in `AirPlan/docs/debug/debug-log.md`.
+6. When debugging needs graphical comparison, screenshots, GUI operation, browser/desktop UI, canvas, layout, focus, popup, or visual evidence, call AirXDB for screenshots, GUI exploration, or operation validation.
+7. For every local or remote GUI test or validation, do not treat process liveness, window launch, command success, or clean logs as a pass; require image/GUI evidence plus at least one GUI operation or state check. If screenshots are not diagnostically useful, such as many embedded-screen or display-pipeline scenarios, record equivalent screen evidence instead.
+8. If the GUI target is a remote device, test machine, VM, server, or SSH host, call the AirXDB remote device helper before local Computer MCP; it should probe SSH, auto-configure missing remote screenshot tools when possible, and save evidence under `AirPlan/docs/debug/airxdb-artifacts/`.
+9. When debugging needs packet capture, pcap reading, BPF filters, DNS/TCP/UDP/TLS/HTTP connectivity, ports, proxy, firewall, packet loss, retransmits, resets, or latency evidence, call AirNDB.
+10. If the network target is a remote device, test machine, VM, container host, server, or SSH host, call the AirNDB remote device helper before local capture; it should probe SSH, auto-configure missing remote tcpdump/dumpcap when possible, and save evidence under `AirPlan/docs/network/airndb-captures/`.
+11. When debugging needs C/C++ static analysis, cppcheck, code quality, security-relevant findings, CWE, null pointer, bounds, resource, conversion, uninitialized-variable evidence, or static-analysis capability to support validation, call AirSDB and read `AirPlan/docs/staticanalysis.md` plus XML/JSON artifacts when helpful.
+12. If the static-analysis target is a remote device, test machine, VM, container host, server, or SSH host, call the AirSDB remote device helper before local cppcheck; it should probe SSH, auto-configure missing remote cppcheck when possible, and maintain `staticanalysis.md`.
+13. Record AirXDB, AirNDB, and AirSDB commands, remote target when applicable, screenshot/pcap/staticanalysis/report paths, observations, and how they relate to root cause in `AirPlan/docs/debug/debug-log.md`.
+14. Update ADR records when a fix changes long-term behavior, contracts, dependencies, data ownership, error handling, GUI automation boundaries, remote-device boundaries, network boundaries, static-analysis boundaries, or architecture decisions.
+15. Update C4 module docs when module boundaries, dependencies, public interfaces, data ownership, GUI automation, local/remote screenshot evidence, local/remote packet capture, static-analysis evidence, network observability, or visual validation boundaries change.
+16. Keep ADRs concise because they are AI context records.
+{MARKER_END}
+"""
+
+
+def c4_module_template() -> str:
+    return """# C4 Module
+
+## System Context
+- TODO: Describe the system, users, and important external systems.
+
+## Containers
+- TODO: Describe deployable/runtime units.
+
+## Modules
+
+| Module | Responsibility | Public Interfaces | Dependencies | Data Ownership | Debug-Relevant Notes |
+| --- | --- | --- | --- | --- | --- |
+| TODO | TODO | TODO | TODO | TODO | TODO |
+
+## Error and Observability Flow
+- TODO: Describe where errors are raised, logged, retried, surfaced, or recovered.
+
+## GUI / Visual Debug Boundaries
+- AirXDB screenshot evidence, GUI operation checks, graphical comparison, or visual validation used in debugging: TODO
+- AirXDB remote device evidence, SSH target, remote screenshot tool, or remote display constraints used in debugging: TODO
+- Browser bridge, desktop control, canvas, focus, popup, layout, or multi-display constraints relevant to defects: TODO
+
+## Network / Packet Debug Boundaries
+- AirNDB pcap evidence, tcpdump/WinDump commands, BPF filters, packet summaries, or network validation used in debugging: TODO
+- AirNDB remote device evidence, SSH target, remote tcpdump/dumpcap tool, or remote capture permissions used in debugging: TODO
+- DNS, TCP, UDP, TLS, HTTP, proxy, firewall, port, NAT, WSL/container/VM/host network constraints relevant to defects: TODO
+
+## Static Analysis Boundaries
+- AirSDB cppcheck evidence, staticanalysis.md entries, XML/JSON reports, suppressions, or quality gates used in debugging: TODO
+- AirSDB remote device evidence, SSH target, remote cppcheck tool, or remote static-analysis permissions used in debugging: TODO
+
+## Change Log
+- TODO: Record module-boundary changes caused by fixes.
+"""
+
+
+def adr_template() -> str:
+    return """# ADR-0001: AirDbg Debug Context Governance
+
+- Status: Accepted
+- Date: TODO
+
+## Context
+Debugging sessions need durable AI-readable context so future fixes can understand prior decisions.
+
+## Decision
+Use AirDbg to maintain `AirPlan/AGENTS.md`, `AirPlan/docs/architecture/c4/module.md`, `AirPlan/docs/architecture/adr/`, and `AirPlan/docs/debug/debug-log.md` during repair work.
+When debugging requires graphical comparison, screenshots, GUI operations, or visual evidence, use AirXDB for evidence gathering and operation validation, then return to AirDbg for root-cause analysis and focused repair. If the GUI target is remote, use AirXDB's remote device helper before local Computer MCP so SSH and remote screenshot tooling are checked or auto-configured.
+Do not treat process liveness, window launch, command success, or clean logs as sufficient proof for a GUI pass. Require image/GUI evidence and a GUI operation or state check for every local or remote GUI validation. If screenshots are not diagnostically useful, such as many embedded-screen or display-pipeline scenarios, record equivalent screen evidence and why screenshots were skipped.
+When debugging requires packet capture, pcap analysis, DNS/TCP/UDP/TLS/HTTP connectivity evidence, ports, proxy, firewall, retransmits, resets, or latency analysis, use AirNDB for bounded network evidence, then return to AirDbg for root-cause analysis and focused repair. If the network target is remote, use AirNDB's remote device helper before local capture so SSH and remote tcpdump/dumpcap are checked or auto-configured.
+When debugging requires C/C++ static analysis, cppcheck, code quality, security-relevant findings, CWE evidence, or static-analysis capability to support validation, use AirSDB for local or remote static-analysis evidence and `staticanalysis.md` context, then return to AirDbg for root-cause analysis and focused repair.
+
+## Consequences
+- Fixes carry reproducible context across sessions.
+- Architecture-impacting repairs must update ADR and C4 module docs.
+- ADRs stay concise and focused on decisions.
+- GUI evidence and graphical operation results are linked to root cause and validation records.
+- Embedded-screen or display-pipeline cases that skip screenshots still record equivalent screen evidence and the reason screenshots were not useful.
+- Network packet evidence and pcap summaries are linked to root cause and validation records.
+- Static-analysis evidence and staticanalysis.md summaries are linked to root cause and validation records.
+- Remote-device SSH targets, auto-configuration outcomes, and permission limits are recorded when they affect debugging.
+
+## Alternatives
+- Chat-only debugging notes: rejected because context is easy to lose.
+"""
+
+
+def debug_log_template() -> str:
+    return """# Debug Log
+
+Append entries for AirDbg sessions.
+
+## Entry Template
+
+### YYYY-MM-DD: short problem title
+
+- Symptom: TODO
+- Expected: TODO
+- Actual: TODO
+- Reproduction: TODO
+- Root cause: TODO
+- AirXDB local/remote evidence: TODO
+- AirNDB local/remote evidence: TODO
+- AirSDB local/remote static-analysis evidence: TODO
+- Fix: TODO
+- Validation: TODO
+- ADR/C4 updates: TODO
+- Residual risk: TODO
+"""
+
+
+def write_if_missing(path: Path, content: str) -> bool:
+    if path.exists():
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8", newline="\n")
+    return True
+
+
+def upsert_agents_md(path: Path) -> str:
+    block = airdbg_agents_block().rstrip() + "\n"
+
+    if path.exists():
+        original = path.read_text(encoding="utf-8")
+        existed = True
+    else:
+        original = "# AGENTS.md\n\n"
+        existed = False
+
+    begin = original.find(MARKER_BEGIN)
+    end = original.find(MARKER_END)
+
+    if begin >= 0 and end > begin:
+        end += len(MARKER_END)
+        updated = original[:begin].rstrip() + "\n\n" + block + original[end:].lstrip()
+        status = "updated"
+    else:
+        updated = original.rstrip() + "\n\n" + block
+        status = "updated" if existed else "created"
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(updated, encoding="utf-8", newline="\n")
+    return status
+
+
+def artifact_map(project_root: Path) -> Dict[str, Path]:
+    return {
+        "AGENTS.md": project_root / "AirPlan" / "AGENTS.md",
+        "c4_module": project_root / "AirPlan" / "docs" / "architecture" / "c4" / "module.md",
+        "adr_dir": project_root / "AirPlan" / "docs" / "architecture" / "adr",
+        "adr_0001": project_root / "AirPlan" / "docs" / "architecture" / "adr" / "ADR-0001-airdbg-debug-context-governance.md",
+        "debug_log": project_root / "AirPlan" / "docs" / "debug" / "debug-log.md",
+        "state": project_root / "AirPlan" / "state" / "airdbg" / "state.json",
+    }
+
+
+def write_state(path: Path, enabled: bool, project_root: Path) -> None:
+    artifacts = artifact_map(project_root)
+    health = {
+        name: artifacts[name].exists()
+        for name in [
+            "AGENTS.md",
+            "c4_module",
+            "adr_dir",
+            "adr_0001",
+            "debug_log",
+        ]
+    }
+
+    payload = {
+        "enabled": enabled,
+        "updatedAt": now_iso(),
+        "projectRoot": str(project_root),
+        "artifactHealth": health,
+    }
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def enter_mode(project_root: Path) -> Tuple[str, Dict[str, str]]:
+    artifacts = artifact_map(project_root)
+    results: Dict[str, str] = {}
+
+    results["AGENTS.md"] = upsert_agents_md(artifacts["AGENTS.md"])
+    results["c4_module"] = "created" if write_if_missing(artifacts["c4_module"], c4_module_template()) else "exists"
+    artifacts["adr_dir"].mkdir(parents=True, exist_ok=True)
+    results["adr_dir"] = "exists"
+    results["adr_0001"] = "created" if write_if_missing(artifacts["adr_0001"], adr_template()) else "exists"
+    results["debug_log"] = "created" if write_if_missing(artifacts["debug_log"], debug_log_template()) else "exists"
+
+    write_state(artifacts["state"], True, project_root)
+    return "enabled", results
+
+
+def exit_mode(project_root: Path) -> Tuple[str, Dict[str, str]]:
+    artifacts = artifact_map(project_root)
+    write_state(artifacts["state"], False, project_root)
+    return "disabled", {}
+
+
+def status_mode(project_root: Path) -> Tuple[str, Dict[str, str]]:
+    artifacts = artifact_map(project_root)
+    state_file = artifacts["state"]
+
+    enabled = False
+    if state_file.exists():
+        try:
+            payload = json.loads(state_file.read_text(encoding="utf-8"))
+            enabled = bool(payload.get("enabled"))
+        except json.JSONDecodeError:
+            enabled = False
+
+    results = {
+        name: ("ok" if path.exists() else "missing")
+        for name, path in artifacts.items()
+        if name != "state"
+    }
+    return ("enabled" if enabled else "disabled"), results
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Manage AirDbg project artifacts.")
+    parser.add_argument("--mode", choices=["enter", "exit", "status"], default="enter")
+    parser.add_argument("--project", default=".")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    project_root = Path(args.project).expanduser().resolve()
+
+    if args.mode == "enter":
+        mode_state, result = enter_mode(project_root)
+    elif args.mode == "exit":
+        mode_state, result = exit_mode(project_root)
+    else:
+        mode_state, result = status_mode(project_root)
+
+    print(f"airdbg_mode={mode_state}")
+    print(f"project_root={project_root}")
+    for key, value in result.items():
+        print(f"{key}={value}")
+
+
+if __name__ == "__main__":
+    main()

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airdbg/scripts/install_airdbg_plugin.py

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""Install the AirDbg plugin into the current user's home-local plugin directory."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+from pathlib import Path
+from typing import Any, Dict
+
+PLUGIN_NAME = "airdbg"
+
+
+def copy_plugin(source: Path, target: Path) -> None:
+    if source.resolve() == target.resolve():
+        return
+    if target.exists():
+        shutil.rmtree(target)
+    ignore = shutil.ignore_patterns("__pycache__", "*.pyc", ".DS_Store", ".git")
+    shutil.copytree(source, target, ignore=ignore)
+
+
+def marketplace_payload() -> Dict[str, Any]:
+    return {
+        "name": "local-airdbg",
+        "interface": {"displayName": "Local AirDbg Plugins"},
+        "plugins": [],
+    }
+
+
+def update_marketplace(path: Path) -> None:
+    if path.exists():
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    else:
+        payload = marketplace_payload()
+
+    payload.setdefault("name", "local-airdbg")
+    payload.setdefault("interface", {}).setdefault("displayName", "Local AirDbg Plugins")
+    plugins = payload.setdefault("plugins", [])
+
+    entry = {
+        "name": PLUGIN_NAME,
+        "source": {
+            "source": "local",
+            "path": f"./plugins/{PLUGIN_NAME}",
+        },
+        "policy": {
+            "installation": "INSTALLED_BY_DEFAULT",
+            "authentication": "ON_INSTALL",
+        },
+        "category": "Productivity",
+    }
+
+    for index, existing in enumerate(plugins):
+        if existing.get("name") == PLUGIN_NAME:
+            plugins[index] = entry
+            break
+    else:
+        plugins.append(entry)
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Install AirDbg as a home-local Codex plugin.")
+    parser.add_argument("--source", default=str(Path(__file__).resolve().parents[1]))
+    parser.add_argument("--home", default=str(Path.home()))
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    source = Path(args.source).expanduser().resolve()
+    home = Path(args.home).expanduser().resolve()
+    target = home / "plugins" / PLUGIN_NAME
+    marketplace = home / ".agents" / "plugins" / "marketplace.json"
+
+    copy_plugin(source, target)
+    update_marketplace(marketplace)
+
+    print(f"installed_plugin={target}")
+    print(f"marketplace={marketplace}")
+
+
+if __name__ == "__main__":
+    main()

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airdbg/skills/airdbg/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: airdbg
+description: Debug-first repair workflow. Use when the user invokes /airdbg or explicitly asks for AirDbg mode to debug, reproduce, diagnose, or fix software errors, including GUI, visual, screenshot, browser UI, desktop UI, remote GUI/device debugging, canvas, layout, focus, popup, graphical operation, network, packet capture, remote packet capture, pcap, DNS, TCP, UDP, TLS, HTTP connectivity, proxy, firewall, port, retransmit, reset, latency, cppcheck, static analysis, code quality, or security-relevant C/C++ defects. Load or initialize AirPlan/AGENTS.md, AirPlan/docs/architecture/adr/ decision records, and AirPlan/docs/architecture/c4/module.md; discuss symptoms and constraints with the user; reproduce the issue; require AirXDB local or remote device helpers or equivalent GUI/screen evidence for every local or remote GUI validation instead of treating process liveness as success; call AirNDB local or remote device helpers when tcpdump/WinDump packet capture, pcap analysis, BPF filters, or network-layer evidence is needed; call AirSDB local or remote device helpers when static-analysis capability, cppcheck evidence, or AirPlan/docs/staticanalysis.md documentation is needed; identify root cause; apply a focused fix; verify with tests or equivalent checks; and update AirPlan/AGENTS.md, ADR, and C4 module docs when project behavior, module boundaries, dependencies, GUI automation boundaries, network boundaries, static-analysis boundaries, remote-device boundaries, or architecture decisions change.
+---
+
+# AirDbg
+
+## 核心约束
+
+- 全程使用中文与用户交流，代码、命令、日志、路径、异常名保持原文。
+- `/airdbg` 是主要触发入口。用户进入 AirDbg 后，围绕调试和修复错误推进。
+- 先加载项目上下文，再修复：`AirPlan/AGENTS.md`、`AirPlan/docs/architecture/adr/`、`AirPlan/docs/architecture/c4/module.md`。
+- 如果这些文件不存在，先分析当前项目并初始化它们；C4 module 要记录真实模块边界，不只放空模板。
+- 与用户交流症状、复现步骤、期望行为、实际行为、影响范围和修复约束。
+- 默认做最小可验证修复，避免顺手重构。
+- 每个修复都要验证。优先自动化测试，其次是可重复命令或明确的手工验证步骤。
+- 只要验证或复现涉及本地或远程 GUI，就不能只以进程存在、窗口拉起、命令退出成功、端口监听或日志无异常判定通过；必须辅以图像/GUI 检验和测试。
+- 调试中遇到图形对比、截图取证、GUI 操作、浏览器/桌面界面、Canvas、弹窗、焦点、布局、视觉回归或其他图形功能时，必须调用 `airxdb` 获取截图、探索界面、执行操作验证或收集视觉证据；如果是嵌入式屏幕、显示链路等截图无诊断价值的场景，可不强制截图，但必须补充等效的 GUI/屏幕状态证据和操作验证，并记录原因。
+- 如果 GUI 问题发生在远程设备、测试机、VM、服务器或 SSH 主机上，调用 AirXDB remote device helper，而不是默认使用本机 Computer MCP。
+- 调试中遇到抓包分析、pcap、tcpdump/WinDump、BPF、DNS、TCP、UDP、TLS、HTTP 连接、端口、代理、防火墙、丢包、重传、RST 或延迟问题时，可以调用 `airndb` 获取网络层调试证据。
+- 如果网络问题发生在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，调用 AirNDB remote device helper，而不是默认使用本机抓包工具。
+- 调试中遇到需要静态分析能力的检验、测试或定位场景，以及 C/C++ 静态分析、cppcheck、代码质量、安全性初筛、未初始化变量、空指针、越界、资源释放、危险转换或 CWE 线索需求时，可以调用 `airsdb` 获取 `AirPlan/docs/staticanalysis.md`、XML/JSON 报告等静态分析证据和辅助调试文档。
+- 如果静态分析目标在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，调用 AirSDB remote device helper，而不是默认使用本机 cppcheck。
+- 一定要根据项目变化维护 `AirPlan/AGENTS.md`、ADR 和 C4 module。
+- ADR 是给 AI 作为上下文的决策记录，短、准、可检索即可，不写冗长修饰。
+
+## 启动与初始化
+
+进入 `/airdbg` 时运行：
+
+```bash
+python ../../scripts/airdbg_mode.py --mode enter --project .
+```
+
+如果当前环境没有 `python`，尝试 `py` 或 `python3`。脚本不可用时，手动确保以下结构存在：
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/docs/debug/debug-log.md`
+- `AirPlan/state/airdbg/state.json`
+
+初始化后读取已有内容作为上下文。不要覆盖用户已有正文；只补齐缺失结构或更新 AirDbg 标记块。
+
+## 图形调试与 AirXDB 协作
+
+AirDbg 负责根因分析、代码层修复和验证收尾；AirXDB 负责图形界面的取证和操作层复现。遇到以下情况时，必须调用 AirXDB 或补充等效 GUI/屏幕证据：
+
+- 需要截图或图形对比来理解错误现场、视觉回归、布局错位、颜色/尺寸/遮挡差异。
+- 需要操作浏览器 UI、桌面 UI、Electron/Qt/WPF 等应用、Canvas、菜单、弹窗、托盘、任务栏或多显示器界面。
+- 需要 `/airxdb screenshot` 保存错误现场，再把截图交给 AirDbg 做代码层诊断。
+- 目标 GUI 在远程设备、测试机、VM、服务器或 SSH 主机上，需要 `/airxdb remote-screenshot` 或 `airxdb_remote_device.py` 保存远程错误现场。
+- 需要用 AirXDB 执行最小 GUI 操作，确认按钮、表单、导航、窗口切换、焦点或图形流程是否真的失败。
+- 需要把 GUI 证据沉淀到 `AirPlan/docs/debug/gui-debug-log.md`、`AirPlan/docs/debug/airxdb-artifacts/` 或 AirDbg 的 `AirPlan/docs/debug/debug-log.md`。
+
+协作规则：
+
+- 先用 AirXDB 收集最小必要证据，再回到 AirDbg 分析代码根因；不要把视觉症状直接当作根因。
+- 任何本地或远程 GUI 测试/验证都不能仅以进程存活、窗口创建成功、命令返回成功或日志无异常视为通过；默认至少保留 1 份截图/图像证据，并完成 1 次关键 GUI 操作或状态检查。
+- 如果是嵌入式屏幕、显示控制器、外接面板链路等截图无诊断价值的场景，可改用外部采集视频、framebuffer dump、串口/日志配合按键或触控操作记录、状态灯/OSD 观察记录等等效证据，但必须在 `debug-log.md` 记录为什么不截图以及替代证据是什么。
+- 截图模式可在没有 Midscene 语义模型配置时使用；语义视觉动作按 AirXDB 规则先检查模型配置。
+- 本机 GUI 证据使用 `/airxdb screenshot` 或 `airxdb_computer_mcp_smoke.py`；远程 GUI 证据使用 `airxdb_remote_device.py --action setup|screenshot`，由它探测 SSH、远端截图工具并在缺失时自动尝试配置。
+- 远程 helper 缺少 `AIRXDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；需要交互式 sudo、管理员确认或无支持包管理器时停止并说明。
+- AirDbg 的 `debug-log.md` 必须记录 AirXDB 命令、截图/报告路径、关键观察、与根因的关系、复验结果和剩余风险。
+- 如果 GUI 自动化、截图取证、视觉验收、浏览器桥接或桌面控制成为长期调试/测试边界，更新 C4 module 并创建或修订 ADR。
+- 如果发现稳定可复用的 GUI 调试命令、截图方式、远程设备配置或视觉验收步骤，更新 `AGENTS.md`。
+- 截图可能包含账号、密钥、客户数据或聊天内容时，先提醒用户脱敏，再外部分享或长期保留。
+
+## 抓包调试与 AirNDB 协作
+
+AirDbg 负责把网络证据和代码行为联系起来，定位根因并修复；AirNDB 负责 tcpdump/WinDump 抓包、pcap 摘要、BPF 过滤器和网络层证据。遇到以下情况时，调用 AirNDB：
+
+- 需要抓包判断请求是否发出、响应是否回来、连接是否被 RST/ICMP/防火墙/代理中断。
+- 需要分析 DNS 查询、TCP 三次握手、TLS 握手、HTTP 连接、UDP 流量、端口可达性、重传、丢包或延迟。
+- 需要读取已有 `.pcap` 或生成新的短时有界 pcap 给调试使用。
+- 需要确定问题在应用代码、系统网络栈、容器/WSL/VM/宿主机边界、代理、防火墙还是远端服务。
+- 目标流量发生在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，需要 `/airndb remote-interfaces`、`/airndb remote-capture` 或 `airndb_remote_device.py` 获取远程网络证据。
+
+协作规则：
+
+- 先让 AirNDB 明确授权范围、接口、BPF 过滤器、抓包窗口和 pcap 输出路径；不要进行无界抓包。
+- 本机网络证据使用 `airndb_capture.py`；远程网络证据使用 `airndb_remote_device.py --action setup|interfaces|command|capture`，由它探测 SSH、远端 `tcpdump` / `dumpcap` 并在缺失时自动尝试配置。
+- 远程 helper 缺少 `AIRNDB_REMOTE_SSH_TARGET` 时，先让用户提供 SSH 目标；需要交互式 sudo、管理员确认或无支持包管理器时停止并说明。
+- AirDbg 的 `debug-log.md` 必须记录 AirNDB 命令、pcap/summary/report 路径、关键包或时间线观察、与根因的关系、复验结果和剩余风险。
+- 如果抓包发现新的长期网络边界、端口、协议、DNS、代理、TLS、容器/WSL/VM/宿主机约束或观测方式，更新 C4 module 并创建或修订 ADR。
+- 如果发现稳定可复用的抓包命令、接口选择规则、BPF、远程设备配置或 pcap 读取方式，更新 `AGENTS.md`。
+- pcap 可能包含 token、cookie、payload、内网地址、主机名或个人信息；对外分享前必须提醒用户脱敏。
+
+## 静态分析与 AirSDB 协作
+
+AirDbg 负责把静态分析线索和代码根因联系起来；AirSDB 负责 cppcheck 检测/安装、本机或远程扫描、XML/JSON 产物和 `AirPlan/docs/staticanalysis.md` 简短报告。遇到以下情况时，可以调用 AirSDB：
+
+- 需要用 cppcheck 辅助定位 C/C++ bug、内存/资源/越界/空指针/未初始化变量/危险转换/CWE 线索。
+- 需要在修复前后比较静态分析结果。
+- 需要给 AirDbg 的根因分析提供短报告而不是长 XML。
+- 检验、测试或调试判断需要静态分析能力、质量门信息或可引用文档时，需要读取 `AirPlan/docs/staticanalysis.md` 或 AirSDB XML/JSON 报告辅助分析。
+- 目标代码在远程设备、测试机、VM、容器宿主机、服务器或 SSH 主机上，需要 `/airsdb remote-scan` 或 `airsdb_remote_device.py` 获取远端静态分析证据。
+
+协作规则：
+
+- 本机静态分析使用 `airsdb_cppcheck.py --action scan`；远程静态分析使用 `airsdb_remote_device.py --action setup|scan`，由它探测 SSH、远端 cppcheck 并在缺失时自动尝试配置。
+- AirDbg 的 `AirPlan/docs/debug/debug-log.md` 必须记录 AirSDB 命令、`AirPlan/docs/staticanalysis.md`、XML/JSON 报告路径、关键 findings、与根因的关系、复验结果和剩余风险。
+- 如果静态分析发现新的长期质量门槛、suppressions、远程设备配置或 cppcheck 命令，更新 `AGENTS.md`。
+- 如果静态分析成为长期测试/调试边界，更新 C4 module 并创建或修订 ADR。
+
+## 调试流程
+
+1. 确认问题边界：
+   - 用户看到的错误是什么。
+   - 期望行为和实际行为是什么。
+   - 复现步骤、输入数据、环境、版本、最近变更是什么。
+   - 有哪些不能破坏的兼容性或性能要求。
+2. 加载上下文：
+   - 读取 `AGENTS.md`。
+   - 读取 ADR 列表和相关 ADR。
+   - 读取 `docs/architecture/c4/module.md`。
+   - 查看测试、入口、依赖、配置和最近相关文件。
+3. 复现问题：
+   - 优先运行已有失败测试或用户给出的命令。
+   - 没有复现命令时，先构造最小复现或定位性测试。
+   - 如果复现依赖 GUI、截图或图形操作，必须调用 AirXDB 获取截图、执行最小界面操作或保存 GUI 报告；远程目标走 AirXDB remote device helper；嵌入式截图无效时改用等效 GUI/屏幕证据并记录原因。
+   - 如果复现依赖网络路径或抓包证据，调用 AirNDB 获取短时 pcap、摘要或网络层时间线；远程目标走 AirNDB remote device helper。
+- 如果复现或定位需要 C/C++ 静态分析，或当前检验需要静态分析能力辅助判断，调用 AirSDB 运行本机或远程 cppcheck，并读取 `AirPlan/docs/staticanalysis.md`。
+   - 记录复现命令和关键输出到 `docs/debug/debug-log.md`。
+4. 定位根因：
+   - 从错误栈、日志、测试断言、数据流和模块边界推断。
+   - 对 GUI 问题，结合 AirXDB 本机或远程截图/报告判断视觉症状、交互失败和代码根因之间的关系。
+   - 对网络问题，结合 AirNDB 本机或远程 pcap/摘要判断请求是否出站、响应是否入站、失败发生在 DNS/TCP/TLS/应用层哪一段。
+   - 对静态分析问题，结合 AirSDB findings 判断哪些是当前 bug 线索、哪些是既有质量债或误报。
+   - 必要时加临时日志或小范围探针，完成后清理。
+   - 区分根因、诱因和表面症状。
+5. 修复：
+   - 优先选择影响面小、能解释根因的修复。
+   - 不做无关格式化、批量重构或架构迁移。
+   - 如果修复会改变模块边界、依赖、接口、数据所有权或关键行为，先更新 C4/ADR。
+6. 验证：
+   - 运行失败用例、相关单元测试、集成测试、lint/typecheck。
+   - 如果修复涉及 GUI 或视觉行为，必须调用 AirXDB 截图、图形对比或操作验证关键路径；远程目标用远程 helper 复验；嵌入式截图无效时改用等效 GUI/屏幕证据并记录原因。
+   - 如果修复涉及网络行为，调用 AirNDB 复验关键网络路径或读取 pcap 摘要；远程目标用远程 helper 复验。
+- 如果修复涉及 C/C++ 风险、静态分析 findings，或验证需要静态分析能力辅助判断，调用 AirSDB 复跑 cppcheck 并更新 `AirPlan/docs/staticanalysis.md`。
+   - 如果不能运行，说明原因，并给出可复验的替代验证。
+   - 记录验证证据到 debug log。
+7. 收尾：
+   - 更新 `AGENTS.md` 中与调试、测试、运行方式相关的项目上下文。
+   - 更新或新增 ADR。
+   - 更新 C4 module。
+   - 向用户汇报根因、改动、验证结果、剩余风险。
+
+## AGENTS.md 维护
+
+在以下情况更新 `AGENTS.md`：
+
+- 发现新的运行、测试、构建、调试命令。
+- 发现新的 AirXDB 截图、GUI 操作验证、图形对比、远程设备配置或视觉验收命令。
+- 发现新的 AirNDB 抓包命令、BPF 过滤器、接口选择规则、远程设备配置、pcap 读取方式或网络复验步骤。
+- 发现新的 AirSDB cppcheck 命令、suppressions、质量门槛、远程设备配置或静态分析复验步骤。
+- 发现影响后续 AI 会话的重要项目约束。
+- 修复改变了模块职责、关键流程或错误处理策略。
+- 发现常见坑、环境要求或验证方式。
+
+保持内容可执行、可复用，不写调试过程流水账。
+
+## ADR 维护
+
+目录：`docs/architecture/adr/`。
+
+需要 ADR 的情况：
+
+- 修复选择了一个会影响长期架构或行为兼容性的方案。
+- 改变错误处理、重试、事务、缓存、一致性、安全边界。
+- 改变模块依赖、数据所有权、接口契约。
+- 将 GUI 自动化、截图取证、远程设备 GUI 取证、视觉验收或图形调试流程纳入长期测试/调试边界。
+- 将抓包、远程设备抓包、pcap 分析、网络观测、端口、协议、DNS、代理、TLS 或网络拓扑纳入长期调试/测试边界。
+- 将 cppcheck、staticanalysis.md、静态分析质量门槛或远程静态分析纳入长期调试/测试边界。
+- 拒绝了明显可选方案，需要给后续 AI 留下原因。
+
+ADR 模板：
+
+```markdown
+# ADR-000X: short-title
+
+- Status: Accepted
+- Date: YYYY-MM-DD
+
+## Context
+简述错误、约束和为什么需要决策。
+
+## Decision
+简述采用的修复或架构选择。
+
+## Consequences
+- 正面影响
+- 代价或风险
+
+## Alternatives
+- 方案 A：放弃原因
+```
+
+## C4 Module 维护
+
+文件：`docs/architecture/c4/module.md`。
+
+必须记录：
+
+- 模块名。
+- 职责。
+- 对外接口。
+- 依赖。
+- 数据所有权。
+- 与本次错误或修复相关的质量属性。
+
+新增模块、拆分模块、改变依赖、改变接口、改变数据边界、改变错误处理流时必须更新。
+
+引入或改变 GUI 自动化、浏览器桥接、桌面控制、截图取证、远程设备 GUI 取证、视觉验收或图形调试基础设施时，也必须更新。
+
+引入或改变 tcpdump/WinDump 抓包、远程设备抓包、pcap 分析、网络观测、端口、协议、DNS、代理、TLS、容器/WSL/VM/宿主机网络边界时，也必须更新。
+
+引入或改变 cppcheck、staticanalysis.md、静态分析质量门槛、suppressions 或远程静态分析边界时，也必须更新。
+
+## debug-log 维护
+
+文件：`docs/debug/debug-log.md`。
+
+每次 AirDbg 修复至少追加：
+
+- 问题摘要。
+- 复现命令或复现步骤。
+- 根因。
+- 修复摘要。
+- 验证命令和结果。
+- AirXDB 本机或远程截图/报告/操作验证证据及其结论（如适用）。
+- AirNDB 本机或远程 pcap/summary/report/抓包分析证据及其结论（如适用）。
+- AirSDB 本机或远程 staticanalysis.md/XML/JSON 静态分析证据及其结论（如适用）。
+- 相关 ADR/C4 更新。
+- 剩余风险。
+
+## 输出格式
+
+调试完成后用中文简洁汇报：
+
+- 根因。
+- 修复了什么。
+- 更新了哪些 `AGENTS.md` / ADR / C4 / debug log 上下文。
+- 运行了哪些验证；是否调用 AirXDB/AirNDB/AirSDB，截图、pcap、staticanalysis、报告或操作证据在哪里。
+- 仍然存在的风险或未验证项。

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airdbg/skills/airdbg/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: airdbg
+short_description: Debug-first repair with local/remote AirXDB, AirNDB, and AirSDB evidence
+default_prompt: "使用 AirDbg 调试并修复当前项目错误；GUI 测试或验证必须保留 GUI 复验证据，嵌入式截图无效时改用等效屏幕证据；网络证据调用 AirNDB，需要静态分析能力时调用 AirSDB。"

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airdo/.codex-plugin/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "airdo",
+  "version": "0.5.0",
+  "description": "AirDo is the public execution plugin for one scoped task slice. It is designed to run standalone or as an isolated AirEng subagent and to finalize structured results into AirPlan.",
+  "author": {
+    "name": "14816",
+    "email": "noreply@example.com",
+    "url": "https://airlongdian.fun"
+  },
+  "homepage": "https://airlongdian.fun/plugins/airdo",
+  "repository": "https://airlongdian.fun/plugins/airdo",
+  "license": "MIT",
+  "keywords": [
+    "airdo",
+    "executor",
+    "subagent",
+    "todo",
+    "validation"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "AirDo",
+    "shortDescription": "Execute one scoped task and finalize a structured result",
+    "longDescription": "AirDo is the public execution plugin for one narrow task slice. It can be run directly or launched by AirEng as a fully isolated subagent, auto-routes GUI work into AirXDB, auto-routes blockers into AirDbg, and finalizes one structured result in AirPlan for AirEng to merge.",
+    "developerName": "14816",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "websiteURL": "https://airlongdian.fun/plugins/airdo",
+    "privacyPolicyURL": "https://openai.com/policies/row-privacy-policy/",
+    "termsOfServiceURL": "https://openai.com/policies/row-terms-of-use/",
+    "defaultPrompt": [
+      "Use AirDo to start one scoped task from AirPlan/todo.md and create a structured result template.",
+      "Use AirDo to execute a handoff in an isolated subagent context and finalize the AirPlan result.",
+      "Use AirDo to continue from a repair brief until fixed or a real blocker remains."
+    ],
+    "brandColor": "#2563EB",
+    "screenshots": []
+  }
+}

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airdo/commands/airdo.md

@@ -0,0 +1,38 @@
+---
+description: Start, inspect, hand off, or finish one scoped AirDo task slice with automatic AirXDB/AirDbg routing and AirPlan result finalization
+argument-hint: [enter|status|handoff|finish]
+allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
+---
+
+# /airdo
+
+Use AirDo for one narrow execution slice. It can run directly in the parent thread, but it is primarily designed to be launched as an isolated AirEng subagent.
+
+## Steps
+
+1. Parse `$ARGUMENTS`; default to `status` when empty.
+2. Always operate from the current project root and store worker state under `AirPlan/state/airdo/`.
+3. Run the matching mode:
+
+```bash
+python "$HOME/plugins/airdo/scripts/airdo_mode.py" --mode <enter|status|handoff|finish> --project . --task-id <task-id>
+```
+
+4. For `enter` or `handoff`, load:
+   - `AirPlan/AGENTS.md`
+   - `AirPlan/docs/architecture/adr/`
+   - `AirPlan/docs/architecture/c4/module.md`
+   - `AirPlan/plan.md`
+   - `AirPlan/todo.md`
+   - `AirPlan/state/airdo/tasks/<task-id>/brief.md`
+
+5. When AirDo is invoked as an AirEng child:
+   - Treat the session as isolated and rebuild context only from the files above.
+   - Stay inside the task write scope from the brief/handoff.
+   - Finalize exactly one structured result under `AirPlan/state/airdo/results/<task-id>.json`.
+   - Treat `AirPlan/state/airdo/tasks/<task-id>/worker-state.json` `resultPath` as the canonical pointer to the latest result artifact. Do not assume the task-local template `result.json` is the finalized output.
+   - Do not stop at "准备实施", implementation-plan-only, or generic progress replies when the task is actionable. Continue editing, validating, and finalizing unless a real blocker or user decision is required.
+   - When the task changes planning or architecture reality, include concrete `documentUpdates` for `AirPlan/plan.md`, `AirPlan/docs/architecture/adr/`, and `AirPlan/docs/architecture/c4/module.md` instead of leaving those docs stale.
+
+6. On GUI-like work, route acceptance through AirXDB before finishing.
+7. On blockers or failed validation, route through AirDbg, continue through active repair briefs when present, and return one structured result for AirEng to merge.

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airdo/scripts/airdo_mode.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _add_lib_path() -> None:
+    root = Path(__file__).resolve().parents[3]
+    lib_path = root / "lib"
+    if str(lib_path) not in sys.path:
+        sys.path.insert(0, str(lib_path))
+
+
+_add_lib_path()
+
+from air_runtime.worker import enter_worker, finish_worker, handoff_worker, status_worker
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="AirDo public worker runtime")
+    parser.add_argument("--mode", choices=["enter", "status", "handoff", "finish"], default="status")
+    parser.add_argument("--project", default=".")
+    parser.add_argument("--task-id", default="")
+    parser.add_argument("--result", default="")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    project_root = Path(args.project).expanduser().resolve()
+
+    if args.mode == "status":
+        status = status_worker(project_root)
+        print(f"airdo_mode={'enabled' if status['enabled'] else 'disabled'}")
+        print(f"project_root={project_root}")
+        print(f"active_task_id={status['activeTaskId']}")
+        print(f"known_tasks={','.join(status['taskIds'])}")
+        for key, value in status["artifactHealth"].items():
+            print(f"{key}={'ok' if value else 'missing'}")
+        return
+
+    if not args.task_id:
+        raise SystemExit("--task-id is required for enter, handoff, and finish modes")
+
+    if args.mode == "enter":
+        result = enter_worker(project_root, args.task_id)
+        print("airdo_mode=entered")
+        print(f"project_root={project_root}")
+        print(f"task_id={result['taskId']}")
+        print(f"brief_path={result['briefPath']}")
+        print(f"handoff_path={result['handoffPath']}")
+        print(f"result_path={result['resultPath']}")
+        print(f"worker_state_path={result['workerStatePath']}")
+        return
+
+    if args.mode == "handoff":
+        result = handoff_worker(project_root, args.task_id)
+        print("airdo_mode=handoff-ready")
+        print(f"project_root={project_root}")
+        print(f"task_id={result['taskId']}")
+        print(f"brief_path={result['briefPath']}")
+        print(f"handoff_path={result['handoffPath']}")
+        print(f"result_path={result['resultPath']}")
+        print(f"worker_state_path={result['workerStatePath']}")
+        return
+
+    result_path = Path(args.result).expanduser().resolve() if args.result else None
+    finalized = finish_worker(project_root, args.task_id, result_path)
+    print("airdo_mode=finished")
+    print(f"project_root={project_root}")
+    print(f"task_id={finalized['taskId']}")
+    print(f"task_status={finalized['status']}")
+    print(f"finalized_result_path={finalized['finalizedResultPath']}")
+    print(f"worker_state_path={finalized['workerStatePath']}")
+
+
+if __name__ == "__main__":
+    main()

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airdo/skills/airdo/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: airdo
+description: Public Air executor for one scoped todo slice. Use it standalone or as an isolated AirEng subagent and finalize the result into AirPlan.
+---
+
+# AirDo
+
+## Role
+
+- Execute one task or one very small implementation slice.
+- Keep AirDo execution guarantees for context loading, evidence, and validation.
+- Finalize one structured result package in `AirPlan/state/airdo/results/`.
+- Act as the standard AirEng child executor when work is delegated into isolated subagents.
+
+## Inputs
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/plan.md`
+- `AirPlan/todo.md`
+- `AirPlan/state/airdo/tasks/<task-id>/brief.md`
+- `AirPlan/state/airdo/tasks/<task-id>/subagent-handoff.md` when launched by AirEng
+
+## Result Rules
+
+- Finalize one `result.json` per task.
+- Treat `AirPlan/state/airdo/tasks/<task-id>/worker-state.json` `resultPath` as the canonical pointer to the latest result artifact. The task-local `result.json` is only the editable template before finalize.
+- Include validations, evidence, risks, blockers, and document updates when needed.
+- Do not edit global `AirPlan/todo.md`, `AirPlan/AGENTS.md`, ADR, or C4 files directly unless explicitly delegated through `documentUpdates`.
+- If the task changes execution planning or architecture reality, include concrete `documentUpdates` so AirEng can keep `todo`, `plan`, ADR, and C4 synchronized during merge.
+
+## Automatic Routing
+
+- On `blocked` results, auto-request AirDbg before finalize.
+- On GUI or visual work, auto-request AirXDB before finalize.
+- If AirEng queued an active repair attempt, continue repairing automatically instead of stopping at the first blocker.
+- Do not stop at implementation-prep or progress-only updates when the task is actionable. Continue until finalize unless a real blocker or explicit user decision is required.
+
+## Commands
+
+```bash
+python ../../scripts/airdo_mode.py --mode enter --project <project-root> --task-id T-001
+python ../../scripts/airdo_mode.py --mode status --project <project-root>
+python ../../scripts/airdo_mode.py --mode handoff --project <project-root> --task-id T-001
+python ../../scripts/airdo_mode.py --mode finish --project <project-root> --task-id T-001
+```

AirPlan/docs/spec/AirPlan-ParaV2/plugins/airdo/skills/airdo/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: airdo
+short_description: Public Air executor for one scoped task, validation evidence, and AirPlan result finalization
+default_prompt: "Use AirDo to execute one task, gather validation evidence, auto-route GUI or debug work, and finalize a structured result in AirPlan for AirEng to merge. Do not stop at implementation-prep or progress-only updates when the task is actionable; continue until finalize unless a real blocker or explicit user decision is required."

AirPlan/docs/spec/AirPlan-ParaV2/plugins/aireng/.codex-plugin/plugin.json

@@ -0,0 +1,42 @@
+{
+  "name": "aireng",
+  "version": "0.6.0",
+  "description": "AirEng is the sole public Air scheduler plugin. It reads AirArc planning artifacts, dispatches isolated AirDo subagents, monitors them on a 5-minute cadence, and merges structured results back into AirPlan without defaulting to parent-thread coding.",
+  "author": {
+    "name": "14816",
+    "email": "noreply@example.com",
+    "url": "https://airlongdian.fun"
+  },
+  "homepage": "https://airlongdian.fun/plugins/aireng",
+  "repository": "https://airlongdian.fun/plugins/aireng",
+  "license": "MIT",
+  "keywords": [
+    "air",
+    "aireng",
+    "scheduler",
+    "subagent",
+    "parallel"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "AirEng",
+    "shortDescription": "Schedule and monitor isolated AirDo subagents from AirArc plans",
+    "longDescription": "AirEng is the sole public scheduler for the Air workflow. It reads AirArc execution artifacts from AirPlan, prepares isolated task handoffs, dispatches multiple AirDo worker subagents with bounded concurrency, monitors them every 5 minutes, repairs stalled flow when possible, and merges structured worker results without replaying long parent-thread context or defaulting to parent-thread coding.",
+    "developerName": "14816",
+    "category": "Productivity",
+    "capabilities": [
+      "Interactive",
+      "Write"
+    ],
+    "websiteURL": "https://airlongdian.fun/plugins/aireng",
+    "privacyPolicyURL": "https://openai.com/policies/row-privacy-policy/",
+    "termsOfServiceURL": "https://openai.com/policies/row-terms-of-use/",
+    "defaultPrompt": [
+      "Use AirEng to load AirArc execution artifacts from AirPlan and plan a bounded dispatch wave.",
+      "Use AirEng to launch isolated AirDo subagents in parallel, keep concurrency within the dispatch manifest, and re-check active workers every 300 seconds.",
+      "Use AirEng to merge finalized AirDo results, repair blocked or stalled tasks, and keep AirPlan documents synchronized without defaulting to parent-thread implementation."
+    ],
+    "brandColor": "#0F766E",
+    "screenshots": []
+  }
+}

AirPlan/docs/spec/AirPlan-ParaV2/plugins/aireng/commands/aireng.md

@@ -0,0 +1,80 @@
+---
+description: Run AirEng as the sole public Air scheduler that reads AirArc artifacts, dispatches isolated AirDo subagents, monitors them every 5 minutes, and merges structured results into AirPlan without defaulting to parent-thread coding
+argument-hint: [run|status|plan|dispatch|monitor|merge|intervene]
+allowed-tools: [Read, Glob, Grep, Bash, Write, Edit]
+---
+
+# /aireng
+
+Use AirEng as the only public execution scheduler when the workflow should stay thin in the parent thread and execute real work through isolated subagents.
+
+## Steps
+
+1. Parse `$ARGUMENTS`; default to `run` when empty.
+2. Always operate from the current project root and store workflow artifacts under `AirPlan/`.
+3. The runtime auto-bootstraps missing `AirPlan/` files on first startup and does not overwrite existing project artifacts.
+4. AirEng is a scheduler and convergence engine, not a default coding worker:
+   - Prefer isolated `/airdo` execution for normal task implementation.
+   - Keep parent-thread work focused on planning-source selection, dispatch, monitoring, merge, repair, and document convergence.
+   - Treat direct parent-thread editing as a temporary unblock action only when a worker is hard-blocked and cannot self-recover.
+   - After any temporary intervention, return immediately to scheduler mode.
+5. AirEng is authorized to autonomously decide commands and file edits when needed to keep development moving unattended, but that autonomy serves orchestration, repair, doc sync, and unblock actions first rather than long-running parent-thread implementation.
+6. For `status`, run:
+
+```bash
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode status --project .
+```
+
+7. For `plan`, run:
+
+```bash
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode plan --project .
+```
+
+8. For `dispatch`, run:
+
+```bash
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode dispatch --project .
+```
+
+Then read the generated dispatch manifest under `AirPlan/state/aireng/dispatch/`, open each `handoffPath`, and prepare one isolated AirDo worker subagent per task. After a worker finishes, treat its `workerStatePath` `resultPath` as canonical instead of re-reading the task-local template `result.json`.
+
+9. For `monitor`, run:
+
+```bash
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode monitor --project .
+```
+
+Use this to perform one non-blocking scheduler inspection pass: merge ready results, detect stalled workers, prepare repair continuation, and update `nextAction` in `AirPlan/state/aireng/state.json`.
+
+10. For `intervene`, run:
+
+```bash
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode intervene --project .
+```
+
+Use this only for hard blockers that AirEng cannot clear through ordinary monitoring, repair, or re-dispatch decisions.
+
+11. For `run`, do one full scheduler step:
+   - Ensure AirEng state exists with `enter` if needed.
+   - Prefer `AirPlan/state/airarc/reviews/execution-plan.json`; if stale or missing, refresh via `plan`.
+   - If no active wave exists, dispatch the next available parallel-safe wave.
+   - If active workers already exist, monitor them instead of re-dispatching blindly.
+   - Spawn one `worker` subagent per dispatched task with `fork_context=false` so contexts stay isolated.
+   - Pass only the project path plus the task handoff file content; do not fork the full parent conversation.
+   - Keep at most `recommendedConcurrency` workers active at once.
+   - Do not execute ordinary child-task implementation in the parent thread.
+   - Do not interrupt actionable workers for midpoint status checks.
+   - Refresh `AirPlan/todo.md` and the active dispatch block in `AirPlan/plan.md` when a wave starts so progress is visible during execution.
+   - When ready results appear, merge them through:
+
+```bash
+python "$HOME/plugins/aireng/scripts/aireng_mode.py" --mode merge --project . --result <result-json>
+```
+
+12. In unattended runs, keep the scheduler on a 5-minute monitoring cadence:
+   - Re-check active workers every 300 seconds.
+   - Continue dispatching later waves automatically when the current wave converges.
+   - Stop only when state reaches `completed` or a true user-decision blocker remains.
+
+13. Throughout execution, keep `AirPlan/todo.md`, `AirPlan/plan.md`, and any required ADR/C4 updates synchronized. AirDo proposes `documentUpdates`; AirEng owns applying them.

AirPlan/docs/spec/AirPlan-ParaV2/plugins/aireng/scripts/aireng_mode.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+def _add_lib_path() -> None:
+    root = Path(__file__).resolve().parents[3]
+    lib_path = root / "lib"
+    if str(lib_path) not in sys.path:
+        sys.path.insert(0, str(lib_path))
+
+
+_add_lib_path()
+
+from air_runtime.engine import (
+    build_engine_plan,
+    dispatch_worker_group,
+    enter_engine,
+    intervene_engine,
+    merge_worker_result,
+    monitor_engine,
+    run_engine_once,
+    status_engine,
+)
+from air_runtime.paths import todo_path as workflow_todo_path
+from air_runtime.project_bootstrap import ensure_project_bootstrap
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="AirEng public scheduler runtime")
+    parser.add_argument(
+        "--mode",
+        choices=["enter", "status", "plan", "dispatch", "merge", "monitor", "run", "intervene"],
+        default="status",
+    )
+    parser.add_argument("--project", default=".")
+    parser.add_argument("--todo", default="")
+    parser.add_argument("--result", default="")
+    parser.add_argument("--dispatch-group", default="")
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    project_root = Path(args.project).expanduser().resolve()
+    ensure_project_bootstrap(project_root)
+
+    if args.mode == "enter":
+        state_path, health = enter_engine(project_root)
+        print("aireng_mode=enabled")
+        print(f"project_root={project_root}")
+        print(f"state_path={state_path}")
+        for key, value in health.items():
+            print(f"{key}={'ok' if value else 'missing'}")
+        return
+
+    if args.mode == "status":
+        state = status_engine(project_root)
+        print(f"aireng_mode={'enabled' if state.get('enabled') else 'disabled'}")
+        print(f"project_root={project_root}")
+        print(f"engine_mode={state.get('engineMode', '')}")
+        print(f"active_wave_id={state.get('activeWaveId', '')}")
+        print(f"active_dispatch_path={state.get('activeDispatchPath', '')}")
+        print(f"active_worker_count={len(state.get('activeWorkers', []))}")
+        print(f"merged_results={len(state.get('mergedResults', []))}")
+        print(f"pending_global_updates={len(state.get('pendingGlobalUpdates', []))}")
+        print(f"planning_source={state.get('planningSource', '')}")
+        print(f"xdb_sessions={len(state.get('xdbSessions', []))}")
+        print(f"xdb_policy_enabled={state.get('xdbPolicy', {}).get('enabled')}")
+        print(f"debug_sessions={len(state.get('debugSessions', []))}")
+        print(f"debug_policy_enabled={state.get('debugPolicy', {}).get('enabled')}")
+        print(f"repair_attempts={len(state.get('repairAttempts', []))}")
+        print(f"active_repairs={state.get('activeRepairCount', 0)}")
+        print(f"repair_policy_enabled={state.get('repairPolicy', {}).get('enabled')}")
+        print(f"monitor_interval_seconds={state.get('monitoringPolicy', {}).get('checkIntervalSeconds', 0)}")
+        print(f"last_loop_at={state.get('lastLoopAt', '')}")
+        print(f"last_intervention_at={state.get('lastInterventionAt', '')}")
+        print(f"next_action={state.get('nextAction', '')}")
+        for key, value in state.get("artifactHealth", {}).items():
+            print(f"{key}={'ok' if value else 'missing'}")
+        return
+
+    if args.mode == "plan":
+        current_todo_path = Path(args.todo).expanduser().resolve() if args.todo else workflow_todo_path(project_root)
+        result = build_engine_plan(project_root, current_todo_path)
+        print("aireng_mode=planned")
+        print(f"project_root={project_root}")
+        print(f"todo_path={current_todo_path}")
+        print(f"plan_path={result['planPath']}")
+        print(f"plan_markdown_path={result['planMarkdownPath']}")
+        print(f"review_json_path={result['reviewJsonPath']}")
+        print(f"review_markdown_path={result['reviewMarkdownPath']}")
+        print(f"planning_source={result['planningSource']}")
+        print(f"review_source_path={result['reviewSourcePath']}")
+        print(f"selected_tasks={','.join(result['selectedTasks'])}")
+        print(f"parallel_group_count={result['parallelGroupCount']}")
+        print(f"conflict_count={result['conflictCount']}")
+        return
+
+    if args.mode == "dispatch":
+        result = dispatch_worker_group(project_root, args.dispatch_group)
+        print("aireng_mode=dispatched")
+        print(f"project_root={project_root}")
+        print(f"dispatch_path={result['dispatchPath']}")
+        print(f"group_name={result['groupName']}")
+        print(f"wave_id={result['waveId']}")
+        print(f"task_ids={','.join(result['taskIds'])}")
+        print(f"recommended_concurrency={result['recommendedConcurrency']}")
+        return
+
+    if args.mode == "monitor":
+        result = monitor_engine(project_root)
+        print("aireng_mode=monitored")
+        print(f"project_root={project_root}")
+        print(f"engine_mode={result['engineMode']}")
+        print(f"active_worker_count={result['activeWorkerCount']}")
+        print(f"ready_to_merge_count={result['readyToMergeCount']}")
+        print(f"merged_count={result['mergedCount']}")
+        print(f"stalled_count={result['stalledCount']}")
+        print(f"intervention_count={result['interventionCount']}")
+        print(f"blocked_task_count={result['blockedTaskCount']}")
+        print(f"repair_queue_path={result['repairQueuePath']}")
+        print(f"next_action={result['nextAction']}")
+        return
+
+    if args.mode == "intervene":
+        result = intervene_engine(project_root)
+        print("aireng_mode=intervened")
+        print(f"project_root={project_root}")
+        print(f"engine_mode={result['engineMode']}")
+        print(f"stalled_count={result['stalledCount']}")
+        print(f"intervention_count={result['interventionCount']}")
+        print(f"blocked_task_count={result['blockedTaskCount']}")
+        print(f"next_action={result['nextAction']}")
+        return
+
+    if args.mode == "run":
+        current_todo_path = Path(args.todo).expanduser().resolve() if args.todo else workflow_todo_path(project_root)
+        result = run_engine_once(project_root, current_todo_path)
+        print("aireng_mode=ran")
+        print(f"project_root={project_root}")
+        print(f"action={result['action']}")
+        print(f"steps={','.join(result['steps'])}")
+        print(f"plan_path={result['planPath']}")
+        print(f"engine_mode={result['engineMode']}")
+        print(f"next_action={result['nextAction']}")
+        if 'dispatchPath' in result:
+            print(f"dispatch_path={result['dispatchPath']}")
+        if 'waveId' in result:
+            print(f"wave_id={result['waveId']}")
+        if 'taskIds' in result:
+            print(f"task_ids={','.join(result['taskIds'])}")
+        if 'activeWorkerCount' in result:
+            print(f"active_worker_count={result['activeWorkerCount']}")
+        return
+
+    if not args.result:
+        raise SystemExit("--result is required for merge mode")
+
+    result_path = Path(args.result).expanduser().resolve()
+    merged = merge_worker_result(project_root, result_path)
+    print("aireng_mode=merged")
+    print(f"project_root={project_root}")
+    print(f"task_id={merged['taskId']}")
+    print(f"task_status={merged['status']}")
+    print(f"archived_result_path={merged['archivedResultPath']}")
+    print(f"pending_global_update_count={merged['pendingGlobalUpdateCount']}")
+    print(f"doc_queue_path={merged['docQueuePath']}")
+    print(f"repair_queue_path={merged['repairQueuePath']}")
+    print(f"todo_path={merged['todoPath']}")
+    print(f"applied_doc_path_count={merged['appliedDocPathCount']}")
+    print(f"xdb_session_count={merged['xdbSessionCount']}")
+    print(f"debug_session_count={merged['debugSessionCount']}")
+    print(f"repair_attempt_count={merged['repairAttemptCount']}")
+    print(f"repair_prepared={merged['repairPrepared']}")
+    print(f"repair_dispatch_path={merged['repairDispatchPath']}")
+    print(f"next_action={merged['nextAction']}")
+
+
+if __name__ == "__main__":
+    main()

AirPlan/docs/spec/AirPlan-ParaV2/plugins/aireng/skills/aireng/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: aireng
+description: Sole public Air scheduler that reads AirArc execution artifacts, dispatches isolated AirDo subagents with bounded concurrency, monitors them on a 5-minute cadence, and merges structured results into AirPlan.
+---
+
+# AirEng
+
+## Role
+
+- Own the global execution contract in `AirPlan/`.
+- Read AirArc review output before falling back to local todo analysis.
+- Dispatch isolated AirDo subagents with `fork_context=false`.
+- Monitor active workers, merge structured worker results, and keep the scheduler moving unattended.
+- Own debug policy, XDB policy, repair policy, intervention policy, and global document convergence.
+- Default to no parent-thread coding; use parent-thread edits only for short unblock actions that restore the scheduler.
+
+## Planning Source Order
+
+1. `AirPlan/state/airarc/reviews/execution-plan.json`
+2. `AirPlan/state/airarc/reviews/parallel-review.json`
+3. Engine fallback analysis of `AirPlan/todo.md`
+
+## Dispatch Contract
+
+- Generate the dispatch manifest under `AirPlan/state/aireng/dispatch/`.
+- Respect `recommendedConcurrency`; do not flood the workspace with overlapping workers.
+- Spawn one isolated AirDo subagent per task handoff.
+- After a worker finishes, read its `workerStatePath` and use the `resultPath` recorded there as the canonical finalized result location.
+- Pass only the task handoff and project path to each worker. Do not fork the full parent thread history.
+- Do not interrupt actionable workers for midpoint status updates; let them continue through implementation and finalize unless they surface a real blocker.
+- Keep parent-thread work limited to orchestration, monitoring, merge, repair, document convergence, and minimal unblock actions.
+- Refresh `AirPlan/todo.md` and the active dispatch block in `AirPlan/plan.md` when a wave starts so execution progress is visible during the run.
+
+## Monitoring Contract
+
+- Store scheduler state in `AirPlan/state/aireng/state.json`.
+- Track `engineMode`, `activeWaveId`, `activeDispatchPath`, `activeWorkers`, `monitoringPolicy`, `nextAction`, and `interventionHistory`.
+- Use `monitoringPolicy.checkIntervalSeconds = 300` as the default cadence for unattended monitoring.
+- Prefer re-dispatch, repair, debug, or other isolated recovery flows before direct intervention.
+- Escalate to user decision only when a worker remains hard-blocked after the allowed intervention budget.
+
+## Merge Guarantees
+
+- Update task status and merge log in `AirPlan/todo.md`.
+- Apply worker `documentUpdates`.
+- Refresh engine-managed sync blocks in `AirPlan/AGENTS.md` and `AirPlan/docs/architecture/c4/module.md`.
+- Track AirXDB sessions in `AirPlan/state/aireng/state.json`.
+- Track debug sessions in `AirPlan/state/aireng/state.json`.
+- Track repair attempts in `AirPlan/state/aireng/state.json`.
+- Refuse a `done` merge when required global document updates are missing.
+- Refuse a GUI-like `done` merge when successful AirXDB evidence is missing.
+- Apply worker `documentUpdates` promptly so plan, ADR, and C4 changes do not lag behind completed slices.
+
+## Commands
+
+```bash
+python ../../scripts/aireng_mode.py --mode enter --project <project-root>
+python ../../scripts/aireng_mode.py --mode status --project <project-root>
+python ../../scripts/aireng_mode.py --mode plan --project <project-root> --todo <airplan-todo-md>
+python ../../scripts/aireng_mode.py --mode dispatch --project <project-root> [--dispatch-group <wave-group-name>]
+python ../../scripts/aireng_mode.py --mode monitor --project <project-root>
+python ../../scripts/aireng_mode.py --mode run --project <project-root> [--todo <airplan-todo-md>]
+python ../../scripts/aireng_mode.py --mode intervene --project <project-root>
+python ../../scripts/aireng_mode.py --mode merge --project <project-root> --result <worker-result-json>
+```

AirPlan/docs/spec/AirPlan-ParaV2/plugins/aireng/skills/aireng/agents/openai.yaml

@@ -0,0 +1,3 @@
+name: aireng
+short_description: Public Air scheduler for isolated AirDo subagent dispatch and AirPlan merges
+default_prompt: "Use AirEng to read AirArc execution artifacts from AirPlan, dispatch isolated AirDo subagents with bounded concurrency, and merge structured worker results back into AirPlan. When dispatching workers, instruct them to continue through implementation and finalize without stopping for midpoint progress updates unless a real blocker or explicit user decision is required."