@michaelxwb/code-flow 0.6.4 → 0.8.1

package/docs/spec-injection-performance.json

@@ -0,0 +1,73 @@
+{
+  "date": "2026-10-26",
+  "hardware": "Apple M5 Pro",
+  "python": "3.9.6",
+  "baseline_commit": "42a43b6",
+  "method": "Fresh Python process per Prompt/Hook, warm filesystem; direct service batch measurements use the same interpreter. Derived parse-cache cold/warm cases are identified separately. Milliseconds are machine-local samples, not SLAs.",
+  "path_prompt_one_match_500_specs": {
+    "before": {
+      "n": 10,
+      "median_ms": 229.33,
+      "p95_ms": 235.37,
+      "max_ms": 235.37
+    },
+    "after": {
+      "n": 10,
+      "median_ms": 56.02,
+      "p95_ms": 57.82,
+      "max_ms": 57.82
+    }
+  },
+  "unchanged_active_prompt_200_bindings": {
+    "before": {
+      "n": 10,
+      "median_ms": 285.23,
+      "p95_ms": 292.18,
+      "max_ms": 292.18
+    },
+    "after": {
+      "n": 10,
+      "median_ms": 56.48,
+      "p95_ms": 58.27,
+      "max_ms": 58.27
+    }
+  },
+  "edit_service_20_files_200_bindings_parse_cache_warm": {
+    "before": {
+      "n": 3,
+      "median_ms": 9631.24,
+      "p95_ms": 9641.59,
+      "max_ms": 9641.59
+    },
+    "after": {
+      "n": 3,
+      "median_ms": 8.03,
+      "p95_ms": 8.24,
+      "max_ms": 8.24
+    }
+  },
+  "installed_codex_20_files_200_bindings": {
+    "before": {
+      "timed_out": true,
+      "stdout_before_timeout": 0,
+      "elapsed_ms": 5004.3
+    },
+    "after": {
+      "bindings": 200,
+      "files": 20,
+      "fresh_python_process_each_event": true,
+      "timeout_seconds": 5,
+      "parse_cache_cold_ms": 333.36,
+      "cold_output_bytes": 455,
+      "parse_cache_warm_median_ms": 67.45,
+      "warm_max_ms": 68.53,
+      "warm_n": 10
+    }
+  },
+  "installed_integrity_check_after": {
+    "n": 20,
+    "median_ms": 3.14,
+    "p95_ms": 3.58,
+    "max_ms": 3.58
+  }
+}

package/docs/spec-optimization.md

@@ -0,0 +1,12 @@
+# Spec 自检与优化
+
+在项目根目录手动执行以下步骤；这些检查不会作为后台任务自动运行。四个平台 Claude、Codex、Costrict、OpenCode 均可通过终端使用同一 CLI，也可从 `cf-stats` 和 `cf-spec` 入口查看指引。
+
+1. 体检：`code-flow stats --audit --human`（机器读取使用 `code-flow stats --audit --json`）。检查过期路径、重复内容、过长规范和待复审规则，结合实际文件验证结果。默认冗长阈值是 500 token；可在 `audit.long_spec_tokens` 中调整，`audit.path_roots` 可指定路径解析根。
+2. 按实际代码路径衡量单次注入，例如 `code-flow spec budget --paths src/app.py --json`。`matched_total` 是该次匹配预算，`aggregate_total` 是项目聚合量；退出码 3 表示超限。只在单次注入超过目标时考虑拆分，重复内容先人工核实。
+3. 查询影响，例如 `code-flow spec impact app-rules --json`。将 ID 换成实际规范 ID 或相对 `specs/` 的路径。`truncated` 或 `errors` 表示结果不完整，需先解决；在途任务及 Context 不能受应用操作影响。
+4. 预览一个明确目标，例如 `code-flow spec optimize --dry-run --paths app/rules.md --target app/conventions.md --json`。将路径替换成项目实际规范，目标目录必须存在且目标文件不存在。保存提案：`code-flow spec optimize --dry-run --paths app/rules.md --target app/conventions.md --json > plan.json`。未指定目标时只给建议，不生成可应用操作。查看 diff、路径映射模式、预算和影响，确认规则 ID、正文及 verifier 保持不变。
+5. 在交互终端执行 `code-flow spec optimize --apply --plan plan.json --json`，阅读实际 diff 后明确输入 `y`。提案或输入变化、在途 Context、非交互终端和不安全路径均会拒绝；重新生成并审查提案。失败会尝试恢复原始字节；进程中断时保留备份和 journal 并拒绝后续应用，需先检查事务现场并恢复，不能直接删除证据。
+6. 对受影响需求执行 `code-flow spec refresh --task-dir <需求目录> --root "$PWD" --json`，再执行 `code-flow spec doctor --task-dir <需求目录> --root "$PWD" --json`，根据结果处理漂移与阶段 Gate。doctor 对域布局默认告警，可通过 `spec_workflow.strict_domain_layout: true` 改为严格阻断。最后对实际代码路径再次运行 budget，执行相应任务验证。
+
+审计和提案是辅助判断，不会自动删除规则或自动修改配置。跨域移动前应特别核对预览中的 source/target patterns：不同匹配范围可能改变 Conventions 的注入范围。

package/package.json

@@ -1,18 +1,33 @@
 {
   "name": "@michaelxwb/code-flow",
-  "version": "0.6.4",
+  "version": "0.8.1",
+  "description": "Initialize and manage AI coding workflow specs (Claude Code / Codex / Costrict / OpenCode)",
   "license": "UNLICENSED",
   "bin": {
     "code-flow": "src/cli.js"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "files": [
     "src/cli.js",
+    "src/runtime.js",
     "src/migrate/**",
     "src/core/**",
+    "src/core/code-flow/scripts/runtime-resources.json",
     "src/adapters/**",
-    "docs/migrations/spec-workflow-0.6.0.md"
+    "docs/migrations/spec-workflow-0.6.0.md",
+    "docs/migrations/runtime-0.7.0.md",
+    "docs/migrations/runtime-0.8.0.md",
+    "docs/migrations/runtime-0.9.0.md",
+    "docs/acceptance-contract.md",
+    "docs/spec-injection-hardening.md",
+    "docs/spec-optimization.md",
+    "docs/spec-injection-performance.json",
+    "docs/USAGE.md",
+    "docs/ci/acceptance-evidence.md"
   ],
   "dependencies": {
     "@ccusage/codex": "^18.0.10"
   }
-}
+}

package/src/adapters/claude/CLAUDE.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/claude/commands/cf-init.md

@@ -153,9 +153,7 @@ CLAUDE.md 的完整内容由适配器模板统一定义，`code-flow init` 已
 
 ### 6. 生成 .claude/settings.local.json Hook 配置
 
-检查 `.claude/settings.local.json` 是否存在。如果不存在，按当前适配器模板创建，必须包含 `PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop` 四类 hook，并使用 guarded project root 定位脚本路径。
-
-如果文件已存在，只合并缺失的 hook 事件、matcher 或 command，保留用户已有 permissions、settings 和自定义 hooks，不得整文件覆盖。
+执行 `code-flow init --platform=claude`，由适配器模板统一生成/合并 `PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop` 四类 Hook，保留用户已有 permissions、settings 和自定义 hooks，不得整文件覆盖。不得手工拼装受管理 Hook；旧安装或清单校验失败时通过 `code-flow migrate --runtime --dry-run` / `--apply` 修复。
 
 ### 7. 安装 pyyaml
 

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

@@ -31,7 +31,7 @@
 
 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。
 
 
@@ -41,7 +41,7 @@
 
 执行：
 
-`python3 .code-flow/scripts/cf_spec_context.py status --task-dir <目录> --root "$PWD"`
+`code-flow spec status --task-dir <目录> --root "$PWD"`
 
 - marker 漂移时输出下一步：先 refresh 自动重同步；仍不一致时用 `active doctor --resync`（hash 取 status --json 的 context_sha256）。
 - 需要机器可读输出时加 `--json`。
@@ -50,7 +50,7 @@
 
 执行：
 
-`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 更新承接后再继续。
@@ -65,3 +65,23 @@
    - **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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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 -->