# task.md 任务跟踪（tracked 模式）设计

## 背景

当前 build 阶段始终读取 task.md 进行任务跟踪，archive 阶段也始终检查 task.md 完成状态。但用户可能不需要任务跟踪流程（例如自定义配置中不含 task 文档），此时 build/archive 强依赖 task.md 是不合理的。

需要一种机制让用户控制是否启用任务跟踪，同时保持内置默认配置的现有行为。

## 方案

在 `metadata` 配置下新增 `tracked: boolean` 字段，控制 plan/build/archive 三阶段的任务跟踪行为。

## 配置变更

### metadata.tracked

```yaml
metadata:
  command: "bunx @lanyuanxiaoyao/rune"
  tracked: true
```

- 类型：`boolean`，可选，不配置时默认 `false`
- 内置默认配置中 `tracked: true`（因为内置 plan 包含 task 文档）
- 放在 `metadata` 而非 `build` 阶段内，因为它影响 plan/build/archive 三阶段

### 类型变更

```typescript
// types.ts
interface RuneConfig {
  stages: StagesConfig;
  metadata?: {
    command?: string;
    tracked?: boolean; // 新增
  };
}
```

`BuildStage` 类型不变，不新增字段。

## 各阶段行为变更

### plan 阶段（config.ts validateConfig）

当 `metadata.tracked === true` 时，校验 `plan.documents` 中必须包含 `name: "task"` 的文档。不包含则抛出 ConfigError：

```
配置错误：tracked 开启时 plan.documents 必须包含 name 为 "task" 的文档
```

当 `metadata.tracked !== true` 时，不进行此校验。

### build 阶段（assembler.ts assembleBuildPrompt）

**tracked === true：**

1. 读取 `task.md`，如不存在则抛出 CommandError（现有行为）
2. **新增格式校验**：调用 `validateTaskFormat`，不通过则抛出 CommandError
3. 解析任务列表，展示进度和待执行任务（现有行为）
4. 提示词末尾附加任务跟踪相关指令（现有行为）

**tracked === false：**

1. 不读取 task.md，不做格式校验
2. 只输出 `build.prompt` 通用提示词（经 applyCommandPrefix 处理）
3. 提示词中不包含任何任务跟踪相关内容

### archive 阶段（assembler.ts assembleArchivePrompt）

**tracked === true：** 现有行为不变——读 task.md，检查未完成项，注入警告。

**tracked === false：** 不读取 task.md，不注入未完成任务警告，只输出 `archive.prompt`（经 applyCommandPrefix 处理）。

## 格式校验规则

在 `task-parser.ts` 中新增 `validateTaskFormat` 函数：

```
校验条件：
1. 文件中至少有一个 checkbox 行（- [ ] 或 - [x]）
2. 每个 checkbox 的文本内容不能为空（即 - [ ] 后面必须有非空文本）

不通过时抛出 CommandError：
"变更 "<变更名>" 的 task.md 格式不符合要求：必须包含至少一个 checkbox 项，且每项必须有非空描述"
```

## 默认配置变更

`defaults/config.ts` 中新增：

```typescript
metadata: {
  tracked: true,
}
```

## 不变更的部分

- `BuildStage` 类型不变
- `scanner.ts` 的 `taskProgress` 逻辑不变（status 命令是查询行为，始终尝试读取 task.md 做信息展示，不受 tracked 开关影响）
- `task-parser.ts` 的 `parseTasks` 不变，新增 `validateTaskFormat` 函数
- `pm.ts` 不变
- `cli/` 目录下的错误类型和输出格式不变，复用现有 CommandError 和 ConfigError

## 影响范围

| 文件                      | 变更类型  | 说明                                         |
| ------------------------- | --------- | -------------------------------------------- |
| `src/types.ts`            | 修改      | metadata 新增 tracked 字段                   |
| `src/defaults/config.ts`  | 修改      | 默认配置新增 metadata.tracked: true          |
| `src/core/config.ts`      | 修改      | validateConfig 新增 tracked 时 task 文档校验 |
| `src/core/task-parser.ts` | 修改      | 新增 validateTaskFormat 函数                 |
| `src/core/assembler.ts`   | 修改      | build/archive 阶段根据 tracked 分支处理      |
| 对应测试文件              | 修改/新增 | 覆盖所有新增逻辑                             |