docs(tasks): make one-task-per-file the default task mode (H-409)

- docs/tasks/README.md: default mode for single and multi agent, drop switch narrative
- docs/06-tasks.md: demote to read-only roadmap (phases, milestones, backlog, suggested split list without status)
- progress.md: optional archive / project-level event log; execution records live in task files
- current-state.md: project-level snapshot; task status authoritative in task frontmatter
- sync all referencing docs (start-here, coding-rules, READMEs, adoption/clean-state checklists, method-map, evaluator-rubric)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/00-ai-start-here.md

@@ -17,10 +17,12 @@
 3. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型。
 4. [`04-architecture.md`](04-architecture.md)：系统结构、职责划分、数据模型和关键难点。
 5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。
-6. [`06-tasks.md`](06-tasks.md)：领取本轮唯一任务。
-7. [`../progress.md`](../progress.md)：历史执行记录、验证结果、阻塞点和关键决策。
+6. [`06-tasks.md`](06-tasks.md)：阶段路线图、里程碑和待办池。
+7. [`tasks/README.md`](tasks/README.md)：任务文件约定（一任务一文件）；本轮任务从 `docs/tasks/` 领取。
 8. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。
 
+`../progress.md` 为可选的历史归档 / 项目级大事记，仅在需要追溯早期历史时查阅。
+
 如果仓库根目录有 `AGENTS.md`、`CLAUDE.md` 或其他 agent 规则文件，也必须先读。仓库级规则优先于项目局部建议。
 
 ## 固定开工流程
@@ -28,12 +30,12 @@
 读完上述文档后，每轮会话按这个机械顺序进入，恢复持久状态再动手：
 
 1. `pwd`：确认在正确的仓库根目录。
-2. 读 [`../progress.md`](../progress.md) 和 [`current-state.md`](current-state.md)：恢复已验证状态、下一步和当前 blocker。
+2. 读 [`current-state.md`](current-state.md) 和 `docs/tasks/` 中 `status: DOING` 的任务文件：恢复已验证状态、下一步和当前 blocker。
 3. `git log --oneline -5`：看清最近发生了什么。
 4. 运行 `./init.sh`（Windows 原生 PowerShell 用 `./init.ps1`）：统一安装、验证、打印启动命令；如果脚本提示命令未替换，先配置脚本顶部三个命令。
 5. 跑一条基础 smoke / 端到端路径，确认基线没坏。
 6. **如果基线已坏，先修基线**，不要在坏的起点上叠新功能。
-7. 基线绿了，再从 [`06-tasks.md`](06-tasks.md) 领取唯一任务。
+7. 基线绿了，再从 `docs/tasks/` 领取唯一任务（路线图见 [`06-tasks.md`](06-tasks.md)）。
 
 ## 当前阶段
 
@@ -49,19 +51,20 @@
 
 ## 领取任务规则
 
-从 [`06-tasks.md`](06-tasks.md) 领取任务时：
+任务以「一任务一文件」存放在 `docs/tasks/`（约定见 [`tasks/README.md`](tasks/README.md)）：
 
-- 只领取第一个状态为 `TODO` 且依赖均为 `DONE` 的任务。
-- 开始前把该任务状态改为 `DOING`。
-- 本轮只完成这一个任务。
-- 验收通过后把状态改为 `DONE`。
-- 完成后把执行记录追加到 [`../progress.md`](../progress.md)，并覆盖更新 [`current-state.md`](current-state.md) 的当前快照。
+- 只领取一个 frontmatter `status: TODO` 且依赖均 `DONE` 的任务文件，取编号最靠前的。
+- 若 `docs/tasks/` 暂无可领任务，先按 [`06-tasks.md`](06-tasks.md) 路线图把下一个建议任务落成任务文件，再领取。
+- 开始前把该文件 frontmatter 的 `status` 改为 `DOING`（同一时间最多 1 个）。
+- 本轮只完成这一个任务；验收通过后改为 `DONE`。
+- **执行记录写进该任务文件的 `## 执行记录`**（改了什么、跑了什么验证、结果、决策）。
+- 若项目现实发生变化（启动/验证路径、目录结构、blocker），覆盖更新 [`current-state.md`](current-state.md)；任务状态以任务文件 frontmatter 为准，不逐任务改写快照。
 - 结束会话前过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)，确保下一轮无需人工修复即可开工。
 - 做完即停，汇报验证结果，等待下一步指令。
 
-> **多 agent / 并发协作**：若项目已切到一任务一文件（见 [`tasks/README.md`](tasks/README.md)），则从 `docs/tasks/` 领取任务文件、状态改在 frontmatter、**执行记录写进该任务文件的 `## 执行记录`**，不再逐任务追加 `progress.md`/覆盖 `current-state.md`（避免多写者抢占共享文件）。
+> 本约定单 agent 与多 agent 并发通用；并发时注意 [`tasks/README.md`](tasks/README.md) 的防撞号规则，只改自己领取的任务文件。
 
-如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。
+如果代码实际状态和任务文件冲突，先说明冲突，不要擅自跳步或重排。
 
 ## MVP 边界
 

docs/05-coding-rules.md

@@ -56,7 +56,7 @@
 - [ ] 对得上需求验收标准。
 - [ ] 没有夹带无关改动。
 - [ ] 涉及文档事实变化时，文档已同步。
-- [ ] 已在 `../progress.md` 记录跑过的命令和结果作为证据，不靠"代码已写"判定完成。
+- [ ] 已在当前任务文件（`docs/tasks/T-<编号>.md`）的 `## 执行记录` 记录跑过的命令和结果作为证据（约定见 [`tasks/README.md`](tasks/README.md)），不靠"代码已写"判定完成。
 - [ ] 回复里如实说明跑了什么命令、结果如何。
 
 把真实命令填在这里：

docs/06-tasks.md

@@ -1,64 +1,57 @@
-# 任务看板（Tasks）
+# 任务路线图（Roadmap）
 
-> 把 MVP 拆成小步、可独立交付的任务，让 AI 一步一步开发，避免一次生成整个项目。
+> 本文是**只读路线图**：维护阶段划分、里程碑、待办池和建议拆分清单，把 MVP 拆成小步、可独立交付的任务，让 AI 一步一步开发，避免一次生成整个项目。
+> 真实任务以「一任务一文件」存放在 [`tasks/`](tasks/README.md)（`docs/tasks/T-<编号>.md`），任务状态以各任务文件 frontmatter 为准；**本文不跟踪单任务状态**。
 
 ## 使用规则
 
-1. **一次只做一个任务**：每轮只领取一个状态为 `TODO`、且依赖均已 `DONE` 的任务，取最靠前的那个。
-2. **做完即停**：完成该任务、自测通过、把状态改成 `DONE` 后，停下来汇报。
+1. **开工先落文件**：从下方「建议拆分清单」把下一个任务按 [`tasks/README.md`](tasks/README.md) 落成 `docs/tasks/T-<编号>.md`（沿用建议编号），把验收要点展开成可执行、可观察的步骤，再开始实现。
+2. **一次只做一个任务**：领取、状态流转、执行记录、完成定义全部遵循 [`tasks/README.md`](tasks/README.md) 和 [编码规则](05-coding-rules.md)；`DONE` 需要可运行证据。
 3. **不跳步**：依赖未完成的任务不能开工。
-4. **完成定义**：以 [编码规则](05-coding-rules.md) 的验证清单为准。
-5. **passing 需证据**：标记 `DONE` 前，必须在 [`../progress.md`](../progress.md) 记录跑过的验证命令和结果作为证据；只有"代码已写"而没有可运行证据，不得标 `DONE`。验收要点要写成可执行、可观察的步骤，不写"应该能用"这类无法验证的描述。
-6. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。
-7. **完成后**把任务状态同步到本文，把执行记录追加到 [`../progress.md`](../progress.md)，覆盖更新 [`current-state.md`](current-state.md)，并过一遍 [`clean-state-checklist.md`](clean-state-checklist.md)。
+4. **本文只在规划变化时修改**：调整阶段划分、里程碑、增删建议任务或 Backlog 条目时才动本文；单个任务开工或完成**不**修改本文。
+5. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。
 
-> **多 agent / 并发协作**：当多个 agent（或人 + agent）并发在同一仓库工作时，单文件看板会被抢改（读到旧版本、ID 撞号、合并冲突）。此时改用 **一任务一文件** [`tasks/README.md`](tasks/README.md)（`docs/tasks/T-<编号>.md`）：新任务只进 `docs/tasks/`、执行记录写进各自任务文件的 `## 执行记录`、不再逐任务追加 `progress.md`/覆盖 `current-state.md`；本单文件看板转为历史归档。单 agent / 小项目继续用本文即可。
+## 建议拆分清单
 
-如新项目希望任务看板放在根目录，可把本文复制或改名为根目录 `tasks.md`，并同步更新 `README.md`、`docs/README.md`、`00-ai-start-here.md` 和 `current-state.md` 的链接。
+以下是按阶段列出的建议任务；`T-编号` 为建议编号，落成任务文件时沿用。
 
-## 状态图例
+### Phase 0 · 地基
 
-`TODO` 待开始 · `DOING` 进行中（同一时间最多 1 个）· `DONE` 已完成并验收 · `BLOCKED` 受阻（注明原因）
+| ID | 任务 | 依赖 | 验收要点 |
+| --- | --- | --- | --- |
+| T-001 | 初始化项目骨架 | - | 依赖安装成功；本地能启动；首页 / 入口可访问；用真实可运行命令替换 `00-ai-start-here.md`、`03-tech-stack.md`、`05-coding-rules.md`、`current-state.md` 中的占位验证命令 |
+| T-002 | 建立基础目录和配置 | T-001 | 目录结构符合 `04-architecture.md`；配置不含密钥 |
+| T-003 | 加入最小测试 / 构建检查 | T-001 | 测试命令和构建命令可运行 |
 
----
+### Phase 1 · 最高风险验证
 
-## Phase 0 · 地基
+| ID | 任务 | 依赖 | 验收要点 |
+| --- | --- | --- | --- |
+| T-101 | 验证最高风险功能原型 | T-001 | 用最小输入跑通核心难点，结论写入文档 |
+| T-102 | 把原型接入正式结构 | T-101 | 代码进入约定模块，测试覆盖关键路径 |
 
-| ID | 任务 | 依赖 | 验收要点 | 状态 |
-| --- | --- | --- | --- | --- |
-| T-001 | 初始化项目骨架 | - | 依赖安装成功；本地能启动；首页 / 入口可访问；用真实可运行命令替换 `00-ai-start-here.md`、`03-tech-stack.md`、`05-coding-rules.md`、`current-state.md` 中的占位验证命令 | TODO |
-| T-002 | 建立基础目录和配置 | T-001 | 目录结构符合 `04-architecture.md`；配置不含密钥 | TODO |
-| T-003 | 加入最小测试 / 构建检查 | T-001 | 测试命令和构建命令可运行 | TODO |
+### Phase 2 · 核心用户流程
 
-## Phase 1 · 最高风险验证
+| ID | 任务 | 依赖 | 验收要点 |
+| --- | --- | --- | --- |
+| T-201 | 实现核心页面 / 入口 | T-102 | 用户能进入主流程第一步 |
+| T-202 | 实现核心动作 | T-201 | 用户能完成 MVP 最关键动作 |
+| T-203 | 实现结果展示 / 状态反馈 | T-202 | 用户能看到保存、提交或处理结果 |
 
-| ID | 任务 | 依赖 | 验收要点 | 状态 |
-| --- | --- | --- | --- | --- |
-| T-101 | 验证最高风险功能原型 | T-001 | 用最小输入跑通核心难点，结论写入文档 | TODO |
-| T-102 | 把原型接入正式结构 | T-101 | 代码进入约定模块，测试覆盖关键路径 | TODO |
+### Phase 3 · 数据与账号
 
-## Phase 2 · 核心用户流程
+| ID | 任务 | 依赖 | 验收要点 |
+| --- | --- | --- | --- |
+| T-301 | 建立数据模型 / 迁移 | T-202 | 表结构符合 `04-architecture.md` |
+| T-302 | 实现鉴权 / 权限边界 | T-301 | 未授权访问被拒绝；授权后可访问 |
+| T-303 | 实现数据持久化 | T-302 | 刷新 / 重进后数据仍在 |
 
-| ID | 任务 | 依赖 | 验收要点 | 状态 |
-| --- | --- | --- | --- | --- |
-| T-201 | 实现核心页面 / 入口 | T-102 | 用户能进入主流程第一步 | TODO |
-| T-202 | 实现核心动作 | T-201 | 用户能完成 MVP 最关键动作 | TODO |
-| T-203 | 实现结果展示 / 状态反馈 | T-202 | 用户能看到保存、提交或处理结果 | TODO |
+### Phase 4 · 收尾与发布
 
-## Phase 3 · 数据与账号
-
-| ID | 任务 | 依赖 | 验收要点 | 状态 |
-| --- | --- | --- | --- | --- |
-| T-301 | 建立数据模型 / 迁移 | T-202 | 表结构符合 `04-architecture.md` | TODO |
-| T-302 | 实现鉴权 / 权限边界 | T-301 | 未授权访问被拒绝；授权后可访问 | TODO |
-| T-303 | 实现数据持久化 | T-302 | 刷新 / 重进后数据仍在 | TODO |
-
-## Phase 4 · 收尾与发布
-
-| ID | 任务 | 依赖 | 验收要点 | 状态 |
-| --- | --- | --- | --- | --- |
-| T-401 | 完整验收 MVP | T-303 | `02-requirements.md` 的 P0 验收全部通过 | TODO |
-| T-402 | 部署 / 打包 / 运行文档 | T-401 | 新环境可按文档运行 | TODO |
+| ID | 任务 | 依赖 | 验收要点 |
+| --- | --- | --- | --- |
+| T-401 | 完整验收 MVP | T-303 | `02-requirements.md` 的 P0 验收全部通过 |
+| T-402 | 部署 / 打包 / 运行文档 | T-401 | 新环境可按文档运行 |
 
 ## 里程碑
 
@@ -71,4 +64,4 @@
 
 - 【V2 功能 1】
 - 【V2 功能 2】
-- 【优化项】
+- 【优化项】

docs/README.md

@@ -15,15 +15,15 @@
 - [`../AGENTS.md`](../AGENTS.md)：Codex / 通用 AI coding agent 的仓库级入口。
 - [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 的薄入口，具体规则以 `AGENTS.md` 为准。
 - [`../tasks.md`](../tasks.md)：当前样本库自身的维护任务列表，不是复制到新项目后的业务任务看板。
-- [`../progress.md`](../progress.md)：复制到新项目后的执行历史流水，只追加记录任务执行、验证、阻塞和决策。
+- [`../progress.md`](../progress.md)：可选历史归档 / 项目级大事记；执行记录默认写各任务文件的 `## 执行记录`。
 - [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。
 - [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。
 - [需求](02-requirements.md)：要什么、用户故事、验收标准，不写技术实现。
 - [技术栈](03-tech-stack.md)：确定使用哪些框架、库、数据库、部署方式。
 - [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。
 - [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。
-- [任务看板](06-tasks.md)：按依赖拆分的小任务，agent 每轮只做一个（单 agent / 小项目）。
-- [任务文件（多 agent 并发）](tasks/README.md)：一任务一文件 `docs/tasks/T-<编号>.md`，多 agent 并发时避免抢改同一看板/进度文件。
+- [任务路线图](06-tasks.md)：阶段划分、里程碑和待办池；只读，不跟踪单任务状态。
+- [任务文件（默认）](tasks/README.md)：一任务一文件 `docs/tasks/T-<编号>.md`，任务状态以 frontmatter 为准，单/多 agent 通用，agent 每轮只做一个。
 - [已有项目接入清单](adoption-checklist.md)：把本模板补进已有代码库时的迁移步骤和第一轮任务建议。
 - [API 合约](api.md)：前后端接口形状、错误格式、鉴权约定。
 - [路由与页面结构](routes.md)：页面路由、页面职责、组件归属。
@@ -36,15 +36,16 @@
 
 ## 任务 / 进度 / 当前状态
 
-- `06-tasks.md` 维护任务看板：任务 ID、依赖、验收要点和状态。
-- `../progress.md` 维护执行进度：每轮实际做了什么、跑了什么验证、遇到什么阻塞、做了什么决策。
-- `current-state.md` 维护当前快照：当前目录、当前可运行命令、已完成任务摘要和下一个可领取任务。
+- `tasks/`（`docs/tasks/T-<编号>.md`）维护任务：规格、依赖、状态（frontmatter）和执行记录，一任务一文件。
+- `06-tasks.md` 维护路线图：阶段划分、里程碑和待办池，不跟踪单任务状态。
+- `current-state.md` 维护当前快照：当前目录、当前可运行命令、任务摘要和下一个可领取任务。
+- `../progress.md` 可选：历史归档或项目级大事记，不逐任务追加。
 
-如果新项目希望任务看板放在根目录，可把 `06-tasks.md` 复制或改名为根目录 `tasks.md`，并同步更新本文、`00-ai-start-here.md` 和 `current-state.md` 的链接。已有项目接入时，先读 `adoption-checklist.md`，不要直接领取新功能。
+已有项目接入时，先读 `adoption-checklist.md`，不要直接领取新功能。
 
 ## 维护原则
 
 - 需求变化先改文档，再改代码。
-- 代码现实变化后同步 `current-state.md` 和 `06-tasks.md`，执行过程追加到 `../progress.md`。
+- 代码现实变化后同步 `current-state.md`；任务状态改在对应任务文件 frontmatter，执行过程写进该任务文件的 `## 执行记录`。
 - API、数据模型、路由、技术栈一旦在文档中定稿，代码不得另起一套。
 - agent 开始新任务前，必须从 `00-ai-start-here.md` 进入。

docs/adoption-checklist.md

@@ -4,7 +4,7 @@
 
 ## 适用场景
 
-- 项目已经有代码，但缺少清晰的 agent 入口、任务看板、当前状态和验证路径。
+- 项目已经有代码，但缺少清晰的 agent 入口、任务文件、当前状态和验证路径。
 - 项目被多轮 AI 修改过，文档、代码和真实可运行状态已经不一致。
 - 想从“靠聊天记录推进”切换到“靠仓库内工件推进”。
 
@@ -20,12 +20,12 @@
 | `CLAUDE.md` | Claude Code 薄入口，指向 `AGENTS.md` |
 | `docs/00-ai-start-here.md` | 每轮开工流程 |
 | `docs/05-coding-rules.md` | 编码纪律和验证底线 |
-| `docs/06-tasks.md` | 任务看板 |
+| `docs/06-tasks.md` | 任务路线图（阶段、里程碑、待办池） |
+| `docs/tasks/` | 默认任务管理：一任务一文件（`README.md` + `_template.md`） |
 | `docs/current-state.md` | 当前实现状态快照 |
-| `progress.md` | 只追加的执行流水 |
 | `init.sh` 或 `init.ps1` | 标准启动与验证入口，按操作系统二选一 |
 
-推荐随后补齐：`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`、`docs/clean-state-checklist.md`。
+推荐随后补齐：`docs/01-vision.md`、`docs/02-requirements.md`、`docs/03-tech-stack.md`、`docs/04-architecture.md`、`docs/api.md`、`docs/routes.md`、`docs/clean-state-checklist.md`；`progress.md` 可选（历史归档 / 项目级大事记）。
 
 ## 接入步骤
 
@@ -34,10 +34,10 @@
 3. 在 `docs/current-state.md` 写清真实目录、真实启动命令、真实验证命令、当前 blocker。
 4. 在 `docs/03-tech-stack.md` 固定已经实际使用的技术栈，不确定项标为“待定”，不要让 agent 自行选择。
 5. 在 `docs/04-architecture.md` 记录当前代码的真实模块边界；不清楚的地方标为“待确认”。
-6. 在 `docs/06-tasks.md` 只放下一阶段能小步交付的任务，不要把历史愿望清单全部搬进去。
+6. 在 `docs/06-tasks.md` 只放下一阶段能小步交付的建议任务，不要把历史愿望清单全部搬进去；第一轮任务按 `docs/tasks/README.md` 落成 `docs/tasks/T-<编号>.md`。
 7. 配置 `init.sh` 或 `init.ps1` 顶部三个命令，让它能安装依赖、运行基础验证、打印启动命令。
 8. 运行标准验证；如果失败，第一轮任务应先修基线，不做新功能。
-9. 把接入过程、验证结果和遗留 blocker 追加到 `progress.md`。
+9. 把接入过程、验证结果写进第一轮任务文件的 `## 执行记录`，遗留 blocker 同步到 `docs/current-state.md`。
 
 ## 第一轮 agent 任务建议
 
@@ -45,16 +45,16 @@
 
 | ID | 任务 | 验收要点 |
 | --- | --- | --- |
-| T-000 | 建立当前状态基线 | `current-state.md` 写清真实状态；`init` 脚本已配置；基础验证结果已记录到 `progress.md` |
+| T-000 | 建立当前状态基线 | `current-state.md` 写清真实状态；`init` 脚本已配置；基础验证结果已记录到本任务文件的 `## 执行记录` |
 | T-001 | 修复启动 / 验证基线 | 标准启动路径和标准验证路径可运行；失败原因已消除或记录为 blocker |
-| T-002 | 对齐任务看板 | `06-tasks.md` 只保留可执行的小任务；第一个 TODO 依赖清楚、验收可观察 |
+| T-002 | 对齐任务路线图 | `06-tasks.md` 只保留可小步交付的建议任务；第一个待落地任务依赖清楚、验收可观察 |
 
 ## 代码现实与文档冲突时
 
 - 以当前可运行代码和真实验证结果为事实起点。
 - 文档描述旧功能但代码不存在时，先把差异记录到 `current-state.md`，不要直接补实现。
 - 代码已有行为但文档没写时，先补 `02-requirements.md`、`04-architecture.md` 或 `api.md`，再继续修改代码。
-- 命令不可运行时，不要标记任务完成；在 `progress.md` 记录失败命令和错误摘要。
+- 命令不可运行时，不要标记任务完成；在当前任务文件的 `## 执行记录` 记录失败命令和错误摘要。
 
 ## 不建议做的事
 

docs/clean-state-checklist.md

@@ -7,9 +7,9 @@
 
 - [ ] 标准启动路径仍可用（`./init.sh` 或本项目等价命令能跑通）。
 - [ ] 标准验证 / smoke 仍可运行，结果如实。
-- [ ] 本轮执行记录已追加到 [`../progress.md`](../progress.md)（含跑过的命令和结果作为证据）。
-- [ ] [`06-tasks.md`](06-tasks.md) 任务状态真实反映 `DONE` 与未验证的边界，没有"假 DONE"。
-- [ ] [`current-state.md`](current-state.md) 已覆盖更新到当前快照（目录、命令、下一步、blocker）。
+- [ ] 本轮执行记录已写进当前任务文件（`docs/tasks/T-<编号>.md`）的 `## 执行记录`（含跑过的命令和结果作为证据）。
+- [ ] 任务文件 frontmatter 的 `status` 真实反映 `DONE` 与未验证的边界，没有"假 DONE"。
+- [ ] [`current-state.md`](current-state.md) 的项目级快照与现实一致（启动/验证路径、目录要点、blocker）。
 - [ ] 没有半成品改动处于未记录状态；如有，已写明 `BLOCKED` / `PARTIAL` 和原因。
 - [ ] 代码处于可安全恢复的状态（必要时已提交，提交信息清晰）。
 

docs/current-state.md

@@ -1,12 +1,13 @@
 # 当前实现状态
 
-> 本文是可覆盖的当前快照，记录代码与任务看板的现实状态，帮助 AI coding agent 避免只看计划而忽略仓库现状。
-> 历史执行流水追加到 [`../progress.md`](../progress.md)，不要在本文重复维护完整执行日志。
+> 本文是可覆盖的**项目级快照**，记录代码与任务的现实状态，帮助 AI coding agent 避免只看计划而忽略仓库现状。
+> 执行记录写进各任务文件（`docs/tasks/T-<编号>.md`）的 `## 执行记录`，不要在本文重复维护完整执行日志。
 
 ## 职责边界
 
-- [`06-tasks.md`](06-tasks.md)：任务看板，维护任务状态、依赖和验收要点。
-- [`../progress.md`](../progress.md)：执行流水，只追加记录每轮执行、验证、阻塞和决策。
+- [`tasks/`](tasks/README.md)（`docs/tasks/T-<编号>.md`）：任务规格、依赖、状态（frontmatter）和执行记录，一任务一文件。
+- [`06-tasks.md`](06-tasks.md)：只读路线图，维护阶段划分、里程碑和待办池。
+- [`../progress.md`](../progress.md)：可选历史归档 / 项目级大事记，不逐任务追加。
 - `current-state.md`：当前快照，可覆盖更新当前目录、当前命令、已完成摘要和下一步。
 
 ## 当前快照
@@ -31,9 +32,9 @@
 | `tests/` | 【已有 / 待建】 | 测试 |
 | `scripts/` | 【已有 / 待建】 | 辅助脚本 |
 
-## 任务看板状态
+## 任务状态
 
-任务状态以 [`06-tasks.md`](06-tasks.md) 为准，历史执行记录见 [`../progress.md`](../progress.md)。
+任务状态以 `docs/tasks/` 各任务文件 frontmatter 的 `status` 为准（可用脚本汇总成只读看板），历史执行记录见各任务文件的 `## 执行记录`。本节只写摘要：
 
 - 已完成：【列出 DONE 任务】。
 - 正在进行：【如有，列出 DOING 任务】。
@@ -59,8 +60,8 @@
 1. 读仓库级 agent 规则文件（如有）。
 2. 读 `docs/00-ai-start-here.md`。
 3. 读 `docs/05-coding-rules.md`。
-4. 在 `docs/06-tasks.md` 取第一个 `TODO` 且依赖均 `DONE` 的任务。
-5. 将该任务状态改为 `DOING`。
+4. 在 `docs/tasks/` 取第一个 frontmatter `status: TODO` 且依赖均 `DONE` 的任务文件；暂无可领任务时，先按 `docs/06-tasks.md` 路线图落成任务文件。
+5. 将该任务文件 frontmatter 的 `status` 改为 `DOING`。
 
 ## 维护规则
 
@@ -74,6 +75,5 @@
 
 同时注意：
 
-- 任务状态变化必须同步 [`06-tasks.md`](06-tasks.md)。
-- 每轮执行记录、验证命令、阻塞点和关键决策追加到 [`../progress.md`](../progress.md)。
+- 任务状态变化改在对应任务文件的 frontmatter；每轮执行记录、验证命令、阻塞点和关键决策写进该任务文件的 `## 执行记录`。
 - 本文件只保留当前快照，不保留完整历史。

docs/evaluator-rubric.md

@@ -10,7 +10,7 @@
 | 维度 | 问题 | 分数 (0-2) | 备注 |
 | --- | --- | --- | --- |
 | 正确性 | 实现出来的行为是否符合目标功能 / 验收标准？ |  |  |
-| 验证 | 要求的检查是否真的跑过，并在 `../progress.md` 留下证据？ |  |  |
+| 验证 | 要求的检查是否真的跑过，并在对应任务文件（`docs/tasks/T-<编号>.md`）的 `## 执行记录` 留下证据？ |  |  |
 | 范围纪律 | 这一轮是否基本保持在选定的单个任务范围内？ |  |  |
 | 可靠性 | 结果是否能在重启或重跑后继续工作？ |  |  |
 | 可维护性 | 代码和文档是否清楚到足以交给下一轮会话？ |  |  |
@@ -40,4 +40,4 @@
 4. 对同一个输出重新打分，看是否对齐。
 5. 重复直到评审判断和人工评审基本一致。
 
-预计需要 3-5 轮校准。每轮在 `../progress.md` 记录改了什么、为什么改。
+预计需要 3-5 轮校准。每轮把改了什么、为什么改记入 `../progress.md` 的项目级大事记（跨任务的校准决策适合记在那里）。

docs/method-map.md

@@ -7,15 +7,15 @@
 
 | 失败模式 | 实际表现 | 首要修复 | 主要工件 |
 | --- | --- | --- | --- |
-| 新会话摸黑 | 新会话花大量时间重新摸索状态和启动方式 | 让仓库成为唯一事实来源 | [`current-state.md`](current-state.md) + [`../progress.md`](../progress.md) |
+| 新会话摸黑 | 新会话花大量时间重新摸索状态和启动方式 | 让仓库成为唯一事实来源 | [`current-state.md`](current-state.md) + [`tasks/`](tasks/README.md) 任务文件的执行记录 |
 | 启动脆弱 | 每轮会话都要重新学怎么启动、装依赖、跑测试 | 统一启动与验证路径 | [`../init.sh`](../init.sh) / [`../init.ps1`](../init.ps1) |
-| 范围蔓延 | 一次启动多个任务，最后没有一个完整收尾 | 限制当前活跃范围，一轮只做一个任务 | [`06-tasks.md`](06-tasks.md) |
-| 提前宣布完成 | 代码改了就说"完成了"，但没有可运行证据 | 把完成绑定到验证证据 | [`06-tasks.md`](06-tasks.md)（passing 需证据）+ [`clean-state-checklist.md`](clean-state-checklist.md) |
+| 范围蔓延 | 一次启动多个任务，最后没有一个完整收尾 | 限制当前活跃范围，一轮只做一个任务 | [`tasks/README.md`](tasks/README.md) |
+| 提前宣布完成 | 代码改了就说"完成了"，但没有可运行证据 | 把完成绑定到验证证据 | [`tasks/README.md`](tasks/README.md)（passing 需证据）+ [`clean-state-checklist.md`](clean-state-checklist.md) |
 | 交接薄弱 | 下一轮看不出哪里可用、哪里坏了、接下来做什么 | 每轮留下明确的当前快照和下一步 | [`current-state.md`](current-state.md) |
 | 评审主观 | 质量判断靠个人记忆和感觉，agent 容易自我说服通过 | 用固定维度做评分 | [`evaluator-rubric.md`](evaluator-rubric.md) |
 | 代码库悄悄退化 | 速度上去了，但几轮会话后代码越来越难审、边界越来越糊 | 定期给代码库健康度打分 | [`quality-document.md`](quality-document.md) |
 | 文档堆叠失控 | 入口文件越来越长，"每次失败加一句" | 渐进披露，入口保持薄 | [`00-ai-start-here.md`](00-ai-start-here.md) + 拆分到具体文档 |
-| 多 agent 抢改任务文件 | 多个 agent 并发时抢改同一个看板/进度文件，出现"读到旧版本"、ID 撞号、合并冲突 | 一任务一文件，执行记录进任务文件，不逐任务改共享收尾文件 | [`tasks/README.md`](tasks/README.md) |
+| 多 agent 抢改任务文件 | 多个 agent 并发时抢改同一个看板/进度文件，出现"读到旧版本"、ID 撞号、合并冲突 | 一任务一文件（默认模式已内建），执行记录进任务文件，不逐任务改共享收尾文件 | [`tasks/README.md`](tasks/README.md) |
 
 ## 使用原则
 

docs/tasks/README.md

@@ -1,16 +1,19 @@
-# 任务文件（一任务一文件 · 多 agent 并发）
+# 任务文件（一任务一文件 · 默认任务管理方式）
 
-> 适用场景：**多个 agent（或人 + agent）并发在同一仓库工作**时，避免所有人抢改同一个 `docs/06-tasks.md` 看板文件。
-> 单 agent / 小项目可继续用单文件看板 `docs/06-tasks.md`；并发协作时改用本目录的"一任务一文件"。
+> 本目录是项目任务的**默认存放位置**：每个任务一个文件 `docs/tasks/T-<编号>.md`，单 agent 与多 agent 并发通用。
+> 阶段划分、里程碑和待办池见路线图 [`../06-tasks.md`](../06-tasks.md)；路线图只读，不跟踪单任务状态。
 
-## 为什么
+## 为什么默认一任务一文件
 
-单个大看板文件 + 多写者 = 三种冲突：**编辑竞争**（读到旧版本、反复重读）、**ID 撞号**（全局递增号是共享计数器）、**合并冲突**（相邻行改动）。一任务一文件后：改哪个任务只动哪个文件，agent 之间互不抢占；ID 撞号在**新建文件时当场暴露**（文件已存在就换号）。
+- **单 agent**：领任务只读一个文件就拿到完整上下文（背景、方案、验收、执行记录），不用在看板、进度流水、快照三个共享文件之间跳转同步；执行记录和任务绑定，审查时 `git log -p` 一个文件即可回放全程。
+- **多 agent 并发**：单个大看板 + 多写者 = **编辑竞争**（读到旧版本、反复重读）、**ID 撞号**（全局递增号是共享计数器）、**合并冲突**（相邻行改动）。一任务一文件后：改哪个任务只动哪个文件，agent 之间互不抢占；ID 撞号在**新建文件时当场暴露**（文件已存在就换号）。
+- **零迁移**：项目从单 agent 长到多 agent，无需切换任何约定。
 
 ## 文件命名与 ID
 
 - 文件名：`docs/tasks/T-<编号>.md`（如 `docs/tasks/T-101.md`）；同族细分用后缀 `T-101a.md`。
-- 分配下一个 ID：取「看板归档 `docs/06-tasks.md` + `docs/tasks/` 现有文件」里最大的 `T-###`，`+1`。
+- 落实路线图建议任务时，**沿用路线图 `../06-tasks.md` 里的建议编号**（如 T-101）。
+- 路线图之外的新任务：取「路线图建议编号 + `docs/tasks/` 现有文件」里最大的 `T-###`，`+1`。
 - **建文件即防撞**：若目标编号文件已存在（别的 agent 先建了），改用下一个号，**不要覆盖别人的文件**。
 - 模板 `_template.md` 以下划线开头，不是真实任务、不参与编号扫描。
 
@@ -20,7 +23,7 @@
 ---
 id: T-101
 title: 一句话任务名
-phase: 1               # 所属阶段，沿用看板的 Phase 编号
+phase: 1               # 所属阶段，沿用路线图的 Phase 编号
 deps: [T-100]          # 依赖的任务 ID
 status: TODO           # TODO | DOING | DONE | BLOCKED
 created: 【日期】
@@ -36,8 +39,9 @@ created: 【日期】
 ## 领取 / 完成流程
 
 - 状态：`TODO` · `DOING`（同一时间最多 1 个）· `DONE` · `BLOCKED`。
-- 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。
-- **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——**不再逐任务追加共享的 `progress.md`、也不再逐任务覆盖 `current-state.md`**（那两个是每任务共享写入点，多 agent 会抢/覆盖）。
+- 一次只领一个 `status: TODO` 且依赖全 `DONE` 的任务，取编号最靠前的；若本目录暂无可领任务，先按路线图把下一个建议任务落成任务文件，再领取。
+- 做完自测、按「passing 需证据」把验证命令与结果写清、改 `status: DONE`。
+- **执行记录写进本任务文件的 `## 执行记录` 一节**（改了什么、跑了什么验证、结果、决策）——不逐任务追加共享的 `progress.md`（可选历史归档）、也不逐任务覆盖 `current-state.md`（项目级快照，只在启动/验证路径、目录结构或 blocker 变化时更新）。
 - **只改自己那个任务文件**；不要编辑别人正在做的任务文件。
 
 ## 用户指令暗语（可选约定）
@@ -53,7 +57,7 @@ created: 【日期】
 | `审 T-<编号>` | **以 git 历史为准**（`git log -p` 该任务文件找出最近改动），先核代码事实，再审核该改动是否合理、给缺口 |
 | `补` | 把讨论新增的结论补进当前任务文件并提交 git |
 | `做 T-<编号>` | 实现该任务 + 跑任务内验证命令；**验证全绿才提交**（执行记录、状态 DONE、提交）；验证失败 → 报告、**不提交**、状态留 DOING 或标 BLOCKED 记原因 |
-| `记backlog: <一行>` | 追加进待办池（如 `docs/06-tasks.md` Backlog）并提交，只记一行、不建任务文件 |
+| `记backlog: <一行>` | 追加进待办池（`docs/06-tasks.md` Backlog）并提交，只记一行、不建任务文件 |
 
 补充规则：
 
@@ -66,7 +70,8 @@ created: 【日期】
 - 现阶段：`ls docs/tasks/` + 看各文件 frontmatter 的 `status`/`deps` 挑任务。
 - 可选：加一个脚本把所有任务文件的 frontmatter 汇总成一张只读看板表，agent 不手改看板。
 
-## 与单文件看板的关系
+## 与路线图和共享文件的关系
 
-- 切换到本模式后，把 `docs/06-tasks.md` **冻结为历史归档**（只在订正历史任务状态时才动），新任务只进 `docs/tasks/`。
-- `progress.md` 冻结为历史归档；`current-state.md` 不再逐任务手动覆盖，当前状态以各任务 frontmatter 为准，可由脚本汇总生成。
+- [`../06-tasks.md`](../06-tasks.md)：只读路线图（Phase 划分、里程碑、Backlog、建议拆分清单）；真实任务状态一律以本目录任务文件的 frontmatter 为准。
+- `../../progress.md`：可选工件，用作历史归档或项目级大事记；执行记录写各任务文件，不逐任务追加。
+- [`../current-state.md`](../current-state.md)：项目级快照（启动/验证路径、目录要点、blocker）；任务状态不在此维护，可由脚本汇总 frontmatter 生成。

docs/tasks/_template.md

@@ -26,4 +26,4 @@ created: 【日期】
 ## 执行记录
 
 （做完在此记录：改了哪些文件、跑的验证命令与结果、阻塞、关键决策。
-取代逐任务追加 `progress.md`——执行记录只写进本任务文件，避免多 agent 抢改共享文件。）
+执行记录只写进本任务文件，不逐任务追加共享的 `progress.md`，避免多 agent 抢改共享文件。）