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

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

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

AirPlan/docs/spec/AirPlanV2/commands/airplan.md

@@ -0,0 +1,46 @@
+---
+description: "AirPlan V2 - unified scheduler with 12 modes"
+argument-hint: "[arc|eng|do|dbg|xdb|sdb|ndb|ctx|dep|tst|sec|rvr] [sub-command]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /airplan
+
+AirPlan V2 - unified scheduler. V1 8 plugins merged into 1, adds 4 components, total 12 sub-modes.
+
+## Sub-modes
+
+| Mode | Role |
+|------|------|
+| arc | Architecture planner |
+| eng | Scheduler engine |
+| do | Task executor |
+| dbg | Debugger |
+| xdb | GUI validator |
+| sdb | Static analyzer |
+| ndb | Network debugger |
+| ctx | Context manager |
+| dep | Deployer |
+| tst | Test runner |
+| sec | Security scanner |
+| rvr | Requirements reviewer |
+
+## Usage
+
+1. Parse $ARGUMENTS; default to "status" when empty.
+2. Run from project root - replace MODE with first arg:
+
+```bash
+python "$HOME/plugins/airplan/scripts/airplan.py" --mode MODE --project . [OPTIONS]
+```
+
+Example: /airplan arc -> runs with --mode arc
+Example: /airplan eng monitor -> runs with --mode eng --sub monitor
+
+3. Common patterns:
+   - /airplan arc parallel-review --todo AirPlan/todo.md
+   - /airplan eng dispatch
+   - /airplan eng monitor
+   - /airplan do finish --task-id T-001 --result /path/to/result.json
+
+4. Runtime auto-bootstraps missing AirPlan/ files.

AirPlan/docs/spec/AirPlanV2/commands/arc.md

@@ -0,0 +1,70 @@
+---
+description: "AirPlan arc - architecture planner, READ-ONLY, never writes code"
+argument-hint: "[enter|status|parallel-review|incremental-replan]"
+allowed-tools: "[Read, Glob, Grep]"
+deny-plan-mode: true
+---
+
+# /arc
+
+AirArc is a pure architecture planner. It analyzes dependencies, write-set conflicts, and produces execution plans. It NEVER writes code, modifies source files, or enters plan mode.
+
+## Hard Rules (violated = bug)
+
+1. **READ-ONLY** — you only Read, Glob, Grep. Never Write, Edit, Bash.
+2. **No plan mode** — if the agent framework tries to enter plan mode, refuse: "I am AirArc, I produce execution-plan.json, not code changes."
+3. **Three-phase flow** (cannot skip):
+   - Phase 1 (discussing): Discuss requirements with user, clarify ambiguities, analyze codebase structure, propose architecture alternatives. **Forbidden to write execution-plan.json.**
+   - Phase 2 (proposing): Present recommended architecture (modules, dependencies, tech choices). Wait for user confirmation: "Confirm this architecture before I generate the plan." User objections return to Phase 1. **Forbidden to write execution-plan.json.**
+   - Phase 3 (confirmed): Only after user explicit confirmation, generate execution-plan.json and task-graph.json.
+
+## Sub-commands
+
+### enter
+
+```bash
+python scripts/airplan.py --mode arc --project . --sub enter
+```
+
+### status
+
+```bash
+python scripts/airplan.py --mode arc --project . --sub status
+```
+
+### parallel-review
+
+```bash
+python scripts/airplan.py --mode arc --project . --sub parallel-review --todo AirPlan/todo.md
+```
+
+### incremental-replan
+
+```bash
+python scripts/airplan.py --mode arc --project . --sub incremental-replan --todo AirPlan/todo.md
+```
+
+## 三阶段 → 命令映射
+
+ArcPhaseGate 控制 execution-plan.json 写入权限。phase 默认 `discussing`，必须推进到 `confirmed` 才能生成规划。
+
+| 阶段 | phase 值 | 操作 |
+|------|---------|------|
+| 需求探讨 | `discussing` | 与用户对话讨论，不需要命令 |
+| 架构确认 | `proposing` | 向用户呈现方案，等待确认 |
+| 生成规划 | `confirmed` | `parallel-review` 或 `incremental-replan` |
+
+**推进方式**：用户说"确认"/"可以"/"同意"后，`ArcPhaseGate.confirm_architecture()` 自动推进。不丢失（已修复）。
+
+## 弱模型安全（INV-16）
+
+Do Worker 可能是廉价模型/本地小模型，字面理解任务无推断能力。产出每个任务时必须：
+
+1. **禁止歧义词** — 不用"清理"、"重构"、"优化"等宽泛动词，指明具体改什么
+2. **否定约束显式化** — 写明**不做什么**（如"不删除 src/ 下现有模块"）
+3. **文件范围精确化** — `files_dirs` 精确到文件级，不写 `src/` 目录级
+4. **完成标准可验证** — `done_when` 能用 `grep`/`diff`/`cmake --build` 客观验证
+
+## Logging Standard
+
+When planning C++ projects, the first task MUST be "integrate spdlog" if not already present. All generated code must use spdlog, not std::cout/qDebug/printf.

AirPlan/docs/spec/AirPlanV2/commands/ctx.md

@@ -0,0 +1,65 @@
+---
+description: "AirPlan ctx mode - context manager: compression, token estimation, stale lock detection"
+argument-hint: "[enter|compress|validate|estimate|status]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /ctx
+
+AirContext 管理上下文压缩、Token 估算、陈旧锁检测。三级降级压缩策略：重试 → 换模型 → 截断。
+
+## 硬规则
+
+1. **压缩质量校验** — 压缩后必须调用 `--sub validate` 验证关键信息（ADR 引用、TODO、文件路径）保留率 ≥70%
+2. **压缩前备份** — 每次压缩自动备份原文件为 `.bak`
+3. **陈旧锁清理** — 检测到锁持有进程已死则自动清理
+
+## 三级降级压缩
+
+1. **RETRY** — 重新压缩（换 prompt）
+2. **FALLBACK_MODEL** — 换模型压缩
+3. **TRUNCATE** — 放弃压缩，保留原始上下文，通知用户
+
+## 子命令
+
+### enter — 初始化上下文管理器
+
+```bash
+python scripts/airplan.py --mode ctx --project . --sub enter
+```
+
+### compress — 压缩上下文
+
+```bash
+python scripts/airplan.py --mode ctx --project . --sub compress
+```
+
+读取 `AirPlan/context.md`，执行三级降级压缩。emit `context.compacted` 事件。
+
+### validate — 校验压缩质量
+
+```bash
+python scripts/airplan.py --mode ctx --project . --sub validate
+```
+
+检查压缩是否保留关键模式：文件路径、ADR-XXXX、TODO/FIXME、INV-X。返回 `{validation_ok, level, tokens}`。
+
+### estimate — Token 估算
+
+```bash
+python scripts/airplan.py --mode ctx --project . --sub estimate
+```
+
+按内容类型（中文/英文/代码/Markdown）分比率估算 token 数。
+
+### status — 查看状态
+
+```bash
+python scripts/airplan.py --mode ctx --project . --sub status
+```
+
+## 集成路径
+
+**Eng 压缩检查**：每轮 `monitor_engine()` 后可调 `--sub validate` 检查上下文质量。
+
+**Do Worker 压缩**：长任务 Worker 可在执行前调 `--sub compress` 精简上下文。

AirPlan/docs/spec/AirPlanV2/commands/dbg.md

@@ -0,0 +1,63 @@
+---
+description: "AirPlan dbg mode - 7-step debug workflow with evidence-first gate"
+argument-hint: "[start|snapshot|status]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /dbg
+
+AirDbg 是调试器，强制 7 步证据先于修复流程。EvidenceFirstGate 硬门控——未取证不可改代码（INV-9）。
+
+## 硬规则
+
+1. **先读后写** — 修改代码前必须至少完成一项取证（截图/抓包/静态分析/日志分析/代码追踪/复现）
+2. **修复前快照** — 修改代码前必须 `--sub snapshot` 创建回滚点
+3. **步骤不可跳过** — 7 步工作流按顺序推进，每步需要对应证据
+
+## 7 步工作流
+
+| 步 | 名称 | 需要证据 | 操作 |
+|----|------|---------|------|
+| 1 | confirm_symptoms | 症状描述 | `--sub start` 初始化会话 |
+| 2 | load_context | | 读取相关文件、日志、配置 |
+| 3 | reproduce | (可跳过) | 复现或标记为不可复现 |
+| 4 | locate_root_cause | ≥1 种证据 | 分析证据定位根因 |
+| 5 | fix | 根因分析结论 | 先 `--sub snapshot`，再改代码 |
+| 6 | verify_again | 测试结果 | 验证修复有效 |
+| 7 | document | | 写 debug-log.md，关闭会话 |
+
+## 子命令
+
+### start — 启动调试会话
+
+```bash
+python scripts/airplan.py --mode dbg --project . --sub start --task-id T-001
+```
+
+返回 `{sessionId, currentStep, steps}`。会话状态写入 `AirPlan/state/airdbg/sessions/`。
+
+### snapshot — 修复前创建回滚点
+
+```bash
+python scripts/airplan.py --mode dbg --project . --sub snapshot --task-id T-001
+```
+
+在当前 HEAD 创建 git tag，返回 `{snapshot_ref}`。
+
+### status — 查看调试状态
+
+```bash
+python scripts/airplan.py --mode dbg --project . --sub status
+```
+
+## 集成路径
+
+**Eng → Dbg**：`monitor_engine()` 检测到 stalled/blocked Worker 且 action=`"upgraded-to-airdbg"` 时：
+1. 读 `interventions[].sessionId` 获取 Dbg 会话 ID
+2. 调 `--sub start --task-id {tid}` 开始 Dbg 会话
+3. Dbg 完成后：finish Worker，然后 merge
+
+**Dbg → Do finish**：Dbg 修复完成后回到原任务：
+```bash
+python scripts/airplan.py --mode do --project . --sub finish --task-id T-001 --result AirPlan/state/airdo/tasks/T-001/result.json
+```

AirPlan/docs/spec/AirPlanV2/commands/dep.md

@@ -0,0 +1,45 @@
+---
+description: "AirPlan dep mode - SSH remote build + deploy + systemd management"
+argument-hint: "[deploy|status]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /dep
+
+AirDep 是部署器。SSH 远程构建 → 二进制传输（scp + MD5 校验）→ systemd 生命周期管理 → 部署验证。
+
+## 硬规则
+
+1. **部署前必须已有构建产物** — 本地 `--binary` 路径文件必须存在
+2. **传输后 MD5 校验** — scp 后远程 MD5 必须与本地一致
+3. **部署后验证** — systemd `is-active` 检查服务状态
+
+## 子命令
+
+### deploy — 执行部署
+
+```bash
+python scripts/airplan.py --mode dep --project . --sub deploy --task-id T-001 --host 192.168.1.100 --binary ./build/myapp
+```
+
+参数：
+- `--task-id`：关联任务 ID
+- `--host`：远程主机地址
+- `--binary`：本地二进制文件路径
+
+返回 `{task_id, success, md5, service_status}`。emit `deploy.completed` 事件。
+
+制品：`AirPlan/state/airdep/sessions/{session_id}.json`
+
+### status — 查看部署状态
+
+```bash
+python scripts/airplan.py --mode dep --project . --sub status
+```
+
+## 集成路径
+
+**Do Worker 完成后部署**：Worker finish → Eng merge 检测 `deployRequired` 字段 → 调 dep deploy：
+```bash
+python scripts/airplan.py --mode dep --project . --sub deploy --task-id T-001 --host <host> --binary <path>
+```

AirPlan/docs/spec/AirPlanV2/commands/do.md

@@ -0,0 +1,131 @@
+---
+description: "AirPlan do mode - task executor with UI skill routing and full expert plugin routing"
+argument-hint: "[enter|status|finish]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /do
+
+AirDo 是任务执行器。运行单个任务，强制执行全专家插件路由规则。
+
+## 硬规则
+
+1. **UI Task Handling (P1-20)** — 当任务涉及 UI/前端/界面时，检测并确保 frontend-design Skill 可用。不可用时阻止执行
+2. **Evidence Gate (INV-4)** — GUI 任务需截图，网络任务需抓包，代码任务需静态分析/测试
+3. **全专家插件强制路由** — finish 时按任务类型和状态强制路由到对应专家插件，不可跳过
+
+## 子命令
+
+### enter — 进入 Worker
+
+```bash
+python scripts/airplan.py --mode do --project . --sub enter --task-id T-001 --task-text "实现登录界面UI"
+```
+
+参数：
+- `--task-id`：任务 ID（必须）
+- `--task-text`：任务描述文本（用于 UI 检测和路由，必须）
+
+创建 `AirPlan/state/airdo/tasks/{task_id}/worker-state.json`。返回 `{taskId, briefPath, resultPath, workerStatePath, uiRouting}`。
+
+### status — 查看 Worker 状态
+
+```bash
+python scripts/airplan.py --mode do --project . --sub status
+```
+
+### finish — 完成 Worker（含全专家插件路由决策）
+
+```bash
+python scripts/airplan.py --mode do --project . --sub finish --task-id T-001 --result AirPlan/state/airdo/tasks/T-001/result.json
+```
+
+finish 执行强制路由（按优先级）：
+
+| 条件 | 路由目标 | 强制 |
+|------|---------|------|
+| blocked / failed | `airdbg` | 是 |
+| done + 无 validations + 无 files_changed | `airdbg` | 是 |
+| GUI 任务（gui/ui/render/widget/dialog 等） | `airxdb` | 是 |
+| 网络任务（network/rtsp/http/tcp/socket 等） | `airndb` | 是 |
+| C/C++ 文件变更（.cpp/.h/.hpp 等） | `airsdb` | 是 |
+| 所有 done 任务 | `airrvr` | 是 |
+| 无强制路由触发 | `merge` | 否 |
+
+返回 `routingDecisions` 列表（可能有多个路由目标，依次处理）。
+
+## AirDbg 路由 — 调试修复
+
+当 finish 返回 `routingDecisions` 含 `airdbg` 时：
+
+```bash
+# 1. 启动调试会话
+python scripts/airplan.py --mode dbg --project . --sub start --task-id {tid}
+
+# 2. Dbg 按 7 步工作流调试（取证→定位→修复→验证）
+# 3. Dbg 完成后，重新 finish:
+python scripts/airplan.py --mode do --project . --sub finish --task-id {tid} --result AirPlan/state/airdo/tasks/{tid}/result.json
+```
+
+## AirXDB 路由 — GUI 截图取证
+
+当 finish 返回 `routingDecisions` 含 `airxdb` 时：
+
+```bash
+python scripts/airplan.py --mode xdb --project . --prefer auto --output task-{tid}-screenshot.png
+```
+截图路径写入 result.json 的 `xdbSessions` 字段后重新 finish。
+
+## AirNDB 路由 — 网络抓包取证
+
+当 finish 返回 `routingDecisions` 含 `airndb` 时：
+
+```bash
+python scripts/airplan.py --mode ndb --project . --sub enter
+# 然后 tcpdump/tshark 抓包，存入 AirPlan/state/airndb/captures/
+```
+抓包路径写入 result.json 的 `ndbSessions` 字段后重新 finish。
+
+## AirSDB 路由 — C/C++ 静态分析
+
+当 finish 返回 `routingDecisions` 含 `airsdb` 时：
+
+```bash
+python scripts/airplan.py --mode sdb --project . --backend cppcheck --target ./src
+```
+分析报告路径写入 result.json 的 `sdbReports` 字段后重新 finish。
+
+## AirRvr 路由 — 需求一致性审查
+
+当 finish 返回 `routingDecisions` 含 `airrvr` 时：
+
+```bash
+python scripts/airplan.py --mode rvr --project . --task-id {tid} --sub review
+```
+审查通过后重新 finish，此时 Rvr 证据已写入 validations。
+
+## 证据采集 — 辅助命令
+
+**GUI 任务截图**：
+```bash
+python scripts/airplan.py --mode xdb --project . --prefer auto --output task-{tid}-screenshot.png
+```
+
+**网络任务抓包**：
+```bash
+python scripts/airplan.py --mode ndb --project . --sub enter
+```
+
+**代码任务静态分析**：
+```bash
+python scripts/airplan.py --mode sdb --project . --backend cppcheck --target ./src
+```
+
+**代码任务测试**：
+```bash
+python scripts/airplan.py --mode tst --project . --sub run --task-id {tid} --framework googletest
+```
+
+## UI 任务检测关键词（中英文）
+
+gui, ui, render, layout, dialog, osd, overlay, visual, widget, pane, toolbar, canvas, button, window, popup, menu, drm, kms, opengl, vulkan, frontend, react, vue, angular, web, css, html, 界面, 按钮, 对话框, 窗口, 菜单, 控件, 渲染, 布局

AirPlan/docs/spec/AirPlanV2/commands/eng.md

@@ -0,0 +1,169 @@
+---
+description: "AirPlan eng - scheduler engine, dispatches isolated workers, never codes directly"
+argument-hint: "[run|status|plan|dispatch|monitor|merge|intervene]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /eng
+
+AirEng 是调度引擎，不是执行器。它派发隔离 Worker、监控、合并结果。绝不直接实现代码。
+
+## 硬规则（违反=bug）
+
+1. **Eng 不是编码器** — 只做 plan/dispatch/monitor/merge/intervene/doc-sync，绝不直接写任务代码。
+2. **必须通过 /do 派发** — 每个任务必须 spawn 隔离的 /do 子代理（fork_context=false）。
+3. **保持父线程精简** — 父线程只做调度操作。
+4. **直接写代码唯一例外** — Worker 硬阻塞无法自恢复时的紧急干预，干预后立即回到调度模式。
+5. **必须使用中文** — 所有状态报告、进度通知、问题描述均使用中文。禁止英文输出。
+6. **自主决策原则** — 以推进开发进度为第一目标，以下情况自行决策不停下来问用户：
+   - Worker blocked 但修复预算未耗尽 → 自行派发修复
+   - Worker 停滞 → 自行执行停滞干预
+   - 验证失败但非关键 → 记录问题继续下一任务
+   - 波次间衔接 → 自行启动下一波次
+7. **仅以下情况才询问用户**：修复预算耗尽且任务仍 blocked；需求歧义无法继续；系统资源耗尽；用户显式暂停。
+
+## 子命令
+
+### run (默认) — 一次完整调度步骤
+
+```bash
+python "$HOME/plugins/airplan/scripts/airplan.py" --mode eng --project . --sub status
+```
+
+然后：
+- 无活跃波次 → 执行 dispatch 流程（见下方 dispatch 段）
+- 有活跃 Worker → 执行 monitor，不要盲目重新派发
+- 就绪结果出现时：merge through `--sub merge --result <path>`
+
+### status
+
+```bash
+python "$HOME/plugins/airplan/scripts/airplan.py" --mode eng --project . --sub status
+```
+
+### plan
+
+```bash
+python "$HOME/plugins/airplan/scripts/airplan.py" --mode eng --project . --sub plan --todo AirPlan/todo.md
+```
+
+### dispatch
+
+```bash
+python "$HOME/plugins/airplan/scripts/airplan.py" --mode eng --project . --sub dispatch
+```
+
+dispatch 返回 `{waveId, taskIds, dispatchPath}`。**然后按以下步骤操作，不可跳过**：
+
+1. 从 dispatch 返回值中取 `taskIds` 列表
+2. 对 `taskIds` 中的**每个** `tid`，在同一条消息中并发调用 `Agent` 工具（**必须** `run_in_background: true`，否则 Eng 会被阻塞等待子 Agent 完成）：
+   ```
+   Agent(
+     description: "Do Worker: {tid}",
+     subagent_type: "general-purpose",
+     run_in_background: true,
+     prompt: """你是 AirDo Worker，任务 ID: {tid}。
+   项目路径: {project_root}
+
+   ## 任务
+   {task_text}
+
+   ## 文件范围
+   {files}
+
+   ## 完成标准
+   {done_when}
+
+   ## 工作流程
+   1. 先运行 `python scripts/airplan.py --mode do --sub enter --task-id {tid} --task-text '{task_text}' --project .` 初始化
+   2. 读取项目文件，理解现有代码结构
+   3. 实现任务需求，修改/创建源代码文件
+   4. 完成后运行 `python scripts/airplan.py --mode do --sub finish --task-id {tid} --result <result_path>`
+
+   ## 约束
+   - 只修改属于此任务的文件
+   - 完成后必须运行 finish 命令
+   - 遇到无法解决的问题时返回 blocked 状态
+   """
+   )
+   ```
+3. 每个 `Agent` 创建**独立子 Agent**，上下文不继承 Eng 对话（满足 INV-2 `fork_context=false`）
+4. 所有 Worker spawn 完成后，进入 monitor 状态
+5. Worker 完成后，对其 `result.json` 调用 `--sub merge --result <path>`
+6. merge 后 `task-graph.json` 节点状态自动同步为 DONE，不会被重复派发
+
+**注意**：
+- 使用 `Agent` 工具，不是 `Skill` 工具——`Skill` 只加载指令到当前上下文，不创建子 Agent
+- `Agent` 创建的每个子 Agent 拥有独立上下文，天然满足上下文隔离
+- 多个 `Agent` 调用可以在同一条消息中并发发起
+- prompt 中的 task-text/files/done_when 从 `task-graph.json` 获取
+
+### monitor
+
+spawn Worker 后，**不自己循环**。用 `ScheduleWakeup` 让系统每 5 分钟唤醒你一次。
+
+```
+1. 所有 Worker 以 Agent(run_in_background: true) 启动后，立即返回当前波次状态给用户
+2. 调用 ScheduleWakeup(delaySeconds: 300, prompt: "检查 Worker 状态并处理")
+3. 系统 5 分钟后唤醒你，唤醒时执行：
+   a. 运行 `python scripts/airplan.py --mode eng --project . --sub monitor`
+   b. 如果 readyToMergeCount > 0: 对每个完成的 Worker 运行 merge
+   c. 如果 stalledCount > 0: 检查 interventions，action=upgraded-to-airdbg 则启动 Dbg
+   d. 如果 activeWorkerCount > 0: 再次 ScheduleWakeup(300, ...)
+   e. 如果 activeWorkerCount == 0: 检查是否需要下一波 dispatch，不需要则结束
+4. 后台 Worker 完成时系统会自动 <task-notification> 推送——收到后也可以立即处理 merge，不一定要等 5 分钟
+```
+
+**ScheduleWakeup 调用格式**：
+```
+ScheduleWakeup(
+  delaySeconds: 300,
+  reason: "Eng monitor: 检查 {n} 个活跃 Worker 状态",
+  prompt: "/eng monitor"
+)
+```
+
+**停滞检测**（monitor_engine 代码自动执行）：
+- Worker state 文件 mtime > 5 分钟未更新 → 标记 stalled
+- Worker 存活时间 > 2 小时 → 标记 wall-time-exceeded
+- 资源压力（loadavg > 2× CPU 数）→ 暂停派发
+
+### merge
+
+```bash
+python "$HOME/plugins/airplan/scripts/airplan.py" --mode eng --project . --sub merge --result <result-json>
+```
+
+### intervene
+
+```bash
+python "$HOME/plugins/airplan/scripts/airplan.py" --mode eng --project . --sub intervene
+```
+
+仅用于无法通过常规监控或重新派发解决的硬阻塞。
+
+**极端接管条件（全部满足才可介入）**：
+1. 子代理陷入循环阻塞，修复预算已耗尽
+2. 问题已通过 AirDbg 定位到明确的根因
+3. 修复范围极小（≤5 行改动，如配置修正、路径修复）
+4. 继续等待 Worker 重派发已无意义（至少尝试过 2 次）
+
+进入极端接管前，必须在引擎日志中记录：
+`EXTREME_TAKEOVER: taskId=X, reason=Y, changes=Z`
+
+**极端接管时的专家插件调用（强制）**：
+即使进入极端接管，也必须像 AirDo 一样调用相关专家插件：
+- 修改代码前：**必须**调用 AirDbg 定位根因
+- GUI 相关变更：**必须**调用 AirXDB 采集修改前后截图
+- 网络相关变更：**必须**调用 AirNDB 采集抓包证据
+- C/C++ 代码变更：**必须**调用 AirSDB 执行静态分析
+- 修改完成后：**必须**调用 AirRvr 进行需求一致性审查
+- **禁止**跳过专家插件直接修改代码
+
+**违规判定**：如果在正常调度流程中（Worker 可用且未阻塞）、修复预算未耗尽时、改动超 5 行、或未调用相关专家插件就猜测修复，均视为违规。
+
+## 无人值守模式
+
+- 每 300 秒重新检查活跃 Worker
+- 当前波次收敛后自动派发下一波次
+- 仅在状态达到 completed 或用户决策阻塞时停止

AirPlan/docs/spec/AirPlanV2/commands/ndb.md

@@ -0,0 +1,31 @@
+---
+description: "AirPlan ndb mode - network debugger for packet capture and analysis"
+argument-hint: "[enter|status]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /ndb
+
+AirNDB 是网络调试器。抓包分析、TLS 解密、pcapng 支持。
+
+## 子命令
+
+### enter — 初始化网络调试器
+
+```bash
+python scripts/airplan.py --mode ndb --project . --sub enter
+```
+
+返回 `{state_path}`。初始化 `AirPlan/state/airndb/` 目录结构。
+
+### status — 查看调试器状态
+
+```bash
+python scripts/airplan.py --mode ndb --project . --sub status
+```
+
+制品：`AirPlan/state/airndb/captures/`
+
+## 集成路径
+
+**Dbg 取证**：Dbg 在 `locate_root_cause` 步骤可调 ndb 获取网络证据。涉及 network/rtsp/http/tcp 的任务需要抓包证据。

AirPlan/docs/spec/AirPlanV2/commands/rvr.md

@@ -0,0 +1,53 @@
+---
+description: "AirPlan rvr mode - requirement reviewer with highRiskAudit and code-to-design"
+argument-hint: "[review|status]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /rvr
+
+AirRvr 是需求审查器。基于原始需求文档对已完成任务进行独立审查，验证交付物与需求的一致性。含 highRiskAudit（生命周期/空指针/悬垂指针/异常安全/并发）和 Code-to-Design 逐行对照。
+
+## 硬规则
+
+1. **code-to-design 对照** — 每次审查必须逐行对照代码实现与设计文档（ADR、C4、需求）
+2. **高风险审计** — 终审必须包含 lifecycle/nullPointer/danglingPointer/exceptionSafety/concurrency 五项检查
+3. **verdict 控制合并** — fail 阻止合并，conditional-pass 记录遗留项，pass 正常合并
+4. **deliveryVerdict = block-release** — eng dispatch 阻止所有后续派发
+
+## 审查模式
+
+| 模式 | 触发时机 | 审查范围 |
+|------|---------|---------|
+| per-task | 单个任务完成后 | 单任务 |
+| per-wave | 波次所有任务完成后 | 整波 |
+| per-milestone | 项目阶段结束时 | 全量（比对 requirements.md） |
+
+## 子命令
+
+### review — 执行审查
+
+```bash
+python scripts/airplan.py --mode rvr --project . --sub review --task-id T-001
+```
+
+返回 `{task_id, verdict, report_path}`。审查报告含 coverage/intentAlignment/regressionRisk/codeQuality/lifecycleHealth/runtimeStability/codeToDesignTable/highRiskAudit。
+
+制品：`AirPlan/state/airrvr/reviews/{task_id}-{ts}.json`
+
+### status — 查看审查状态
+
+```bash
+python scripts/airplan.py --mode rvr --project . --sub status
+```
+
+## 集成路径
+
+**Eng merge 时自动检查**：merge_worker_result Phase 1.5 自动调用 `get_verdict_for_task(task_id)`：
+- `verdict=fail` → 抛出 `ValueError` 阻止合并
+- `verdict=conditional-pass` → 记录 residualItems 但允许合并
+- `deliveryVerdict=block-release` → dispatch_worker_group 阻止所有后续派发
+
+**触发方式**：设置 `reviewPolicy.requireBeforeMerge=true` 或在 result 中设 `requireReview=true`。
+
+**INVALIDATED 任务清理检查**（P1-21）：ADR 变更级联失效后，手动调 `check_invalidated_cleanup()` 验证旧代码已清理。

AirPlan/docs/spec/AirPlanV2/commands/sdb.md

@@ -0,0 +1,49 @@
+---
+description: "AirPlan sdb mode - multi-language static analyzer (cppcheck/clang-tidy/clippy/go-vet/tsc/mypy)"
+argument-hint: "[analyze]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /sdb
+
+AirSDB 是多语言静态分析器。支持六种后端和 diff 模式。
+
+## 支持的后端
+
+| 后端 | --backend 值 | 语言 |
+|------|-------------|------|
+| Cppcheck | `cppcheck` | C/C++ |
+| Clang-Tidy | `clang-tidy` | C/C++ |
+| Clippy | `clippy` | Rust |
+| go vet + staticcheck | `go-vet` | Go |
+| tsc --noEmit | `tsc` | TypeScript |
+| mypy + ruff | `mypy` | Python |
+
+## 子命令
+
+### 执行静态分析
+
+```bash
+python scripts/airplan.py --mode sdb --project . --backend cppcheck --target ./src
+```
+
+参数：
+- `--backend`：分析后端（默认 `cppcheck`）
+- `--target`：分析目标路径
+
+返回每行一个 finding：`{file}:{line}: {severity}: {message}`。最多显示 10 个。
+
+## diff 模式
+
+两次扫描结果对比，高亮新增/消除的 finding：
+```bash
+# 第一次扫描 → 保存基线
+python scripts/airplan.py --mode sdb --project . --backend cppcheck --target ./src > baseline.txt
+# 修改代码后第二次扫描 → Agent 读取两次结果对比 diff
+```
+
+## 集成路径
+
+**Dbg 取证**：Dbg 在 `locate_root_cause` 步骤可调 sdb 获取静态分析证据。
+
+**Do Worker 完成前**：Worker finish 前可调 sdb 验证代码质量。

AirPlan/docs/spec/AirPlanV2/commands/sec.md

@@ -0,0 +1,57 @@
+---
+description: "AirPlan sec mode - security scanner for sensitive data detection"
+argument-hint: "[scan|status]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /sec
+
+AirSec 是安全扫描器。扫描制品中的敏感数据（API 密钥、令牌、密码），支持 advisory（只报告）和 blocking（阻止合并）两种模式。
+
+## 两种扫描模式
+
+| 模式 | --sec-mode | 行为 |
+|------|-----------|------|
+| advisory | `advisory` | 只报告，不阻止 |
+| blocking | `blocking` | 发现敏感数据时阻止合并 |
+
+## 子命令
+
+### scan — 执行安全扫描
+
+扫描单个文件：
+```bash
+python scripts/airplan.py --mode sec --project . --sub scan --task-id T-001 --scan-path ./src/config.cpp --sec-mode blocking
+```
+
+扫描整个目录：
+```bash
+python scripts/airplan.py --mode sec --project . --sub scan --task-id T-001 --scan-path ./src --sec-mode advisory
+```
+
+不传 `--scan-path` 时扫描 Worker result：
+```bash
+python scripts/airplan.py --mode sec --project . --sub scan --task-id T-001 --sec-mode blocking
+```
+
+参数：
+- `--task-id`：关联任务 ID
+- `--scan-path`：扫描目标路径（文件或目录，可选）
+- `--sec-mode`：`advisory`（默认）或 `blocking`
+
+返回 `{task_id, clean, findings, whitelisted, mode}`。emit `sec.scan` 事件。
+
+### status — 查看扫描状态
+
+```bash
+python scripts/airplan.py --mode sec --project . --sub status
+```
+
+## 集成路径
+
+**Do Worker finish 前**：Worker 完成代码后、调 finish 前，先调 sec scan：
+```bash
+python scripts/airplan.py --mode sec --project . --sub scan --task-id {tid} --sec-mode blocking
+```
+
+**Eng merge 前**：merge_worker_result Phase 1 验证后检查 sec 扫描结果。`clean=false` 时阻止合并。

AirPlan/docs/spec/AirPlanV2/commands/tst.md

@@ -0,0 +1,53 @@
+---
+description: "AirPlan tst mode - unified test runner for CTest/GoogleTest/pytest/jest/go test/cargo test"
+argument-hint: "[run|status]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /tst
+
+AirTst 是测试运行器。支持多框架统一执行和结构化结果报告。
+
+## 支持的框架
+
+| 框架 | --framework 值 | 语言 |
+|------|---------------|------|
+| CTest / GoogleTest | `googletest` | C++ |
+| pytest | `pytest` | Python |
+| jest / vitest | `jest` | TypeScript |
+| go test | `go` | Go |
+| cargo test | `cargo` | Rust |
+
+## 子命令
+
+### run — 执行测试
+
+```bash
+python scripts/airplan.py --mode tst --project . --sub run --task-id T-001 --framework googletest
+```
+
+参数：
+- `--task-id`：关联任务 ID
+- `--framework`：测试框架（见上表）
+
+返回 `{task_id, framework, total, passed, failed}`。emit `test.run` 事件。
+
+制品：`AirPlan/state/airtst/reports/{task_id}-{ts}.json`
+
+### status — 查看测试状态
+
+```bash
+python scripts/airplan.py --mode tst --project . --sub status
+```
+
+## 集成路径
+
+**Arc 注入的边界测试任务执行**：Arc 规划的 `T-TEST-*` 任务执行时调 tst run：
+```bash
+python scripts/airplan.py --mode tst --project . --sub run --task-id T-TEST-001 --framework googletest
+```
+
+**Do Worker 完成前自测**：Worker finish 前可调 tst 验证：
+```bash
+python scripts/airplan.py --mode tst --project . --sub run --task-id {tid} --framework {fw}
+```

AirPlan/docs/spec/AirPlanV2/commands/xdb.md

@@ -0,0 +1,43 @@
+---
+description: "AirPlan xdb mode - GUI validator with DRM/KMS native screenshot and headless CI"
+argument-hint: "[capture]"
+allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
+---
+
+# /xdb
+
+AirXDB 是 GUI 验证器。支持 DRM/KMS 原生截图（kmsgrab）、Xvfb headless 截图、多后端自动降级。
+
+## 截图后端
+
+| 后端 | --prefer 值 | 适用场景 |
+|------|------------|---------|
+| KMS grab | `kms` | 嵌入式 DRM/KMS 显示 |
+| Xvfb | `xvfb` | CI headless 环境 |
+| fallback | `fallback` | 通用桌面环境 |
+| auto | `auto` | 自动检测（默认，按 kms → xvfb → fallback 尝试） |
+
+## 子命令
+
+### 截图采集
+
+```bash
+python scripts/airplan.py --mode xdb --project . --prefer auto --output screenshot.png
+```
+
+参数：
+- `--prefer`：截图后端偏好（默认 `auto`）
+- `--output`：输出文件名（默认 `screenshot.png`）
+
+返回 `{success, method, output, error}`。
+
+## 集成路径
+
+**Dbg 取证**：Dbg 在 `confirm_symptoms` 步骤调 xdb 获取截图证据：
+```bash
+python scripts/airplan.py --mode xdb --project . --prefer auto --output debug-screenshot.png
+```
+
+**Do Worker GUI 任务验证**：涉及 GUI/UI/Render 的任务，finish 前必须有截图证据。Worker 调 xdb 采集后，将截图路径写入 result.json 的 validations 字段。
+
+**证据门控**：`EvidenceGatePolicy` 检测到任务含 GUI 关键词时，自动要求 xdb 截图证据。