@michaelxwb/code-flow 0.6.4 → 0.8.1

package/src/adapters/costrict/commands/cf-stats.md

@@ -18,7 +18,7 @@
 用 Bash 执行：
 
 ```bash
-python3 .code-flow/scripts/cf_stats.py [--human] [--domain=frontend] [--audit]
+code-flow stats [--human] [--domain=frontend] [--audit]
 ```
 
 将用户传入的参数原样透传。
@@ -84,3 +84,13 @@ COMPRESSION: 1820 → 1580 (-13.2%)
 
 - `.code-flow/` 不存在 → 提示运行 `/project:cf-init`
 - Python 脚本执行失败 → 输出错误信息，建议检查 Python 环境
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow stats --help
+```
+
+<!-- code-flow:runtime-commands end -->

package/src/adapters/costrict/commands/cf-sync.md

@@ -1,25 +1,39 @@
 # cf-sync
 
+> **命令面状态（0.8）**：internal — 仅开发/发布维护使用，不属于 0.8 用户命令面；普通用户无需调用。
+
 一键同步双副本（canonical 源 → 部署副本），并检查漂移。用法：
 
-- `python3 .code-flow/scripts/cf_sync.py check` — 检查全部配对是否一致（默认）
-- `python3 .code-flow/scripts/cf_sync.py sync` — 把 canonical 源复制到部署副本
-- `python3 .code-flow/scripts/cf_sync.py check --verbose` — 额外列出部署侧独有文件
+- `code-flow sync check` — 检查全部配对是否一致（默认）
+- `code-flow sync apply` — 把 canonical 源复制到部署副本
+- `code-flow sync check --verbose` — 额外列出部署侧独有文件
 
 ## 同步配对
 
 | canonical 源 | 部署副本 | 同步内容 |
 |---|---|---|
-| `src/core/code-flow` | `.code-flow` | `scripts/`、`.version`、`.gitignore` |
+| `src/core/code-flow` | `.code-flow` | `scripts/`、`runtime-commands.json`、`.version`、`.gitignore` |
 | `src/adapters/claude` | `.claude` | `commands/` |
-| `src/adapters/codex` | `.codex` | `hooks.json` |
 | `src/adapters/codex/skills` | `.agents/skills` | 全部 |
 | `src/adapters/costrict` | `.costrict` | `commands/` |
 | `src/adapters/opencode` | `.opencode` | `commands/`、`plugins/` |
 
+`.codex/hooks.json` 由 init 的合并逻辑和 runtime 事务迁移管理，不属于 cf-sync 的字节同步配对。
+
 ## 规则
 
 1. 项目自有内容（`specs/`、`tasks/`、`config.yml`、`validation.yml`、`settings.local.json`）不在同步范围内，不会被动覆盖。
 2. 部署侧独有文件不会被删除（避免误删本地产物）。
-3. 只改一侧 = 测试通过但 live 行为不变；改完 canonical 源后运行 `cf-sync sync` 部署，提交时双副本一起提交。
+3. 只改一侧 = 测试通过但 live 行为不变；改完 canonical 源后运行 `code-flow sync apply` 部署，提交时双副本一起提交。
 4. 每对 `check` 全绿后提交，保证四平台命令与运行副本同步。
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow sync check --help
+code-flow sync apply --help
+```
+
+<!-- code-flow:runtime-commands end -->

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

@@ -2,6 +2,14 @@
 
 从需求出发，通过结构化对话产出设计简报（`.design.md`），为 `cf-task:plan` 提供足够丰富的输入。支持三种输入：纯文本需求、`.prd.md` 产品需求文档、`.design.md` 草稿。
 
+## Scenario-First（0.9）
+
+全栈用户场景统一写入 `<需求>.scenarios.md`，作为验收场景唯一源；design 文档只写实现逻辑并引用场景 ID。场景文件不存在时，新需求不得进入 plan。
+
+设计简报 frontmatter 写明实际选择的 `design_template: lite`、`full` 或 `frontend`。FEAT/API/NFR 定义与场景引用必须闭合；每个范围内功能关联验收场景。生成后执行 `code-flow design lint --file "<需求>.design.md" --scenarios-file "<需求>.scenarios.md" --json`，多份设计重复传 `--file`。按模板保留必填章节，不适用的可选章节按模板删除。
+
+场景区分浏览器 E2E 与 API/CLI 的 system/integration；capacity 可使用独立层级或 tags。expected 必须具体，并通过 expected_refs 关联步骤或已声明断言；延后场景保留原因、责任人及目标阶段。详细可执行格式见 `docs/acceptance-contract.md`。
+
 ## 输入
 
 - `/cf-task:align "需求描述"` — 从需求描述新建设计简报
@@ -114,7 +122,7 @@ PRD 已覆盖的维度如无需调整，将直接使用。
 
 进入技术讨论前先定位需求目录中的 `spec-context.yml`：
 
-1. PRD 派生/恢复模式必须执行 `python3 .code-flow/scripts/cf_spec_context.py refresh --task-dir <需求目录> --root "$PWD" --json`；missing/stale/conflict 必须先处理。
+1. PRD 派生/恢复模式必须执行 `code-flow spec refresh --task-dir <需求目录> --root "$PWD" --json`；missing/stale/conflict 必须先处理。
 2. 已有 binding 必须从 PRD Context 原样继承，**不得重新选择**、降级 enforcement 或清空 PRD 阶段 refs/decision/evidence。根据预计实现路径运行 `catalog --stage design`，只对新增 design-stage 候选做增量 bind，并记录 reason。
 3. 为每条 design-stage required Rule 预建 `Spec Compliance Matrix` 行：`Spec/Rule`、enforcement、设计影响、具体设计落点、验证场景/verifier、状态或 N/A 理由。
 4. required Rule 没有具体 heading/item 和验证方式时不得进入可评审状态；只写“遵循规范”无效。
@@ -172,7 +180,9 @@ CLI 场景：
 **验收标准**（必选）
 - 怎么判断做完了？正常 / 异常场景各列至少一条
 - 可验证、可转为自动化测试断言的条件（明确输入与可观测输出）；场景 ID（S-/E-/B-）即测试用例来源
-- 为每个场景指定测试层级（unit / integration / E2E / manual）和关键真实边界；跨 API、存储、运行时生成、渲染或用户可见结果等多个边界时必须选 E2E
+- 为每个场景指定测试层级（unit / component / contract / integration / E2E / manual）和关键真实边界；按最低可覆盖层选择：UI/表单/布局用 component，DTO/错误码用 contract，鉴权/事务/模块边界用 integration，只有真实浏览器 + 真实后端 + 鉴权/DB 才能暴露的 P0/P1 关键旅程才用 E2E
+- ✅ CAS 冲突由 contract + component + 真实存储 integration 共同证明；聚合补零用数据 contract + component，关系绑定用真实存储 integration。Cookie 身份隔离和 SSE 恢复可保留对应关键 E2E。❌ 按用户可见结果机械增加 E2E 或用固定比例决定层级；描述独特故障、低层覆盖和剩余接线风险，由设计评审判断。
+- E2E 场景必须同时给出 `why_e2e`（低层为什么不够）、`trigger_paths`（哪些源码变化触发）和 `smoke`（是否发布冒烟）；缺少时不得进入 plan
 - RULE 与高影响 RISK 必须映射到至少一个 S/E/B 场景；manual 仅限无法自动化的外部条件，必须写明原因
 
 **妥协与技术债**（按需）
@@ -283,7 +293,7 @@ CLI 场景：
 写入后，对 Matrix 每一行调用 `bind --stage design` 的 `applications` 回填 design artifact、`section_id`、稳定 `item_id` 和脚本计算的 hash；随后执行：
 
 ```bash
-python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage design --json
+code-flow spec gate --task-dir <需求目录> --stage design --json
 ```
 
 只有 Design Gate `decision=pass` 才能输出 Plan 下一步。缺 Matrix 行、artifact ref、验证方式、用户确认或发生 drift 时保留草稿并修复，不得推迟到 Coding/Done 才发现。
@@ -307,3 +317,15 @@ python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage des
   - 标注问题: 在文件中添加 #NOTES，然后 /cf-task:note <name>.design
   - 生成任务: /cf-task:plan <完整路径>
 ```
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow spec refresh --task-dir "<需求目录>" --root "$PWD" --json
+code-flow spec gate --help
+code-flow design lint --file "<需求>.design.md" --scenarios-file "<需求>.scenarios.md" --json
+```
+
+<!-- code-flow:runtime-commands end -->

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

@@ -4,7 +4,7 @@
 
 ## 输入
 
-- `/cf-task:archive <file>` — 归档指定的 task 文件
+- `/cf-task:archive <需求目录或任务文件>` — 定位需求，通过运行时归档整个需求目录
 
 其中 `<file>` 可省略日期目录前缀和 `.md` 后缀。
 
@@ -16,7 +16,8 @@
 
 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`；其他状态不能归档。
 
 若有未完成子任务，拒绝归档并输出：
 
@@ -32,28 +33,27 @@
 
 ### 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 没有结构化场景时注明“不适用”，不得伪造覆盖
 
 **一致性**：
@@ -64,35 +64,25 @@
 ```
 归档前校验:
   [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 都必须执行）**：
 
@@ -107,8 +97,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：
@@ -136,16 +124,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）尚未迁移时，报告原路径与缺少的需求边界，不输出“已归档”。
 
 ```
 摘要:
@@ -157,3 +140,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/costrict/commands/cf-task/block.md

@@ -1,5 +1,7 @@
 # cf-task:block
 
+> **命令面状态（0.8）**：alias — 等价于 `cf-task-status --block`；保留一个 minor，0.9.0 移除。
+
 标记子任务为阻塞状态。
 
 ## 输入
@@ -20,7 +22,7 @@
 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 不得改动。
@@ -30,7 +32,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/costrict/commands/cf-task/graph.md

@@ -1,5 +1,7 @@
 # cf-task:graph
 
+> **命令面状态（0.8）**：alias — 等价于 `cf-task-status --graph`；保留一个 minor，0.9.0 移除。
+
 可视化子任务的依赖关系 DAG，识别可并行执行的任务组。
 
 ## 输入
@@ -15,7 +17,7 @@
 
 ### 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` 仅为后者的兼容别名，不要把它显示成组内并行。
 
@@ -78,3 +80,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/costrict/commands/cf-task/note.md

@@ -1,5 +1,7 @@
 # cf-task:note
 
+> **命令面状态（0.8）**：alias — 等价于 `cf-task-status --notes`；保留一个 minor，0.9.0 移除。
+
 与用户协作讨论文件中的 `#NOTES` 标记，对齐最优解后将结论沉淀回原文，删除标记。
 
 支持两种文件类型：
@@ -134,7 +136,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. 输出摘要
@@ -234,3 +236,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 -->