@michaelxwb/code-flow 0.6.5 → 1.0.0

package/templates/skills/cf-task-start.md

@@ -0,0 +1,41 @@
+---
+name: cf-task-start
+description: Start one TASK or the next dependency batch.
+---
+<!-- code-flow:v1 -->
+Use `code-flow task status --json` to locate the task document and IDs. Never infer a Task from its status.
+
+Single Task:
+
+```bash
+code-flow task start <task-document>.md --task TASK-001 --session <token>
+```
+
+Batch (dependency layer):
+
+1. Read `Depends`, choose the next ready layer, and create worktrees:
+
+```bash
+code-flow task parallel prepare --task-file <task-document>.md --tasks TASK-001,TASK-002 --run-id <id> --workers 2
+```
+
+2. Read `workers` and each worker `env` from the run ledger. Dispatch no more than `workers` workers at once (default 2), one worker per Task. Give each worker its ledger `CF_*` environment. Workers use the global CLI; prepare does not install tool files into them. Add `--init` only when a host session must run inside a worker.
+
+3. In each worker: start → implement → **finish**. `finish` is the only test entry and runs the Task's declared tests; do not run those tests a second time before finish.
+
+```bash
+code-flow task start <task-document>.md --task TASK-001 --session <token>
+code-flow task finish <task-document>.md --task TASK-001 --json
+```
+
+Commit the worker's business changes and its own TASK section after `finish`.
+
+4. From the coordinator, collect, merge/integrate, then cleanup:
+
+```bash
+code-flow task parallel collect --run-id <id> --json
+code-flow task parallel merge --run-id <id> --json
+code-flow task parallel cleanup --run-id <id> --json
+```
+
+If merge or integration fails, stop and keep the worktrees, branches and ledger for inspection. Do not run `task archive` inside a worker; archive only in the coordinator worktree after the run is complete. E2E and full regression stay in CI.

package/{src/core/code-flow/specs/shared/design → templates/workflow}/design-frontend.md

@@ -1,5 +1,7 @@
 # {模块名称} 前端模块需求与设计简报
 
+> **生成约定**：产出文档的 frontmatter 声明 `design_template: frontend`。验收场景引用 `<需求>.scenarios.md` 的 S-/E-/B- 场景 ID；场景是人工验收参照，不生成集中验收清单或结果登记，不阻断 start/finish/archive。设计需要给出真实可执行的相关测试建议，由任务文档声明。
+
 > **文档编号**: FE-{模块代号}-{版本号}
 > **文档版本**: v1.0
 > **创建日期**: YYYY-MM-DD
@@ -24,6 +26,7 @@
   - [2.2 功能方案](#22-功能方案-必填)
   - [2.3 范围与边界](#23-范围与边界-必填)
   - [2.4 验收条件](#24-验收条件-必填)
+    - [2.4.1 验证环境假设](#241-验证环境假设-必填)
 - [3. 前端技术设计](#3-前端技术设计)
   - [3.1 技术选型](#31-技术选型-必填)
   - [3.2 页面与路由结构](#32-页面与路由结构-必填)
@@ -90,25 +93,25 @@
 
 ### 2.4 验收条件 [必填]
 
-> 交互层面的可验证场景，写到可转 E2E / 组件交互测试断言的粒度（明确操作与可观测 UI 结果）。场景 ID 即测试用例来源。测试层级只能填 `unit` / `integration` / `E2E` / `manual`；跨路由、服务请求、状态更新和最终 UI 的用户流程必须标为 `E2E`。关键真实边界列出不得 mock 的浏览器、路由、状态或服务边界。
-
-**正常场景**
-
-| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 操作步骤 | 预期 UI 结果 |
-|--------|--------|--------|---------|-------------|---------|-------------|
-| S-01 | FEAT-01 | P0 | E2E | Browser → Router → Service → UI | 1. <操作> | <可见结果> |
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。本节只保留场景引用和前端设计影响，不复制完整场景表；场景只记录人工验收所需的 step / expected / boundary / owner；没有可执行命令的场景标为 manual。
+>
+> **前端 E2E 精度**：表单交互、布局、文案、字段顺序、空态和错误提示用 component + mock API；E2E 只保留真实浏览器 + 真实后端 + 鉴权/DB 的关键用户旅程，并写清可观察结果。禁止源码字符串/CSS/宽度断言。
 
-**异常场景**
+| 场景ID | 前端设计影响 / 备注 |
+|--------|--------------------|
+| S-01 | 正常交互路径；涉及的页面、组件与真实边界 |
+| E-01 | 异常/空态路径；涉及的组件状态与用户可见反馈 |
 
-| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | UI 表现 |
-|--------|--------|---------|-------------|---------|---------|
-| E-01 | FEAT-01 | integration | Service → UI | （接口失败 / 空数据 / 校验不通过） | （错误提示 / 空态 / 字段定位） |
+#### 2.4.1 验证环境假设 [必填]
 
-**非功能指标** [按需]
+> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行时缺少环境应由人工验收记录缺失项与 owner，不得伪装成产品失败。
 
-| 指标ID | 指标名称 | 目标值 | 测量方法 |
-|--------|---------|-------|---------|
-| NFR-PERF-01 | 首屏 / 交互响应 | 待定 | Lighthouse / 实测 |
+| 维度 | 假设 | 验证方式 / 参数 | 不满足时 |
+|------|------|----------------|---------|
+| 容量 | （页面/组件规模、并发用户、浏览器矩阵；无实测填"待定"） | Playwright projects / 基准 fixture | 记录缺失项与 owner，拆分批次 |
+| 硬件 | （CI runner / 设备 / 视口规格） | 人工检查 | 记录缺失项与 owner |
+| 依赖 | （后端 API / 浏览器版本 / 测试账号 / 字体与静态资源） | 人工检查 | 记录缺失项与 owner |
+| 测试预算 | （Task tests 的 unit/integration 范围；E2E 与全量回归留在 CI） | 人工核对任务文档 | 记录未覆盖风险与 owner |
 
 ---
 
@@ -235,11 +238,11 @@
 
 ## Spec Compliance Matrix
 
-> 从需求目录 `spec-context.yml` 继承并逐 Rule 回填。required Rule 必须有具体设计落点和 verifier/验收场景；N/A 只接受逐项用户确认。
+> 从当前适用 Spec 与任务 `Spec-Refs` 读取 Rule，并逐条回填设计影响、设计落点与人工验收场景。
 
-| Spec/Rule | enforcement | 设计影响 | 设计落点 | 验证场景 | 状态/N/A 理由 |
-|-----------|-------------|---------|---------|---------|----------------|
-| `{spec-id}#RULE-{domain}-001` | required / advisory | <对方案/交互的影响> | §<heading> / <item-id> | S-/E-/B- + verifier | applied / confirmed N/A |
+| Spec/Rule | 设计影响 | 设计落点 | 验收场景 | 状态/N/A 理由 |
+|-----------|---------|---------|---------|----------------|
+| `{spec-id}#RULE-{domain}-001` | <对方案/交互的影响> | §<heading> / <item-id> | S-/E-/B- | applied / confirmed N/A |
 
 ---
 

package/{src/core/code-flow/specs/shared/design → templates/workflow}/design-full.md

@@ -1,5 +1,7 @@
 # {模块名称} 模块需求与设计一体化文档
 
+> **生成约定**：产出文档的 frontmatter 声明 `design_template: full`。验收场景引用 `<需求>.scenarios.md` 的 S-/E-/B- 场景 ID；场景是人工验收参照，不生成集中验收清单或结果登记，不阻断 start/finish/archive。设计需要给出真实可执行的相关测试建议，由任务文档声明。
+
 > **文档编号**: MOD-{模块代号}-{版本号}
 > **文档版本**: v1.0
 > **创建日期**: YYYY-MM-DD
@@ -28,6 +30,7 @@
   - [2.3 功能方案](#23-功能方案-必填)
   - [2.4 范围与边界](#24-范围与边界-必填)
   - [2.5 验收条件](#25-验收条件-必填)
+    - [2.5.4 验证环境假设](#254-验证环境假设-必填)
 - [3. 技术设计](#3-技术设计)
   - [3.1 方案选型](#31-方案选型-必填)
   - [3.2 架构设计](#32-架构设计-必填)
@@ -131,6 +134,8 @@
 
 ### 2.5 验收条件 [必填]
 
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。本节只保留业务规则、设计影响和场景引用；不要在此复制完整全局场景表。
+
 #### 2.5.1 业务规则与约束
 
 | ID | 类型 | 描述 | 验证场景 |
@@ -140,27 +145,17 @@
 
 #### 2.5.2 功能验收场景
 
-> 场景写到可转自动化测试断言的粒度（明确前置、输入、可观测输出）。场景 ID（S-/E-/B-）即测试用例来源，§6 追溯矩阵直接引用这些场景 ID。
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。设计文档只引用全局场景 ID，并说明设计影响，不复制完整场景字段；场景只记录人工验收所需的 step / expected / boundary / owner；没有可执行命令的场景标为 manual。
 >
-> **测试层级**只能填 `unit` / `integration` / `E2E` / `manual`。跨 API、存储、运行时生成、渲染或用户可见结果等多个边界的场景必须标为 `E2E`；`manual` 仅限无法自动化的外部条件，并记录原因。**关键真实边界**列出测试中不得 mock 的组件或最终可观测面，编码阶段不得自行降级。
-
-**正常场景**
-
-| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 前置条件 | 操作步骤 | 预期结果 |
-|--------|--------|--------|---------|-------------|---------|---------|---------|
-| S-01 | FEAT-01 | P0 | E2E | API → Store → 最终输出 | | | |
-
-**异常场景**
-
-| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | 系统行为 | 用户感知 |
-|--------|--------|---------|-------------|---------|---------|---------|
-| E-01 | FEAT-01 | integration | Service → Store | | | |
-
-**边界场景** [按需]
+> **E2E 精度**：E2E 只用于关键用户旅程，并写清真实边界与可观察结果。UI 布局/文案/字段顺序用 component，DTO/错误码用 contract，鉴权/事务/模块边界用 integration；不要把 E2E 当成所有用户可见结果的默认层级。
+>
+> ✅ CAS 409：contract 验响应、component 验表单保留、integration 用真实存储验并发；聚合补零与关系绑定同样优先采用相应低层组合。Cookie 隔离和 SSE 恢复保留必要的跨边界关键验证。❌ 设固定 E2E 数量或比例；比例和任务耗时仅作诊断，零 E2E 的完整覆盖合法。
 
-| 场景ID | 测试层级 | 关键真实边界 | 字段/条件 | 边界值 | 预期行为 |
-|--------|---------|-------------|----------|--------|---------|
-| B-01 | unit | 校验函数 | | | |
+| 场景ID | 设计影响 / 备注 |
+|--------|----------------|
+| S-01 | 正常路径；涉及的设计组件与真实边界 |
+| E-01 | 异常路径；涉及的设计组件与失败表现 |
+| B-01 | 边界条件；按需 |
 
 #### 2.5.3 非功能指标 [按需]
 
@@ -184,6 +179,17 @@
 | NFR-SEC-01 | 认证鉴权 | 未授权用户无法访问 |
 | NFR-SEC-02 | 数据加密 | 敏感字段不可明文 |
 
+#### 2.5.4 验证环境假设 [必填]
+
+> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行时缺少环境应由人工验收记录缺失项与 owner，不得伪装成产品失败。
+
+| 维度 | 假设 | 验证方式 / 参数 | 不满足时 |
+|------|------|----------------|---------|
+| 容量 | （数据量、并发数、场景规模；无实测填"待定"） | 基准 fixture / 压测命令 | 记录缺失项与 owner，拆分批次 |
+| 硬件 | （CPU / 内存 / 磁盘 / 网络规格，如 8C16G） | 人工检查 | 记录缺失项与 owner |
+| 依赖 | （数据库 / 浏览器 / API / CI runner / 端口 / 测试账号） | 人工检查 | 记录缺失项与 owner |
+| 测试预算 | （Task tests 的 unit/integration 范围；E2E 与全量回归留在 CI） | 人工核对任务文档 | 记录未覆盖风险与 owner |
+
 ---
 
 ## 3. 技术设计
@@ -465,23 +471,25 @@ flowchart TD
 
 ---
 
-## 6. 需求追溯矩阵
+## 6. 需求追溯矩阵（生成式）
+
+> 本节由设计者手工维护，用于把 PRD 用户故事、功能/接口 ID 与场景 ID 对齐。场景只是人工验收参照；`cf-task:plan` 将相关场景映射到任务段落。
 
-| 用户故事 | 功能ID | 接口ID | 测试用例ID | 测试层级 | 状态 |
-|---------|--------|--------|-----------|---------|------|
-| US-01 | FEAT-01 | API-01 | S-01 | E2E | 待实现 |
+| 用户故事 | 功能ID | 接口ID | 场景ID | 测试层级 | 执行方式 | 负责 TASK | 状态 |
+|---------|--------|--------|--------|---------|---------|----------|------|
+| US-01 | FEAT-01 | API-01 | S-01 | e2e | manual | TASK-001 | 待实现 |
 
-> 用户故事一列引用 PRD 中的 US-XX（无 PRD 时填"需求描述"）；测试用例 ID 列引用 §2.5.2 的场景 ID（S-/E-/B-），不要另造编号。RULE 与高影响 RISK 必须映射到场景；无法自动化时写明手动验证原因，不得留空。
+> 用户故事一列引用 PRD 中的 US-XX（无 PRD 时填"需求描述"）；场景 ID 引用 `<需求>.scenarios.md` 的 S-/E-/B-，不要另造编号。RULE 与高影响 RISK 应映射到场景；无法自动化时写明人工验证原因，不得留空。
 
 ---
 
 ## Spec Compliance Matrix
 
-> 从需求目录 `spec-context.yml` 继承并逐 Rule 回填。required Rule 必须有具体设计落点和 verifier/验收场景；N/A 只接受逐项用户确认。
+> 从当前适用 Spec 与任务 `Spec-Refs` 读取 Rule，并逐条回填设计影响、设计落点与人工验收场景。
 
-| Spec/Rule | enforcement | 设计影响 | 设计落点 | 验证场景 | 状态/N/A 理由 |
-|-----------|-------------|---------|---------|---------|----------------|
-| `{spec-id}#RULE-{domain}-001` | required / advisory | <对方案的影响> | §<heading> / <item-id> | S-/E-/B- + verifier | applied / confirmed N/A |
+| Spec/Rule | 设计影响 | 设计落点 | 验收场景 | 状态/N/A 理由 |
+|-----------|---------|---------|---------|----------------|
+| `{spec-id}#RULE-{domain}-001` | <对方案的影响> | §<heading> / <item-id> | S-/E-/B- | applied / confirmed N/A |
 
 ---
 

package/{src/core/code-flow/specs/shared/design → templates/workflow}/design-lite.md

@@ -1,5 +1,7 @@
 # {模块名称} 模块需求与设计简报
 
+> **生成约定**：产出文档的 frontmatter 声明 `design_template: lite`。验收场景引用 `<需求>.scenarios.md` 的 S-/E-/B- 场景 ID；场景是人工验收参照，不生成集中验收清单或结果登记，不阻断 start/finish/archive。设计需要给出真实可执行的相关测试建议，由任务文档声明。
+
 > **文档编号**: MOD-{模块代号}-{版本号}
 > **文档版本**: v1.0
 > **创建日期**: YYYY-MM-DD
@@ -29,6 +31,7 @@
   - [2.2 功能方案](#22-功能方案-必填)
   - [2.3 范围与边界](#23-范围与边界-必填)
   - [2.4 验收条件](#24-验收条件-必填)
+    - [2.4.3 验证环境假设](#243-验证环境假设-必填)
 - [3. 技术设计](#3-技术设计)
   - [3.1 技术选型](#31-技术选型-必填)
   - [3.2 架构设计](#32-架构设计-必填)
@@ -106,23 +109,19 @@
 
 ### 2.4 验收条件 [必填]
 
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。本节只保留业务规则、设计影响和场景引用；不要在此复制完整全局场景表。
+
 #### 2.4.1 功能验收场景
 
-> 每个 P0/P1 FEAT 至少 1 条正常 + 1 条异常场景；"操作步骤/预期结果"写到可直接转为自动化测试断言的粒度（明确输入与可观测输出）。场景 ID（S-/E-/B-）即测试用例编号，供 plan 拆解引用。
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。设计文档只引用全局场景 ID，并说明设计影响，不复制完整场景字段；场景只记录人工验收所需的 step / expected / boundary / owner；没有可执行命令的场景标为 manual。
 >
-> **测试层级**只能填 `unit` / `integration` / `E2E` / `manual`。跨 API、存储、运行时生成、渲染或用户可见结果等多个边界的场景必须标为 `E2E`；`manual` 仅限无法自动化的外部条件，并记录原因。**关键真实边界**列出测试中不得 mock 的组件或最终可观测面，编码阶段不得自行降级。
-
-**正常场景**
-
-| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 操作步骤 | 预期结果 |
-|--------|--------|--------|---------|-------------|---------|---------|
-| S-01 | FEAT-01 | P0 | E2E | API → Store → 最终输出 | 1. <步骤><br>2. <步骤> | <结果> |
+> **E2E 精度**：E2E 只用于关键用户旅程，并写清真实边界与可观察结果。UI 布局/文案/字段顺序用 component，DTO/错误码用 contract，鉴权/事务/模块边界用 integration。
 
-**异常场景**
-
-| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | 系统行为 |
-|--------|--------|---------|-------------|---------|---------|
-| E-01 | FEAT-01 | integration | Service → Store | | |
+| 场景ID | 设计影响 / 备注 |
+|--------|----------------|
+| S-01 | 正常路径；涉及的设计组件与真实边界 |
+| E-01 | 异常路径；涉及的设计组件与失败表现 |
+| B-01 | 边界条件；按需 |
 
 #### 2.4.2 非功能指标 [按需]
 
@@ -131,6 +130,17 @@
 | NFR-PERF-01 | 响应时间（P95） | ≤200ms | APM监控 |
 | NFR-REL-01 | 可用性（SLA） | ≥99.9% | 年度可用时长 |
 
+#### 2.4.3 验证环境假设 [必填]
+
+> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行时缺少环境应由人工验收记录缺失项与 owner，不得伪装成产品失败。
+
+| 维度 | 假设 | 验证方式 / 参数 | 不满足时 |
+|------|------|----------------|---------|
+| 容量 | （数据量、并发数、场景规模；无实测填"待定"） | 基准 fixture / 压测命令 | 记录缺失项与 owner，拆分批次 |
+| 硬件 | （CPU / 内存 / 磁盘 / 网络规格） | 人工检查 | 记录缺失项与 owner |
+| 依赖 | （数据库 / 浏览器 / API / 端口 / 测试账号） | 人工检查 | 记录缺失项与 owner |
+| 测试预算 | （Task tests 的 unit/integration 范围；E2E 与全量回归留在 CI） | 人工核对任务文档 | 记录未覆盖风险与 owner |
+
 ---
 
 ## 3. 技术设计
@@ -284,11 +294,11 @@ flowchart TD
 
 ## Spec Compliance Matrix
 
-> 从需求目录 `spec-context.yml` 继承并逐 Rule 回填。required Rule 必须有具体设计落点和 verifier/验收场景；N/A 只接受逐项用户确认。
+> 从当前适用 Spec 与任务 `Spec-Refs` 读取 Rule，并逐条回填设计影响、设计落点与人工验收场景。
 
-| Spec/Rule | enforcement | 设计影响 | 设计落点 | 验证场景 | 状态/N/A 理由 |
-|-----------|-------------|---------|---------|---------|----------------|
-| `{spec-id}#RULE-{domain}-001` | required / advisory | <对方案的影响> | §<heading> / <item-id> | S-/E-/B- + verifier | applied / confirmed N/A |
+| Spec/Rule | 设计影响 | 设计落点 | 验收场景 | 状态/N/A 理由 |
+|-----------|---------|---------|---------|----------------|
+| `{spec-id}#RULE-{domain}-001` | <对方案的影响> | §<heading> / <item-id> | S-/E-/B- | applied / confirmed N/A |
 
 ---
 

package/{src/core/code-flow/specs/shared/prd-template.md → templates/workflow/prd.md}

@@ -175,7 +175,7 @@
 
 ## 8. Existing Spec Constraints
 
-> 仅列出 `stages` 含 `prd` 且已绑定到 `spec-context.yml` 的 Rule。required Rule 必须明确落到范围、FEAT 验收或 NFR；不适用必须逐条记录用户确认，不能由 Agent 自行填写 N/A。
+> 仅列出当前适用 Spec 中与需求范围相关的 Rule。Rule 必须明确落到范围、FEAT 验收或 NFR；不适用必须逐条记录用户确认，不能由 Agent 自行填写 N/A。
 
 | Spec/Rule | 约束 | 对范围/验收的影响 | 状态 |
 |-----------|------|------------------|------|

package/templates/workflow/project-guidelines.md

@@ -0,0 +1,48 @@
+# 项目规范（starter）
+
+> 这是项目自己的规范说明，位于 `.code-flow/templates/project-guidelines.md`。
+> 把它复制/改写为项目内容，写入 `CLAUDE.md` / `AGENTS.md` 的 code-flow 托管块之外。
+> 不要修改 `<!-- code-flow:v1 start --> ... <!-- code-flow:v1 end -->` 托管块，也不要覆盖用户已有内容。
+
+## 项目身份
+
+- 项目：
+- 主要语言 / 运行时：
+- 包管理器 / 版本约束：
+- 代码风格 / 格式化：
+
+## 架构与边界
+
+- 入口与核心模块：
+- 数据与持久化：
+- 外部服务 / 依赖：
+- 不应跨越的模块边界：
+
+## 开发命令
+
+- 安装：
+- 单元 / 集成测试：
+- 完整回归 / E2E（CI）：
+- 构建 / 发布：
+
+## 规范来源（模型必须阅读）
+
+- `.code-flow/specs/` 是本项目的规范事实源；实现前读取当前 Task 的 `Spec-Refs`。
+- `.code-flow/config.json` 的 `always` / `paths` 决定哪些 Spec 会被注入；新增 Spec 后同步更新引用。
+- Task 文档的 `### Tests` 声明相关测试；`task finish` 执行声明测试，通过后才写 done。
+- 设计文档（PRD/design/scenarios）是项目资产，不是 prompt 输入；`workflow: hook`（默认）不要求它们，`workflow: full` 或复杂需求才使用。
+
+## Spec 编写约定
+
+- 路径身份：`.code-flow/specs/<path>.md`，引用时不带 `.md`；不要用标签或相似度匹配。
+- JSON frontmatter：`{"description":"...","next_rule":<当前最大数字 ID + 1>}`。
+- 在 `## Rules` 下使用稳定的 `RULE-NNN` 或语义 ID；每条规则写清触发条件、可验证的 ✅/❌ 示例。
+- 共享基础规则放 `always`；领域规则放 `paths` 的文件 glob；Task 通过 `Spec-Refs` 引用。
+- 数字 ID 从 `next_rule` 单调分配，删除后不复用；保留 `## Applied Deltas` 记录，保证重试安全。
+- 规范要可执行：避免“注意质量”这类口号，写成可检查的约束和边界。
+
+## 完成标准
+
+- Task 的 tests 只声明有意义的 unit/integration；完整回归 / E2E 留在 CI。
+- 测试失败、超时或中断时保持 in-progress，不写 done。
+- 归档只应用 Spec Delta 并移动需求，不执行测试。

package/templates/workflow/scenarios.md

@@ -0,0 +1,67 @@
+---
+id: scenarios-template
+description: Manual acceptance scenarios referenced by designs and tasks
+---
+
+# {需求名} 验收场景
+
+> 本文件是设计、计划与人工验收共同引用的场景清单。场景不生成集中验收清单、不登记执行结果，也不阻断 `task finish` 或 `task archive`。`cf-task:plan` 只把场景 ID 写入 Task 的 `Scenarios` 字段。
+
+```yaml
+schema: 1
+requirement: {需求名}
+scenarios:
+  - id: S-01
+    title: 正常完成主流程
+    level: manual
+    boundary: 真实入口与真实依赖
+    preconditions:
+      - 已准备可复现的测试数据
+    steps:
+      - 执行用户会执行的主要操作
+    expected:
+      - 出现可观察且可断言的预期结果
+    exec: manual
+    owner: TASK-001
+  - id: E-01
+    title: 关键依赖失败时明确报错
+    level: integration
+    boundary: 外部服务超时或返回错误
+    preconditions: []
+    steps:
+      - 触发依赖失败
+    expected:
+      - 返回明确错误，不产生部分写入
+    exec: manual
+    owner: TASK-001
+  - id: B-01
+    title: 边界输入保持稳定
+    level: manual
+    boundary: 空值、最大长度或并发边界
+    preconditions: []
+    steps:
+      - 输入边界值
+    expected:
+      - 行为符合设计约束，错误信息可理解
+    exec: manual
+    owner: TASK-002
+```
+
+字段说明：
+
+| 字段 | 说明 |
+|---|---|
+| id | S-/E-/B- 编号，需求内唯一 |
+| title | 场景标题 |
+| level | unit / component / contract / integration / system / e2e / manual |
+| boundary | 关键真实边界；manual 场景写清人工步骤 |
+| preconditions / steps / expected | 人工验收可复现的输入与可观察结果 |
+| exec | manual / local / ci；e2e 可写 `ci:<job>` |
+| owner | 负责 TASK 或人工验收人 |
+
+约束：
+
+- 场景是人工执行标准和追溯资产，不是测试清单或执行证明。
+- 不创建集中验收清单、check 注册表或证据缓存。
+- `tests` 只声明快速 unit/integration；E2E 和全量回归留在 CI。
+- `finish` 只跑 Task 的 `tests`，不解析本文件；`archive` 也不解析。

package/templates/workflow/task.md

@@ -0,0 +1,56 @@
+---
+{"version":1,"requirement":"{requirement}"}
+---
+# Tasks: {requirement}
+
+<!--
+一个需求一份任务文档。每个 TASK 使用一个 `## TASK-NNN: 标题` 段。
+不要把 TASK 拆成单独文件。
+-->
+
+## TASK-001: {title}
+
+- **Status**: draft
+- **Depends**:
+- **Source**: {design}.design.md#{section}
+- **Scenarios**: {S-01, E-01}
+- **Spec-Refs**: {spec/path}
+- **Paths**: {src/**, test/**}
+- **E2E**: {ci:e2e or empty}
+- **Skip-Tests**:
+- **Skip-Reason**:
+
+### Tests
+
+```json
+[
+  {
+    "id": "unit",
+    "argv": ["node", "--test", "test/example.test.js"],
+    "timeout": 120,
+    "parallel": true
+  }
+]
+```
+
+### Description
+
+{实现目标}
+
+### Checklist
+
+- [ ] {可验证的步骤}
+
+### Spec Delta
+
+```json
+[]
+```
+
+### Log
+
+- [{date}] created
+
+### Verification
+
+- 尚未执行

package/docs/migrations/spec-workflow-0.6.0.md

@@ -1,42 +0,0 @@
-# Spec Workflow 0.6.0 Migration
-
-0.6.0 replaces prompt-keyword/full injection with one Context-first runtime. It is a breaking, transactional migration; `code-flow init` will not overwrite a 0.4.2–0.5.x project before migration.
-
-## Upgrade
-
-```bash
-code-flow migrate --spec-workflow --dry-run
-code-flow migrate --spec-workflow --prepare
-cf-spec migrate --plan .code-flow/migrations/<id>/migration-plan.json  # only when unresolved exists
-code-flow migrate --spec-workflow --apply --plan .code-flow/migrations/<id>/migration-plan.json
-code-flow init --platform=<claude|codex|costrict|opencode>
-```
-
-`--dry-run` performs no project writes. `--prepare` creates `.code-flow/migrations/<id>/backup/`, empty staging, a source-hash-bound plan, and `journal.json`. Apply refuses unresolved decisions or source hash drift. `.code-flow/.version` is written as `0.6.0` only after every target hash is committed.
-
-## Backup and rollback
-
-The backup stores the exact bytes present at prepare time, including dirty working-tree and user-managed files. Keep it until the migrated project has passed its normal tests.
-
-```bash
-code-flow migrate --spec-workflow --rollback <id>
-```
-
-Rename/EXDEV failures automatically roll back. If interruption leaves `committing`, rerunning apply finishes only when every target hash is proven; otherwise it restores the backup. `recovery_required` must be resolved before Hooks or task commands continue.
-
-## Unsupported older projects
-
-Projects older than 0.4.2 must first bridge through the previous release:
-
-```bash
-npx @michaelxwb/code-flow@0.5.2 init --platform=<platform>
-```
-
-Then run the 0.6.0 migration. Do not delete `.inject-state`, old commands, or task files manually before prepare—the transaction needs the original bytes for recovery and residue validation.
-
-## Runtime changes
-
-- Active tasks inject only their persisted `spec-context.yml` TASK projection.
-- Without an active task, explicit paths use `path_mapping`; only pathless exploration receives Catalog.
-- `cf-inject`, full/tag fallback, `.inject-state`, and SessionStart reset are removed.
-- `cf-spec context/refresh/doctor` is available on Claude, Codex, Costrict, and OpenCode.

package/src/adapters/claude/CLAUDE.md

@@ -1,45 +0,0 @@
-# Project Guidelines
-
-## Team Identity
-- Team: [team name]
-- Project: [project name]
-- Language: [primary language]
-
-## Core Principles
-- All changes must include tests
-- Single responsibility per function (<= 50 lines)
-- No loose typing or silent exception handling
-- Handle errors explicitly
-
-## Forbidden Patterns
-- Hard-coded secrets or credentials
-- Unparameterized SQL
-- Network calls inside tight loops
-
-<!-- code-flow:spec-loading schema=1 start -->
-## Spec Workflow (schema 1)
-
-- If `.code-flow/.active-task.json` exists, validate it and `spec-context.yml`, then use only the active TASK's `Spec-Refs`, Design refs, and Acceptance Contract. Never reselect Specs from Catalog.
-- Without an active TASK, explicit file paths use deterministic `path_mapping` constraints; prompts without paths receive the Spec Catalog for exploration or creation of the next Context.
-- PRD, Design, Plan, Start, Coding, and Done inherit one persisted Context. Required rules must be applied and verified before their stage gate passes.
-- A corrupt marker, Context hash drift, or required scope expansion is `SPEC_WORKFLOW_BLOCKED`; run `cf-spec refresh/doctor` instead of falling back.
-- Tier 0 `_map.md` files are navigation only. Rule constraints live in metadata-bearing Tier 1 Specs.
-
-Do NOT ask the user which Specs to load—the Context-first router is authoritative.
-<!-- code-flow:spec-loading schema=1 end -->
-
-## 合规反馈协议（quality_loop）
-
-1. 编辑代码后收到 **Spec 合规反馈 (auto-check)** 时，先按提示修正违规，再继续当前任务
-2. 用户表示某条反馈是误报（"这是误报"/"忽略这个检查"）时，代为执行：
-   `python3 .code-flow/scripts/cf_feedback.py ignore <check-id>`
-   （check-id 见反馈中的 `规则: <spec>#<check-id>`；同一规则误报达阈值会自动停用）
-3. 会话收尾被校验拦回（cf-stop 反馈未过项）时，修复后再结束；不要绕过
-4. 新增/修改规范时优先用 ✅/❌ 代码对照示例表达（见 spec 模板 Examples 段）
-
-## Task Documents (cf-task workflow)
-
-- `.code-flow/specs/shared/` holds PRD/design templates（含前端 `design-frontend.md`）used by `/cf-task:prd` and `/cf-task:align`
-- 一个需求的 prd / design / tasks 同放需求目录 `.code-flow/tasks/<日期>/<需求>/`；全栈需求可有 `<需求>.frontend.design.md` + `<需求>.backend.design.md`，`/cf-task:plan <需求目录>` 合并拆解，`/cf-task:archive` 按整个需求目录归档（旧扁平布局仍兼容）
-- Workflow: `/cf-task:prd` → `.prd.md` → `/cf-task:align <.prd.md>` → `.design.md`(s) → `/cf-task:plan <需求目录>` → tasks
-- Templates are read by the commands themselves; you do not need to pre-load them