From 9ad232af380c9ecfa229a65e99c2889e08ac1fd6 Mon Sep 17 00:00:00 2001
From: AirLongDian <airlongdian@airlongdian.fun>
Date: Thu, 11 Jun 2026 15:57:12 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=85=A8=E9=83=A8=2012=20=E4=B8=AA?=
 =?UTF-8?q?=E5=91=BD=E4=BB=A4=E6=96=87=E4=BB=B6=E5=AE=8C=E6=95=B4=E5=8C=96?=
 =?UTF-8?q?=20=E2=80=94=20=E6=B6=88=E9=99=A4=20P0/P1=20=E6=93=8D=E4=BD=9C?=
 =?UTF-8?q?=E6=AD=A7=E4=B9=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

P0: 9 个存根命令文件从 11 行模板扩展为完整操作文档
- dbg: 7 步工作流表格 + 证据类型 + 子命令 + Dbg↔Do 集成路径
- ctx: 三级降级压缩 + 质量校验 + Token 估算 + 陈旧锁清理
- dep: SSH 部署流程 + MD5 校验 + systemd 管理
- tst: 5 种测试框架 + run 命令 + T-TEST 集成
- sec: advisory/blocking 双模式 + 文件/目录/Woker result 三种扫描
- rvr: 审查模式 + highRiskAudit + code-to-design + Eng merge 集成
- sdb: 6 种后端 + diff 模式 + Dbg 取证集成
- ndb: 网络抓包 + Dbg 取证集成
- xdb: kmsgrab/xvfb/fallback 三后端 + Dbg/Do GUI 验证集成

P1: 3 个有内容文件的歧义修复
- do: AirDbg 路由具体命令 + 证据采集（xdb/ndb/sdb/tst）命令
- arc: 三阶段→命令映射表 + phase 推进方式
- eng: monitor 轮询循环伪代码（Agent 无时钟概念，必须循环调 monitor）

全部命令统一使用 `python scripts/airplan.py` 路径（清除旧 $HOME/plugins 引用）

63 项功能测试全通过

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 commands/arc.md | 20 ++++++++---
 commands/ctx.md | 62 +++++++++++++++++++++++++++++++---
 commands/dbg.md | 60 ++++++++++++++++++++++++++++++---
 commands/dep.md | 42 ++++++++++++++++++++---
 commands/do.md  | 90 ++++++++++++++++++++++++++++++++-----------------
 commands/eng.md | 29 ++++++++++++++--
 commands/ndb.md | 28 ++++++++++++---
 commands/rvr.md | 50 ++++++++++++++++++++++++---
 commands/sdb.md | 46 ++++++++++++++++++++++---
 commands/sec.md | 54 ++++++++++++++++++++++++++---
 commands/tst.md | 50 ++++++++++++++++++++++++---
 commands/xdb.md | 40 +++++++++++++++++++---
 12 files changed, 499 insertions(+), 72 deletions(-)

diff --git a/commands/arc.md b/commands/arc.md
index e5b86b1..cb08848 100644
--- a/commands/arc.md
+++ b/commands/arc.md
@@ -23,27 +23,39 @@ AirArc is a pure architecture planner. It analyzes dependencies, write-set confl
 ### enter
 
 ```bash
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode arc --project . --sub enter
+python scripts/airplan.py --mode arc --project . --sub enter
 ```
 
 ### status
 
 ```bash
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode arc --project . --sub status
+python scripts/airplan.py --mode arc --project . --sub status
 ```
 
 ### parallel-review
 
 ```bash
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode arc --project . --sub parallel-review --todo AirPlan/todo.md
+python scripts/airplan.py --mode arc --project . --sub parallel-review --todo AirPlan/todo.md
 ```
 
 ### incremental-replan
 
 ```bash
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode arc --project . --sub incremental-replan --todo AirPlan/todo.md
+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()` 自动推进。不丢失（已修复）。
+
 ## 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.
\ No newline at end of file
diff --git a/commands/ctx.md b/commands/ctx.md
index 17a19f2..f166c0a 100644
--- a/commands/ctx.md
+++ b/commands/ctx.md
@@ -1,11 +1,65 @@
 ---
-description: "AirPlan ctx mode"
-argument-hint: "[enter|status|...]"
+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
 
-Run AirPlan ctx mode.
+AirContext 管理上下文压缩、Token 估算、陈旧锁检测。三级降级压缩策略：重试 → 换模型 → 截断。
 
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode ctx --project . [OPTIONS]
+## 硬规则
+
+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` 精简上下文。
diff --git a/commands/dbg.md b/commands/dbg.md
index ed669e6..6d6f19c 100644
--- a/commands/dbg.md
+++ b/commands/dbg.md
@@ -1,11 +1,63 @@
 ---
-description: "AirPlan dbg mode"
-argument-hint: "[enter|status|...]"
+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
 
-Run AirPlan dbg mode.
+AirDbg 是调试器，强制 7 步证据先于修复流程。EvidenceFirstGate 硬门控——未取证不可改代码（INV-9）。
 
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode dbg --project . [OPTIONS]
+## 硬规则
+
+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
+```
diff --git a/commands/dep.md b/commands/dep.md
index 75bb3f7..e7d284b 100644
--- a/commands/dep.md
+++ b/commands/dep.md
@@ -1,11 +1,45 @@
 ---
-description: "AirPlan dep mode"
-argument-hint: "[enter|status|...]"
+description: "AirPlan dep mode - SSH remote build + deploy + systemd management"
+argument-hint: "[deploy|status]"
 allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
 ---
 
 # /dep
 
-Run AirPlan dep mode.
+AirDep 是部署器。SSH 远程构建 → 二进制传输（scp + MD5 校验）→ systemd 生命周期管理 → 部署验证。
 
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode dep --project . [OPTIONS]
+## 硬规则
+
+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>
+```
diff --git a/commands/do.md b/commands/do.md
index eb134da..4e40638 100644
--- a/commands/do.md
+++ b/commands/do.md
@@ -1,54 +1,84 @@
 ---
-description: "AirPlan do mode - task executor with UI skill routing"
+description: "AirPlan do mode - task executor with UI skill routing and evidence gate"
 argument-hint: "[enter|status|finish]"
 allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
 ---
 
 # /do
 
-AirDo is the task executor. It runs individual tasks, enforces routing rules, and integrates with other AirPlan modes.
+AirDo 是任务执行器。运行单个任务，强制执行路由规则，集成其他 AirPlan 模式。
 
-## Hard Rules
+## 硬规则
 
-1. **UI Task Handling (P1-20)** — When task involves UI/frontend/interface design:
-   - Must detect UI tasks via keyword matching (gui, ui, render, widget, frontend, react, vue, etc.)
-   - Must ensure frontend-design Skill is available before executing UI code
-   - If frontend-design Skill is not installed, block the task
-   - Use `ensure_frontend_design_skill()` and `route_ui_task()` functions
+1. **UI Task Handling (P1-20)** — 当任务涉及 UI/前端/界面时，检测并确保 frontend-design Skill 可用。不可用时阻止执行
+2. **Evidence Gate (INV-4)** — GUI 任务需截图，网络任务需抓包，代码任务需静态分析/测试
+3. **Force AirDbg Routing** — done 无证据 → airdbg；blocked/failed → airdbg
 
-2. **Evidence Gate (INV-4)** — Tasks with GUI/network indicators must have corresponding evidence before finishing:
-   - GUI tasks require screenshot/validation evidence
-   - Network tasks require packet capture/connectivity evidence
-   - Code tasks require static analysis/test results
+## 子命令
 
-3. **Force AirDbg Routing (INV-4)** — If task finishes without evidence, force route to AirDbg:
-   - `done` status + no validations/files_changed → route to airdbg
-   - `blocked`/`failed` status → always route to airdbg
-
-## Sub-commands
-
-### enter
+### enter — 进入 Worker
 
 ```bash
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode do --project . --sub enter --task-id T-001 --task-text "实现登录界面UI"
+python scripts/airplan.py --mode do --project . --sub enter --task-id T-001 --task-text "实现登录界面UI"
 ```
 
-### status
+参数：
+- `--task-id`：任务 ID（必须）
+- `--task-text`：任务描述文本（用于 UI 检测和路由，必须）
+
+创建 `AirPlan/state/airdo/tasks/{task_id}/worker-state.json`。返回 `{taskId, briefPath, resultPath, workerStatePath, uiRouting}`。
+
+### status — 查看 Worker 状态
 
 ```bash
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode do --project . --sub status
+python scripts/airplan.py --mode do --project . --sub status
 ```
 
-### finish
+### finish — 完成 Worker（含路由决策）
 
 ```bash
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode do --project . --sub finish --task-id T-001 --result /path/to/result.json
+python scripts/airplan.py --mode do --project . --sub finish --task-id T-001 --result AirPlan/state/airdo/tasks/T-001/result.json
 ```
 
-## UI Task Detection Keywords
+finish 执行强制路由：
+- `done` + 有 validations/filesChanged → route to `merge`
+- `done` + 无 evidence → forced route to `airdbg`
+- `blocked`/`failed` → forced route to `airdbg`
 
-UI task detection uses these keywords (case-insensitive):
-- gui, ui, render, layout, dialog, osd, overlay, visual
-- widget, pane, toolbar, settings_dialog, canvas, button
-- window, popup, menu, drm, kms, opengl, vulkan
-- frontend, react, vue, angular, web, css, html
\ No newline at end of file
+## AirDbg 路由 — 具体操作
+
+当 finish 返回 `routingDecision.target = "airdbg"` 时，**必须**调 dbg 模式：
+
+```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
+```
+
+## 证据采集 — GUI/Network 任务
+
+**GUI 任务**（涉及 gui/ui/render/widget/dialog 等关键词）— 需要截图：
+```bash
+python scripts/airplan.py --mode xdb --project . --prefer auto --output task-{tid}-screenshot.png
+```
+截图路径写入 result.json 的 validations 字段。
+
+**网络任务**（涉及 network/rtsp/http/tcp 等关键词）— 需要抓包：
+```bash
+python scripts/airplan.py --mode ndb --project . --sub enter
+# 然后 tcpdump/tshark 抓包，存入 AirPlan/state/airndb/captures/
+```
+
+**代码任务** — 需要静态分析或测试：
+```bash
+python scripts/airplan.py --mode sdb --project . --backend cppcheck --target ./src
+# 或
+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, 界面, 按钮, 对话框, 窗口, 菜单, 控件, 渲染, 布局
diff --git a/commands/eng.md b/commands/eng.md
index af3e3fd..6a87ccf 100644
--- a/commands/eng.md
+++ b/commands/eng.md
@@ -100,11 +100,36 @@ dispatch 返回 `{waveId, taskIds, dispatchPath}`。**然后按以下步骤操
 
 ### monitor
 
+spawn Worker 之后**必须进入轮询循环**。CLI 的 `monitor_engine()` 只执行一次检测——你需要循环调用它。
+
 ```bash
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode eng --project . --sub monitor
+python scripts/airplan.py --mode eng --project . --sub monitor
 ```
 
-合并就绪结果，检测停滞 Worker，更新 nextAction。
+monitor 返回 `{activeWorkerCount, readyToMergeCount, stalledCount, interventionCount, nextAction}`。
+
+**轮询循环（伪代码，每轮执行）**：
+```
+while 有活跃 Worker (activeWorkerCount > 0):
+  1. 等待 60-300 秒（根据 Worker 阶段自适应）
+  2. 运行 monitor 命令
+  3. 如果 readyToMergeCount > 0:
+     a. 找到完成的 Worker（读 state.json activeWorkers 中 status=done 的）
+     b. 对每个完成的 Worker 运行 merge 命令
+  4. 如果 stalledCount > 0:
+     a. 检查 interventions 列表
+     b. action="upgraded-to-airdbg" → 启动 Dbg 会话
+     c. action="terminate-and-block" → 标记任务 blocked
+  5. 如果 activeWorkerCount == 0:
+     退出循环，检查是否需要下一波 dispatch
+```
+
+**停滞检测逻辑**（代码自动执行，Agent 只需读结果）：
+- Worker state 文件 mtime > 5 分钟未更新 → 标记 stalled
+- Worker 存活时间 > 2 小时 → 标记 wall-time-exceeded
+- 资源压力（loadavg > 2× CPU 数）→ 暂停派发
+
+**注意**：Agent 没有内置时钟——你必须主动循环调用 monitor，不能等。
 
 ### merge
 
diff --git a/commands/ndb.md b/commands/ndb.md
index 11e89aa..6049666 100644
--- a/commands/ndb.md
+++ b/commands/ndb.md
@@ -1,11 +1,31 @@
 ---
-description: "AirPlan ndb mode"
-argument-hint: "[enter|status|...]"
+description: "AirPlan ndb mode - network debugger for packet capture and analysis"
+argument-hint: "[enter|status]"
 allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
 ---
 
 # /ndb
 
-Run AirPlan ndb mode.
+AirNDB 是网络调试器。抓包分析、TLS 解密、pcapng 支持。
 
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode ndb --project . [OPTIONS]
+## 子命令
+
+### 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 的任务需要抓包证据。
diff --git a/commands/rvr.md b/commands/rvr.md
index 0267a2a..c5a05c0 100644
--- a/commands/rvr.md
+++ b/commands/rvr.md
@@ -1,11 +1,53 @@
 ---
-description: "AirPlan rvr mode"
-argument-hint: "[enter|status|...]"
+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
 
-Run AirPlan rvr mode.
+AirRvr 是需求审查器。基于原始需求文档对已完成任务进行独立审查，验证交付物与需求的一致性。含 highRiskAudit（生命周期/空指针/悬垂指针/异常安全/并发）和 Code-to-Design 逐行对照。
 
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode rvr --project . [OPTIONS]
+## 硬规则
+
+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()` 验证旧代码已清理。
diff --git a/commands/sdb.md b/commands/sdb.md
index 1f4c906..2a21fc4 100644
--- a/commands/sdb.md
+++ b/commands/sdb.md
@@ -1,11 +1,49 @@
 ---
-description: "AirPlan sdb mode"
-argument-hint: "[enter|status|...]"
+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
 
-Run AirPlan sdb mode.
+AirSDB 是多语言静态分析器。支持六种后端和 diff 模式。
 
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode sdb --project . [OPTIONS]
+## 支持的后端
+
+| 后端 | --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 验证代码质量。
diff --git a/commands/sec.md b/commands/sec.md
index 50f54e2..c7d2616 100644
--- a/commands/sec.md
+++ b/commands/sec.md
@@ -1,11 +1,57 @@
 ---
-description: "AirPlan sec mode"
-argument-hint: "[enter|status|...]"
+description: "AirPlan sec mode - security scanner for sensitive data detection"
+argument-hint: "[scan|status]"
 allowed-tools: "[Read, Glob, Grep, Bash, Write, Edit]"
 ---
 
 # /sec
 
-Run AirPlan sec mode.
+AirSec 是安全扫描器。扫描制品中的敏感数据（API 密钥、令牌、密码），支持 advisory（只报告）和 blocking（阻止合并）两种模式。
 
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode sec --project . [OPTIONS]
+## 两种扫描模式
+
+| 模式 | --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` 时阻止合并。
diff --git a/commands/tst.md b/commands/tst.md
index 79a549d..2a7a1b1 100644
--- a/commands/tst.md
+++ b/commands/tst.md
@@ -1,11 +1,53 @@
 ---
-description: "AirPlan tst mode"
-argument-hint: "[enter|status|...]"
+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
 
-Run AirPlan tst mode.
+AirTst 是测试运行器。支持多框架统一执行和结构化结果报告。
 
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode tst --project . [OPTIONS]
+## 支持的框架
+
+| 框架 | --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}
+```
diff --git a/commands/xdb.md b/commands/xdb.md
index 7e3b763..b8535cb 100644
--- a/commands/xdb.md
+++ b/commands/xdb.md
@@ -1,11 +1,43 @@
 ---
-description: "AirPlan xdb mode"
-argument-hint: "[enter|status|...]"
+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
 
-Run AirPlan xdb mode.
+AirXDB 是 GUI 验证器。支持 DRM/KMS 原生截图（kmsgrab）、Xvfb headless 截图、多后端自动降级。
 
-python "$HOME/plugins/airplan/scripts/airplan.py" --mode xdb --project . [OPTIONS]
+## 截图后端
+
+| 后端 | --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 截图证据。