@michaelxwb/code-flow 0.6.4 → 0.8.1

package/src/adapters/costrict/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/costrict/commands/cf-task/prd.md

@@ -39,7 +39,7 @@
 在开始写需求内容前，先确定 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。
@@ -136,7 +136,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` 按整个需求目录归档。
@@ -160,3 +160,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 -->

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

@@ -41,6 +41,9 @@
 - `Acceptance-Refs` 中每个 S-/E-/B- 都必须出现在全局覆盖表和当前契约中，测试层级与关键真实边界必须和 design 一致
 - 旧 task 没有覆盖表但来源 design 含结构化验收场景时，先从 design 回填覆盖表与契约；回填完成前不得修改生产代码
 - 非行为类任务可显式写 `Acceptance-Refs: N/A`；不得用 N/A 跳过已有设计场景
+- E2E 必须已通过 plan 精度门禁：P0/P1、`why_e2e`、`boundary`、非 smoke 的 `trigger_paths` 缺一不可；`start` 会在 `e2e_plan.quality.ok=false` 时阻断，不要手工改 manifest 绕过
+- 有 canonical 场景源时，start 同时复核浏览器边界、expected_refs 和延后责任信息。沿用 plan 已登记的可收集测试骨架；按当前 TASK 补齐断言并执行 functional RED/GREEN；关键 E2E 可在相关批次完成后验证，剩余缺口由需求终验核对。
+- 显式 `exec: deferred` 保留在 owned/smoke 提示中，但不进入 scheduled，也不在 Start 收集。旧锁文件缺少 `quality_schema: 2` 时保留原门禁并提示 `legacy_quality_schema`；按提示补字段、重锁和验证计划，不宣称新质量检查已通过。Done 阶段的显式延期场景允许 e2e_deferred，verified 仍须完整验收。
 
 ### 2. 加载详设上下文
 
@@ -61,12 +64,12 @@
 
 在改状态或生产代码前，顺序固定且不得跳步：
 
-1. 调用 `cf_spec_context.py start --task-dir ... --root ... --task ... --task-file ... --json`，由单个进程按 refresh → active start → session 顺序执行 Start Gate；stdin JSON 传入逐路径确认的 `owned_paths`。stale/conflict、依赖未闭合、已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。前置硬门禁（blocked / #NOTES / 依赖）由 workflow service 在改状态前强制执行。用户已确认内容时，Design/Plan 的 pending 不单独阻止激活；不新增阶段状态门禁。
+1. 调用 `code-flow task start --task-dir ... --root ... --task ... --task-file ... --json`，由单个进程按 refresh → active start → session 顺序执行 Start Gate；stdin JSON 的 `owned_paths` 只填启动前已存在的未提交改动（逐路径确认归属），不是计划要改的文件；干净工作区传空数组（提交后的改动由基线并集自动纳入）。stale/conflict、依赖未闭合、已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。前置硬门禁（blocked / #NOTES / 依赖）由 workflow service 在改状态前强制执行。用户已确认内容时，Design/Plan 的 pending 不单独阻止激活；不新增阶段状态门禁。
 2. 从命令返回值读取 refresh 后的 Context hash、active 状态和 session 输出路径；该命令只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `.code-flow/specs/_session/task-<name>.md`，禁止重新 catalog 或猜测规则。
 3. Start 返回成功时，workflow service 已通过可恢复事务同步 Status、started log 和 active marker；不要再手动改状态。失败保留原状态，按返回原因恢复。
-4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令（E2E 只登记，不在本阶段执行）
-5. 先编写验收测试（E2E 只编写并登记）。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
-6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败。E2E 场景不执行 RED，登记为 e2e_deferred 留给 verify-e2e
+4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令（E2E 先登记真实边界与执行方式）
+5. 先编写验收测试（E2E 编写并登记真实边界）。从 `start` 返回的 `e2e_plan` 读取范围：只编写 `owned` 中的 E2E；`smoke` 由相关批次或需求级 verify 运行，不在本 TASK 重写；`deferred` 中的 E2E 不得顺手补。E2E 必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
+6. E2E 只断言用户可观察结果和真实链路；禁止断言源码字符串、CSS、组件宽度、字段顺序、文案顺序。UI 布局/交互细节应下沉到 component 测试。关键 E2E 可随相关批次运行；未运行者登记为 e2e_deferred，终验检查剩余证据。新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因；纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
 
 RED 证据写入 `Acceptance Evidence`：
 
@@ -84,7 +87,7 @@ RED 证据写入 `Acceptance Evidence`：
 
 ### 3.2 GREEN 与验收证据
 
-1. 执行 functional 验收和受影响范围的回归测试；E2E 只登记场景、断言、真实边界和命令，RED/GREEN 都不在编码阶段执行，统一留给 verify-e2e。
+1. 执行 functional 验收和受影响范围的回归测试；登记 E2E 场景、断言、真实边界和命令；按已就绪的相关批次运行关键 smoke，其余留作终验证据缺口；manual 场景只登记 `manual_pending`（原因、边界、验收方式），人工确认统一留给 verify-e2e。
 2. 对每个预期结果记录断言位置与 fixture/构造路径；环境未就绪的错误不得冒充有效 RED，明确记录尚未验证。
 3. 由 runner 写入最新状态和运行历史；不要覆盖原契约、RED 证据或历史失败。functional 必须 verified，已登记的 E2E 在实现阶段允许 e2e_deferred。
 4. 测试未收集、命令未实际执行或缺少关键断言，都不算验证完成。失败重跑必须使旧 verified 失效。
@@ -105,20 +108,25 @@ RED 证据写入 `Acceptance Evidence`：
 
 只有同时满足以下条件才能自动完成：
 - 所有 checklist 项均为 `[x]`
-- functional/manual 在契约、证据和覆盖表中均为 `verified`；仅 E2E 可为 `e2e_deferred`，仍不得遗留未登记的 `planned` / `pending` / `TBD`
+- functional 在契约、证据和覆盖表中均为 `verified`；E2E 可为 `e2e_deferred`，`manual` 场景与 review 层 manual 规则延后到需求级终验由用户确认，仍不得遗留未登记的 `planned` / `pending` / `TBD`
 - 测试层级未低于 design，关键真实边界没有被 mock 绕过
-- 每个预期结果都有具体断言位置，functional 验收命令和回归测试均已实际通过；E2E 留到终验执行
-- `manual` 场景已有用户确认和可复核记录
+- E2E 按 `e2e_plan.owned` 登记，没有把 `deferred` 场景补成本任务测试；新增 E2E 必须回到 plan 重新过质量门禁
+- 每个预期结果都有具体断言位置，functional 验收命令和回归测试均已实际通过；相关批次关键 E2E 可先验证，终验补足证据缺口
+- 显式 `stage: code` 的 manual 规则已有用户确认和可复核记录；默认 review 层的 manual 规则与 manual 场景在 verify-e2e 一次性确认
+
+普通 task 完成后，相关批次可执行 `code-flow task verify --task-dir "<需求目录>" --tasks TASK-001 --layers validators,e2e --profile smoke --root "$PWD" --json`。只选择依赖已就绪的关联 smoke；`not_ready` 或失败保留真实状态，不阻断无关任务。不要将全域浏览器或容量检查作为每个普通 task 的默认工作。
 
 满足后，执行唯一收尾入口：
 
 ```bash
-python3 .code-flow/scripts/cf_task_workflow.py finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
+code-flow task finish --root "$PWD" --task-dir "<需求目录>" --task TASK-001 --json
 ```
 
-该命令先校验完整任务身份与锁定 manifest，再执行 Done Gate（acceptance 场景 + spec verifiers + 全量 validation.yml，含 heavy）；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
+该命令先校验完整任务身份与锁定 manifest，再执行 Done Gate：本任务范围（`Spec-Refs` ∪ 改动路径命中）的 code verifier + 本任务 acceptance 场景 + 轻量 validation.yml（不含 heavy）；范围外且明确归属需求级 review 的 verifier 标记 `deferred_to_review`，`heavy: true` validator 标记 `deferred_heavy`，统一在需求级 verify-e2e / 归档全量补跑；本任务 required code 检查因预算、环境或其他原因未执行时进入 `provisional`，保留 active marker，补齐检查后重新执行 finish，不能标记 done；通过后以可恢复事务更新 done、Log、Updated 并清理 marker。只有 `decision=pass` 才输出完成并启动下一 TASK。禁止手动设置 done 或传入自报的 gate_passed 绕过验证。
+
+Done Gate 只执行 code 层验证；review 层 manual 规则与 manual 场景不逐任务确认，延后到需求级 verify-e2e（返回 `manual_confirmation_required` 时按该命令的「人工验收确认」流程一次性确认）。
 
-任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
+验收断言失败时保持 `in-progress`；required code 检查未执行时由运行时转为 `provisional`。明确列出缺口，不能标记为 `done`。
 
 ### 5. 文档同步检查
 
@@ -192,7 +200,7 @@ Spec 同步提示:
 #### 4.1 并行预检与 worktree 准备
 
 ```bash
-python3 .code-flow/scripts/cf_task_parallel.py prepare --root "$PWD" \
+code-flow task parallel prepare --root "$PWD" \
   --task-file "<任务文件相对路径>" --tasks TASK-001,TASK-003 --json
 ```
 
@@ -204,52 +212,61 @@ python3 .code-flow/scripts/cf_task_parallel.py prepare --root "$PWD" \
 若当前平台提供子 agent/Task 派发能力，为本批次每个 TASK 各派发一个子 agent（同一批并发不超过 3，超出时按 TASK 顺序拆成多轮）。子 agent prompt 必须包含 worktree 绝对路径、TASK-ID、任务文件相对路径，并声明以下硬性要求：
 
 1. 进入 worktree：所有命令 `cd <worktree>` 执行，文件读写使用该 worktree 内路径。
-2. 按本命令"单任务模式"步骤 1-4 完成该 TASK：`cf_spec_context.py start` → functional RED → 实现 → functional GREEN（E2E 只登记）→ `cf_task_workflow.py finish --root "<worktree>"`。
-3. 平台 hook 注入绑定主工作区；子 agent 必须显式读取 Spec Session（`.code-flow/specs/_session/task-*.md`）与详设章节，不得依赖自动注入。
+2. 按本命令"单任务模式"步骤 1-4 完成该 TASK：`code-flow task start` → functional RED → 实现 → functional GREEN（E2E 按计划登记并在相关批次验证）→ `code-flow task finish --root "<worktree>"`。
+3. 平台 hook 注入绑定主工作区；子 agent 必须显式读取 Spec Session（路径取 start 返回的 `session_output`，默认 `.code-flow/specs/_session/task-<任务文件stem>.md`）与详设章节，不得依赖自动注入。
 4. 完成时在 worktree 内提交全部改动（含任务文件 Checklist/Evidence/Status 更新），提交信息 `cf-task(<TASK-ID>): <标题>`。
-5. 返回摘要：TASK-ID、Status、验收命令及结果、提交 SHA、遗留问题。
+5. `finish` 返回 `decision: block` 时不得提交：保留现场，原样回报阻断原因（如 scope expansion 新增 required Spec、验收失败）与 `code-flow spec status --json` 输出，由主 agent 决定局部 Plan/Align、修复后重派或接管；不得自行 resume 绕过门禁。
+6. 返回摘要：TASK-ID、Status、验收命令及结果、提交 SHA、遗留问题。
+
+标准 worker prompt 模板（替换占位符后派发）：
+
+```
+你在隔离 worktree 中执行 <TASK-ID>：<worktree 绝对路径>。
+1) cd 到 worktree；先读 Spec Session（start 返回的 session_output，默认 .code-flow/specs/_session/task-<任务文件stem>.md）、任务文件的当前 TASK 段落与 design 来源章节；
+2) code-flow task start → 写验收测试记录 RED → 实现 → GREEN；
+3) 运行 code-flow task finish --root "$PWD" --task <TASK-ID> --json；decision=pass 后【再】提交全部改动（含 finish 回写的 Evidence/状态）：git add -A && git commit -m "cf-task(<TASK-ID>): <标题>"；
+4) 返回摘要：TASK-ID、Status、验收命令与结果、commit SHA、遗留问题。
+```
+
+> 提交必须在 finish 之后：finish 通过后会回写 Evidence/状态；collect 默认会自动提交这些回写，但显式提交更清晰。
+
+子 agent 中断（取消/超时）时不要重新 prepare：检查该 worktree 的 `git status`、`git log <base>..HEAD` 与 marker——
+- 无改动且无 marker：直接接管，按单任务模式继续；
+- 有未提交改动或已有提交但未 done：在 worktree 内接管收尾（补实现/测试并 finish），再走 4.3 collect；
+- 已 done 且 marker 已清理：直接进入 4.3。
 
 平台不支持子 agent 时，不建 worktree，直接走 4.6 串行回退。
 
 #### 4.3 收集与校验
 
 ```bash
-python3 .code-flow/scripts/cf_task_parallel.py collect --root "$PWD" --run-id <run_id> --json
+code-flow task parallel collect --root "$PWD" --run-id <run_id> --json
 ```
 
 - 每个任务必须 `ok: true`（改动已提交、Status 为 done/verified、marker 已清理、有提交）。
+- `collect` 在任务 done/verified 且 marker 已清理后，会自动提交 finish 回写的 Evidence/状态（`--no-commit` 关闭并回到严格模式）；finish 之外的未提交改动仍应人工确认。
 - 任一任务失败：停止本批次，不合并；保留 worktree 并列出失败原因。修复后重跑 collect；确认放弃时执行 4.5 cleanup。
 
 #### 4.4 回并主分支
 
-按 TASK-ID 先后顺序逐个回并；先 rebase 再合并，让冲突只在任务自己的 worktree 内解决。
-
-1. 取主工作区当前分支名（主工作区执行 `git rev-parse --abbrev-ref HEAD`，记为 <主分支>），在任务 worktree 内对齐：
+按 TASK-ID 先后顺序回并。统一入口自动完成：worktree 内 rebase → 状态文件冲突按确定性并集规则解决 → 主工作区 `--no-ff` 合并 → `code-flow spec refresh` 收敛 hash：
 
 ```bash
-cd <worktree> && git rebase <主分支>
+code-flow task parallel merge --root "$PWD" --run-id <run_id> --json
 ```
 
-- rebase 冲突：读取冲突现场 + 本任务详设章节与 Acceptance Contract，合并双方意图（不是二选一）；无法调和（设计要求互斥）→ `git rebase --abort`，保留现场与分支，列出矛盾点叫停交用户决策，不得擅自删除一方实现。
-- rebase 成功后重跑该任务的 functional 验收命令（E2E 留给 verify-e2e）；失败则在 worktree 内修复并提交，再执行 4.3 collect 复核。
+- 返回 `ok: true` 才继续；`already_merged` 表示该任务已并入（幂等，可重跑）；任一任务失败即停止，修复后重跑 merge 续跑。
+- `code_conflict`：代码文件冲突无法程序化合并（返回冲突文件列表，rebase 已中止、主工作区未受影响）。人工读取冲突现场 + 本任务详设章节与 Acceptance Contract，合并双方意图（不是二选一）；无法调和（设计要求互斥）→ 保留现场与分支，列出矛盾点叫停交用户决策，不得擅自删除一方实现。解决后重跑 merge。
+- 状态文件冲突（任务 md 覆盖状态列 / `spec-context.yml` / `.acceptance-manifest.json`）由 merge 自动按确定性并集规则处理，无需手工编辑：覆盖状态列两边各自 verified 的行均保留；`spec-context.yml` 取证据并集、verified 优先；manifest 按 verified/revision 合并。
+- merge 成功后自动执行 `refresh` 并在结果中返回 `pass` / `block: ...`；随后重跑合并双方的 functional 验收与 `cf_spec_gate --stage code --json`，失败则记录合并前 HEAD 并 `git reset --hard <合并前HEAD>`（分支与 worktree 原样保留），回到 4.2 让对应子 agent 修复后重新 collect / merge。
+- merge 运行关联批次 smoke；其他 E2E 由需求终验按证据缺口补验。
 
-2. 回到主工作区合并（此时应无冲突）：
-
-```bash
-git merge --no-ff -m "merge cf-task <TASK-ID>" <branch>
-```
-
-- 仍出现冲突（主区期间有新合并）：按双方意图解决并重跑双方 functional 验收；通过后提交 merge。
-- 合并后验收失败：记录合并前 HEAD 并 `git reset --hard <合并前HEAD>`（分支与 worktree 原样保留），回到 4.2 让对应子 agent 修复后重新 collect / rebase / 合并。
-
-3. 全部任务合并完成后进入 4.5 清理。
-
-- E2E 验收留给 verify-e2e，不在本步骤执行。
+全部任务合并完成后进入 4.5 清理。
 
 #### 4.5 清理
 
 ```bash
-python3 .code-flow/scripts/cf_task_parallel.py cleanup --root "$PWD" --run-id <run_id> --json
+code-flow task parallel cleanup --root "$PWD" --run-id <run_id> --json
 ```
 
 清理 worktree；已合入的分支自动删除，未合入的保留供排查。worktree 存在未提交改动时 cleanup 会拒绝，先人工确认再决定处理方式。全部批次完成后进入步骤 5。
@@ -283,3 +300,18 @@ Spec 同步提示:
 ```
 
 3. 若需求目录已无 `draft` / `in-progress` / `blocked` 子任务，提示：运行 `/cf-task:verify-e2e <需求目录>` 执行延迟的 E2E 终验。
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow spec status --task-dir "<需求目录>" --root "$PWD" --json
+code-flow spec refresh --task-dir "<需求目录>" --root "$PWD" --json
+code-flow task start --task-dir "<需求目录>" --task-file "<任务文件>" --task TASK-001 --root "$PWD" --json
+code-flow task finish --task-dir "<需求目录>" --task TASK-001 --root "$PWD" --json
+code-flow task verify --task-dir "<需求目录>" --tasks TASK-001,TASK-002 --layers validators,e2e --profile smoke --root "$PWD" --json
+code-flow task parallel --help
+```
+
+<!-- code-flow:runtime-commands end -->

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

@@ -1,5 +1,17 @@
 # cf-task:status
 
+## 命令面（0.8）
+
+`cf-task-status` 收敛了原先三个独立命令；旧命令保留一个 minor（0.9.0 移除）：
+
+| 子动作 | 等价旧命令 | 用途 |
+|--------|-----------|------|
+| `--notes` | `cf-task-note` | 讨论并收敛 `#NOTES` |
+| `--block` | `cf-task-block` | 标记阻塞并记录原因 |
+| `--graph` | `cf-task-graph` | 依赖 DAG 与并行批次 |
+
+带上述参数时，按对应旧命令章节的步骤执行；不带参数时行为不变。
+
 显示任务状态总览。
 
 ## 输入