cmshoppe/docs/tasks/README.md

# 任务文件（一任务一文件）

> 目的：多个 agent 并发时，避免所有人抢改同一个 `../06-tasks.md`——单大文件 + 多写者会导致「读到旧版本」的编辑冲突和 ID 撞号（本项目已实际发生）。
> 约定：**新任务一律一个文件放这里 `docs/tasks/T-<编号>.md`；不再往 `../06-tasks.md` 加新任务**（它已冻结为历史归档，保留 T-000~T-549）。

## 为什么这样

一任务一文件后：改哪个任务只动哪个文件，agent 之间互不抢占；ID 撞号在**新建文件时当场暴露**（文件已存在就换号），不像往大表塞行、撞了也不知道。

## 文件命名与 ID（方案 1：连续编号）

- 文件名：`docs/tasks/T-<编号>.md`，如 `docs/tasks/T-550.md`；同族细分用后缀 `T-550a.md`。
- 分配下一个 ID：取「`../06-tasks.md` 归档 + `docs/tasks/` 现有文件」里最大的 `T-###`，`+1`。
- **建文件即防撞**：若 `T-550.md` 已存在（别的 agent 先建了），直接改用下一个号（`T-551`），**不要覆盖别人的文件**。
- 模板 `_template.md` 以下划线开头，不是真实任务、不参与编号扫描。

## 每个任务文件的结构（frontmatter + 正文）

```markdown
---
id: T-550
title: 一句话任务名
phase: 7               # 所属阶段，沿用 06-tasks.md 的 Phase 编号
deps: [T-546, T-538]   # 依赖的任务 ID（跨归档/新结构都用完整 ID 引用）
status: TODO           # TODO | DOING | DONE | BLOCKED
created: 2026-07-08
---

## 问题 / 背景
...

## 方案
...

## 验收要点
...

## 边界（不改什么）
...
```

## 状态与领取流程（同 `../06-tasks.md`「使用规则」）

- 状态：`TODO` · `DOING`（同一时间最多 1 个）· `DONE` · `BLOCKED`。
- 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；做完自测、改 `status: DONE`。
- **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——**不再逐任务追加 `../../progress.md`、不再逐任务覆盖 `../current-state.md`**（那两个是每任务共享写入点，多 agent 会抢/覆盖；`progress.md` 已冻结归档，`current-state.md` 不再手动逐任务维护、当前状态以各任务 frontmatter 为准）。
- **只改自己那个任务文件**；不要编辑别人正在做的任务文件。

## 看板视图

- 现阶段：`ls docs/tasks/` + 看各文件 frontmatter 的 `status`/`deps` 挑任务。
- （可选，后续）加一个脚本把所有任务文件汇总成一张看板表，agent 不手改看板。

## 历史归档

- `docs/06-tasks.md` = T-000~T-549 的历史归档，**冻结、不再新增**；只有历史任务需要订正状态时才动它，新任务不进去。