@michaelxwb/code-flow 0.8.1 → 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,6 +1,6 @@
 # {模块名称} 前端模块需求与设计简报
 
-> **生成约定**：产出文档的 frontmatter 声明 `design_template: frontend`。浏览器 E2E 必须有匹配的 env/components/boundary，expected 逐条用 expected_refs 关联步骤或断言；deferred 补原因、owner 与 target_phase。API/CLI/后台全链路用 system，容量用 capacity；非 E2E 不写 why_e2e。完成后运行 scenarios parse --quality 与 design lint；计划再校验真实测试登记/收集。完整示例见工具文档 `docs/acceptance-contract.md`。
+> **生成约定**：产出文档的 frontmatter 声明 `design_template: frontend`。验收场景引用 `<需求>.scenarios.md` 的 S-/E-/B- 场景 ID；场景是人工验收参照，不生成集中验收清单或结果登记，不阻断 start/finish/archive。设计需要给出真实可执行的相关测试建议，由任务文档声明。
 
 > **文档编号**: FE-{模块代号}-{版本号}
 > **文档版本**: v1.0
@@ -93,9 +93,9 @@
 
 ### 2.4 验收条件 [必填]
 
-> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。本节只保留场景引用和前端设计影响，不复制完整场景表；优先级、执行方式、环境、输入等执行元数据以 scenarios 源为准；没有可执行命令的场景必须显式标为 aspirational；plan 阶段投影到 manifest check；测试层级（unit / component / contract / integration / system / capacity / E2E / manual）与关键真实边界定义在 scenarios 源中。
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。本节只保留场景引用和前端设计影响，不复制完整场景表；场景只记录人工验收所需的 step / expected / boundary / owner；没有可执行命令的场景标为 manual。
 >
-> **前端 E2E 精度**：表单交互、布局、文案、字段顺序、空态和错误提示用 component + mock API；E2E 只保留真实浏览器 + 真实后端 + 鉴权/DB 的关键用户旅程。E2E 必须有 `why_e2e`、非 smoke 的 `trigger_paths` 和可观察结果，禁止源码字符串/CSS/宽度断言。
+> **前端 E2E 精度**：表单交互、布局、文案、字段顺序、空态和错误提示用 component + mock API；E2E 只保留真实浏览器 + 真实后端 + 鉴权/DB 的关键用户旅程，并写清可观察结果。禁止源码字符串/CSS/宽度断言。
 
 | 场景ID | 前端设计影响 / 备注 |
 |--------|--------------------|
@@ -104,14 +104,14 @@
 
 #### 2.4.1 验证环境假设 [必填]
 
-> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行期缺失时应返回 `env_blocked` 并列出 owner，不得伪装成产品失败。
+> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行时缺少环境应由人工验收记录缺失项与 owner，不得伪装成产品失败。
 
 | 维度 | 假设 | 验证方式 / 参数 | 不满足时 |
 |------|------|----------------|---------|
-| 容量 | （页面/组件规模、并发用户、浏览器矩阵；无实测填"待定"） | Playwright projects / 基准 fixture | 标记 `incomplete` 或拆分批次 |
-| 硬件 | （CI runner / 设备 / 视口规格） | preflight 检查 | 返回 `env_blocked` |
-| 依赖 | （后端 API / 浏览器版本 / 测试账号 / 字体与静态资源） | `preflight` 命令（health check） | 返回 `env_blocked` 并列出缺失项 |
-| profile 参数 | （smoke / changed / full、浏览器矩阵、重试与超时） | `verify --layers e2e --profile ...` | 显式报 `incomplete`，不自动降级 |
+| 容量 | （页面/组件规模、并发用户、浏览器矩阵；无实测填"待定"） | Playwright projects / 基准 fixture | 记录缺失项与 owner，拆分批次 |
+| 硬件 | （CI runner / 设备 / 视口规格） | 人工检查 | 记录缺失项与 owner |
+| 依赖 | （后端 API / 浏览器版本 / 测试账号 / 字体与静态资源） | 人工检查 | 记录缺失项与 owner |
+| 测试预算 | （Task tests 的 unit/integration 范围；E2E 与全量回归留在 CI） | 人工核对任务文档 | 记录未覆盖风险与 owner |
 
 ---
 
@@ -238,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,6 +1,6 @@
 # {模块名称} 模块需求与设计一体化文档
 
-> **生成约定**：产出文档的 frontmatter 声明 `design_template: full`。浏览器 E2E 必须有匹配的 env/components/boundary，expected 逐条用 expected_refs 关联步骤或断言；deferred 补原因、owner 与 target_phase。API/CLI/后台全链路用 system，容量用 capacity；非 E2E 不写 why_e2e。完成后运行 scenarios parse --quality 与 design lint；计划再校验真实测试登记/收集。完整示例见工具文档 `docs/acceptance-contract.md`。
+> **生成约定**：产出文档的 frontmatter 声明 `design_template: full`。验收场景引用 `<需求>.scenarios.md` 的 S-/E-/B- 场景 ID；场景是人工验收参照，不生成集中验收清单或结果登记，不阻断 start/finish/archive。设计需要给出真实可执行的相关测试建议，由任务文档声明。
 
 > **文档编号**: MOD-{模块代号}-{版本号}
 > **文档版本**: v1.0
@@ -145,9 +145,9 @@
 
 #### 2.5.2 功能验收场景
 
-> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。设计文档只引用全局场景 ID，并说明设计影响，不复制完整场景字段；优先级、执行方式、环境、输入等执行元数据以 scenarios 源为准；没有可执行命令的场景必须显式标为 aspirational；plan 阶段投影到 manifest check；测试层级（unit / component / contract / integration / system / capacity / E2E / manual）与关键真实边界定义在 scenarios 源中。
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。设计文档只引用全局场景 ID，并说明设计影响，不复制完整场景字段；场景只记录人工验收所需的 step / expected / boundary / owner；没有可执行命令的场景标为 manual。
 >
-> **E2E 精度**：E2E 只用于 P0/P1 关键用户旅程，且必须有 `why_e2e`（低层测试为什么不够）、非 smoke 的 `trigger_paths`（哪些源码变化才触发）和可观察结果。UI 布局/文案/字段顺序用 component，DTO/错误码用 contract，鉴权/事务/模块边界用 integration；不要用 E2E 覆盖所有用户可见结果。
+> **E2E 精度**：E2E 只用于关键用户旅程，并写清真实边界与可观察结果。UI 布局/文案/字段顺序用 component，DTO/错误码用 contract，鉴权/事务/模块边界用 integration；不要把 E2E 当成所有用户可见结果的默认层级。
 >
 > ✅ CAS 409：contract 验响应、component 验表单保留、integration 用真实存储验并发；聚合补零与关系绑定同样优先采用相应低层组合。Cookie 隔离和 SSE 恢复保留必要的跨边界关键验证。❌ 设固定 E2E 数量或比例；比例和任务耗时仅作诊断，零 E2E 的完整覆盖合法。
 
@@ -181,14 +181,14 @@
 
 #### 2.5.4 验证环境假设 [必填]
 
-> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行期缺失时应由 runner 返回 `env_blocked` 并列出 owner，不得伪装成产品失败。
+> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行时缺少环境应由人工验收记录缺失项与 owner，不得伪装成产品失败。
 
 | 维度 | 假设 | 验证方式 / 参数 | 不满足时 |
 |------|------|----------------|---------|
-| 容量 | （数据量、并发数、场景规模，如 119 任务 / 62 E2E；无实测填"待定"） | 基准 fixture / 压测命令 | 标记 `incomplete` 或拆分批次 |
-| 硬件 | （CPU / 内存 / 磁盘 / 网络规格，如 8C16G） | preflight 检查 | 返回 `env_blocked` 并列出缺失项 |
-| 依赖 | （数据库 / 浏览器 / API / CI runner / 端口 / 测试账号） | `preflight` 命令（health check、端口探测） | 返回 `env_blocked` 并列出 owner |
-| profile 参数 | （smoke / changed / full 选择、deadline、并行度、重试与超时） | `verify --layers ... --profile ... --deadline ...` | 显式报 `incomplete`，不自动降级 |
+| 容量 | （数据量、并发数、场景规模；无实测填"待定"） | 基准 fixture / 压测命令 | 记录缺失项与 owner，拆分批次 |
+| 硬件 | （CPU / 内存 / 磁盘 / 网络规格，如 8C16G） | 人工检查 | 记录缺失项与 owner |
+| 依赖 | （数据库 / 浏览器 / API / CI runner / 端口 / 测试账号） | 人工检查 | 记录缺失项与 owner |
+| 测试预算 | （Task tests 的 unit/integration 范围；E2E 与全量回归留在 CI） | 人工核对任务文档 | 记录未覆盖风险与 owner |
 
 ---
 
@@ -473,25 +473,23 @@ flowchart TD
 
 ## 6. 需求追溯矩阵（生成式）
 
-> 本节由 `cf_traceability.py --design <design.md> --manifest <.acceptance-manifest.json>` 从 §2.5 与 manifest **生成，不手工维护**；不要直接编辑下面的表格，提交前用生成结果替换。
->
-> 生成矩阵会列出每个场景的优先级、测试层级、执行方式、环境、输入、追溯 check、执行命令、owner 与状态；没有 check 且未显式标为 `aspirational` 的场景会让生成命令返回 block。
+> 本节由设计者手工维护，用于把 PRD 用户故事、功能/接口 ID 与场景 ID 对齐。场景只是人工验收参照；`cf-task:plan` 将相关场景映射到任务段落。
 
-| 用户故事 | 功能ID | 接口ID | 测试用例ID | 测试层级 | 执行方式 | 追溯 check | 状态 |
-|---------|--------|--------|-----------|---------|---------|-----------|------|
-| US-01 | FEAT-01 | API-01 | S-01 | E2E | auto | CHK-xxxx | 待实现 |
+| 用户故事 | 功能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,6 +1,6 @@
 # {模块名称} 模块需求与设计简报
 
-> **生成约定**：产出文档的 frontmatter 声明 `design_template: lite`。浏览器 E2E 必须有匹配的 env/components/boundary，expected 逐条用 expected_refs 关联步骤或断言；deferred 补原因、owner 与 target_phase。API/CLI/后台全链路用 system，容量用 capacity；非 E2E 不写 why_e2e。完成后运行 scenarios parse --quality 与 design lint；计划再校验真实测试登记/收集。完整示例见工具文档 `docs/acceptance-contract.md`。
+> **生成约定**：产出文档的 frontmatter 声明 `design_template: lite`。验收场景引用 `<需求>.scenarios.md` 的 S-/E-/B- 场景 ID；场景是人工验收参照，不生成集中验收清单或结果登记，不阻断 start/finish/archive。设计需要给出真实可执行的相关测试建议，由任务文档声明。
 
 > **文档编号**: MOD-{模块代号}-{版本号}
 > **文档版本**: v1.0
@@ -113,9 +113,9 @@
 
 #### 2.4.1 功能验收场景
 
-> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。设计文档只引用全局场景 ID，并说明设计影响，不复制完整场景字段；优先级、执行方式、环境、输入等执行元数据以 scenarios 源为准；没有可执行命令的场景必须显式标为 aspirational；plan 阶段投影到 manifest check；测试层级（unit / component / contract / integration / system / capacity / E2E / manual）与关键真实边界定义在 scenarios 源中。
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。设计文档只引用全局场景 ID，并说明设计影响，不复制完整场景字段；场景只记录人工验收所需的 step / expected / boundary / owner；没有可执行命令的场景标为 manual。
 >
-> **E2E 精度**：E2E 只用于 P0/P1 关键用户旅程，且必须有 `why_e2e`、非 smoke 的 `trigger_paths` 和可观察结果。UI 布局/文案/字段顺序用 component，DTO/错误码用 contract，鉴权/事务/模块边界用 integration。
+> **E2E 精度**：E2E 只用于关键用户旅程，并写清真实边界与可观察结果。UI 布局/文案/字段顺序用 component，DTO/错误码用 contract，鉴权/事务/模块边界用 integration。
 
 | 场景ID | 设计影响 / 备注 |
 |--------|----------------|
@@ -132,14 +132,14 @@
 
 #### 2.4.3 验证环境假设 [必填]
 
-> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行期缺失时应返回 `env_blocked` 并列出 owner，不得伪装成产品失败。
+> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行时缺少环境应由人工验收记录缺失项与 owner，不得伪装成产品失败。
 
 | 维度 | 假设 | 验证方式 / 参数 | 不满足时 |
 |------|------|----------------|---------|
-| 容量 | （数据量、并发数、场景规模；无实测填"待定"） | 基准 fixture / 压测命令 | 标记 `incomplete` 或拆分批次 |
-| 硬件 | （CPU / 内存 / 磁盘 / 网络规格） | preflight 检查 | 返回 `env_blocked` |
-| 依赖 | （数据库 / 浏览器 / API / 端口 / 测试账号） | `preflight` 命令 | 返回 `env_blocked` 并列出缺失项 |
-| profile 参数 | （smoke / changed / full、deadline、并行度、重试） | `verify --profile ... --deadline ...` | 显式报 `incomplete`，不自动降级 |
+| 容量 | （数据量、并发数、场景规模；无实测填"待定"） | 基准 fixture / 压测命令 | 记录缺失项与 owner，拆分批次 |
+| 硬件 | （CPU / 内存 / 磁盘 / 网络规格） | 人工检查 | 记录缺失项与 owner |
+| 依赖 | （数据库 / 浏览器 / API / 端口 / 测试账号） | 人工检查 | 记录缺失项与 owner |
+| 测试预算 | （Task tests 的 unit/integration 范围；E2E 与全量回归留在 CI） | 人工核对任务文档 | 记录未覆盖风险与 owner |
 
 ---
 
@@ -294,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
+
+- 尚未执行