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/AirPlan-Para_V1.0.0_CTO版_参考.md

@@ -0,0 +1,215 @@
+# AirPlan-Para V1.0.0：面向 CTO 与架构负责人的 AI 工程治理参考稿
+
+## 一句话定位
+
+AirPlan-Para V1.0.0 是一套面向 Claude Code / Codex 本地工作流的 AI 工程治理框架。它已经把规划、调度、执行、调试、GUI 证据、网络证据、静态分析和长会话恢复固化为本地插件体系，用来解决 AI 辅助开发在真实项目中的稳定性和可追溯性问题。其中 aireng 作为公共调度层，多数时候处于非占用状态，开发者可以随时介入交流、补充约束或更正方向；同时支持并行派发多个隔离 worker，将串行等待变为并发推进，大幅压缩交付周期。
+
+## 它解决的不是“能不能写代码”，而是“能不能稳定交付”
+
+多数 coding agent 的问题不在于完全不会改代码，而在于工程行为不稳定：
+
+- 新会话无法稳定继承历史上下文
+- 任务状态只存在聊天记录中，无法断点续作
+- 规划、执行、调试之间缺少统一的工作流契约
+- GUI 验证容易把进程存活误判为通过
+- 网络问题缺少 packet-level evidence
+- C/C++ 项目缺少静态分析质量门
+- 长会话 compact 后上下文语义容易漂移
+- 多个子任务并行时容易出现上下文串扰或结果文件误读
+- 调度过程像一个黑盒，开发者难以在任务执行中即时介入调整方向
+- 串行执行模式下，独立子任务无法并发推进，整体交付周期被线性拉长
+
+AirPlan-Para 当前版本的价值，在于把这些问题分别落到明确的插件职责、项目文件和运行时状态里。
+
+## 当前版本的真实套件边界
+
+AirPlan-Para 当前是 **8 插件** 体系：
+
+- `airarc 0.3.1`
+- `aireng 0.6.0`
+- `airdo 0.5.0`
+- `airdbg 0.1.4`
+- `airxdb 0.2.2`
+- `airndb 0.1.2`
+- `airsdb 0.1.1`
+- `aircontext 0.1.0`
+
+其中：
+
+- 前 7 个插件构成围绕 `AirPlan/` 工作流根的规划-调度-执行-调试-证据链
+- `aircontext` 负责同一套件中的上下文压缩与自动恢复层
+
+## 当前版本已经实现的核心能力
+
+### 1. 结构化项目上下文
+
+系统围绕 `AirPlan/` 工作流根运行，并维护以下关键资产：
+
+- `AirPlan/AGENTS.md`
+- `AirPlan/plan.md`
+- `AirPlan/todo.md`
+- `AirPlan/docs/architecture/adr/`
+- `AirPlan/docs/architecture/c4/module.md`
+- `AirPlan/docs/debug/debug-log.md`
+- `AirPlan/docs/debug/gui-debug-log.md`
+- `AirPlan/docs/network/airndb-log.md`
+- `AirPlan/docs/staticanalysis.md`
+- `AirPlan/state/`
+- `AirPlan/AirContext/`
+
+其中 `airarc` 与 `aireng` 已经支持首次启动时自动补齐缺失的 `AirPlan/` bootstrap 工件；`aircontext` 则在需要时维护 `AirPlan/AirContext/` 中的压缩规则、状态与 snapshots。
+
+### 2. 规划与并发评审
+
+`airarc` 当前已经实现：
+
+- architecture-first planning
+- `plan.md` / `todo.md` 驱动的执行协议输出
+- post-plan parallel review
+- dependency edges、parallel groups、shared write-set conflicts、serialization points 输出
+- 供调度层优先读取的 execution plan 工件
+
+### 3. 受控调度与结果合并
+
+`aireng` 是整个套件的公共调度层，其设计有两个关键优势，直接区别于常见的单线程 agent 执行模式：
+
+**随时可介入的调度层。** `aireng` 在派发 worker 后多数时候处于非占用状态——它不需要像 worker 一样持续消耗上下文窗口去执行具体任务。这意味着开发者在任务执行期间可以随时与 aireng 交流：补充遗漏信息、调整执行约束、重新排定优先级，或是在发现方向偏差时立即介入更正。调度不是一个黑盒，而是一个开放的协作节点。
+
+**并行推进替代串行等待。** `aireng` 按 bounded concurrency 策略将独立子任务并行派发给多个隔离的 `airdo` worker。不再是“做完一个再看下一个”，而是同一波次内多个 worker 并发执行，互不阻塞。对于有多个独立模块、多组件并行开发的项目，这种模式大幅压缩了端到端交付时间。
+
+在此基础上，`aireng` 当前已经实现：
+
+- 读取 `airarc` execution artifacts
+- 生成 dispatch manifest
+- 按 bounded concurrency 调度多个隔离 `airdo` worker
+- 使用任务级 handoff 保持上下文隔离
+- 合并结构化 worker result
+- 自动准备 repair dispatch，并维护 repair queue
+- 在 merge 过程中同步 `plan.md`、`todo.md`、ADR 和 C4 文档
+
+同时，`aireng` 已经明确使用 `worker-state.json` 中的 `resultPath` 作为 canonical finalized result locator，避免把任务目录里的模板 `result.json` 误当成最终结果。
+
+### 4. 单任务执行与 finalize 完整性保护
+
+`airdo` 当前已经实现：
+
+- 单任务 scoped execution
+- task-local brief 与 subagent handoff
+- 结构化 `result.json`
+- finalize 后写入 `AirPlan/state/airdo/results/<task-id>.json`
+- `worker-state.json` 记录 canonical result path
+- GUI 任务自动衔接 `airxdb`
+- blocked 或 failed validation 自动衔接 `airdbg`
+- active repair brief 下继续执行而不是停在中间状态
+
+当前运行时还带有 finalize guard：
+
+- untouched 默认模板不能直接 finalize
+- `done` 结果不能是逻辑空载荷
+- `done` 结果至少要带上变更、验证、证据或文档更新之一
+- 无真实 blocker 时，worker 默认继续执行到 finalize，而不是停在“准备实施”或泛化进度汇报
+
+### 5. Debug-first 维修闭环
+
+`airdbg` 当前已经实现 debug-first repair workflow：
+
+- reproduce -> evidence -> RCA -> minimal fix -> verification
+- GUI 相关问题必须引入 `airxdb` 或等效 GUI/屏幕证据
+- 网络问题可调用 `airndb`
+- C/C++ 静态分析问题可调用 `airsdb`
+- 持续维护 `AGENTS.md`、ADR、C4 module 和 `debug-log.md`
+
+### 6. GUI / 网络 / 静态分析证据层
+
+AirPlan-Para 当前已交付 3 个专门的证据插件：
+
+- `airxdb`
+  - Midscene-based GUI 调试
+  - 截图证据
+  - Computer MCP smoke test
+  - model-family gating
+  - 远程设备截图 helper
+  - Windows 截图资产修复
+
+- `airndb`
+  - bounded local / remote tcpdump or WinDump capture
+  - Windows 首次启动自动下载官方 WinDump.exe
+  - BPF filters
+  - pcap 读取与摘要
+  - 远程 SSH 抓包辅助
+
+- `airsdb`
+  - 本机与远程 cppcheck
+  - `--check-level=exhaustive`
+  - XML / JSON 报告
+  - `staticanalysis.md` AI-readable 摘要
+
+### 7. 长会话压缩与自动恢复层
+
+`aircontext` 当前实现的是同一套件里的 session continuity layer：
+
+- 通过 `aircontext` wrapper 启动 Claude Code
+- 在 `SessionStart`、`UserPromptSubmit`、`PostToolUse`、`PreCompact` 上接入 hook
+- 基于阈值和冷却时间决定何时 compact
+- 调用外部 OpenAI-compatible LLM 按规则压缩当前活跃链
+- 把摘要与 continuation prompt 写回 session JSONL
+- 自动执行 `claude --resume <session-id>` 继续长任务
+- 在项目内维护 `AirPlan/AirContext/`
+
+## 管理层视角的价值
+
+从 CTO 或架构负责人角度看，AirPlan-Para 的价值不在“多一个插件”，而在于它已经把 AI 工程中的关键风险做了制度化约束：
+
+- 用项目文件代替临时聊天上下文
+- 用规划工件约束后续调度
+- 用隔离 worker 替代大上下文单线程执行
+- 用结构化 result 和 worker-state 约束交付结果
+- 用 GUI / 网络 / 静态分析证据降低误判
+- 用 session compaction policy 降低长会话语义漂移
+- 用 repair queue 和可恢复状态提升中断后的连续性
+- 用非占用式调度层保持开发者对执行过程的可见性与即时应变能力
+- 用隔离并行执行替代串行等待，以并发换交付速度
+
+## 当前交付清单
+
+### 插件清单（8 个）
+
+- `airarc 0.3.1`
+- `aireng 0.6.0`
+- `airdo 0.5.0`
+- `airdbg 0.1.4`
+- `airxdb 0.2.2`
+- `airndb 0.1.2`
+- `airsdb 0.1.1`
+- `aircontext 0.1.0`
+
+### 部署入口
+
+- `AirPlan-Para.zip`
+- `install_to_home.ps1`
+- `install_to_home.cmd`
+- `init_project_airplan.ps1`
+
+## 边界说明
+
+当前插件体系已经明确支持：
+
+- 多会话上下文恢复
+- 任务级 SubAgent 隔离执行
+- 受控并发调度
+- GUI / 网络 / C/C++ 证据驱动验证
+- 调试与修复闭环
+- 规则驱动 compact 与自动 resume
+
+当前插件体系不应被宣传为：
+
+- 容器级 runtime sandbox
+- 完整的企业 SaaS 平台
+- 面向多个账号的 broker / relay 调度系统
+- 已实现的 file lock / document lock runtime
+
+## 结论
+
+AirPlan-Para V1.0.0 已经不是“若干 AI 插件的集合”，而是一套具备规划、调度、执行、调试、证据和恢复能力的本地 AI 工程治理框架。其中 aireng 的独特价值在于：既通过并行调度把交付效率从串行约束中释放出来，又以非占用式的设计让开发者始终可以介入协作——调度不是黑盒，效率不以失控为代价。
+
+它解决的核心问题，不是让 AI 开始写代码，而是让 AI 在真实项目里更稳定、更快速、更可协作地持续交付。