@michaelxwb/code-flow 0.6.4 → 0.8.1

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

@@ -9,7 +9,7 @@ description: 归档已完成的 task 文件
 
 ## 输入
 
-- `/cf-task:archive <file>` — 归档指定的 task 文件
+- `/cf-task:archive <需求目录或任务文件>` — 定位需求，通过运行时归档整个需求目录
 
 其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
 
@@ -21,7 +21,8 @@ description: 归档已完成的 task 文件
 
 1. 用 Read 读取匹配到的 task 文件
 2. 提取所有 `## TASK-xxx` 段落的 Status
-3. 检查是否所有子任务均为 `verified`（E2E 终验后的终态；仍为 `done` 说明 verify-e2e 尚未执行，先跑它）
+3. 若 active marker 指向本需求，读取其中真实 TASK ID；满足 finish 条件后先执行 `code-flow task finish --root "$PWD" --task-dir "<需求目录>" --task <实际TASK-ID> --json`。失败按原因修复，禁止手动改状态。
+4. 检查所有子任务均为 `done` 或 `verified`。`done` 由下一步需求级终验提升为 `verified`；其他状态不能归档。
 
 若有未完成子任务，拒绝归档并输出：
 
@@ -37,28 +38,27 @@ description: 归档已完成的 task 文件
 
 ### 2. 归档前校验（Verify）
 
-**Spec Context / Code Gate（先于四维校验）**：
+**Spec Context / 终验与 Gate（先于四维校验）**：
 
-- 需求目录必须存在 `spec-context.yml`；执行 `python3 .code-flow/scripts/cf_spec_context.py refresh --task-dir <需求目录> --root "$PWD" --json`
-- 执行 `python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage code --json`；required Rule 的 stale/pending/conflict/unverified 任一存在即 FAIL
-- 若 `.code-flow/.active-task.json` 仍指向本需求，先执行 `python3 .code-flow/scripts/cf_task_workflow.py finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json`，通过后再 verify-e2e；不得自报 gate_passed 或通过归档绕过 active 状态
+- 需求目录必须存在 `spec-context.yml`；执行 `code-flow spec refresh --task-dir <需求目录> --root "$PWD" --json`
+- 不单独运行 verify-e2e 或重复 Spec Gate：步骤 3 的 archive 一次执行 required verifier、项目 validators 和 acceptance，并在移动前校验证据与输入快照。
 - Context 与 Evidence 随需求目录一并归档，`_session` 仅是可重建投影，不是事实源
 
-所有子任务 verified 后，执行四维校验：
+先执行静态四维校验；运行结果在步骤 3 的 archive 返回后核对：
 
 **完整性**：
 - 所有 Checklist 项已勾选
 - 全文无残留的 `#NOTES` 标记
 
 **正确性**：
-- 执行 `python3 .code-flow/scripts/cf_validation.py --root "$PWD" --json`；归档时任务已无 marker，须补充本需求基线至当前的变更路径作为 `--files` 参数，不能把工作区干净误认为本需求无需验证
-- 检查本次变更涉及的文件是否通过 lint/type check
+- 步骤 3 核对 archive 返回的 `verify.layers.validators`：全量 validation（含 heavy）必须通过；失败按具体命令与输出修复后重跑 archive。
+- 失败时按具体 validator 的命令、输出和修复建议处理，再重跑终验；通过记录按内容指纹复用。
 
 **验收追溯**：
-- 来源 design 含结构化 S-/E-/B- 场景时，逐项对照 `## Acceptance Coverage`，P0/P1 场景以及 RULE/高影响 RISK 映射场景必须全部存在且状态为 `verified`
-- 每个负责任务的 `Acceptance-Refs`、`Acceptance Contract`、`Acceptance Evidence` 必须闭合，不得残留 `planned` / `pending` / `TBD`
+- 来源 design 含结构化 S-/E-/B- 场景时，逐项对照 `## Acceptance Coverage`，P0/P1 场景以及 RULE/高影响 RISK 映射场景必须全部存在；步骤 3 终验后确认状态为 `verified`
+- 每个负责任务的 `Acceptance-Refs`、`Acceptance Contract`、`Acceptance Evidence` 必须闭合；待运行或待人工确认的条目由步骤 3 终验处理，成功后不得残留 `planned` / `pending` / `TBD`
 - 测试层级不得低于 design；E2E 的真实边界和关键断言必须有文件/用例位置与 fixture/构造证据
-- 先用 `cf_acceptance_manifest.py --task-file "<任务文件>" --output "<需求目录>/.acceptance-manifest.json" --verify-plan` 校验基线，再用 `cf_acceptance_runner.py --manifest "<需求目录>/.acceptance-manifest.json" --root "$PWD" --include-e2e --write-evidence` 统一复验。相同 argv、cwd、timeout 的命令在单次运行内复用结果；跨运行不复用，依赖步骤不跨状态屏障复用。测试未收集、未执行或失败均为 FAIL
+- 步骤 3 核对 archive 返回的 `verify.layers.e2e` 与逐 check 证据：多 check 场景全部必要成员必须有效；缺失或失败时修复后重跑 archive。
 - `manual` 场景必须有用户确认和可复核记录。旧 design 没有结构化场景时注明“不适用”，不得伪造覆盖
 
 **一致性**：
@@ -69,35 +69,25 @@ description: 归档已完成的 task 文件
 ```
 归档前校验:
   [PASS] 完整性: 所有 Checklist 已完成，无未解决 Notes
-  [PASS] 正确性: cf-validate 通过
+  [PASS] 正确性: layers.validators 通过
   [PASS] 验收追溯: 6/6 场景 verified，2 条 E2E 命令通过
-  [WARN] 一致性: Proposal 提到"支持 OAuth 登录"，但未发现相关实现
-
-WARN 不阻塞归档，但建议确认后再继续。继续归档？
+  [FAIL] 一致性: Proposal 要求"支持 OAuth 登录"，但缺少对应实现与验收证据
 ```
 
-PASS → 继续。WARN → 提示用户确认。FAIL → 阻塞归档，列出失败原因。
+全部 PASS → 继续。FAIL → 列出具体缺口，修复后重新验证。只有涉及需求取舍或人工验收时请求用户确认。
 
 ### 3. 执行归档
 
-校验通过后，先判断布局（任务文件路径形态）：
+**A. 需求目录布局**（任务文件位于 `.code-flow/tasks/<日期>/<需求>/<需求>.md`）——**整个需求目录一并归档**。先完成临时约束清理，再调用唯一移动入口：
 
-**A. 需求目录布局**（任务文件位于 `.code-flow/tasks/<日期>/<需求>/<需求>.md`）——**整个需求目录一并归档**：
 ```bash
-mkdir -p .code-flow/tasks/archived/<日期>
-mv .code-flow/tasks/<日期>/<需求>/ .code-flow/tasks/archived/<日期>/<需求>/
+code-flow task cleanup-session --task-dir "<需求目录>" --root "$PWD" --json
+code-flow task archive --task-dir "<需求目录>" --root "$PWD" --json
 ```
-目录内的 `.prd.md` / `.frontend.design.md` / `.backend.design.md` / `.design.md` / `.md` 随目录一并归档，无需逐个 mv。
 
-**B. 旧扁平布局**（任务文件直接位于 `.code-flow/tasks/<日期>/<file>.md`，无需求目录，向后兼容）——逐文件归档：
-1. 提取文件所在的日期目录名（如 `2026-03-15`）
-2. 创建归档目录并移动任务文件：
-   ```bash
-   mkdir -p .code-flow/tasks/archived/<日期目录>
-   mv .code-flow/tasks/<日期目录>/<file>.md .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/<日期目录>/`
+cleanup-session 逐任务删除 `specs/_session/task-<任务文件stem>.md` 投影，必须在源目录仍存在时执行。archive 内置 full verify；内容未变时复用有效证据，失败返回 `archive_verify_failed` 与具体 `verify` 结果，源目录保留。只有 `decision=pass` 才完成移动，目标路径使用返回的 `archived_to`，不得自行推算日期或同名后缀，不得手工 `mv` 绕过门禁。 返回 `manual_confirmation_required` 时，按 verify-e2e 的人工验收确认流程取得用户确认，执行 `confirm-manual` 后重跑 archive。
+
+**B. 旧扁平布局**（任务文件直接位于 `.code-flow/tasks/<日期>/<file>.md`）——保留向后兼容的文件查找。当前归档运行时以独立需求目录为边界；旧文件缺少该边界时，报告“先完成需求目录迁移”，保留原文件。不得把包含其他需求的日期目录作为 `--task-dir`，也不得逐文件归档绕过 Context、manifest 和 full verify。
 
 **归档后统一收尾（布局 A/B 都必须执行）**：
 
@@ -112,8 +102,6 @@ mv .code-flow/tasks/<日期>/<需求>/ .code-flow/tasks/archived/<日期>/<需
 3. 复查归档目标存在、原任务/需求路径不存在；如果源日期目录仍存在但为空，视为归档未完成，立即删除后再继续。
 4. 源日期目录包含其他条目时不得删除，摘要明确写“保留（仍有 N 个条目）”。
 
-**临时约束清理（FEAT-08）**：删除 `.code-flow/specs/_session/task-<name>.md`（存在时）。该文件由 cf-task:start 生成，归档后不得残留。
-
 ### 4. Spec 更新提示
 
 归档完成后，检查本次变更是否引入了新的规范约束需要同步到 specs：
@@ -141,16 +129,11 @@ Spec 同步建议:
 
 需求目录布局（A）：
 ```
-已归档需求目录: <需求>/ → .code-flow/tasks/archived/<日期>/<需求>/
+已归档需求目录: <需求>/ → <archived_to>
   含: <需求>.prd.md、<需求>.frontend.design.md / <需求>.backend.design.md（按实际）、<需求>.md
 ```
 
-旧扁平布局（B）：
-```
-已归档: <file>.md → .code-flow/tasks/archived/<日期目录>/<file>.md
-（如有关联设计简报）: <file>.design.md → .code-flow/tasks/archived/<日期目录>/<file>.design.md
-（如有关联 PRD）: <file>.prd.md → .code-flow/tasks/archived/<日期目录>/<file>.prd.md
-```
+旧扁平布局（B）尚未迁移时，报告原路径与缺少的需求边界，不输出“已归档”。
 
 ```
 摘要:
@@ -162,3 +145,16 @@ Spec 同步建议:
   - 校验: 4/4 PASS
   - 源日期目录: 已删除（为空）/ 已保留（仍有 N 个条目）
 ```
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow spec refresh --task-dir "<需求目录>" --root "$PWD" --json
+code-flow task finish --task-dir "<需求目录>" --task TASK-001 --root "$PWD" --json
+code-flow task cleanup-session --help
+code-flow task archive --task-dir "<需求目录>" --root "$PWD" --json
+```
+
+<!-- code-flow:runtime-commands end -->

package/src/adapters/opencode/commands/cf-task/block.md

@@ -4,6 +4,9 @@ description: 标记子任务为阻塞状态
 
 # cf-task:block
 
+
+> **命令面状态（0.8）**：alias — 等价于 `cf-task-status --block`；保留一个 minor，0.9.0 移除。
+
 标记子任务为阻塞状态。
 
 ## 输入
@@ -24,7 +27,7 @@ description: 标记子任务为阻塞状态
 3. 调用统一 workflow service 入口（与 active block 同一状态机），不要先编辑状态或 marker：
 
 ```bash
-python3 .code-flow/scripts/cf_task_workflow.py block --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --reason "<阻塞原因>" --json
+code-flow task block --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --reason "<阻塞原因>" --json
 ```
 
 命令同时更新 Status、阻塞原因、Log、Updated 和匹配的 marker；无 marker 的 draft 任务只改变任务文档。仅在返回成功后确认阻塞；其他需求的 marker 不得改动。
@@ -34,7 +37,18 @@ python3 .code-flow/scripts/cf_task_workflow.py block --root "$PWD" --task-dir "<
 先解决 Notes 或外部依赖，再执行：
 
 ```bash
-python3 .code-flow/scripts/cf_task_workflow.py resume --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
+code-flow task resume --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
 ```
 
 resume 会检查未解决的 #NOTES 和依赖，原子同步任务与 marker。未激活的 blocked 任务恢复 draft；已有匹配 marker 的任务恢复 in-progress。失败时保留阻塞状态，不通过手动改 Status 绕过。
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow task block --help
+code-flow task resume --help
+```
+
+<!-- code-flow:runtime-commands end -->

package/src/adapters/opencode/commands/cf-task/graph.md

@@ -4,6 +4,9 @@ description: 可视化子任务依赖关系 DAG
 
 # cf-task:graph
 
+
+> **命令面状态（0.8）**：alias — 等价于 `cf-task-status --graph`；保留一个 minor，0.9.0 移除。
+
 可视化子任务的依赖关系 DAG，识别可并行执行的任务组。
 
 ## 输入
@@ -19,7 +22,7 @@ description: 可视化子任务依赖关系 DAG
 
 ### 0. 程序计算（推荐）
 
-用 `python3 .code-flow/scripts/cf_task_index.py --task-file <file> --dag --json` 直接输出拓扑批次与独立分组，不要全文手算。单 worktree 一次仅激活一个 TASK；批次内的独立任务由 cf-task:start 在各自 worktree 中并行派发子 agent（预检失败自动回退串行），详见 cf-task:start 步骤 4。
+用 `code-flow task index --task-file <file> --dag --json` 直接输出拓扑批次与独立分组，不要全文手算。单 worktree 一次仅激活一个 TASK；批次内的独立任务由 cf-task:start 在各自 worktree 中并行派发子 agent（预检失败自动回退串行），详见 cf-task:start 步骤 4。
 
 `batches` 是组内可独立开发的拓扑批次；`dependency_components` 是依赖连通分组，只保证组与组之间独立，组内仍有先后依赖。`independent_groups` 仅为后者的兼容别名，不要把它显示成组内并行。
 
@@ -82,3 +85,13 @@ Layer 2:
 ### 5. 多文件模式
 
 当显示所有文件时，按文件分组输出，每个文件一个独立的 DAG。
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow task index --help
+```
+
+<!-- code-flow:runtime-commands end -->

package/src/adapters/opencode/commands/cf-task/note.md

@@ -4,6 +4,9 @@ description: 讨论文件中的 #NOTES 标记，对齐最优解后沉淀回原
 
 # cf-task:note
 
+
+> **命令面状态（0.8）**：alias — 等价于 `cf-task-status --notes`；保留一个 minor，0.9.0 移除。
+
 与用户协作讨论文件中的 `#NOTES` 标记，对齐最优解后将结论沉淀回原文，删除标记。
 
 支持两种文件类型：
@@ -138,7 +141,7 @@ TASK-002:
 所有 `#NOTES` 讨论完毕后：
 
 1. 再次扫描文件，确认无残留 `#NOTES` 标记
-2. 如果子任务之前因 `#NOTES` 被标记为 `blocked`，清除当前阻塞条目后调用 `python3 .code-flow/scripts/cf_task_workflow.py resume --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json`。命令检查依赖和残留 Notes，同步 marker 与任务状态；不得从历史 Log 猜测状态后只改 Markdown。失败保留 blocked 并报告原因。
+2. 如果子任务之前因 `#NOTES` 被标记为 `blocked`，清除当前阻塞条目后调用 `code-flow task resume --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json`。命令检查依赖和残留 Notes，同步 marker 与任务状态；不得从历史 Log 猜测状态后只改 Markdown。失败保留 blocked 并报告原因。
 3. 更新文件头 `Updated` 日期
 
 ### 6. 输出摘要
@@ -238,3 +241,13 @@ TASK-002:
 文件已更新，所有 #NOTES 标记已清除。
 可执行 /cf-task:plan .code-flow/tasks/2026-04-06/user-auth.design.md 拆解任务。
 ```
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow task resume --help
+```
+
+<!-- code-flow:runtime-commands end -->

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

@@ -2,6 +2,46 @@
 
 从设计文档或设计简报拆解需求，生成结构化任务文件。
 
+## Scenario-First（0.9）
+
+若需求目录存在 `<需求>.scenarios.md`，场景只能从该文件读取并分配 owner；design 只引用场景 ID。没有场景文件时回退 0.8 双 design 逻辑合并并标记 `deprecated`。
+
+## E2E 精度（plan 硬门禁）
+
+E2E 不是“用户可见结果”的默认测试层。plan 阶段必须按风险选择最低成本层级：
+
+- `unit`：纯函数、状态机、解析器、构造器。
+- `component`：表单/交互/布局/文案/空态/错误提示，使用 mock API。
+- `contract`：DTO、OpenAPI、错误码、前后端字段一致性。
+- `integration`：鉴权、事务、模块边界、真实 DB、进程内 ASGI。
+- `system`：完整 API/CLI/后台服务链路的系统验证；不要求浏览器。
+- `capacity`：容量与负载验证；check 与实际收集用例必须具有 capacity 标记。
+- `e2e`：只有真实浏览器 + 真实后端 + 鉴权/DB 才能暴露的 P0/P1 关键旅程。
+- `manual`：无法自动化的外部条件，必须用户确认。
+
+每个 E2E **必须**同时满足：
+
+1. `priority` 为 P0/P1；P2 不得用 E2E。
+2. `why_e2e` 说明为什么 unit/component/contract/integration 都覆盖不了。
+3. `boundary` 写出浏览器开始的真实边界（浏览器/API/DB/鉴权/SSE 等），并声明 `env: browser` 或 `components` 中的 `frontend/browser`。只有 API/CLI 的链路使用 system/integration。
+4. `steps` 和 `expected` 是可复现的用户步骤与可观察结果，不是实现细节。
+5. 非 `smoke` E2E 必须有 `trigger_paths`（源码 glob）；没有触发路径的 E2E 会让小改动跑全量，直接拒绝。
+6. 不得断言源码字符串、CSS、组件宽度、字段顺序、文案顺序；这些属于 component/visual。
+7. 同一旅程只保留一条 E2E；重复旅程合并。
+
+`scenarios parse --quality` 和 `acceptance manifest --verify-plan` 会失败关闭。plan 摘要必须输出 E2E 数量、占比、smoke 数量和每条 E2E 的理由；数量、比例和任务耗时只用于诊断，不设固定配额；零 E2E 且覆盖完整的计划合法。
+
+### 可执行计划质量
+
+- 每个 expected 使用 `expected_refs` 引用现有步骤（从 1 开始）或 `assertions` 中已声明的断言 ID。例如 `expected_refs: [{expected: 1, steps: [1]}]`。拒绝“可观、不回归”等无法检验的表述；合法条件分支应给出可构造的 preconditions 和具体结果。
+- `exec: deferred` 必须带 `defer_reason`、`owner`、`target_phase`。环境允许 none/local/local-api/browser/external/staging/capacity/ci/production；components 使用稳定标识符。
+- 新场景先准备可收集的测试骨架与具体测试 ID，再登记 check 的 `suite`、`test_ids`、`markers`、`collect`。本阶段只执行有超时和总预算的测试收集，不实现生产代码，也不执行 E2E；新模块尚不存在时将其导入放到测试体内，避免收集依赖实现。
+- 浏览器 check 使用 `suite: browser`，实际收集的用例须具备 browser 能力；smoke/capacity 标记必须同时出现在 check 与收集结果中。收集支持原生 pytest、Playwright JSON 或项目适配器 JSON，配置示例见 `docs/acceptance-contract.md`。
+- 锁定 manifest 时加 `--register-checks`，从真实 pytest/Playwright 收集生成登记；自定义收集器使用 `--registration-file`。失败时修复具体 check，原锁文件保留。重锁保留历史，契约变化标为 stale；修改工件后先运行 `code-flow spec refresh --task-dir "<需求目录>" --root "$PWD" --json`，再验证计划。
+- `code-flow acceptance manifest --verify-plan --task-dir "<需求目录>" --task-file "<任务文件>"` 始终校验 manifest 基线、场景质量、check 投影、测试登记、设计 ID 闭环和 Spec Gate；不得通过省略 `--require-scenarios` 跳过已有场景源的质量检查。
+- 设计通过 `code-flow design lint --file "<需求>.design.md" --scenarios-file "<需求>.scenarios.md" --json` 校验。多 design 重复传 `--file`，FEAT/API/NFR 与场景引用必须闭合；设计的 `design_template` 决定必填章节。
+- 报告区分 `e2e_browser_count`、`system_count`、`capacity_count` 与 `runnable_smoke_count`。未执行登记检查时 runnable 为 null；收集可用不等于真实边界执行已通过，后者必须读取执行证据。
+
 ## 输入
 
 - `/cf-task:plan <设计文档路径>` — 指定文档路径
@@ -11,6 +51,8 @@
 - `/cf-task:plan <设计文档路径> --draft` — 仅生成任务草案，必须经过 `--verify-plan` 后才能启动
 - `/cf-task:plan <任务文件> --verify-plan` — 执行完整 Acceptance Coverage 与 Spec Rule 门禁
 - `/cf-task:plan <.design.md 路径>` — 从 cf-task:align 产出的设计简报拆解（自动跳过缺口分析）
+- `/cf-task:plan <设计文档路径> --task-size capability|file` — 拆解粒度；默认 `--task-size capability`（1-2 天可演示能力），`file` 仅作旧行为兼容
+- `/cf-task:plan <设计文档路径> --max-tasks 25 --min-average-hours 2` — 覆盖预算阈值（一般不需要）
 
 ## 执行步骤
 
@@ -66,10 +108,17 @@ Read 设计文档后，**先扫描文档结构**，建立章节索引表：
 `--verify-plan` 的执行命令为：
 
 ```bash
-python3 .code-flow/scripts/cf_acceptance_manifest.py \
-  --verify-plan --task-dir <需求目录> --task-file <任务文件>
+code-flow scenarios parse --file <需求目录>/<需求>.scenarios.md --quality --json
+code-flow acceptance project \
+  --task-file <任务文件> \
+  --scenarios-file <需求目录>/<需求>.scenarios.md \
+  --output <需求目录>/.acceptance-manifest.json
+code-flow acceptance manifest \
+  --verify-plan --require-scenarios --task-dir <需求目录> --task-file <任务文件>
 ```
 
+`scenarios parse --quality` 的 `quality.ok=false` 或 `acceptance manifest --verify-plan` 返回 block 时，不得进入 start；按错误码把场景下沉到 component/contract/integration，或补齐 E2E 理由/触发路径后重跑。
+
 ### 2.5. Explore 模式（--explore）
 
 如果用户传入 `--explore`，在建立章节索引后，输出以下分析报告，**不生成任务文件**：
@@ -146,10 +195,14 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 
 阅读设计文档内容，按以下原则拆解：
 
-**拆解粒度**：
-- 每个子任务应是一个可独立编码和验证的原子单元
-- 一个子任务对应 1-3 个文件的修改
-- 预估编码时间 15-60 分钟
+**拆解粒度（默认 capability）**：
+- 每个子任务是一个 **1-2 天可完成、可独立演示和验收的能力单元**
+- 一个任务可以跨多个文件/模块，只要它们共同交付一个用户可观察、可演示的能力
+- 禁止按“改一个函数/一个文件”机械切碎；禁止默认 15-60 分钟级任务
+- 每个任务必须写 `Capability`（用户可运行/可看到的结果）与 `Estimate`（如 `1.5d`）
+- 能力交付面超过 2 天时先合并或重新切分，不得为凑任务数按文件拆分
+
+`--task-size file` 仅用于兼容旧计划：1-3 文件 / 15-60 分钟；仍受任务数预算约束，并在计划摘要中标注为 legacy。
 
 **提取内容**：
 - 功能需求 → 子任务标题 + 描述（提炼重点，不必复制全文）
@@ -169,7 +222,7 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 **验收契约拆解（硬约束）**：
 
 1. 从全部 design 提取 P0/P1 的 S-/E-/B- 场景，以及 RULE 和高影响 RISK 到场景的映射。
-2. 优先沿用 design 指定的测试层级与关键真实边界。旧 design 未填写时，跨 API、存储、运行时生成、渲染或最终用户可见结果的场景推断为 `E2E`，局部模块协作推断为 `integration`，纯函数约束才可用 `unit`。
+2. 优先沿用 design 指定的测试层级与关键真实边界。旧 design 未填写时按风险取**最低可覆盖层**：纯函数 `unit`；UI/表单/布局/字段顺序 `component`；DTO/错误码/字段契约 `contract`；鉴权/事务/模块边界/真实 DB `integration`；只有“真实浏览器 + 真实后端 + 鉴权/DB 才能暴露”的 P0/P1 关键旅程才用 `E2E`。**不得因为“用户可见”就推断 E2E。**
 3. 每个场景必须分配给一个负责的 TASK，并写入 `Acceptance-Refs`；同一场景可被多个任务引用，但必须有且仅有一个最终验收负责人。
 4. `manual` 只允许用于无法自动化的外部条件，必须记录原因并经用户明确确认。agent 不得把 design 的 E2E 自行降级为 unit/integration。
 5. Checklist 禁止使用泛化的“编写测试”。必须写成 `[场景ID][测试层级] + 真实边界 + 关键断言`，并为新功能/缺陷修复安排先写测试和 RED 记录。
@@ -178,8 +231,8 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 **Spec 责任拆解（硬约束）**：
 
 1. 先执行 Context `refresh`，读取 Design `Spec Compliance Matrix` 与每个 design-stage/plan-stage Rule 的 `verifier_ref`，继承已有 applied refs，禁止重新选择或降级。
-2. 每条 plan-stage required Rule 必须有且仅有一个责任 TASK；该 TASK 的 `Spec-Refs` 写完整 `{spec-id}#{rule-ref}`，Checklist 写具体 verifier 命令/输入，Acceptance Contract 写测试层级、不得 Mock 的真实边界和关键断言。
-3. Rule 可被其他 TASK 引用为依赖，但 Acceptance Coverage 只能有一个最终负责人。E2E 层级**不得降级**；manual 仍仅限经用户确认的外部边界。
+2. 每条 plan-stage required Rule 必须有且仅有一个责任 TASK；该 TASK 的 `Spec-Refs` 和 `Rule-Owner-Refs` 均写完整 `{spec-id}#{rule-ref}`，Checklist 写具体 verifier 命令/输入，Acceptance Contract 写测试层级、不得 Mock 的真实边界和关键断言。
+3. 其他 TASK 在 `Spec-Refs` 中保留实际适用的 Rule，可用 `Rule-Owner-Refs: N/A` 表示不承担计划责任；不能用 `Spec-Refs: N/A` 隐藏适用规则。整个任务文件均没有 `Rule-Owner-Refs` 时，旧计划只允许每条 Rule 有一个引用者。E2E 层级**不得降级**；manual 仍仅限经用户确认的外部边界。
 4. 缺 `verifier_ref`、责任 TASK 为 0/多个、Checklist/Contract 不含 Rule-specific 验证责任时，任务文件只能保留为缺口草稿，不能启动。
 
 ### 4. 生成任务文件方案
@@ -214,12 +267,28 @@ 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 |
+| 场景ID | 来源设计 | 测试层级 | 关键真实边界 | 负责任务 | 状态 | 执行命令 | 优先级 | 执行方式 | 环境 | 输入 | E2E理由 | 触发路径 | 冒烟 |
+|--------|---------|---------|-------------|---------|------|---------|--------|---------|------|------|--------|---------|------|
+| S-01 | xxx.design.md#2.5 验收条件 | E2E | 浏览器 → API → Store → Renderer | TASK-001 | planned | ["python3","-m","pytest","-q","tests/test_s01.py"] | P0 | deferred | browser | | 只有真实浏览器+API+DB能暴露路由/鉴权/渲染 wiring | ["src/frontend/model/**"] | no |
+| E-01 | xxx.design.md#2.5 验收条件 | integration | Service → Store | TASK-001 | planned | ["python3","-m","pytest","-q","tests/test_e01.py"] | P1 | auto | none | tests/** | - | - | no |
+| S-03 | xxx.design.md#2.5 验收条件 | component | Renderer + mocked API | TASK-001 | planned | ["npx","playwright","test","tests/component/model.spec.ts"] | P1 | auto | browser | | - | - | no |
 
 > 本表必须覆盖 design 中全部 P0/P1 场景，以及 RULE/高影响 RISK 映射的场景；存在缺口时不生成可启动任务。
+>
+> **执行元数据（与 manifest v3 对齐）**：
+> - `执行命令`：`unit/component/contract/integration` 场景必须登记可单独执行的命令，argv JSON
+>   数组最稳（含空格/引号路径不拆参）；也可写 shell 词串。命令也可只写在 TASK
+>   段 `Acceptance Contract` 的执行命令列，manifest 会按场景 ID 回退读取。
+> - `优先级` → `scenario.priority`；`执行方式` 取 `auto` / `manual` / `deferred` /
+>   `aspirational`；`环境` / `输入` 进入 manifest check 的 `env` / `inputs`。
+> - `E2E理由` / `触发路径` / `冒烟` → `why_e2e` / `trigger_paths` / `smoke`；
+>   `触发路径` 进入 check `paths`，changed profile 只跑命中的 E2E；`冒烟=yes`
+>   等价于 check `profile=smoke`。非 E2E 的这三列写 `-`。
+> - **每个场景必须绑定 check（有执行命令）或显式标为 `aspirational`**；没有命令
+>   又未标 aspirational 的计划会被追溯矩阵/审计阻断。`E2E`/`manual` 无本地命令时
+>   使用 `deferred` 或 `manual`，纯愿望项使用 `aspirational`。
+> - E2E 缺少 `E2E理由`、非 smoke 缺少 `触发路径`、或优先级为 P2 时，
+>   `--verify-plan` 直接 block；不要用“先写 E2E 再补理由”的方式绕过。
 
 ---
 
@@ -230,15 +299,19 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 - **Depends**:
 - **Source**: docs/xxx.md#§3.1 数据模型(L83-L110)
 - **Spec-Refs**: product-rules#RULE-product-001
-- **Acceptance-Refs**: S-01, E-01, RULE-01
+- **Rule-Owner-Refs**: product-rules#RULE-product-001
+- **Acceptance-Refs**: S-01, E-01, S-03, RULE-01
+- **Estimate**: 1.5d
+- **Capability**: <一句话：用户可运行/可演示的结果，例如“导入配置并看到成功摘要”>
 
 ### Description
 <从设计文档提取的需求重点，不必复制全文>
 
 ### Checklist
+- [ ] 交付 `<Capability>`，并提供可重复的演示命令/操作（1-2 天可完成）
 - [ ] <具体实现步骤1>
 - [ ] <具体实现步骤2>
-- [ ] [S-01][E2E] 编写 E2E 验收测试并登记可单独执行的命令（真实边界：API → Store → Renderer）；不在编码期执行 RED/GREEN，统一留给 verify-e2e
+- [ ] [S-01][E2E] 编写只覆盖关键旅程的 E2E，登记可单独执行的命令与触发路径（真实边界：浏览器 → API → Store → Renderer）；只断言用户可观察结果，不做源码/CSS/布局断言；相关批次就绪后执行关键 smoke
 - [ ] [S-01] 断言 <最终可观测结果 1> 与 <最终可观测结果 2>
 - [ ] [E-01][integration] 覆盖 <异常输入> 与 <可观测失败行为>
 - [ ] 运行验收命令并填写 Acceptance Evidence
@@ -252,7 +325,7 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 
 ### Acceptance Evidence
 
-> `cf-task-start` 在编码期填写 functional/manual 的 RED/GREEN 结果、每个关键断言的位置和真实组件证据；E2E 仅登记测试与命令，执行统一留给 verify-e2e。全部 functional 状态 verified 后任务才可 done。
+> `cf-task-start` 在编码期填写 functional 的 RED/GREEN 结果、每个关键断言的位置和真实组件证据；manual 场景登记原因/边界/验收方式并由用户确认；相关批次先验证已就绪的关键 smoke，需求终验补足剩余 E2E 证据。全部 functional 状态 verified 后任务才可 done。全量套件/构建/E2E 类 verifier 建议显式标 `stage: review`，由需求终验统一执行；本任务 required code 检查因预算或环境未执行时，Done Gate 返回 `provisional`，补齐后重跑 finish，不能自动延后并标记 done。
 
 ### Log
 - [<当前日期>] created (draft)
@@ -277,7 +350,9 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 
 TASK-001: <标题> [P0]
   来源: §3.1 数据模型 (L83-L110)
-  验收: S-01(E2E), E-01(integration)
+  能力: <用户可演示的结果>
+  预估: 1.5d
+  验收: S-01(E2E), E-01(integration), S-03(component)
   描述: ...
   Checklist: N 项
   依赖: 无
@@ -308,13 +383,13 @@ TASK-002: <标题> [P1]
 写入后用 `bind --stage plan` 的 `applications` 将每条 required Rule 指向任务文件内唯一 TASK item，并执行：
 
 ```bash
-python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage plan --artifact <任务文件> --json
+code-flow spec gate --task-dir <需求目录> --stage plan --artifact <任务文件> --json
 ```
 
 通过 Plan Gate 后，锁定验收基线：
 
 ```bash
-python3 .code-flow/scripts/cf_acceptance_manifest.py \
+code-flow acceptance manifest \
   --task-file <任务文件> \
   --output <需求目录>/.acceptance-manifest.json
 ```
@@ -322,14 +397,14 @@ python3 .code-flow/scripts/cf_acceptance_manifest.py \
 Manifest 锁定场景 ID、来源、测试层级、真实边界和责任 TASK。编码阶段不得静默修改这些字段；如发生范围变化，必须重新执行 plan 验证。
 
 验收类型按测试层级归类：
-- `unit/integration` → `functional`（Done Gate 自动执行）
+- `unit/component/contract/integration` → `functional`（Done Gate 自动执行）
 - `E2E` → `e2e`（延迟至所有任务完成后，需 `--include-e2e` 显式执行）
 - `manual` → `manual`（用户手动验证，永不自动执行）
 
-E2E 场景依赖外部环境（数据库、API、浏览器），在编码阶段默认跳过（状态 `e2e_deferred`），不阻断 Done Gate。所有子任务完成后，执行：
+浏览器 E2E 依赖浏览器及其声明的真实服务，在编码阶段默认跳过（状态 `e2e_deferred`），不阻断 Done Gate。API/CLI 系统测试使用 system。所有子任务完成后，执行：
 
 ```bash
-python3 .code-flow/scripts/cf_acceptance_runner.py \
+code-flow acceptance run \
   --manifest <需求目录>/.acceptance-manifest.json \
   --root . \
   --include-e2e \
@@ -338,6 +413,26 @@ python3 .code-flow/scripts/cf_acceptance_runner.py \
 
 不得为了提速降低 design 指定的 E2E 层级。
 
+### 5.1. 计划预算门禁（capability 默认）
+
+写入任务文件后、绑定 Plan Gate / 锁定 manifest 前，必须执行：
+
+```bash
+code-flow task index \
+  --task-file <任务文件> \
+  --budget \
+  --task-size capability \
+  --json
+```
+
+- JSON 的 `budget` 字段输出任务数、总工时、平均任务时长、每任务场景数与每任务 `Capability`
+- `task_count > 25`：明确警告并要求合并（同能力任务合并为 1-2 天能力单元）
+- `average_hours < 2h`：任务过碎，要求合并后重新评估
+- 缺少 `Estimate` 或 `Capability`：不得进入 start
+- `requires_merge=true` 时只输出需合并的 TASK 清单，不继续 Plan Gate / manifest；合并后重跑直到 `decision=pass`
+- `--task-size file` 兼容旧粒度，不做平均 2h 检查，但仍禁止任务数 >25
+- 阈值可用 `--max-tasks` / `--min-average-hours` 显式覆盖，并在任务文件 Proposal 记录原因
+
 只有 Context Plan 状态与任务结构校验都 `decision=pass` 才输出 Start 下一步；缺唯一 owner、`verifier_ref`、测试层级或真实边界时必须回到拆解修复。
 
 ### 6. 输出摘要
@@ -345,10 +440,12 @@ python3 .code-flow/scripts/cf_acceptance_runner.py \
 ```
 已生成任务文件: .code-flow/tasks/2026-03-15/auth-module.md
 - 子任务数: N
+- 计划预算: 总工时 Xh / 平均 Yh（阈值：≤25 任务且平均 ≥2h；通过/需合并）
 - 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 个
+- 验收覆盖: P0/P1 场景 x/x，RULE/高影响 RISK 映射 y/y
+- E2E 预算: z 个（占比 p%，smoke s 个）；每条 E2E 的 why_e2e / trigger_paths 已通过质量门禁
 
 建议执行顺序:
   1. TASK-001 (无依赖)
@@ -361,3 +458,20 @@ python3 .code-flow/scripts/cf_acceptance_runner.py \
   - 添加批注: /cf-task:note auth-module TASK-001 "批注内容"
   - 开始编码: /cf-task:start auth-module
 ```
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow spec refresh --task-dir "<需求目录>" --root "$PWD" --json
+code-flow spec gate --help
+code-flow task index --help
+code-flow acceptance manifest --task-file "<任务文件>" --output "<需求目录>/.acceptance-manifest.json"
+code-flow acceptance project --task-file "<任务文件>" --output "<需求目录>/.acceptance-manifest.json"
+code-flow acceptance run --manifest "<需求目录>/.acceptance-manifest.json" --root "$PWD" --write-evidence
+code-flow scenarios parse --file "<需求>.scenarios.md" --quality --json
+code-flow design lint --file "<需求>.design.md" --scenarios-file "<需求>.scenarios.md" --json
+```
+
+<!-- code-flow:runtime-commands end -->

package/src/adapters/opencode/commands/cf-task/prd.md

@@ -44,7 +44,7 @@ description: 从一句话需求出发产生产品需求文档(PRD)
 在开始写需求内容前，先确定 Step 5 的需求目录和预计涉及路径，再执行：
 
 ```bash
-python3 .code-flow/scripts/cf_spec_context.py catalog --stage prd --root "$PWD" --paths <预计路径...> --json
+code-flow spec catalog --stage prd --root "$PWD" --paths <预计路径...> --json
 ```
 
 1. 必须检查完整 `candidates`，不得按展示条数截断；只消费 resolver 返回的 `stages` 含 `prd` 的产品、安全、兼容、业务约束，`code-only` Spec 不得进入 PRD。
@@ -141,7 +141,7 @@ python3 .code-flow/scripts/cf_spec_context.py catalog --stage prd --root "$PWD"
 写入后必须完成 Context 回填和 PRD Gate：
 
 1. 再次调用 `bind --stage prd`，`selections` 可为空，`applications` 为每条已承接 Rule 写入 `artifact`、`section_id`、`item_id`；artifact 必须指向本需求目录内 PRD，由脚本计算 `artifact_sha256`。
-2. 执行 `python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage prd --json`。
+2. 执行 `code-flow spec gate --task-dir <需求目录> --stage prd --json`。
 3. 只有 `decision=pass` 才能把 PRD 标为可评审并输出下一步；pending/conflict/stale、缺少范围/验收落点或无有效用户确认的 N/A 均保持阻断。
 
 **文件位置说明**：PRD、设计简报（`<name>.frontend.design.md` / `<name>.backend.design.md`）、任务文件（`<name>.md`）同放**需求目录** `.code-flow/tasks/<日期>/<name>/`，`cf-task:archive` 按整个需求目录归档。
@@ -165,3 +165,14 @@ python3 .code-flow/scripts/cf_spec_context.py catalog --stage prd --root "$PWD"
   - 推进设计: /cf-task:align .code-flow/tasks/<日期>/<name>/<name>.prd.md
     （align 将从 PRD 派生设计简报，继承目标/用户/功能/范围，只需补技术维度）
 ```
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow spec catalog --help
+code-flow spec gate --help
+```
+
+<!-- code-flow:runtime-commands end -->