@michaelxwb/code-flow 0.6.4 → 0.8.1

package/src/adapters/claude/commands/cf-task/verify-e2e.md

@@ -1,15 +1,32 @@
 ---
-description: Execute deferred E2E scenarios after all functional tests pass
+description: Run layered verification or full requirement verification, including deferred E2E
 globs: []
 ---
 
 # cf-task:verify-e2e
 
+
+## 验证子动作（0.8）
+
+- `code-flow task verify --checks` — 等价于 `--layers validators`，是 `cf-validate` 的 0.8 入口。
+- `code-flow task verify-e2e --checks` 同样只跑 validators；需要包含 heavy validator 时显式指定 `--profile full`。仅 validators 可在任务进行中运行，使用 active TASK 基线以来的变更，不推进任务状态。
+- `cf-validate` 保留为兼容别名，0.9.0 移除。
+
 执行需求目录下被延迟的 E2E 验收场景。
 
 ## 使用场景
 
-E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶段默认跳过（状态 `e2e_deferred`）。当所有子任务的 functional 测试通过后，使用此命令统一执行 E2E 验收。
+本命令是**需求级终验**入口，在所有子任务的 functional 测试通过后统一执行：
+
+1. **全量 verifier**：需求目录全部 task context 绑定的 required rules（code 层被任务延后的 `deferred_to_review` + `stage: review` 重型验证），按 spec/rule 去重全量执行一次，证据写回全部相关 context；输出 `executed` / `reused` / `failed` 计数。
+2. **E2E 验收场景**：依赖外部环境（数据库、API、浏览器等）、编码阶段标记 `e2e_deferred` 的场景；已通过且工作树内容指纹未变的场景跨运行复用（不重复执行 E2E），内容变化/失败自动重跑，`code-flow acceptance run --no-cache` 可强制全量。
+3. **全量 validation**：执行 `validation.yml` 全部 validator（含 `heavy: true` 全量套件/构建/E2E）；结果按工作树内容指纹缓存，归档复验命中即复用、不重复执行，`code-flow validate --no-cache` 强制重跑。
+
+失败不写 verified、不反转已 done 的任务状态；归档前必须 `decision=pass`。未声明 review verifier 且无 E2E 场景时为空操作（`reason=nothing_to_verify`）。
+
+> 0.8 分层入口：`code-flow task verify --layers validators,review,e2e --profile smoke|changed|full`。每层独立返回 `decision/executed/reused/failed/env_blocked/incomplete`，`profile` 默认 `changed`，`full` 必须显式；`task verify-e2e` 保留为兼容别名（全层 + full）。
+>
+> E2E 也按范围执行：`profile=changed` 只跑 `trigger_paths` 命中当前 diff 的 E2E，没有 `trigger_paths` 的 smoke E2E 不会在 changed 中顺跑；`profile=smoke` 只跑标记 `smoke` / `profile=smoke` 的 E2E（旧计划没有 smoke 标记时才回退全量 E2E）。不要把全量 E2E 当成每个小改动的默认门禁。
 
 ## 调用方式
 
@@ -27,58 +44,69 @@ E2E 测试依赖外部环境（数据库、API、浏览器等），在编码阶
 rg "^- \*\*Status\*\*:" <需求目录>/*.md
 ```
 
-如有 `in-progress` 或 `blocked` 任务，提示用户先完成。
+本步骤只适用于包含 review/e2e 的需求验证。如有 `in-progress` 或 `blocked` 任务，先完成任务；仅 `--checks` / `--layers validators` 不要求任务 done，但仍校验 active Context 与需求身份。
 
 ### 2. 检查环境依赖
 
-读取 `.acceptance-manifest.json` 中的 E2E 场景，提取所需的外部依赖（从 `boundary` 字段推断）：
+读取所选 checks 的 `env`、`env_scope`、`preflight` 声明。运行时在实际执行 check 前自动运行 preflight；已有有效证据时允许复用。不要从 `boundary` 猜测端口、数据库或驱动，也不要固定询问环境是否就绪。
 
-- `HTTP API` → 提示确认 API 服务运行中
-- `Browser` → 提示确认浏览器驱动已安装
-- `Database` → 提示确认测试数据库可访问
+收到 `env_blocked` 时，展示 `env_blocked_details` 中的 check ID、owner、失败的 preflight 命令、退出码和输出。根据真实失败修复可处理的本地问题；只有缺少外部配置、需要用户启动外部环境或涉及权限时请求用户输入。未声明 preflight 的检查仍按真实执行结果判断，不能自报环境已通过。
 
-显示清单并询问：
+### 3. 执行 E2E 场景
 
-```
-E2E 场景需要以下环境：
-  - 本地 API 服务 (http://localhost:3000)
-  - PostgreSQL 测试数据库
-  - Chrome WebDriver
+用户请求需求级终验时，执行：
 
-环境已就绪？(y/N)
+```bash
+code-flow task verify \
+  --task-dir "<需求目录>" --root "$PWD" \
+  --layers validators,review,e2e --profile full --json
 ```
 
-### 3. 执行 E2E 场景
+相关批次使用 `code-flow task verify --tasks TASK-001,TASK-002 --layers validators,e2e --profile smoke`；部分通过仅表示所选范围通过，不提升整个需求。日常增量验证使用 `--profile changed`，明确只跑 smoke 时使用 `--profile smoke`；不要把增量请求升级成全量。`code-flow task verify-e2e` 保留为默认全层 full 的兼容入口。仅检查代码时使用 `code-flow task verify --checks --task-dir "<需求目录>" --root "$PWD" --json`。
+
+全量终验重新检查所有 TASK、锁定 manifest 与 functional/manual 最新证据，执行全量 validation（含 heavy）和 code+review verifier（含 deferred 项）。runner 按范围执行 acceptance：仅 E2E 的路径使用 `--only-e2e`，full 或 functional 证据过期时同时复验所需 functional。只有全层 full 通过才将任务提升为 verified；单层、changed、smoke 通过均不推进状态。不得手动改状态。
 
-用户确认后，执行：
+### 4. 人工验收确认（manual_confirmation_required）
+
+需求中的 manual 验收默认落 review 层，编码阶段不逐任务打断，统一在这里确认。`verify-e2e` 返回 `reason=manual_confirmation_required` 时：
+
+1. 向用户完整展示 `manual_rules`（spec 规则、checklist、owner）与 `manual_scenarios`（场景 ID、真实边界），一次性请求确认；用户只确认部分时记录未确认的 ref/id。
+2. 用户明确回复后执行（`--confirmed-by` 必须是用户身份，Agent 不得代确认；`--source` 填写用户回复原文）：
 
 ```bash
-python3 .code-flow/scripts/cf_task_workflow.py verify-e2e \
-  --task-dir "<需求目录>" --root "$PWD" --json
+code-flow task confirm-manual \
+  --task-dir "<需求目录>" --root "$PWD" \
+  --confirmed-by "user:<用户>" --source "<用户回复原文>" --json
 ```
 
-该入口重新检查所有 TASK、锁定 manifest 和 functional/manual 最新证据，内部以 `--only-e2e` 调用 runner；只有全通过才把任务提升为 verified。不得手动改状态。
+部分确认时追加 `--refs <spec#RULE,...>` 与/或 `--scenarios <S-01,...>`。
+3. 重跑 `verify-e2e`；全部通过后任务才提升为 `verified`。
+
+> 显式声明 `stage: code` 的 manual 规则仍在任务 Done Gate 逐个确认，属于有意保留的强门禁。
 
-### 4. 报告结果
+### 5. 报告结果
 
 解析执行结果：
 
 ```json
 {
   "decision": "block",
-  "results": [
-    {"id": "E-01", "kind": "e2e", "status": "passed"},
-    {"id": "E-02", "kind": "e2e", "status": "failed", "exit_code": 1}
-  ]
+  "layers": {
+    "e2e": {
+      "decision": "block",
+      "checks": [{"id": "CHK-B", "status": "failed", "scenarios": ["E-02"]}]
+    }
+  }
 }
 ```
 
-- `decision=pass`：所有 E2E 场景通过，提示"E2E 验收完成"
-- `decision=block`：有失败场景，列出失败的场景 ID 和错误信息
+- `decision=pass`：报告实际 `selected_layers`、`profile`、执行与复用计数，不将部分范围通过报告为全量终验完成
+- `decision=block`：列出失败层、场景 ID 与 check ID，从 `check_results` 或 `env_blocked_details` 展示对应命令、退出码和错误输出
+- `reason=manual_confirmation_required`：先按「人工验收确认」章节取得用户确认并执行 `confirm-manual`，再重跑本命令
 
-### 5. 更新任务状态
+### 6. 更新任务状态
 
-确认命令已将需求目录下所有任务 Status 更新为 `verified`，并保留原契约与运行历史。无需再次编辑状态。
+全层 full 通过后确认运行时已将任务 Status 更新为 `verified`，并保留原契约与运行历史。其他验证范围保留原状态。无需再次编辑状态。
 
 ## 失败处理
 
@@ -86,7 +114,7 @@ E2E 失败时：
 
 1. 显示失败场景的完整命令和退出码
 2. 提示查看 `.acceptance-manifest.json` 中的 `evidence` 字段
-3. 不自动修改任务状态，等待用户修复后重新执行
+3. 修复可处理的问题后重跑所选范围；缺少用户输入时报告具体阻塞，不自动修改任务状态
 
 ## 示例
 
@@ -95,11 +123,7 @@ E2E 失败时：
 
 > 检查子任务状态... 所有任务已完成
 > 
-> E2E 场景需要以下环境：
->   - 本地 API 服务 (http://localhost:3000)
->   - PostgreSQL 测试数据库 (postgresql://localhost:5432/test)
-> 
-> 环境已就绪？(y/N) y
+> 按 checks 声明执行 preflight... 通过
 > 
 > 执行 E2E 场景...
 >   ✓ E-01: 用户登录流程 (1.2s)
@@ -108,3 +132,17 @@ E2E 失败时：
 > E2E 验收完成！2/2 场景通过
 > 已更新任务状态为 verified
 ```
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow task verify --task-dir "<需求目录>" --tasks TASK-001,TASK-002 --layers validators,e2e --profile smoke --root "$PWD" --json
+code-flow task verify-e2e --task-dir "<需求目录>" --root "$PWD" --json
+code-flow task confirm-manual --help
+code-flow acceptance run --manifest "<需求目录>/.acceptance-manifest.json" --root "$PWD" --write-evidence
+code-flow validate --root "$PWD" --json
+```
+
+<!-- code-flow:runtime-commands end -->

package/src/adapters/claude/commands/cf-validate.md

@@ -1,5 +1,7 @@
 # cf-validate
 
+> **命令面状态（0.8）**：alias — 等价于 `cf-task-verify-e2e --checks`（运行时 `code-flow task verify --checks`）；保留一个 minor，0.9.0 移除。
+
 根据变更文件自动匹配并执行验证规则（测试、类型检查、lint），失败时自动尝试修复。
 
 ## 输入
@@ -15,7 +17,7 @@
 用 Bash 执行：
 
 ```bash
-python3 .code-flow/scripts/cf_validation.py --root "$PWD" --scope-only --json
+code-flow validate --root "$PWD" --scope-only --json
 ```
 
 有 active TASK 时使用冻结基线以来的全部任务变更（含已提交文件）；无 active TASK 时包含暂存、未暂存和未跟踪文件。用户指定路径时用 `--files "src/a.py" "src/b.py"` 原样传递；若结果确实为空才输出“无变更需要验证”。
@@ -32,21 +34,33 @@ validators:
     trigger: "**/*.{ts,tsx}"
     command: "npx tsc --noEmit"
     timeout: 30000
-    heavy: false          # true = Stop 每轮跳过，finish 与 /cf-validate 执行
+    heavy: false          # true = Stop 与 finish 跳过，需求终验与 /cf-validate 执行
     on_fail: "修复建议"
 ```
 
-全量测试 / e2e 等慢命令标 `heavy: true`：Stop 每轮跳过，**任务 finish 自动执行一次**，也可显式运行 `/cf-validate`（或 CI），避免拖慢每个任务。
+全量测试 / e2e 等慢命令标 `heavy: true`：Stop 与任务 finish 跳过，由需求终验 / 归档执行，也可显式运行 `/cf-validate`（或 CI），避免拖慢每个任务。
 
 ### 3. 匹配并执行验证
 
 执行统一验证入口：
 
+文末是通用入口示例；本技能的实际调用使用以下 validators 范围，不额外执行 review/e2e。
+
+- 有 active TASK 时走任务验证入口（`--checks` 等价于 `--layers validators`）：
+
+```bash
+code-flow task verify --checks --profile full --task-dir "<需求目录>" --root "$PWD" --json
+```
+
+- 无 active TASK 或用户显式指定文件时走变更验证入口：
+
 ```bash
-python3 .code-flow/scripts/cf_validation.py --root "$PWD" --json
+code-flow validate --root "$PWD" --json
 ```
 
-显式范围追加 `--files "src/a.py" "src/b.py"`。程序匹配 trigger、解析 argv 并展开 `{files}`，不拼接 shell 命令；同一运行内相同 argv/cwd/timeout 去重，跨运行不复用。删除文件仍触发全局测试，但不传给文件级编译器。每条 timeout 仍按配置的毫秒值生效，总预算耗尽返回 incomplete/block。
+仅 validators 支持任务进行中运行，不要求所有 TASK 完成，也不推进任务状态；active Context 损坏或身份不匹配仍阻断。`--profile full` 包含 heavy validator；只做轻量检查时明确使用 `--profile changed`。
+
+显式范围在 `code-flow validate` 后追加 `--files "src/a.py" "src/b.py"`。程序匹配 trigger、解析 argv 并展开 `{files}`，不拼接 shell 命令；通过结果按工作树内容指纹跨运行复用（失败永不缓存，需要强制重跑时使用 `code-flow validate --no-cache`），同一运行内相同 argv/cwd/timeout 去重。删除文件仍触发全局测试，但不传给文件级编译器。每条 timeout 仍按配置的毫秒值生效，总预算耗尽返回 incomplete/block。
 
 ### 4. 汇总结果
 
@@ -73,3 +87,14 @@ python3 .code-flow/scripts/cf_validation.py --root "$PWD" --json
 - 命令执行超时 → 输出超时提示，建议增大 timeout 或缩小验证范围
 - 命令不存在或配置无效 → 返回 block 并提示所缺依赖，不当作验证通过
 - 无变更文件 → 输出"无变更需要验证"
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow task verify --task-dir "<需求目录>" --tasks TASK-001,TASK-002 --layers validators,e2e --profile smoke --root "$PWD" --json
+code-flow validate --root "$PWD" --json
+```
+
+<!-- code-flow:runtime-commands end -->

package/src/adapters/codex/AGENTS.md

@@ -32,7 +32,7 @@ Do NOT ask the user which Specs to load—the Context-first router is authoritat
 
 1. 编辑代码后收到 **Spec 合规反馈 (auto-check)** 时，先按提示修正违规，再继续当前任务
 2. 用户表示某条反馈是误报（"这是误报"/"忽略这个检查"）时，代为执行：
-   `python3 .code-flow/scripts/cf_feedback.py ignore <check-id>`
+   `code-flow feedback ignore <check-id>`
    （check-id 见反馈中的 `规则: <spec>#<check-id>`；同一规则误报达阈值会自动停用）
 3. 会话收尾被校验拦回（cf-stop 反馈未过项）时，修复后再结束；不要绕过
 4. 新增/修改规范时优先用 ✅/❌ 代码对照示例表达（见 spec 模板 Examples 段）

package/src/adapters/codex/hooks.json

@@ -2,24 +2,26 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Edit|Write|MultiEdit",
+        "matcher": "^apply_patch$",
         "hooks": [
           {
             "type": "command",
-            "command": "d=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}\"; f=\"$d/.code-flow/scripts/cf_pre_tool_hook.py\"; if [ -f \"$f\" ]; then cd \"$d\" && python3 \"$f\"; fi",
-            "timeout": 5
+            "command": "d=\"$PWD\"; while [ ! -f \"$d/.code-flow/scripts/cf_codex_hook.py\" ] && [ \"$d\" != / ]; do d=\"$(dirname \"$d\")\"; done; f=\"$d/.code-flow/scripts/cf_codex_hook.py\"; if [ -f \"$f\" ]; then python3 \"$f\"; fi",
+            "timeout": 5,
+            "commandWindows": "py -3 -c \"import pathlib,runpy,sys; roots=(pathlib.Path.cwd(), *pathlib.Path.cwd().parents); script=next((root/'.code-flow/scripts/cf_codex_hook.py' for root in roots if (root/'.code-flow/scripts/cf_codex_hook.py').is_file()), None); sys.path.insert(0,str(script.parent)) if script else None; runpy.run_path(str(script),run_name='__main__') if script else None\""
           }
         ]
       }
     ],
     "PostToolUse": [
       {
-        "matcher": "Edit|Write|MultiEdit",
+        "matcher": "^apply_patch$",
         "hooks": [
           {
             "type": "command",
-            "command": "d=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}\"; f=\"$d/.code-flow/scripts/cf_post_hook.py\"; if [ -f \"$f\" ]; then cd \"$d\" && python3 \"$f\"; fi",
-            "timeout": 5
+            "command": "d=\"$PWD\"; while [ ! -f \"$d/.code-flow/scripts/cf_codex_hook.py\" ] && [ \"$d\" != / ]; do d=\"$(dirname \"$d\")\"; done; f=\"$d/.code-flow/scripts/cf_codex_hook.py\"; if [ -f \"$f\" ]; then python3 \"$f\"; fi",
+            "timeout": 5,
+            "commandWindows": "py -3 -c \"import pathlib,runpy,sys; roots=(pathlib.Path.cwd(), *pathlib.Path.cwd().parents); script=next((root/'.code-flow/scripts/cf_codex_hook.py' for root in roots if (root/'.code-flow/scripts/cf_codex_hook.py').is_file()), None); sys.path.insert(0,str(script.parent)) if script else None; runpy.run_path(str(script),run_name='__main__') if script else None\""
           }
         ]
       }
@@ -29,8 +31,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "d=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}\"; f=\"$d/.code-flow/scripts/cf_user_prompt_hook.py\"; if [ -f \"$f\" ]; then cd \"$d\" && python3 \"$f\"; fi",
-            "timeout": 5
+            "command": "d=\"$PWD\"; while [ ! -f \"$d/.code-flow/scripts/cf_codex_hook.py\" ] && [ \"$d\" != / ]; do d=\"$(dirname \"$d\")\"; done; f=\"$d/.code-flow/scripts/cf_codex_hook.py\"; if [ -f \"$f\" ]; then python3 \"$f\"; fi",
+            "timeout": 5,
+            "commandWindows": "py -3 -c \"import pathlib,runpy,sys; roots=(pathlib.Path.cwd(), *pathlib.Path.cwd().parents); script=next((root/'.code-flow/scripts/cf_codex_hook.py' for root in roots if (root/'.code-flow/scripts/cf_codex_hook.py').is_file()), None); sys.path.insert(0,str(script.parent)) if script else None; runpy.run_path(str(script),run_name='__main__') if script else None\""
           }
         ]
       }
@@ -40,8 +43,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "d=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}\"; f=\"$d/.code-flow/scripts/cf_stop_hook.py\"; if [ -f \"$f\" ]; then cd \"$d\" && python3 \"$f\"; fi",
-            "timeout": 35
+            "command": "d=\"$PWD\"; while [ ! -f \"$d/.code-flow/scripts/cf_codex_hook.py\" ] && [ \"$d\" != / ]; do d=\"$(dirname \"$d\")\"; done; f=\"$d/.code-flow/scripts/cf_codex_hook.py\"; if [ -f \"$f\" ]; then python3 \"$f\"; fi",
+            "timeout": 35,
+            "commandWindows": "py -3 -c \"import pathlib,runpy,sys; roots=(pathlib.Path.cwd(), *pathlib.Path.cwd().parents); script=next((root/'.code-flow/scripts/cf_codex_hook.py' for root in roots if (root/'.code-flow/scripts/cf_codex_hook.py').is_file()), None); sys.path.insert(0,str(script.parent)) if script else None; runpy.run_path(str(script),run_name='__main__') if script else None\""
           }
         ]
       }

package/src/adapters/codex/skills/cf-init/SKILL.md

@@ -158,11 +158,9 @@ AGENTS.md 的完整内容由适配器模板统一定义，`code-flow init` 已
 
 ### 6. 生成 .codex/hooks.json 和 .codex/config.toml
 
-检查 `.codex/hooks.json` 是否存在。如果不存在，用 apply_patch 创建，结构必须是三层：event → [{ hooks: [{ type, command }] }]，并包含 `PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop`。`PreToolUse` 必须沿用适配器 `hooks.json` 中的写文件 matcher，并调用 `cf_pre_tool_hook.py`；不要在技能正文重复其他平台的工具名。
+安装 Hook 和配置必须执行 `code-flow init --platform=codex`，由适配器模板统一生成/合并，保留用户配置。`PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop` 四个事件调用 `cf_codex_hook.py`，配置启用 `[features] hooks = true`，保留用户模型、sandbox、approval 设置，不得整文件覆盖；写文件 matcher 为 `^apply_patch$`，输入来自 `tool_input.command`、`cwd`、`session_id`。不得手工拼装或修改受管理 Hook。
 
-如果 `.codex/hooks.json` 已存在，只合并缺失事件或 command，保留用户自定义 hooks，不得整文件覆盖。
-
-检查 `.codex/config.toml`。如果缺少 `[features] hooks = true`，只补这一项；若存在旧版 `codex_hooks = true`，迁移为 `hooks = true`；保留用户已有模型、sandbox、approval 等配置。
+旧安装或清单校验失败时执行 `code-flow migrate --runtime --dry-run` 查看范围，再执行 `code-flow migrate --runtime --apply` 更新全部已安装平台。
 
 Codex 会要求 review/trust 非 managed command hooks。生成或更新 hook 后，提醒用户在 Codex CLI 中运行 `/hooks` 并信任 code-flow hooks。
 
@@ -271,3 +269,5 @@ Token 估算: ...
 ## v0.5 质量闭环部署说明
 
 init/upgrade 后新增：PostToolUse / Stop hook 注册（合规反馈与收尾守门）、`.code-flow/.gitignore`（运行时数据不入库）。运行时数据 `.session-log.jsonl` / `.check-state.json` 首次使用自动创建，仅存本地。规范写作建议：frontmatter 加 `description`（Spec Catalog 行）与 `checks`（机检标注），规则优先用 ✅/❌ Examples 段表达（cf-learn 候选自动生成草稿）。
+
+安装产物由 `code-flow init --platform=codex` 统一部署。脚本、Skill、Hook 的完整性由安装清单校验；损坏时执行 `code-flow migrate --runtime --dry-run` 查看修复范围，再执行 `code-flow migrate --runtime --apply`。不得凭技能名猜 Python 脚本入口。

package/src/adapters/codex/skills/cf-spec/SKILL.md

@@ -3,10 +3,6 @@ name: cf-spec
 description: Manage schema-v1 Spec Context, drift recovery, and prepared one-shot migration plans.
 ---
 
-# cf-spec
-
-管理 schema v1 Spec Context 与一次性迁移。用法：
-
 - `cf-spec migrate --plan <migration-plan.yml>`
 - `cf-spec context [需求目录]`
 - `cf-spec refresh [需求目录]`
@@ -36,14 +32,26 @@ description: Manage schema-v1 Spec Context, drift recovery, and prepared one-sho
 
 1. 读取并展示 `spec-context.yml` 的 bindings、Rule stage status、artifact refs、Evidence 与 drift。
 2. 执行：
-   `python3 .code-flow/scripts/cf_spec_context.py validate --task-dir <目录> --json`
+   `code-flow spec validate --task-dir <目录> --json`
 3. Context 缺失、schema/hash 无效时 fail-closed，不回退 Catalog。
 
+
+## status
+
+展示人话版 Context 状态：任务、marker hash 是否一致、code Gate 结果、各绑定 Rule 状态。
+
+执行：
+
+`code-flow spec status --task-dir <目录> --root "$PWD"`
+
+- marker 漂移时输出下一步：先 refresh 自动重同步；仍不一致时用 `active doctor --resync`（hash 取 status --json 的 context_sha256）。
+- 需要机器可读输出时加 `--json`。
+
 ## refresh
 
 执行：
 
-`python3 .code-flow/scripts/cf_spec_context.py refresh --task-dir <目录> --root "$PWD" --json`
+`code-flow spec refresh --task-dir <目录> --root "$PWD" --json`
 
 - changed required Rule 标为 stale，关联 stage Gate 必须阻断。
 - missing/conflict 不自动降级；回 Align 或 Plan 更新承接后再继续。
@@ -58,3 +66,23 @@ description: Manage schema-v1 Spec Context, drift recovery, and prepared one-sho
    - **marker 损坏或归属无法证明**：向用户说明影响，仅在用户明确确认放弃该 TASK 后执行 `active doctor --abandon`，随后重新规划该任务。
 3. `active doctor` 返回 `recovery_required`（退出码 3）是诊断结果而非崩溃：按第 2 步选择 refresh / `--resync` / `--abandon`，不要用 `--help` 探测或反复重试。
 4. 输出明确修复命令。不得删除损坏 marker、越过 required Gate 或静默切换到无任务模式。
+5. doctor 的安装/Context 健康结果与 `readiness.plan/code/review` 分开阅读。`applied` 只表示存在引用，不能替代 code/review 的 verified 执行证据；引用条目仍有“待同步/待确认/TBD”时返回 `rule_applied_unresolved`。
+6. `decision=null` 是自动验证的正常情况；无需改代码但已符合规则时提交对应证据，不强制用户 N/A。只有确实不适用/豁免时要求用户 decision。
+7. `convention_review_required` 表示绑定 Spec 的 Conventions 尚未成为可执行约束；审查与当前设计的冲突，关键条目提升为稳定 Rule 并配置 verifier。CLI 低于 runtime 时先按提示升级 CLI；不要尝试把项目 runtime 降级。
+
+## 规范自检与优化
+
+按 `docs/spec-optimization.md` 执行审计、路径预算、影响查询和只读优化预览。`code-flow spec optimize --apply --plan <提案>` 需要在交互终端展示并获得用户对具体 diff 的明确确认；不得代为确认。应用后对受影响需求执行 refresh 和 doctor。
+
+<!-- code-flow:runtime-commands start -->
+
+运行时命令示例（由命令契约生成；实际参数见各命令 --help）：
+
+```bash
+code-flow spec optimize --help
+code-flow spec validate --task-dir "<需求目录>" --json
+code-flow spec status --task-dir "<需求目录>" --root "$PWD" --json
+code-flow spec refresh --task-dir "<需求目录>" --root "$PWD" --json
+```
+
+<!-- code-flow:runtime-commands end -->

package/src/adapters/codex/skills/cf-stats/SKILL.md

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

package/src/adapters/codex/skills/cf-sync/SKILL.md

@@ -5,26 +5,41 @@ description: One-command canonical → deploy sync for dual-copy artifacts, with
 
 # 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/codex/skills/cf-task-align/SKILL.md

@@ -3,6 +3,14 @@ name: cf-task-align
 description: Generate a design brief (.design.md) from a requirement through structured interactive dialogue. Accepts plain text, an existing PRD (.prd.md) to derive from, or a .design.md draft to resume. Adapts to the nature of the work — feature development, refactoring, CLI tools, background jobs, performance optimization, etc.
 ---
 
+## 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 "需求描述"` — 从需求描述新建设计简报
@@ -20,7 +28,7 @@ description: Generate a design brief (.design.md) from a requirement through str
 |---------|------|------|
 | 已存在的 `.design.md` 文件 | **恢复模式** | 读取，展示当前内容，询问调整点，进入 Step 3 |
 | 已存在的 `.prd.md` 文件 | **PRD 派生模式** | 读取 PRD，执行 Step 2.6 预填充维度，Step 3 只补技术维度 |
-| 已存在的其他 `.md` 文件 | **新建模式（带上下文）** | 读取作为参考材料，进入 Step 2 |
+| 已存在的其他 `.md` 文件 | **新建模式（带上下文）** | 读取 作为参考材料，进入 Step 2 |
 | 纯文本字符串 | **新建模式** | 以文本作为初始需求，进入 Step 2 |
 | 无参数 | **交互模式** | 询问"要实现什么功能？"，进入 Step 2 |
 
@@ -28,9 +36,9 @@ description: Generate a design brief (.design.md) from a requirement through str
 
 快速了解项目现状，为后续建议提供依据：
 
-1. 用 `rg --files` 或 `find` 检查 `.code-flow/specs/*/_map.md` 是否存在，若有则读取（了解项目结构）
+1. 用 `rg --files` 检查 `.code-flow/specs/*/_map.md` 是否存在，若有则 读取（了解项目结构）
 2. 检测技术栈：读取 `package.json` / `requirements.txt` / `go.mod` / `pyproject.toml` 等（取存在的）
-3. 用 `rg --files` 或 `find` 扫描与需求相关的现有代码目录，了解已有模式
+3. 用 `rg --files` 扫描与需求相关的现有代码目录，了解已有模式
 
 目的：**让后续建议基于实际代码库**，而非泛泛的通用建议。
 
@@ -115,7 +123,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 和验证方式时不得进入可评审状态；只写“遵循规范”无效。
@@ -173,7 +181,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 仅限无法自动化的外部条件，必须写明原因
 
 **妥协与技术债**（按需）
@@ -272,19 +282,19 @@ CLI 场景：
    - **恢复模式**：保持原需求名
    - **新建/交互模式**：从目标推导 kebab-case，如 `user-auth`
 2. **确定需求目录**：
-   - **PRD 派生模式**：使用 PRD 所在的需求目录 `.code-flow/tasks/<日期>/<需求>/`（PRD 与 design 同目录，便于 `cf-task-archive` 整目录归档）
+   - **PRD 派生模式**：使用 PRD 所在的需求目录 `.code-flow/tasks/<日期>/<需求>/`（PRD 与 design 同目录，便于 `cf-task:archive` 整目录归档）
    - **恢复模式**：保持原目录
    - **新建/交互模式**：按当前日期创建需求目录 `.code-flow/tasks/<YYYY-MM-DD>/<需求>/`；目录已存在且非本次草稿时目录名追加序号 `<需求>-2`…
 3. **按域后缀命名**（同一需求目录内）：
    - 前端设计（design-frontend）→ `<需求>.frontend.design.md`
    - 后端/通用设计（design-lite/full）→ 全栈时 `<需求>.backend.design.md`；纯后端/通用单域时 `<需求>.design.md`
    - **全栈需求**：前后端各写一份到同一需求目录
-4. 用 apply_patch 写入最终路径
+4. 写入最终路径
 
 写入后，对 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 才发现。
@@ -308,3 +318,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 -->