@michaelxwb/code-flow 0.5.1 → 0.6.0

package/src/adapters/codex/AGENTS.md

@@ -16,23 +16,17 @@
 - Unparameterized SQL
 - Network calls inside tight loops
 
-## Spec Loading
-本项目使用 code-flow 两层规范体系。
-
-**两层架构**：
-- **Tier 0 `_map.md`（导航地图）**：项目结构、关键文件、数据流。你手动读取，帮助理解代码在哪里。
-- **Tier 1 约束规范**：编码规则、模式、反模式。prompt 引用相关文件时自动注入完整约束；其他场景注入 **Spec Catalog**（spec 目录），由你按场景自行读取。
-
-**你的职责**：
-1. 从问题判断领域：
-   - **frontend**：components、pages、hooks、styles、UI、.tsx/.jsx/.css
-   - **backend**：services、API、database、models、logging、.py/.go
-2. 读取 `.code-flow/specs/<domain>/_map.md` 获取导航上下文
-3. 收到 **Spec Catalog** 时，编码前先 Read 其中与当前任务匹配的 spec 全文（路径相对 `.code-flow/specs/`）；prompt 引用明确文件路径时完整约束自动注入，无需手动读取
-4. 问题跨多个领域时，读取所有匹配的 `_map.md`
-5. 没有匹配领域时，跳过规范加载
-
-不要询问用户加载哪些规范——按 Catalog 自取或等待自动注入即可。
+<!-- code-flow:spec-loading schema=1 start -->
+## Spec Workflow (schema 1)
+
+- If `.code-flow/.active-task.json` exists, validate it and `spec-context.yml`, then use only the active TASK's `Spec-Refs`, Design refs, and Acceptance Contract. Never reselect Specs from Catalog.
+- Without an active TASK, explicit file paths use deterministic `path_mapping` constraints; prompts without paths receive the Spec Catalog for exploration or creation of the next Context.
+- PRD, Design, Plan, Start, Coding, and Done inherit one persisted Context. Required rules must be applied and verified before their stage gate passes.
+- A corrupt marker, Context hash drift, or required scope expansion is `SPEC_WORKFLOW_BLOCKED`; run `cf-spec refresh/doctor` instead of falling back.
+- Tier 0 `_map.md` files are navigation only. Rule constraints live in metadata-bearing Tier 1 Specs.
+
+Do NOT ask the user which Specs to load—the Context-first router is authoritative.
+<!-- code-flow:spec-loading schema=1 end -->
 
 ## 合规反馈协议（quality_loop）
 

package/src/adapters/codex/hooks.json

@@ -1,23 +1,25 @@
 {
   "hooks": {
-    "PostToolUse": [
+    "PreToolUse": [
       {
         "matcher": "Edit|Write|MultiEdit",
         "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",
+            "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
           }
         ]
       }
     ],
-    "SessionStart": [
+    "PostToolUse": [
       {
+        "matcher": "Edit|Write|MultiEdit",
         "hooks": [
           {
             "type": "command",
-            "command": "d=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}\"; f=\"$d/.code-flow/scripts/cf_session_hook.py\"; if [ -f \"$f\" ]; then cd \"$d\" && python3 \"$f\"; fi"
+            "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
           }
         ]
       }

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

@@ -44,10 +44,11 @@ description: Initialize the code-flow spec system in a project. Use when setting
 `code-flow init` 已从 `src/core/code-flow/config.yml` 复制当前核心模板。cf-init 不要复制或手写旧版 YAML；应该读取现有 `.code-flow/config.yml`，只做保守修补。
 
 必须保持或补齐这些核心能力：
-- `inject.compress: true`
-- `inject.dedup_window: 5`
+- `spec_workflow.schema_version: 1`
+- `spec_workflow.catalog.dedup_window: 5`
+- `quality_loop.compress: true`
 - 完整 `skip_extensions`，包括图片、压缩包、PDF 等非代码文件
-- `skip_paths` 中的平台目录：`.claude/**`、`.codex/**`、`.costrict/**`
+- `skip_paths` 中的平台目录：`.claude/**`、`.codex/**`、`.costrict/**`、`.opencode/**`
 - `path_mapping.shared`，包括 `shared/_map.md`、`shared/prd-template.md`、`shared/design/design-lite.md`、`shared/design/design-full.md`、`shared/design/design-frontend.md`
 - backend patterns 中同时包含 `*.py` 与 `**/*.py`
 - 按检测到的前端框架动态补 `frontend.patterns`：Vue→`**/*.vue`、Svelte→`**/*.svelte`、Next→`app/**` 等（保守追加，按检测结果，不预塞所有框架）
@@ -156,7 +157,7 @@ AGENTS.md 的完整内容由适配器模板统一定义，`code-flow init` 已
 
 ### 6. 生成 .codex/hooks.json 和 .codex/config.toml
 
-检查 `.codex/hooks.json` 是否存在。如果不存在，用 apply_patch 创建，结构必须是三层：event → [{ hooks: [{ type, command }] }]，并包含 `SessionStart` 与 `UserPromptSubmit`。
+检查 `.codex/hooks.json` 是否存在。如果不存在，用 apply_patch 创建，结构必须是三层：event → [{ hooks: [{ type, command }] }]，并包含 `PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop`。`PreToolUse` 必须沿用适配器 `hooks.json` 中的写文件 matcher，并调用 `cf_pre_tool_hook.py`；不要在技能正文重复其他平台的工具名。
 
 如果 `.codex/hooks.json` 已存在，只合并缺失事件或 command，保留用户自定义 hooks，不得整文件覆盖。
 

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

@@ -0,0 +1,55 @@
+---
+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 [需求目录]`
+- `cf-spec doctor [需求目录]`
+
+## 通用硬门禁
+
+1. 先读取 `.code-flow/config.yml`；`spec_workflow.schema_version` 不是 `1` 时，只有 `migrate --plan` 可继续。
+2. 不存在有效 Context 时，不得伪造 binding、Rule 状态、Evidence 或用户确认。
+3. stdout JSON 由 `cf_*.py` 产生；本命令不得手写成功结果。
+
+## migrate --plan
+
+只处理 `code-flow migrate --spec-workflow --prepare` 已产生的 prepared plan：
+
+1. 校验 plan 位于当前项目 `.code-flow/migrations/<id>/`，状态为 `prepared_blocked` 或 `prepared`，source hashes 未漂移。
+2. 逐条展示 `unresolved` 的来源、候选和影响；读取关联 Spec 与活跃需求文档后给出建议。
+3. 每项必须由用户明确选择。写入 `confirmed_by`、`confirmed_at`、`source`、`reason`；Agent 不能代确认，不能批量 N/A。
+4. 只修改 prepared plan，不修改项目目标、backup、staging、journal 或 `.version`。
+5. unresolved 清零后提示执行：
+   `code-flow migrate --spec-workflow --apply --plan <migration-plan.yml>`
+
+## context
+
+定位显式需求目录；省略时只可使用有效 `.active-task.json` 的 `task_dir`。
+
+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`
+3. Context 缺失、schema/hash 无效时 fail-closed，不回退 Catalog。
+
+## refresh
+
+执行：
+
+`python3 .code-flow/scripts/cf_spec_context.py refresh --task-dir <目录> --root "$PWD" --json`
+
+- changed required Rule 标为 stale，关联 stage Gate 必须阻断。
+- missing/conflict 不自动降级；回 Align 或 Plan 更新承接后再继续。
+- refresh 不替用户做 N/A/waiver 决策。
+
+## doctor
+
+1. 校验 config schema、active marker、lock、Context hash、task/status、migration journal 和 legacy residue。
+2. active marker 存在时执行 `cf_spec_context.py active doctor`，传入可证明的 Context hash；无法证明时保持 `recovery_required`。
+3. 输出明确修复命令。不得删除损坏 marker、越过 required Gate 或静默切换到无任务模式。

package/src/adapters/codex/skills/cf-task-align/SKILL.md

@@ -111,6 +111,18 @@ PRD 已覆盖的维度如无需调整，将直接使用。
 - Step 3 中已从 PRD 获得充分信息的维度**不重复提问**，除非用户主动修改
 - design 中 FEAT 的"来源"列必须引用 PRD 中对应的 US-XX
 
+### 2.7. 继承并刷新 Spec Context（硬门禁）
+
+进入技术讨论前先定位需求目录中的 `spec-context.yml`：
+
+1. PRD 派生/恢复模式必须执行 `python3 .code-flow/scripts/cf_spec_context.py 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 和验证方式时不得进入可评审状态；只写“遵循规范”无效。
+5. N/A/waiver 必须逐 Rule 请求用户确认并调用 `decision`；`batch` 必须为 false，Agent 不得代确认。无有效确认来源时 fail-closed。
+
+> 无 PRD 的新建模式也必须先 catalog/bind 并创建 Context，再写 Design；不能因为缺 PRD 跳过 Specs。
+
 ### 3. 交互式细化
 
 围绕选中的维度逐步推进，**每轮提 2-3 个问题**（不要一次性抛 10 个问题）：
@@ -161,6 +173,8 @@ CLI 场景：
 **验收标准**（必选）
 - 怎么判断做完了？正常 / 异常场景各列至少一条
 - 可验证、可转为自动化测试断言的条件（明确输入与可观测输出）；场景 ID（S-/E-/B-）即测试用例来源
+- 为每个场景指定测试层级（unit / integration / E2E / manual）和关键真实边界；跨 API、存储、运行时生成、渲染或用户可见结果等多个边界时必须选 E2E
+- RULE 与高影响 RISK 必须映射到至少一个 S/E/B 场景；manual 仅限无法自动化的外部条件，必须写明原因
 
 **妥协与技术债**（按需）
 - 本次有意接受的取舍或欠债？后续偿还设想？
@@ -189,7 +203,8 @@ CLI 场景：
 3. **只包含适用的章节**，模板中有但需求不涉及的章节跳过
 4. 用 `{}` 占位符替换为实际内容
 5. PRD 派生模式：功能清单的"来源"列填 PRD 中对应的 US-XX
-6. 展示生成的设计简报
+6. 生成 `Spec Compliance Matrix`，每条 required Rule 的验证场景必须引用 S-/E-/B- 或说明仅可人工验证的外部边界
+7. 展示生成的设计简报
 
 **章节映射**（Lite 模板，对应 `design-lite.md` 实际章节）：
 
@@ -241,8 +256,10 @@ CLI 场景：
 **追溯硬约束（plan 拆解与质量门的基础）**：
 - 功能清单每个 FEAT 保留"来源"列（PRD 派生填 US-XX；无 PRD 填需求描述）
 - 接口（API/CLI/函数）与验收场景标注其实现 / 覆盖的 FEAT-XX
+- 每个验收场景写明测试层级、关键真实边界和最终可观测结果；编码阶段不得把 E2E 自行降级为 mock 后的 unit/integration 测试
+- 每个 RULE 与高影响 RISK 映射到 S/E/B 场景；只能手动验证时记录原因
 - Full 模板 §6 需求追溯矩阵必须闭合：US → FEAT → API → TC 不留断点，TC 引用 §2.5.2 场景 ID
-- 任一缺口（FEAT 无来源 / FEAT 无验收 / 矩阵断点）在展示时显式列出并提示补全
+- 任一缺口（FEAT 无来源 / FEAT 无验收 / 场景无测试层级或真实边界 / RULE·RISK 无验证场景 / 矩阵断点）在展示时显式列出并提示补全
 
 展示后询问用户：**确认写入？可以调整任何部分。**
 
@@ -264,6 +281,14 @@ CLI 场景：
    - **全栈需求**：前后端各写一份到同一需求目录
 4. 用 apply_patch 写入最终路径
 
+写入后，对 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
+```
+
+只有 Design Gate `decision=pass` 才能输出 Plan 下一步。缺 Matrix 行、artifact ref、验证方式、用户确认或发生 drift 时保留草稿并修复，不得推迟到 Coding/Done 才发现。
+
 ### 6. 输出摘要
 
 ```
@@ -274,7 +299,8 @@ CLI 场景：
 内容:
   - <按实际包含的章节列出>
   - 验收标准: N 项
-  - 追溯自检: 每个 FEAT 有来源(US/需求)✓、有验收场景✓；Full 模板 §6 矩阵 US→FEAT→API→TC 闭合，缺口显式列出
+  - 追溯自检: 每个 FEAT 有来源(US/需求)✓、有验收场景✓；每个场景有测试层级和关键真实边界✓；RULE/高影响 RISK 有验证场景✓；Full 模板 §6 矩阵闭合
+  - Spec Compliance: required Rules N/N 已落点；Design Gate: pass
   - 性能自检: 标记性能敏感则方案须体现最优性能设计依据（§3.1/§3.5 或 lite §3.4），否则提示补全或显式声明"无性能敏感点"
 
 下一步:

package/src/adapters/codex/skills/cf-task-archive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cf-task-archive
-description: Archive a completed task file after three-dimensional validation (completeness, correctness, consistency). Use when all subtasks are done and you want to archive the task file and check for spec updates.
+description: Archive a completed task file after completeness, correctness, traceability, and consistency validation. Use when all subtasks are done and you want to archive the task file and check for spec updates.
 ---
 
 ## 输入
@@ -33,7 +33,14 @@ description: Archive a completed task file after three-dimensional validation (c
 
 ### 2. 归档前校验（Verify）
 
-所有子任务 done 后，执行三维校验：
+**Spec Context / Code 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` 仍指向本需求，必须先完成对应 TASK 的 Done Gate，并以 `{"gate_passed": true}` 调用 `active complete`；不得通过归档绕过 active 状态
+- Context 与 Evidence 随需求目录一并归档，`_session` 仅是可重建投影，不是事实源
+
+所有子任务 done 后，执行四维校验：
 
 **完整性**：
 - 所有 Checklist 项已勾选
@@ -43,6 +50,13 @@ description: Archive a completed task file after three-dimensional validation (c
 - 如果 `.code-flow/validation.yml` 存在，读取验证规则，用 shell 命令执行其中匹配的 `command`（如 `npx tsc --noEmit`、`python3 -m pytest` 等）
 - 检查本次变更涉及的文件是否通过 lint/type check
 
+**验收追溯**：
+- 来源 design 含结构化 S-/E-/B- 场景时，逐项对照 `## Acceptance Coverage`，P0/P1 场景以及 RULE/高影响 RISK 映射场景必须全部存在且状态为 `verified`
+- 每个负责任务的 `Acceptance-Refs`、`Acceptance Contract`、`Acceptance Evidence` 必须闭合，不得残留 `planned` / `pending` / `TBD`
+- 测试层级不得低于 design；E2E 的真实边界和关键断言必须有文件/用例位置与 fixture/构造证据
+- 汇总并重新执行契约中所有唯一验收命令；测试未收集、未执行或失败均为 FAIL
+- `manual` 场景必须有用户确认和可复核记录。旧 design 没有结构化场景时注明“不适用”，不得伪造覆盖
+
 **一致性**：
 - 读取 task 文件的 `## Proposal`，对照实际代码变更，检查意图是否已实现
 
@@ -52,6 +66,7 @@ description: Archive a completed task file after three-dimensional validation (c
 归档前校验:
   [PASS] 完整性: 所有 Checklist 已完成，无未解决 Notes
   [PASS] 正确性: cf-validate 通过
+  [PASS] 验收追溯: 6/6 场景 verified，2 条 E2E 命令通过
   [WARN] 一致性: Proposal 提到"支持 OAuth 登录"，但未发现相关实现
 
 WARN 不阻塞归档，但建议确认后再继续。继续归档？
@@ -79,7 +94,19 @@ mv .code-flow/tasks/<日期>/<需求>/ .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/<日期目录>/`
-5. 如果原日期目录为空，删除空目录
+
+**归档后统一收尾（布局 A/B 都必须执行）**：
+
+1. 保存源日期目录为 `.code-flow/tasks/<日期>/`，完成移动后检查该目录是否还有其他需求或任务。
+2. 如果目录为空，必须执行安全删除；非空则保留并在摘要中列出剩余条目：
+   ```bash
+   source_date_dir=".code-flow/tasks/<日期>"
+   if [ -d "$source_date_dir" ] && [ -z "$(find "$source_date_dir" -mindepth 1 -maxdepth 1 -print -quit)" ]; then
+     rmdir "$source_date_dir"
+   fi
+   ```
+3. 复查归档目标存在、原任务/需求路径不存在；如果源日期目录仍存在但为空，视为归档未完成，立即删除后再继续。
+4. 源日期目录包含其他条目时不得删除，摘要明确写“保留（仍有 N 个条目）”。
 
 **临时约束清理（FEAT-08）**：删除 `.code-flow/specs/_session/task-<name>.md`（存在时）。该文件由 cf-task-start 生成，归档后不得残留。
 
@@ -128,5 +155,6 @@ Spec 同步建议:
   - 创建日期: 2026-03-15
   - 归档日期: 2026-03-20
   - 历时: 5 天
-  - 校验: 3/3 PASS
+  - 校验: 4/4 PASS
+  - 源日期目录: 已删除（为空）/ 已保留（仍有 N 个条目）
 ```

package/src/adapters/codex/skills/cf-task-plan/SKILL.md

@@ -154,6 +154,22 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 设计简报模式：记录**章节名**，无需行号。
 引用格式：`<name>.design.md#3.3 数据设计`, `<name>.design.md#3.4 接口设计` 等（章节名须与模板真实标题一致）。
 
+**验收契约拆解（硬约束）**：
+
+1. 从全部 design 提取 P0/P1 的 S-/E-/B- 场景，以及 RULE 和高影响 RISK 到场景的映射。
+2. 优先沿用 design 指定的测试层级与关键真实边界。旧 design 未填写时，跨 API、存储、运行时生成、渲染或最终用户可见结果的场景推断为 `E2E`，局部模块协作推断为 `integration`，纯函数约束才可用 `unit`。
+3. 每个场景必须分配给一个负责的 TASK，并写入 `Acceptance-Refs`；同一场景可被多个任务引用，但必须有且仅有一个最终验收负责人。
+4. `manual` 只允许用于无法自动化的外部条件，必须记录原因并经用户明确确认。agent 不得把 design 的 E2E 自行降级为 unit/integration。
+5. Checklist 禁止使用泛化的“编写测试”。必须写成 `[场景ID][测试层级] + 真实边界 + 关键断言`，并为新功能/缺陷修复安排先写测试和 RED 记录。
+6. 如果场景缺测试层级、真实边界或 RULE/高影响 RISK 没有验证场景，先以 `#NOTES` 列为设计缺口；未解决前不得开始编码。
+
+**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 仍仅限经用户确认的外部边界。
+4. 缺 `verifier_ref`、责任 TASK 为 0/多个、Checklist/Contract 不含 Rule-specific 验证责任时，任务文件只能保留为缺口草稿，不能启动。
+
 ### 4. 生成任务文件方案
 
 将拆解结果按以下格式组织，展示给用户确认：
@@ -184,12 +200,25 @@ 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 |
+
+> 本表必须覆盖 design 中全部 P0/P1 场景，以及 RULE/高影响 RISK 映射的场景；存在缺口时不生成可启动任务。
+
+---
+
 ## TASK-001: <子任务标题>
 
 - **Status**: draft
 - **Priority**: P0
 - **Depends**:
 - **Source**: docs/xxx.md#§3.1 数据模型(L83-L110)
+- **Spec-Refs**: product-rules#RULE-product-001
+- **Acceptance-Refs**: S-01, E-01, RULE-01
 
 ### Description
 <从设计文档提取的需求重点，不必复制全文>
@@ -197,7 +226,21 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 ### Checklist
 - [ ] <具体实现步骤1>
 - [ ] <具体实现步骤2>
-- [ ] <编写测试>
+- [ ] [S-01][E2E] 修改生产代码前，按 API → Store → Renderer 真实边界编写验收测试并记录 RED
+- [ ] [S-01] 断言 <最终可观测结果 1> 与 <最终可观测结果 2>
+- [ ] [E-01][integration] 覆盖 <异常输入> 与 <可观测失败行为>
+- [ ] 运行验收命令并填写 Acceptance Evidence
+
+### Acceptance Contract
+
+| 场景ID | 测试层级 | 不得 Mock 的真实边界 | 关键断言 | 测试文件 / 用例 | 执行命令 | 状态 |
+|--------|---------|--------------------|---------|----------------|---------|------|
+| S-01 | E2E | API、Store、Renderer | <断言列表> | planned | planned | planned |
+| E-01 | integration | Service、Store | <断言列表> | planned | planned | planned |
+
+### Acceptance Evidence
+
+> `cf-task-start` 在编码期填写 RED/GREEN 结果、每个关键断言的位置和真实组件证据；全部状态 verified 后任务才可 done。
 
 ### Log
 - [<当前日期>] created (draft)
@@ -222,6 +265,7 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 
 TASK-001: <标题> [P0]
   来源: §3.1 数据模型 (L83-L110)
+  验收: S-01(E2E), E-01(integration)
   描述: ...
   Checklist: N 项
   依赖: 无
@@ -249,6 +293,14 @@ TASK-002: <标题> [P1]
 3. 如果输入为 docs/ 设计文档（无需求目录）→ 按当前日期创建需求目录 `.code-flow/tasks/<YYYY-MM-DD>/<需求>/` 并写入其中
 4. 用 apply_patch 写入
 
+写入后用 `bind --stage plan` 的 `applications` 将每条 required Rule 指向任务文件内唯一 TASK item，并执行：
+
+```bash
+python3 .code-flow/scripts/cf_spec_gate.py --task-dir <需求目录> --stage plan --artifact <任务文件> --json
+```
+
+只有 Context Plan 状态与任务结构校验都 `decision=pass` 才输出 Start 下一步；缺唯一 owner、`verifier_ref`、测试层级或真实边界时必须回到拆解修复。
+
 ### 6. 输出摘要
 
 ```
@@ -257,6 +309,7 @@ TASK-002: <标题> [P1]
 - 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 个
 
 建议执行顺序:
   1. TASK-001 (无依赖)

package/src/adapters/codex/skills/cf-task-prd/SKILL.md

@@ -35,6 +35,22 @@ description: Generate a Product Requirements Document (PRD) from a one-liner req
 
 目的：**让 PRD 基于实际业务背景**，而非泛泛的通用描述。本步只读不提问，所有提问统一放到 Step 3。
 
+### 2.1 先解析并绑定 Existing Specs（硬门禁）
+
+在开始写需求内容前，先确定 Step 5 的需求目录和预计涉及路径，再执行：
+
+```bash
+python3 .code-flow/scripts/cf_spec_context.py catalog --stage prd --root "$PWD" --paths <预计路径...> --json
+```
+
+1. 必须检查完整 `candidates`，不得按展示条数截断；只消费 resolver 返回的 `stages` 含 `prd` 的产品、安全、兼容、业务约束，`code-only` Spec 不得进入 PRD。
+2. 对每个适用候选记录 `selected_by` 和具体 `reason`，立即用 `bind --stage prd` 写入需求目录的 `spec-context.yml`（首次 `applications` 为空），然后再进入需求细化。
+3. required Rule 必须进入 PRD 的 `Existing Spec Constraints`，并明确影响哪个范围项、FEAT 验收或 NFR；只复制一句“遵循规范”不算承接。
+4. 不适用的 required Rule 必须逐 Rule 说明具体理由并请求用户确认，再调用 `decision` 保存 `not_applicable`；禁止批量 N/A，**Agent 不得代确认**。
+5. Catalog/Context 失败、同级 required 冲突或 required Rule 尚未决定时 fail-closed：保留草稿并修复，不得绕过后继续产出可批准 PRD。
+
+> 预计路径尚不明确时仍须以空 `--paths` 运行，确保 global/task-stage 规则先进入 Context；后续范围明确时重新 catalog，并补充绑定新增候选。
+
 ### 3. 交互式细化
 
 围绕 PRD 各要素逐步推进，**每轮提 2-3 个问题**：
@@ -95,6 +111,7 @@ description: Generate a Product Requirements Document (PRD) from a one-liner req
 | 5. 非功能需求 | Step 3 的"非功能需求"（按需，分配 NFR 编号） |
 | 6. 范围与边界 | Step 3 的"范围与边界" |
 | 7. 依赖与风险 | Step 3 的"依赖与风险"（按需） |
+| 8. Existing Spec Constraints | Step 2.1 的 prd-stage Rule；逐条关联范围/FEAT 验收/NFR |
 
 **编号与追溯（硬约束，`cf-task-align` 派生的基础）**：
 - 用户故事按出现顺序分配 `US-01`、`US-02`…，写入 §3.2 用户故事表
@@ -117,6 +134,12 @@ description: Generate a Product Requirements Document (PRD) from a one-liner req
 3. **重名检查**：需求目录已存在且非本次草稿时，目录名追加序号 `<name>-2`、`<name>-3`… 避免覆盖；恢复模式复用原目录、不改名
 4. 用 apply_patch 写入 `.code-flow/tasks/<YYYY-MM-DD>/<name>/<name>.prd.md`
 
+写入后必须完成 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`。
+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` 按整个需求目录归档。
 
 ### 6. 输出摘要
@@ -129,6 +152,7 @@ description: Generate a Product Requirements Document (PRD) from a one-liner req
   - 用户故事: N 个
   - 功能: N 个（P0: X, P1: Y）
   - 追溯自检: FEAT↔US 全部关联 ✓ ｜ 有缺口则列出「未关联 FEAT-XX / 未覆盖 US-XX」
+  - Existing Specs: N 个 / required Rules: N 条 / PRD Gate: pass
 
 > 自检发现缺口（FEAT 无来源 US 或 US 无 FEAT 覆盖）时，在摘要显式标注并提示用户补 US 或降级，不要静默放过。
 

package/src/adapters/codex/skills/cf-task-start/SKILL.md

@@ -24,7 +24,7 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
 
 **状态检查**：Status 必须为 `draft`。若为其他状态：
 - `in-progress` → 提示"任务已在进行中，继续编码"（不阻塞，直接跳到步骤 2）
-- `done` → 提示"任务已完成"，结束
+- `done` → 先执行验收契约检查；全部 verified 才提示"任务已完成"并结束，否则恢复为 `in-progress`，列出缺口并继续补齐测试与证据
 - `blocked` → 提示"任务被阻塞"，列出 Notes 中的阻塞原因，结束
 
 **#NOTES 检查**：扫描该子任务段落全文（Description、Checklist 等）
@@ -36,6 +36,12 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
 - 所有依赖必须为 `done`
 - 未满足 → 输出：`前置检查失败：以下依赖未完成\n- TASK-001: in-progress\n- TASK-003: draft`
 
+**验收契约检查**：
+- 如果 task 含 `## Acceptance Coverage`，当前子任务必须有 `Acceptance-Refs`、`Acceptance Contract` 和 `Acceptance Evidence`
+- `Acceptance-Refs` 中每个 S-/E-/B- 都必须出现在全局覆盖表和当前契约中，测试层级与关键真实边界必须和 design 一致
+- 旧 task 没有覆盖表但来源 design 含结构化验收场景时，先从 design 回填覆盖表与契约；回填完成前不得修改生产代码
+- 非行为类任务可显式写 `Acceptance-Refs: N/A`；不得用 N/A 跳过已有设计场景
+
 ### 2. 加载详设上下文
 
 前置检查通过后，**编码前先加载关联的详设文档章节**：
@@ -45,39 +51,75 @@ description: Activate a subtask and begin coding. Runs pre-checks (status, #NOTE
    - 提取：文件路径 + 行号范围
 2. 按行号范围读取详设文档的对应章节（使用 offset/limit 参数）
 3. 将读取的章节内容作为编码上下文，与 Checklist 一起指导实现
+4. 按 `Acceptance-Refs` 精确读取验收场景及其关联 RULE/RISK；不得只依赖摘要，也不得遗漏场景的测试层级、关键真实边界和预期结果
 
 示例：Source 为 `docs/auth.md#§3.2 API 接口(L111-L155), docs/auth.md#§3.5 错误码(L201-L220)`
 → 读取 `docs/auth.md` offset=111 limit=45
 → 读取 `docs/auth.md` offset=201 limit=20
 
-### 3. 激活并编码
+### 3. 激活并准备验收测试
 
-1. 用 apply_patch 更新子任务 Status 为 `in-progress`
-2. 在 `### Log` 追加：`- [<当前日期>] started (in-progress)`
-3. 更新文件头 `Updated` 日期
-4. 结合详设上下文 + Checklist，逐项执行编码工作
-5. 每完成一个 checklist 项 → 用 apply_patch 将 `- [ ]` 改为 `- [x]`
+在改状态或生产代码前，顺序固定且不得跳步：
+
+1. 调用 `cf_spec_context.py refresh --task-dir ...`，执行 Start Gate；stale/pending/conflict 或依赖未闭合均不得继续。
+2. 重新读取 refresh 后的 Context hash，再调用 `cf_spec_context.py active start`，传 task/context hash 和逐路径确认的 pre-existing ownership；已有/损坏 marker、未归属 diff 或 hash 不一致立即阻断。禁止先 start 再 refresh，避免 active marker 在编码前自行漂移。
+3. 调用 `cf_spec_session.py`，只根据当前 TASK 的 `Spec-Refs`、Source 与 Acceptance Contract 覆盖写入 `_session/task-<name>.md`。禁止重新 catalog 或猜测规则。
+4. 只有前三步全部成功，才用 apply_patch 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
+5. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
+6. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
+7. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
+
+RED 证据写入 `Acceptance Evidence`：
+
+```markdown
+| 场景ID | RED | GREEN | 断言位置 | 真实边界证据 | 状态 |
+|--------|-----|-------|---------|-------------|------|
+| S-01 | FAIL: generation 未递增 | pending | pending | real Store + Renderer fixture | test-written |
+```
 
-### 3.5 会话级临时约束（FEAT-08）
+### 3.1 实现与逐项更新
+
+1. RED 证据就绪后，结合详设上下文、Acceptance Contract 与 Checklist 修改生产代码
+2. 每完成一个 checklist 项，用 apply_patch 将 `- [ ]` 改为 `- [x]`
+3. 如果实现中发现必须改变测试层级或真实边界，停止编码并记录 `#NOTES`，经用户确认并同步 design 后才能继续；agent 不得自行降级
+
+### 3.2 GREEN 与验收证据
+
+1. 执行每个契约中的验收命令，再执行受影响范围的回归测试
+2. 对每个预期结果记录对应的测试断言位置，并指出 fixture/构造路径如何证明关键边界使用真实组件
+3. 将 `Acceptance Contract` 行状态改为 `verified`，将 `Acceptance Evidence` 补齐 GREEN、断言位置和边界证据
+4. 负责该场景的任务验证完成后，将全局 `Acceptance Coverage` 对应行改为 `verified`
+5. 测试文件存在但未被测试框架收集、命令未实际执行、只有场景 ID 没有关键断言，都视为未验证
+
+### 3.5 TASK-bound Spec Session
 
 激活后，若任务文件头 Source 指向的 design 文档含验收条件章节（如 §2.5 验收条件 / 验收标准）：
 
-1. 提取该章节的场景与 RULE 约束，生成 `.code-flow/specs/_session/task-<name>.md`：
+1. 只提取当前任务 `Spec-Refs` 与 `Acceptance-Refs` 对应的 Rule hash、verifier、artifact refs、场景、测试层级和真实边界，生成 `.code-flow/specs/_session/task-<name>.md`：
    - frontmatter：`description: 当前任务 <name> 的验收约束（cf-task:start 生成，archive 清理）`
-   - 正文：验收场景与约束的精简列表（≤300 token）
-2. Spec Catalog 目录扫描自动纳入该文件，无需配置；编辑代码时的自动注入同样生效
-3. design 无验收章节时静默跳过；同名文件已存在则覆盖（同任务重复 start）
+   - 正文：验收场景与约束的精简列表（≤300 token）；必须保留全部引用 ID、层级、边界和预期结果，不能为压缩而删除场景
+2. 任务模式直接读取这个投影，禁止经 Spec Catalog 二次选择；同名文件已存在则原子覆盖。
+3. 50 Rule 等超预算任务按 required/当前阶段优先输出受控摘要，完整 Context 保留不丢失，并明确提示拆 TASK；不得用截断隐藏 required 缺口。
 
 > `_session/` 不入库（.gitignore 模板已覆盖）、不参与规范审计与预算。
 
 ### 4. 自动完成
 
-当所有 checklist 项都勾选为 `[x]` 后：
+只有同时满足以下条件才能自动完成：
+- 所有 checklist 项均为 `[x]`
+- 每个 Acceptance-Ref 在契约、证据和全局覆盖表中均为 `verified`，不存在 `planned` / `pending` / `TBD`
+- 测试层级未低于 design，关键真实边界没有被 mock 绕过
+- 每个预期结果都有具体断言位置，验收命令和回归测试均已实际通过
+- `manual` 场景已有用户确认和可复核记录
+
+满足后：
 1. 用 apply_patch 更新 Status 为 `done`
 2. 在 `### Log` 追加：`- [<当前日期>] completed (done)`
 3. 更新文件头 `Updated` 日期
 4. 输出：`TASK-xxx 已完成`
 
+任一验收条件不满足时保持 `in-progress`，明确列出缺口，不能标记为 `done`。
+
 ### 5. 文档同步检查
 
 子任务完成后，轻量检查本次编码是否引入了需要同步到 specs 或导航地图的内容：
@@ -145,7 +187,7 @@ Spec 同步提示:
 
 ### 4. 按序执行
 
-对每个可激活的子任务，执行单任务模式的步骤 3-4（详设已在步骤 2 加载，无需重复读取）。
+对每个可激活的子任务，执行单任务模式的步骤 3-4，包括先写验收测试、RED、实现、GREEN 和证据核对（详设已在步骤 2 加载，无需重复读取）。
 
 完成一个子任务后，检查是否解锁了新的子任务（依赖已满足），如果是则继续执行。
 

package/src/adapters/costrict/CLAUDE.md

@@ -16,23 +16,17 @@
 - Unparameterized SQL
 - Network calls inside tight loops
 
-## Spec Loading
-本项目使用 code-flow 两层规范体系。
-
-**两层架构**：
-- **Tier 0 `_map.md`（导航地图）**：项目结构、关键文件、数据流。你手动读取，帮助理解代码在哪里。
-- **Tier 1 约束规范**：编码规则、模式、反模式。编辑代码时（PreToolUse）自动注入完整约束；其他场景注入 **Spec Catalog**（spec 目录），由你按场景自行读取。
-
-**你的职责**：
-1. 从问题判断领域：
-   - **frontend**：components、pages、hooks、styles、UI、.tsx/.jsx/.css
-   - **backend**：services、API、database、models、logging、.py/.go
-2. 读取 `.code-flow/specs/<domain>/_map.md` 获取导航上下文
-3. 收到 **Spec Catalog** 时，编码前先 Read 其中与当前任务匹配的 spec 全文（路径相对 `.code-flow/specs/`）；prompt 引用明确文件路径或你编辑代码（PreToolUse）时，完整约束自动注入，无需手动读取
-4. 问题跨多个领域时，读取所有匹配的 `_map.md`
-5. 没有匹配领域时，跳过规范加载
-
-不要询问用户加载哪些规范——按 Catalog 自取或等待自动注入即可。
+<!-- code-flow:spec-loading schema=1 start -->
+## Spec Workflow (schema 1)
+
+- If `.code-flow/.active-task.json` exists, validate it and `spec-context.yml`, then use only the active TASK's `Spec-Refs`, Design refs, and Acceptance Contract. Never reselect Specs from Catalog.
+- Without an active TASK, explicit file paths use deterministic `path_mapping` constraints; prompts without paths receive the Spec Catalog for exploration or creation of the next Context.
+- PRD, Design, Plan, Start, Coding, and Done inherit one persisted Context. Required rules must be applied and verified before their stage gate passes.
+- A corrupt marker, Context hash drift, or required scope expansion is `SPEC_WORKFLOW_BLOCKED`; run `cf-spec refresh/doctor` instead of falling back.
+- Tier 0 `_map.md` files are navigation only. Rule constraints live in metadata-bearing Tier 1 Specs.
+
+Do NOT ask the user which Specs to load—the Context-first router is authoritative.
+<!-- code-flow:spec-loading schema=1 end -->
 
 ## 合规反馈协议（quality_loop）
 

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

@@ -39,10 +39,11 @@
 `code-flow init` 已从 `src/core/code-flow/config.yml` 复制当前核心模板。cf-init 不要复制或手写旧版 YAML；应该读取现有 `.code-flow/config.yml`，只做保守修补。
 
 必须保持或补齐这些核心能力：
-- `inject.compress: true`
-- `inject.dedup_window: 5`
+- `spec_workflow.schema_version: 1`
+- `spec_workflow.catalog.dedup_window: 5`
+- `quality_loop.compress: true`
 - 完整 `skip_extensions`，包括图片、压缩包、PDF 等非代码文件
-- `skip_paths` 中的平台目录：`.claude/**`、`.codex/**`、`.costrict/**`
+- `skip_paths` 中的平台目录：`.claude/**`、`.codex/**`、`.costrict/**`、`.opencode/**`
 - `path_mapping.shared`，包括 `shared/_map.md`、`shared/prd-template.md`、`shared/design/design-lite.md`、`shared/design/design-full.md`、`shared/design/design-frontend.md`
 - backend patterns 中同时包含 `*.py` 与 `**/*.py`
 - 按检测到的前端框架动态补 `frontend.patterns`：Vue→`**/*.vue`、Svelte→`**/*.svelte`、Next→`app/**` 等（保守追加，按检测结果，不预塞所有框架）
@@ -151,7 +152,7 @@ CLAUDE.md 的完整内容由适配器模板统一定义，`code-flow init` 已
 
 ### 6. 生成 .costrict/settings.local.json Hook 配置
 
-检查 `.costrict/settings.local.json` 是否存在。如果不存在，按当前适配器模板创建，必须包含 `PreToolUse`、`SessionStart`、`UserPromptSubmit` 三类 hook，并使用 git root 定位脚本路径。
+检查 `.costrict/settings.local.json` 是否存在。如果不存在，按当前适配器模板创建，必须包含 `PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop` 四类 hook，并使用 guarded project root 定位脚本路径。
 
 如果文件已存在，只合并缺失的 hook 事件、matcher 或 command，保留用户已有 permissions、settings 和自定义 hooks，不得整文件覆盖。