docs: 新增 tracked 任务跟踪模式设计文档

docs/superpowers/specs/2026-06-10-tracked-task-design.md

@@ -0,0 +1,115 @@
+# 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 分支处理      |
+| 对应测试文件              | 修改/新增 | 覆盖所有新增逻辑                             |