@michaelxwb/code-flow 0.5.1 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelxwb/code-flow",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "license": "UNLICENSED",
   "bin": {
     "code-flow": "src/cli.js"

package/src/adapters/claude/commands/cf-task/align.md

@@ -160,6 +160,8 @@ CLI 场景：
 **验收标准**（必选）
 - 怎么判断做完了？正常 / 异常场景各列至少一条
 - 可验证、可转为自动化测试断言的条件（明确输入与可观测输出）；场景 ID（S-/E-/B-）即测试用例来源
+- 为每个场景指定测试层级（unit / integration / E2E / manual）和关键真实边界；跨 API、存储、运行时生成、渲染或用户可见结果等多个边界时必须选 E2E
+- RULE 与高影响 RISK 必须映射到至少一个 S/E/B 场景；manual 仅限无法自动化的外部条件，必须写明原因
 
 **妥协与技术债**（按需）
 - 本次有意接受的取舍或欠债？后续偿还设想？
@@ -240,8 +242,10 @@ CLI 场景：
 **追溯硬约束（plan 拆解与质量门的基础）**：
 - 功能清单每个 FEAT 保留"来源"列（PRD 派生填 US-XX；无 PRD 填需求描述）
 - 接口（API/CLI/函数）与验收场景标注其实现 / 覆盖的 FEAT-XX
+- 每个验收场景写明测试层级、关键真实边界和最终可观测结果；编码阶段不得把 E2E 自行降级为 mock 后的 unit/integration 测试
+- 每个 RULE 与高影响 RISK 映射到 S/E/B 场景；只能手动验证时记录原因
 - Full 模板 §6 需求追溯矩阵必须闭合：US → FEAT → API → TC 不留断点，TC 引用 §2.5.2 场景 ID
-- 任一缺口（FEAT 无来源 / FEAT 无验收 / 矩阵断点）在展示时显式列出并提示补全
+- 任一缺口（FEAT 无来源 / FEAT 无验收 / 场景无测试层级或真实边界 / RULE·RISK 无验证场景 / 矩阵断点）在展示时显式列出并提示补全
 
 展示后询问用户：**确认写入？可以调整任何部分。**
 
@@ -273,7 +277,7 @@ CLI 场景：
 内容:
   - <按实际包含的章节列出>
   - 验收标准: N 项
-  - 追溯自检: 每个 FEAT 有来源(US/需求)✓、有验收场景✓；Full 模板 §6 矩阵 US→FEAT→API→TC 闭合，缺口显式列出
+  - 追溯自检: 每个 FEAT 有来源(US/需求)✓、有验收场景✓；每个场景有测试层级和关键真实边界✓；RULE/高影响 RISK 有验证场景✓；Full 模板 §6 矩阵闭合
   - 性能自检: 标记性能敏感则方案须体现最优性能设计依据（§3.1/§3.5 或 lite §3.4），否则提示补全或显式声明"无性能敏感点"
 
 下一步:

package/src/adapters/claude/commands/cf-task/archive.md

@@ -1,6 +1,6 @@
 # cf-task:archive
 
-归档已完成的整个 task 文件。归档前执行三维校验，归档后提示更新 specs。
+归档已完成的整个 task 文件。归档前执行四维校验，归档后提示更新 specs。
 
 ## 输入
 
@@ -32,7 +32,7 @@
 
 ### 2. 归档前校验（Verify）
 
-所有子任务 done 后，执行三维校验：
+所有子任务 done 后，执行四维校验：
 
 **完整性**：
 - 所有 Checklist 项已勾选
@@ -42,6 +42,13 @@
 - 如果 `.code-flow/validation.yml` 存在，Read 读取验证规则，用 Bash 执行其中匹配的 `command`（如 `npx tsc --noEmit`、`python3 -m pytest` 等）
 - 检查本次变更涉及的文件是否通过 lint/type check
 
+**验收追溯**：
+- 来源 design 含结构化 S-/E-/B- 场景时，逐项对照 `## Acceptance Coverage`，P0/P1 场景以及 RULE/高影响 RISK 映射场景必须全部存在且状态为 `verified`
+- 每个负责任务的 `Acceptance-Refs`、`Acceptance Contract`、`Acceptance Evidence` 必须闭合，不得残留 `planned` / `pending` / `TBD`
+- 测试层级不得低于 design；E2E 的真实边界和关键断言必须有文件/用例位置与 fixture/构造证据
+- 汇总并重新执行契约中所有唯一验收命令；测试未收集、未执行或失败均为 FAIL
+- `manual` 场景必须有用户确认和可复核记录。旧 design 没有结构化场景时注明“不适用”，不得伪造覆盖
+
 **一致性**：
 - 读取 task 文件的 `## Proposal`，对照实际代码变更，检查意图是否已实现
 
@@ -51,6 +58,7 @@
 归档前校验:
   [PASS] 完整性: 所有 Checklist 已完成，无未解决 Notes
   [PASS] 正确性: cf-validate 通过
+  [PASS] 验收追溯: 6/6 场景 verified，2 条 E2E 命令通过
   [WARN] 一致性: Proposal 提到"支持 OAuth 登录"，但未发现相关实现
 
 WARN 不阻塞归档，但建议确认后再继续。继续归档？
@@ -78,7 +86,19 @@ mv .code-flow/tasks/<日期>/<需求>/ .code-flow/tasks/archived/<日期>/<需
    ```
 3. 同名 `.design.md` 存在则一并移动：`mv .code-flow/tasks/<日期目录>/<file>.design.md .code-flow/tasks/archived/<日期目录>/`
 4. 同名 `.prd.md` 存在则一并移动：`mv .code-flow/tasks/<日期目录>/<file>.prd.md .code-flow/tasks/archived/<日期目录>/`
-5. 如果原日期目录为空，删除空目录
+
+**归档后统一收尾（布局 A/B 都必须执行）**：
+
+1. 保存源日期目录为 `.code-flow/tasks/<日期>/`，完成移动后检查该目录是否还有其他需求或任务。
+2. 如果目录为空，必须执行安全删除；非空则保留并在摘要中列出剩余条目：
+   ```bash
+   source_date_dir=".code-flow/tasks/<日期>"
+   if [ -d "$source_date_dir" ] && [ -z "$(find "$source_date_dir" -mindepth 1 -maxdepth 1 -print -quit)" ]; then
+     rmdir "$source_date_dir"
+   fi
+   ```
+3. 复查归档目标存在、原任务/需求路径不存在；如果源日期目录仍存在但为空，视为归档未完成，立即删除后再继续。
+4. 源日期目录包含其他条目时不得删除，摘要明确写“保留（仍有 N 个条目）”。
 
 **临时约束清理（FEAT-08）**：删除 `.code-flow/specs/_session/task-<name>.md`（存在时）。该文件由 cf-task:start 生成，归档后不得残留。
 
@@ -127,5 +147,6 @@ Spec 同步建议:
   - 创建日期: 2026-03-15
   - 归档日期: 2026-03-20
   - 历时: 5 天
-  - 校验: 3/3 PASS
+  - 校验: 4/4 PASS
+  - 源日期目录: 已删除（为空）/ 已保留（仍有 N 个条目）
 ```

package/src/adapters/claude/commands/cf-task/plan.md

@@ -153,6 +153,15 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 设计简报模式：记录**章节名**，无需行号。
 引用格式：`<name>.design.md#3.3 数据设计`, `<name>.design.md#3.4 接口设计` 等（章节名须与模板真实标题一致）。
 
+**验收契约拆解（硬约束）**：
+
+1. 从全部 design 提取 P0/P1 的 S-/E-/B- 场景，以及 RULE 和高影响 RISK 到场景的映射。
+2. 优先沿用 design 指定的测试层级与关键真实边界。旧 design 未填写时，跨 API、存储、运行时生成、渲染或最终用户可见结果的场景推断为 `E2E`，局部模块协作推断为 `integration`，纯函数约束才可用 `unit`。
+3. 每个场景必须分配给一个负责的 TASK，并写入 `Acceptance-Refs`；同一场景可被多个任务引用，但必须有且仅有一个最终验收负责人。
+4. `manual` 只允许用于无法自动化的外部条件，必须记录原因并经用户明确确认。agent 不得把 design 的 E2E 自行降级为 unit/integration。
+5. Checklist 禁止使用泛化的“编写测试”。必须写成 `[场景ID][测试层级] + 真实边界 + 关键断言`，并为新功能/缺陷修复安排先写测试和 RED 记录。
+6. 如果场景缺测试层级、真实边界或 RULE/高影响 RISK 没有验证场景，先以 `#NOTES` 列为设计缺口；未解决前不得开始编码。
+
 ### 4. 生成任务文件方案
 
 将拆解结果按以下格式组织，展示给用户确认：
@@ -183,12 +192,24 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 
 ---
 
+## Acceptance Coverage
+
+| 场景ID | 来源设计 | 测试层级 | 关键真实边界 | 负责任务 | 状态 |
+|--------|---------|---------|-------------|---------|------|
+| S-01 | xxx.design.md#2.5 验收条件 | E2E | API → Store → Renderer | TASK-001 | planned |
+| E-01 | xxx.design.md#2.5 验收条件 | integration | Service → Store | TASK-001 | planned |
+
+> 本表必须覆盖 design 中全部 P0/P1 场景，以及 RULE/高影响 RISK 映射的场景；存在缺口时不生成可启动任务。
+
+---
+
 ## TASK-001: <子任务标题>
 
 - **Status**: draft
 - **Priority**: P0
 - **Depends**:
 - **Source**: docs/xxx.md#§3.1 数据模型(L83-L110)
+- **Acceptance-Refs**: S-01, E-01, RULE-01
 
 ### Description
 <从设计文档提取的需求重点，不必复制全文>
@@ -196,7 +217,21 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 ### Checklist
 - [ ] <具体实现步骤1>
 - [ ] <具体实现步骤2>
-- [ ] <编写测试>
+- [ ] [S-01][E2E] 修改生产代码前，按 API → Store → Renderer 真实边界编写验收测试并记录 RED
+- [ ] [S-01] 断言 <最终可观测结果 1> 与 <最终可观测结果 2>
+- [ ] [E-01][integration] 覆盖 <异常输入> 与 <可观测失败行为>
+- [ ] 运行验收命令并填写 Acceptance Evidence
+
+### Acceptance Contract
+
+| 场景ID | 测试层级 | 不得 Mock 的真实边界 | 关键断言 | 测试文件 / 用例 | 执行命令 | 状态 |
+|--------|---------|--------------------|---------|----------------|---------|------|
+| S-01 | E2E | API、Store、Renderer | <断言列表> | planned | planned | planned |
+| E-01 | integration | Service、Store | <断言列表> | planned | planned | planned |
+
+### Acceptance Evidence
+
+> `cf-task-start` 在编码期填写 RED/GREEN 结果、每个关键断言的位置和真实组件证据；全部状态 verified 后任务才可 done。
 
 ### Log
 - [<当前日期>] created (draft)
@@ -221,6 +256,7 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 
 TASK-001: <标题> [P0]
   来源: §3.1 数据模型 (L83-L110)
+  验收: S-01(E2E), E-01(integration)
   描述: ...
   Checklist: N 项
   依赖: 无
@@ -256,6 +292,7 @@ TASK-002: <标题> [P1]
 - P0: x 个, P1: y 个, P2: z 个
 - 依赖链深度: N 层
 - 详设引用覆盖: §3.1, §3.2, §3.3, §3.5 (共 4 个章节)
+- 验收覆盖: P0/P1 场景 x/x，RULE/高影响 RISK 映射 y/y，E2E 场景 z 个
 
 建议执行顺序:
   1. TASK-001 (无依赖)

package/src/adapters/claude/commands/cf-task/start.md

@@ -23,7 +23,7 @@
 
 **状态检查**：Status 必须为 `draft`。若为其他状态：
 - `in-progress` → 提示"任务已在进行中，继续编码"（不阻塞，直接跳到步骤 2）
-- `done` → 提示"任务已完成"，结束
+- `done` → 先执行验收契约检查；全部 verified 才提示"任务已完成"并结束，否则恢复为 `in-progress`，列出缺口并继续补齐测试与证据
 - `blocked` → 提示"任务被阻塞"，列出 Notes 中的阻塞原因，结束
 
 **#NOTES 检查**：扫描该子任务段落全文（Description、Checklist 等）
@@ -35,6 +35,12 @@
 - 所有依赖必须为 `done`
 - 未满足 → 输出：`前置检查失败：以下依赖未完成\n- TASK-001: in-progress\n- TASK-003: draft`
 
+**验收契约检查**：
+- 如果 task 含 `## Acceptance Coverage`，当前子任务必须有 `Acceptance-Refs`、`Acceptance Contract` 和 `Acceptance Evidence`
+- `Acceptance-Refs` 中每个 S-/E-/B- 都必须出现在全局覆盖表和当前契约中，测试层级与关键真实边界必须和 design 一致
+- 旧 task 没有覆盖表但来源 design 含结构化验收场景时，先从 design 回填覆盖表与契约；回填完成前不得修改生产代码
+- 非行为类任务可显式写 `Acceptance-Refs: N/A`；不得用 N/A 跳过已有设计场景
+
 ### 2. 加载详设上下文
 
 前置检查通过后，**编码前先加载关联的详设文档章节**：
@@ -44,26 +50,50 @@
    - 提取：文件路径 + 行号范围
 2. 用 Read 按行号范围读取详设文档的对应章节（使用 offset/limit 参数）
 3. 将读取的章节内容作为编码上下文，与 Checklist 一起指导实现
+4. 按 `Acceptance-Refs` 精确读取验收场景及其关联 RULE/RISK；不得只依赖摘要，也不得遗漏场景的测试层级、关键真实边界和预期结果
 
 示例：Source 为 `docs/auth.md#§3.2 API 接口(L111-L155), docs/auth.md#§3.5 错误码(L201-L220)`
 → Read `docs/auth.md` offset=111 limit=45
 → Read `docs/auth.md` offset=201 limit=20
 
-### 3. 激活并编码
+### 3. 激活并准备验收测试
 
 1. 用 Edit 更新子任务 Status 为 `in-progress`
 2. 在 `### Log` 追加：`- [<当前日期>] started (in-progress)`
 3. 更新文件头 `Updated` 日期
-4. 结合详设上下文 + Checklist，逐项执行编码工作
-5. 每完成一个 checklist 项 → 用 Edit 将 `- [ ]` 改为 `- [x]`
+4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
+5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
+6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
+
+RED 证据写入 `Acceptance Evidence`：
+
+```markdown
+| 场景ID | RED | GREEN | 断言位置 | 真实边界证据 | 状态 |
+|--------|-----|-------|---------|-------------|------|
+| S-01 | FAIL: generation 未递增 | pending | pending | real Store + Renderer fixture | test-written |
+```
+
+### 3.1 实现与逐项更新
+
+1. RED 证据就绪后，结合详设上下文、Acceptance Contract 与 Checklist 修改生产代码
+2. 每完成一个 checklist 项，用 Edit 将 `- [ ]` 改为 `- [x]`
+3. 如果实现中发现必须改变测试层级或真实边界，停止编码并记录 `#NOTES`，经用户确认并同步 design 后才能继续；agent 不得自行降级
+
+### 3.2 GREEN 与验收证据
+
+1. 执行每个契约中的验收命令，再执行受影响范围的回归测试
+2. 对每个预期结果记录对应的测试断言位置，并指出 fixture/构造路径如何证明关键边界使用真实组件
+3. 将 `Acceptance Contract` 行状态改为 `verified`，将 `Acceptance Evidence` 补齐 GREEN、断言位置和边界证据
+4. 负责该场景的任务验证完成后，将全局 `Acceptance Coverage` 对应行改为 `verified`
+5. 测试文件存在但未被测试框架收集、命令未实际执行、只有场景 ID 没有关键断言，都视为未验证
 
 ### 3.5 会话级临时约束（FEAT-08）
 
 激活后，若任务文件头 Source 指向的 design 文档含验收条件章节（如 §2.5 验收条件 / 验收标准）：
 
-1. 提取该章节的场景与 RULE 约束，生成 `.code-flow/specs/_session/task-<name>.md`：
+1. 只提取当前任务 `Acceptance-Refs` 对应的场景、测试层级、关键真实边界与 RULE/RISK，生成 `.code-flow/specs/_session/task-<name>.md`：
    - frontmatter：`description: 当前任务 <name> 的验收约束（cf-task:start 生成，archive 清理）`
-   - 正文：验收场景与约束的精简列表（≤300 token）
+   - 正文：验收场景与约束的精简列表（≤300 token）；必须保留全部引用 ID、层级、边界和预期结果，不能为压缩而删除场景
 2. Spec Catalog 目录扫描自动纳入该文件，无需配置；编辑代码时的自动注入同样生效
 3. design 无验收章节时静默跳过；同名文件已存在则覆盖（同任务重复 start）
 
@@ -71,12 +101,21 @@
 
 ### 4. 自动完成
 
-当所有 checklist 项都勾选为 `[x]` 后：
+只有同时满足以下条件才能自动完成：
+- 所有 checklist 项均为 `[x]`
+- 每个 Acceptance-Ref 在契约、证据和全局覆盖表中均为 `verified`，不存在 `planned` / `pending` / `TBD`
+- 测试层级未低于 design，关键真实边界没有被 mock 绕过
+- 每个预期结果都有具体断言位置，验收命令和回归测试均已实际通过
+- `manual` 场景已有用户确认和可复核记录
+
+满足后：
 1. 用 Edit 更新 Status 为 `done`
 2. 在 `### Log` 追加：`- [<当前日期>] completed (done)`
 3. 更新文件头 `Updated` 日期
 4. 输出：`TASK-xxx 已完成`
 
+任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
+
 ### 5. 文档同步检查
 
 子任务完成后，轻量检查本次编码是否引入了需要同步到 specs 或导航地图的内容：
@@ -144,7 +183,7 @@ Spec 同步提示:
 
 ### 4. 按序执行
 
-对每个可激活的子任务，执行单任务模式的步骤 3-4（详设已在步骤 2 加载，无需重复读取）。
+对每个可激活的子任务，执行单任务模式的步骤 3-4，包括先写验收测试、RED、实现、GREEN 和证据核对（详设已在步骤 2 加载，无需重复读取）。
 
 完成一个子任务后，检查是否解锁了新的子任务（依赖已满足），如果是则继续执行。
 

package/src/adapters/codex/skills/cf-task-align/SKILL.md

@@ -161,6 +161,8 @@ CLI 场景：
 **验收标准**（必选）
 - 怎么判断做完了？正常 / 异常场景各列至少一条
 - 可验证、可转为自动化测试断言的条件（明确输入与可观测输出）；场景 ID（S-/E-/B-）即测试用例来源
+- 为每个场景指定测试层级（unit / integration / E2E / manual）和关键真实边界；跨 API、存储、运行时生成、渲染或用户可见结果等多个边界时必须选 E2E
+- RULE 与高影响 RISK 必须映射到至少一个 S/E/B 场景；manual 仅限无法自动化的外部条件，必须写明原因
 
 **妥协与技术债**（按需）
 - 本次有意接受的取舍或欠债？后续偿还设想？
@@ -241,8 +243,10 @@ CLI 场景：
 **追溯硬约束（plan 拆解与质量门的基础）**：
 - 功能清单每个 FEAT 保留"来源"列（PRD 派生填 US-XX；无 PRD 填需求描述）
 - 接口（API/CLI/函数）与验收场景标注其实现 / 覆盖的 FEAT-XX
+- 每个验收场景写明测试层级、关键真实边界和最终可观测结果；编码阶段不得把 E2E 自行降级为 mock 后的 unit/integration 测试
+- 每个 RULE 与高影响 RISK 映射到 S/E/B 场景；只能手动验证时记录原因
 - Full 模板 §6 需求追溯矩阵必须闭合：US → FEAT → API → TC 不留断点，TC 引用 §2.5.2 场景 ID
-- 任一缺口（FEAT 无来源 / FEAT 无验收 / 矩阵断点）在展示时显式列出并提示补全
+- 任一缺口（FEAT 无来源 / FEAT 无验收 / 场景无测试层级或真实边界 / RULE·RISK 无验证场景 / 矩阵断点）在展示时显式列出并提示补全
 
 展示后询问用户：**确认写入？可以调整任何部分。**
 
@@ -274,7 +278,7 @@ CLI 场景：
 内容:
   - <按实际包含的章节列出>
   - 验收标准: N 项
-  - 追溯自检: 每个 FEAT 有来源(US/需求)✓、有验收场景✓；Full 模板 §6 矩阵 US→FEAT→API→TC 闭合，缺口显式列出
+  - 追溯自检: 每个 FEAT 有来源(US/需求)✓、有验收场景✓；每个场景有测试层级和关键真实边界✓；RULE/高影响 RISK 有验证场景✓；Full 模板 §6 矩阵闭合
   - 性能自检: 标记性能敏感则方案须体现最优性能设计依据（§3.1/§3.5 或 lite §3.4），否则提示补全或显式声明"无性能敏感点"
 
 下一步:

package/src/adapters/codex/skills/cf-task-archive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cf-task-archive
-description: Archive a completed task file after three-dimensional validation (completeness, correctness, consistency). Use when all subtasks are done and you want to archive the task file and check for spec updates.
+description: Archive a completed task file after completeness, correctness, traceability, and consistency validation. Use when all subtasks are done and you want to archive the task file and check for spec updates.
 ---
 
 ## 输入
@@ -33,7 +33,7 @@ description: Archive a completed task file after three-dimensional validation (c
 
 ### 2. 归档前校验（Verify）
 
-所有子任务 done 后，执行三维校验：
+所有子任务 done 后，执行四维校验：
 
 **完整性**：
 - 所有 Checklist 项已勾选
@@ -43,6 +43,13 @@ description: Archive a completed task file after three-dimensional validation (c
 - 如果 `.code-flow/validation.yml` 存在，读取验证规则，用 shell 命令执行其中匹配的 `command`（如 `npx tsc --noEmit`、`python3 -m pytest` 等）
 - 检查本次变更涉及的文件是否通过 lint/type check
 
+**验收追溯**：
+- 来源 design 含结构化 S-/E-/B- 场景时，逐项对照 `## Acceptance Coverage`，P0/P1 场景以及 RULE/高影响 RISK 映射场景必须全部存在且状态为 `verified`
+- 每个负责任务的 `Acceptance-Refs`、`Acceptance Contract`、`Acceptance Evidence` 必须闭合，不得残留 `planned` / `pending` / `TBD`
+- 测试层级不得低于 design；E2E 的真实边界和关键断言必须有文件/用例位置与 fixture/构造证据
+- 汇总并重新执行契约中所有唯一验收命令；测试未收集、未执行或失败均为 FAIL
+- `manual` 场景必须有用户确认和可复核记录。旧 design 没有结构化场景时注明“不适用”，不得伪造覆盖
+
 **一致性**：
 - 读取 task 文件的 `## Proposal`，对照实际代码变更，检查意图是否已实现
 
@@ -52,6 +59,7 @@ description: Archive a completed task file after three-dimensional validation (c
 归档前校验:
   [PASS] 完整性: 所有 Checklist 已完成，无未解决 Notes
   [PASS] 正确性: cf-validate 通过
+  [PASS] 验收追溯: 6/6 场景 verified，2 条 E2E 命令通过
   [WARN] 一致性: Proposal 提到"支持 OAuth 登录"，但未发现相关实现
 
 WARN 不阻塞归档，但建议确认后再继续。继续归档？
@@ -79,7 +87,19 @@ mv .code-flow/tasks/<日期>/<需求>/ .code-flow/tasks/archived/<日期>/<需
    ```
 3. 同名 `.design.md` 存在则一并移动：`mv .code-flow/tasks/<日期目录>/<file>.design.md .code-flow/tasks/archived/<日期目录>/`
 4. 同名 `.prd.md` 存在则一并移动：`mv .code-flow/tasks/<日期目录>/<file>.prd.md .code-flow/tasks/archived/<日期目录>/`
-5. 如果原日期目录为空，删除空目录
+
+**归档后统一收尾（布局 A/B 都必须执行）**：
+
+1. 保存源日期目录为 `.code-flow/tasks/<日期>/`，完成移动后检查该目录是否还有其他需求或任务。
+2. 如果目录为空，必须执行安全删除；非空则保留并在摘要中列出剩余条目：
+   ```bash
+   source_date_dir=".code-flow/tasks/<日期>"
+   if [ -d "$source_date_dir" ] && [ -z "$(find "$source_date_dir" -mindepth 1 -maxdepth 1 -print -quit)" ]; then
+     rmdir "$source_date_dir"
+   fi
+   ```
+3. 复查归档目标存在、原任务/需求路径不存在；如果源日期目录仍存在但为空，视为归档未完成，立即删除后再继续。
+4. 源日期目录包含其他条目时不得删除，摘要明确写“保留（仍有 N 个条目）”。
 
 **临时约束清理（FEAT-08）**：删除 `.code-flow/specs/_session/task-<name>.md`（存在时）。该文件由 cf-task-start 生成，归档后不得残留。
 
@@ -128,5 +148,6 @@ Spec 同步建议:
   - 创建日期: 2026-03-15
   - 归档日期: 2026-03-20
   - 历时: 5 天
-  - 校验: 3/3 PASS
+  - 校验: 4/4 PASS
+  - 源日期目录: 已删除（为空）/ 已保留（仍有 N 个条目）
 ```

package/src/adapters/codex/skills/cf-task-plan/SKILL.md

@@ -154,6 +154,15 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 设计简报模式：记录**章节名**，无需行号。
 引用格式：`<name>.design.md#3.3 数据设计`, `<name>.design.md#3.4 接口设计` 等（章节名须与模板真实标题一致）。
 
+**验收契约拆解（硬约束）**：
+
+1. 从全部 design 提取 P0/P1 的 S-/E-/B- 场景，以及 RULE 和高影响 RISK 到场景的映射。
+2. 优先沿用 design 指定的测试层级与关键真实边界。旧 design 未填写时，跨 API、存储、运行时生成、渲染或最终用户可见结果的场景推断为 `E2E`，局部模块协作推断为 `integration`，纯函数约束才可用 `unit`。
+3. 每个场景必须分配给一个负责的 TASK，并写入 `Acceptance-Refs`；同一场景可被多个任务引用，但必须有且仅有一个最终验收负责人。
+4. `manual` 只允许用于无法自动化的外部条件，必须记录原因并经用户明确确认。agent 不得把 design 的 E2E 自行降级为 unit/integration。
+5. Checklist 禁止使用泛化的“编写测试”。必须写成 `[场景ID][测试层级] + 真实边界 + 关键断言`，并为新功能/缺陷修复安排先写测试和 RED 记录。
+6. 如果场景缺测试层级、真实边界或 RULE/高影响 RISK 没有验证场景，先以 `#NOTES` 列为设计缺口；未解决前不得开始编码。
+
 ### 4. 生成任务文件方案
 
 将拆解结果按以下格式组织，展示给用户确认：
@@ -184,12 +193,24 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 
 ---
 
+## Acceptance Coverage
+
+| 场景ID | 来源设计 | 测试层级 | 关键真实边界 | 负责任务 | 状态 |
+|--------|---------|---------|-------------|---------|------|
+| S-01 | xxx.design.md#2.5 验收条件 | E2E | API → Store → Renderer | TASK-001 | planned |
+| E-01 | xxx.design.md#2.5 验收条件 | integration | Service → Store | TASK-001 | planned |
+
+> 本表必须覆盖 design 中全部 P0/P1 场景，以及 RULE/高影响 RISK 映射的场景；存在缺口时不生成可启动任务。
+
+---
+
 ## TASK-001: <子任务标题>
 
 - **Status**: draft
 - **Priority**: P0
 - **Depends**:
 - **Source**: docs/xxx.md#§3.1 数据模型(L83-L110)
+- **Acceptance-Refs**: S-01, E-01, RULE-01
 
 ### Description
 <从设计文档提取的需求重点，不必复制全文>
@@ -197,7 +218,21 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 ### Checklist
 - [ ] <具体实现步骤1>
 - [ ] <具体实现步骤2>
-- [ ] <编写测试>
+- [ ] [S-01][E2E] 修改生产代码前，按 API → Store → Renderer 真实边界编写验收测试并记录 RED
+- [ ] [S-01] 断言 <最终可观测结果 1> 与 <最终可观测结果 2>
+- [ ] [E-01][integration] 覆盖 <异常输入> 与 <可观测失败行为>
+- [ ] 运行验收命令并填写 Acceptance Evidence
+
+### Acceptance Contract
+
+| 场景ID | 测试层级 | 不得 Mock 的真实边界 | 关键断言 | 测试文件 / 用例 | 执行命令 | 状态 |
+|--------|---------|--------------------|---------|----------------|---------|------|
+| S-01 | E2E | API、Store、Renderer | <断言列表> | planned | planned | planned |
+| E-01 | integration | Service、Store | <断言列表> | planned | planned | planned |
+
+### Acceptance Evidence
+
+> `cf-task-start` 在编码期填写 RED/GREEN 结果、每个关键断言的位置和真实组件证据；全部状态 verified 后任务才可 done。
 
 ### Log
 - [<当前日期>] created (draft)
@@ -222,6 +257,7 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 
 TASK-001: <标题> [P0]
   来源: §3.1 数据模型 (L83-L110)
+  验收: S-01(E2E), E-01(integration)
   描述: ...
   Checklist: N 项
   依赖: 无
@@ -257,6 +293,7 @@ TASK-002: <标题> [P1]
 - P0: x 个, P1: y 个, P2: z 个
 - 依赖链深度: N 层
 - 详设引用覆盖: §3.1, §3.2, §3.3, §3.5 (共 4 个章节)
+- 验收覆盖: P0/P1 场景 x/x，RULE/高影响 RISK 映射 y/y，E2E 场景 z 个
 
 建议执行顺序:
   1. TASK-001 (无依赖)

package/src/adapters/codex/skills/cf-task-start/SKILL.md

@@ -24,7 +24,7 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
 
 **状态检查**：Status 必须为 `draft`。若为其他状态：
 - `in-progress` → 提示"任务已在进行中，继续编码"（不阻塞，直接跳到步骤 2）
-- `done` → 提示"任务已完成"，结束
+- `done` → 先执行验收契约检查；全部 verified 才提示"任务已完成"并结束，否则恢复为 `in-progress`，列出缺口并继续补齐测试与证据
 - `blocked` → 提示"任务被阻塞"，列出 Notes 中的阻塞原因，结束
 
 **#NOTES 检查**：扫描该子任务段落全文（Description、Checklist 等）
@@ -36,6 +36,12 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
 - 所有依赖必须为 `done`
 - 未满足 → 输出：`前置检查失败：以下依赖未完成\n- TASK-001: in-progress\n- TASK-003: draft`
 
+**验收契约检查**：
+- 如果 task 含 `## Acceptance Coverage`，当前子任务必须有 `Acceptance-Refs`、`Acceptance Contract` 和 `Acceptance Evidence`
+- `Acceptance-Refs` 中每个 S-/E-/B- 都必须出现在全局覆盖表和当前契约中，测试层级与关键真实边界必须和 design 一致
+- 旧 task 没有覆盖表但来源 design 含结构化验收场景时，先从 design 回填覆盖表与契约；回填完成前不得修改生产代码
+- 非行为类任务可显式写 `Acceptance-Refs: N/A`；不得用 N/A 跳过已有设计场景
+
 ### 2. 加载详设上下文
 
 前置检查通过后，**编码前先加载关联的详设文档章节**：
@@ -45,26 +51,50 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
    - 提取：文件路径 + 行号范围
 2. 按行号范围读取详设文档的对应章节（使用 offset/limit 参数）
 3. 将读取的章节内容作为编码上下文，与 Checklist 一起指导实现
+4. 按 `Acceptance-Refs` 精确读取验收场景及其关联 RULE/RISK；不得只依赖摘要，也不得遗漏场景的测试层级、关键真实边界和预期结果
 
 示例：Source 为 `docs/auth.md#§3.2 API 接口(L111-L155), docs/auth.md#§3.5 错误码(L201-L220)`
 → 读取 `docs/auth.md` offset=111 limit=45
 → 读取 `docs/auth.md` offset=201 limit=20
 
-### 3. 激活并编码
+### 3. 激活并准备验收测试
 
 1. 用 apply_patch 更新子任务 Status 为 `in-progress`
 2. 在 `### Log` 追加：`- [<当前日期>] started (in-progress)`
 3. 更新文件头 `Updated` 日期
-4. 结合详设上下文 + Checklist，逐项执行编码工作
-5. 每完成一个 checklist 项 → 用 apply_patch 将 `- [ ]` 改为 `- [x]`
+4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
+5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
+6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
+
+RED 证据写入 `Acceptance Evidence`：
+
+```markdown
+| 场景ID | RED | GREEN | 断言位置 | 真实边界证据 | 状态 |
+|--------|-----|-------|---------|-------------|------|
+| S-01 | FAIL: generation 未递增 | pending | pending | real Store + Renderer fixture | test-written |
+```
+
+### 3.1 实现与逐项更新
+
+1. RED 证据就绪后，结合详设上下文、Acceptance Contract 与 Checklist 修改生产代码
+2. 每完成一个 checklist 项，用 apply_patch 将 `- [ ]` 改为 `- [x]`
+3. 如果实现中发现必须改变测试层级或真实边界，停止编码并记录 `#NOTES`，经用户确认并同步 design 后才能继续；agent 不得自行降级
+
+### 3.2 GREEN 与验收证据
+
+1. 执行每个契约中的验收命令，再执行受影响范围的回归测试
+2. 对每个预期结果记录对应的测试断言位置，并指出 fixture/构造路径如何证明关键边界使用真实组件
+3. 将 `Acceptance Contract` 行状态改为 `verified`，将 `Acceptance Evidence` 补齐 GREEN、断言位置和边界证据
+4. 负责该场景的任务验证完成后，将全局 `Acceptance Coverage` 对应行改为 `verified`
+5. 测试文件存在但未被测试框架收集、命令未实际执行、只有场景 ID 没有关键断言，都视为未验证
 
 ### 3.5 会话级临时约束（FEAT-08）
 
 激活后，若任务文件头 Source 指向的 design 文档含验收条件章节（如 §2.5 验收条件 / 验收标准）：
 
-1. 提取该章节的场景与 RULE 约束，生成 `.code-flow/specs/_session/task-<name>.md`：
+1. 只提取当前任务 `Acceptance-Refs` 对应的场景、测试层级、关键真实边界与 RULE/RISK，生成 `.code-flow/specs/_session/task-<name>.md`：
    - frontmatter：`description: 当前任务 <name> 的验收约束（cf-task:start 生成，archive 清理）`
-   - 正文：验收场景与约束的精简列表（≤300 token）
+   - 正文：验收场景与约束的精简列表（≤300 token）；必须保留全部引用 ID、层级、边界和预期结果，不能为压缩而删除场景
 2. Spec Catalog 目录扫描自动纳入该文件，无需配置；编辑代码时的自动注入同样生效
 3. design 无验收章节时静默跳过；同名文件已存在则覆盖（同任务重复 start）
 
@@ -72,12 +102,21 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
 
 ### 4. 自动完成
 
-当所有 checklist 项都勾选为 `[x]` 后：
+只有同时满足以下条件才能自动完成：
+- 所有 checklist 项均为 `[x]`
+- 每个 Acceptance-Ref 在契约、证据和全局覆盖表中均为 `verified`，不存在 `planned` / `pending` / `TBD`
+- 测试层级未低于 design，关键真实边界没有被 mock 绕过
+- 每个预期结果都有具体断言位置，验收命令和回归测试均已实际通过
+- `manual` 场景已有用户确认和可复核记录
+
+满足后：
 1. 用 apply_patch 更新 Status 为 `done`
 2. 在 `### Log` 追加：`- [<当前日期>] completed (done)`
 3. 更新文件头 `Updated` 日期
 4. 输出：`TASK-xxx 已完成`
 
+任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
+
 ### 5. 文档同步检查
 
 子任务完成后，轻量检查本次编码是否引入了需要同步到 specs 或导航地图的内容：
@@ -145,7 +184,7 @@ Spec 同步提示:
 
 ### 4. 按序执行
 
-对每个可激活的子任务，执行单任务模式的步骤 3-4（详设已在步骤 2 加载，无需重复读取）。
+对每个可激活的子任务，执行单任务模式的步骤 3-4，包括先写验收测试、RED、实现、GREEN 和证据核对（详设已在步骤 2 加载，无需重复读取）。
 
 完成一个子任务后，检查是否解锁了新的子任务（依赖已满足），如果是则继续执行。
 

package/src/adapters/costrict/commands/cf-task/align.md

@@ -160,6 +160,8 @@ CLI 场景：
 **验收标准**（必选）
 - 怎么判断做完了？正常 / 异常场景各列至少一条
 - 可验证、可转为自动化测试断言的条件（明确输入与可观测输出）；场景 ID（S-/E-/B-）即测试用例来源
+- 为每个场景指定测试层级（unit / integration / E2E / manual）和关键真实边界；跨 API、存储、运行时生成、渲染或用户可见结果等多个边界时必须选 E2E
+- RULE 与高影响 RISK 必须映射到至少一个 S/E/B 场景；manual 仅限无法自动化的外部条件，必须写明原因
 
 **妥协与技术债**（按需）
 - 本次有意接受的取舍或欠债？后续偿还设想？
@@ -240,8 +242,10 @@ CLI 场景：
 **追溯硬约束（plan 拆解与质量门的基础）**：
 - 功能清单每个 FEAT 保留"来源"列（PRD 派生填 US-XX；无 PRD 填需求描述）
 - 接口（API/CLI/函数）与验收场景标注其实现 / 覆盖的 FEAT-XX
+- 每个验收场景写明测试层级、关键真实边界和最终可观测结果；编码阶段不得把 E2E 自行降级为 mock 后的 unit/integration 测试
+- 每个 RULE 与高影响 RISK 映射到 S/E/B 场景；只能手动验证时记录原因
 - Full 模板 §6 需求追溯矩阵必须闭合：US → FEAT → API → TC 不留断点，TC 引用 §2.5.2 场景 ID
-- 任一缺口（FEAT 无来源 / FEAT 无验收 / 矩阵断点）在展示时显式列出并提示补全
+- 任一缺口（FEAT 无来源 / FEAT 无验收 / 场景无测试层级或真实边界 / RULE·RISK 无验证场景 / 矩阵断点）在展示时显式列出并提示补全
 
 展示后询问用户：**确认写入？可以调整任何部分。**
 
@@ -273,7 +277,7 @@ CLI 场景：
 内容:
   - <按实际包含的章节列出>
   - 验收标准: N 项
-  - 追溯自检: 每个 FEAT 有来源(US/需求)✓、有验收场景✓；Full 模板 §6 矩阵 US→FEAT→API→TC 闭合，缺口显式列出
+  - 追溯自检: 每个 FEAT 有来源(US/需求)✓、有验收场景✓；每个场景有测试层级和关键真实边界✓；RULE/高影响 RISK 有验证场景✓；Full 模板 §6 矩阵闭合
   - 性能自检: 标记性能敏感则方案须体现最优性能设计依据（§3.1/§3.5 或 lite §3.4），否则提示补全或显式声明"无性能敏感点"
 
 下一步: