## Detection Wave 编排策略

> 本文件定义缺陷检测阶段的编排流程——主任务如何调度子任务、子任务的执行模板、输入/输出契约。

### 主任务职责（Orchestrator）

#### 1. 恢复上下文

1. 读取 `<输出目录>/.draft-01-change-analysis.md`（扫描文件列表 + 项目环境）
2. 创建 `<输出目录>/.draft-02-detection/` 目录
3. 写入 `<输出目录>/.draft-02-detection/manifest.json` 初始版本：
```json
{
  "version": 1,
  "stage": "detection",
  "status": "in_progress",
  "scan_mode": "<branch|file|directory>",
  "source_branch": "<source_branch>",
  "target_branch": "<target_branch>",
  "files": [],
  "skipped_files": [],
  "defects": [
    {
      "id": "D001",
      "severity": "高/中/低",
      "type": "静态缺陷/安全漏洞/逻辑缺陷/内存问题",
      "title": "缺陷标题",
      "file": "原始文件路径",
      "location": "文件路径:起始行号-结束行号",
      "source_file": "展平后的 per-file output 文件名（路径 / 替换为 -）",
      "detection_types": ["匹配到的检测类型"]
    }
  ],
  "summary": {
    "total_files": 0,
    "completed_files": 0,
    "total_defects": 0,
    "by_type": {},
    "by_severity": {}
  }
}
```

#### 2. 排除无需扫描的文件

对 `.draft-01-change-analysis.md` 中的扫描文件列表，排除以下类型的文件：
- 纯配置文件（JSON、YAML、TOML、.env）
- 纯样式文件（CSS、SCSS、LESS）
- 纯静态资源（图片、字体）

将排除的文件及原因记录到 `manifest.json` 的 `files` 数组（`status: "skipped"`）。

#### 3. 逐文件调度

对 `.draft-01-change-analysis.md` 中每个需要检测的文件，按顺序执行：

##### 3.1 基于触发信号的检测类型分配

对每个文件，主任务先读取文件内容，匹配触发信号，精确确定检测类型：

1. **读取文件**：`Read` 获取文件内容（文件扫描模式下读取指定行范围）
2. **匹配触发信号**：依次读取以下 routing.md，匹配代码特征：
   - `<skill-root>/references/detection/static-defects/routing.md`
   - `<skill-root>/references/detection/security-vulnerabilities/routing.md`
   - `<skill-root>/references/detection/logical-defects/routing.md`
   - `<skill-root>/references/detection/memory-issues/routing.md`
3. **确定检测类型**：将匹配到的触发信号对应的检测类型作为该文件的检测分配
4. **记录分配结果**：将文件路径和分配的检测类型记录到 `manifest.json` 的 `files` 数组

##### 3.2 拉起子任务

根据分配的检测类型，拉起 Agent 子任务，传入**子任务执行模板**（见下方）并填充以下变量：
   - `<file-path>`：文件路径
   - `<detection_types>`：由 3.1 触发信号匹配确定的检测类型列表
   - `<project_env>`：从 `.draft-01-change-analysis.md` 提取的项目环境信息
   - `<output_dir>`：输出目录路径
   - `<skill-root>`：技能根路径
3. 等待子任务完成
4. 更新 `manifest.json` 的 `files` 数组（添加该文件条目，设置 `status: "completed"`）
5. 更新 TodoWrite

#### 4. 汇总

所有文件检测完成后：

1. 读取 `.draft-02-detection/` 目录下所有输出文件
2. 按文件顺序，从每个 per-file output 中按序号提取缺陷
3. 为每个缺陷分配全局唯一 ID（D001, D002, ...），构造 defect 对象：
   - `id`：D-series ID
   - `severity`、`type`、`title`：从 per-file output 的检测结果表中提取
   - `file`：原始文件路径
   - `location`：从检测结果表中提取（如 `file:15-18`）
   - `source_file`：当前 per-file output 的展平文件名（路径 `/` 替换为 `-`，加 `.md` 后缀）
   - `detection_types`：该文件分配的检测类型列表
4. 将所有 defect 对象写入 `manifest.json` 的 `defects` 数组
5. 统计 `summary`（by_type, by_severity）
6. 设置 `manifest.json` 的 `status: "completed"`

### 子任务执行模板

---

## 角色
你是一个代码缺陷检测专家。

## 输入
- **文件路径**：`<file-path>`
- **检测类型**：<detection_types>
- **项目环境**：<project_env>

## 执行步骤

**⚠️ 必须使用 TodoWrite 工具组织执行流程**

### 步骤 1：数据流分析

1. 读取 `<skill-root>/references/tools/lsp.md` 获取 LSP 工具使用策略
2. 读取文件 `<file-path>`
3. 识别数据输入源（API参数、数据库查询、外部调用）
4. 追踪关键数据流向（**最多向上/向下5层调用**）
5. 识别敏感操作点（数据库写入、权限检查、状态变更）
6. 使用 LSP 工具辅助分析：`find_definition` 验证符号定义、`find_references` 追踪数据流

### 步骤 2：缺陷检测

对每个已分配的检测类型，逐个执行：
   - **static-defects**（如已分配）：读取 `<skill-root>/references/detection/static-defects/routing.md`，匹配触发信号，加载对应子文件，按子文件检测规范执行
   - **security-vulnerabilities**（如已分配）：读取 `<skill-root>/references/detection/security-vulnerabilities/routing.md`，匹配触发信号，加载对应子文件，按子文件检测规范执行
   - **logical-defects**（如已分配）：读取 `<skill-root>/references/detection/logical-defects/routing.md`，匹配触发信号，加载对应子文件，按子文件检测规范执行
   - **memory-issues**（如已分配）：读取 `<skill-root>/references/detection/memory-issues/routing.md`，匹配触发信号，加载对应子文件，按子文件检测规范执行

## 输出格式

写入 `<output_dir>/.draft-02-detection/<flattened-path>.md`（`<flattened-path>` 将原始文件路径中的 `/` 替换为 `-`，如 `src/utils/helper.ts` → `src-utils-helper.ts.md`）：

```
### <文件路径>

#### 数据流分析
- **检测类型**：安全漏洞 / 逻辑缺陷
- **数据输入源**：...
- **数据流向**：...
- **敏感操作点**：...

#### 检测结果

| 序号 | 严重程度 | 缺陷类型 | 问题代码位置 | 缺陷标题 |
|------|---------|---------|-------------|---------|
| 1 | 高 | 安全漏洞 | `file:line-line` | 简要标题 |

**[1] 简要标题**
- **分析**：问题根因和触发条件
- **影响**：业务影响和破坏方式
- **问题代码**：
```代码语言
问题代码片段
```
- **修复代码**：
```代码语言
修复代码片段（可选）
```
- **证据链**：
```mermaid
graph LR
    A["源代码位置1<br>file:line"] -->|"数据流/调用关系"| B["源代码位置2<br>file:line"]
    B -->|"数据流/调用关系"| C["危险操作<br>file:line"]
```

安全漏洞证据链模式：Source（用户输入） → Propagation（数据传递） → Sink（危险操作）
静态缺陷证据链模式：声明 → 使用 → 错误点
逻辑缺陷证据链模式：业务操作 → 状态变更 → 约束违反
内存问题证据链模式：分配 → 使用 → 释放（或缺失）
```

如某个检测类型无触发信号匹配或无发现，该部分输出"无发现"即可。
