@michaelxwb/code-flow 0.5.2 → 0.6.0

package/docs/migrations/spec-workflow-0.6.0.md

@@ -0,0 +1,42 @@
+# Spec Workflow 0.6.0 Migration
+
+0.6.0 replaces prompt-keyword/full injection with one Context-first runtime. It is a breaking, transactional migration; `code-flow init` will not overwrite a 0.4.2–0.5.x project before migration.
+
+## Upgrade
+
+```bash
+code-flow migrate --spec-workflow --dry-run
+code-flow migrate --spec-workflow --prepare
+cf-spec migrate --plan .code-flow/migrations/<id>/migration-plan.json  # only when unresolved exists
+code-flow migrate --spec-workflow --apply --plan .code-flow/migrations/<id>/migration-plan.json
+code-flow init --platform=<claude|codex|costrict|opencode>
+```
+
+`--dry-run` performs no project writes. `--prepare` creates `.code-flow/migrations/<id>/backup/`, empty staging, a source-hash-bound plan, and `journal.json`. Apply refuses unresolved decisions or source hash drift. `.code-flow/.version` is written as `0.6.0` only after every target hash is committed.
+
+## Backup and rollback
+
+The backup stores the exact bytes present at prepare time, including dirty working-tree and user-managed files. Keep it until the migrated project has passed its normal tests.
+
+```bash
+code-flow migrate --spec-workflow --rollback <id>
+```
+
+Rename/EXDEV failures automatically roll back. If interruption leaves `committing`, rerunning apply finishes only when every target hash is proven; otherwise it restores the backup. `recovery_required` must be resolved before Hooks or task commands continue.
+
+## Unsupported older projects
+
+Projects older than 0.4.2 must first bridge through the previous release:
+
+```bash
+npx @michaelxwb/code-flow@0.5.2 init --platform=<platform>
+```
+
+Then run the 0.6.0 migration. Do not delete `.inject-state`, old commands, or task files manually before prepare—the transaction needs the original bytes for recovery and residue validation.
+
+## Runtime changes
+
+- Active tasks inject only their persisted `spec-context.yml` TASK projection.
+- Without an active task, explicit paths use `path_mapping`; only pathless exploration receives Catalog.
+- `cf-inject`, full/tag fallback, `.inject-state`, and SessionStart reset are removed.
+- `cf-spec context/refresh/doctor` is available on Claude, Codex, Costrict, and OpenCode.

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@michaelxwb/code-flow",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "license": "UNLICENSED",
   "bin": {
     "code-flow": "src/cli.js"
   },
   "files": [
     "src/cli.js",
+    "src/migrate/**",
     "src/core/**",
-    "src/adapters/**"
+    "src/adapters/**",
+    "docs/migrations/spec-workflow-0.6.0.md"
   ],
   "dependencies": {
     "@ccusage/codex": "^18.0.10"

package/src/adapters/claude/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/claude/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. 生成 .claude/settings.local.json Hook 配置
 
-检查 `.claude/settings.local.json` 是否存在。如果不存在，按当前适配器模板创建，必须包含 `PreToolUse`、`SessionStart`、`UserPromptSubmit` 三类 hook，并使用 git root 定位脚本路径。
+检查 `.claude/settings.local.json` 是否存在。如果不存在，按当前适配器模板创建，必须包含 `PreToolUse`、`PostToolUse`、`UserPromptSubmit`、`Stop` 四类 hook，并使用 guarded project root 定位脚本路径。
 
 如果文件已存在，只合并缺失的 hook 事件、matcher 或 command，保留用户已有 permissions、settings 和自定义 hooks，不得整文件覆盖。
 

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

@@ -0,0 +1,50 @@
+# 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/claude/commands/cf-task/align.md

@@ -110,6 +110,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 个问题）：
@@ -190,7 +202,8 @@ CLI 场景：
 3. **只包含适用的章节**，模板中有但需求不涉及的章节跳过
 4. 用 `{}` 占位符替换为实际内容
 5. PRD 派生模式：功能清单的"来源"列填 PRD 中对应的 US-XX
-6. 展示生成的设计简报
+6. 生成 `Spec Compliance Matrix`，每条 required Rule 的验证场景必须引用 S-/E-/B- 或说明仅可人工验证的外部边界
+7. 展示生成的设计简报
 
 **章节映射**（Lite 模板，对应 `design-lite.md` 实际章节）：
 
@@ -267,6 +280,14 @@ CLI 场景：
    - **全栈需求**：前后端各写一份到同一需求目录
 4. 用 Write 写入最终路径
 
+写入后，对 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. 输出摘要
 
 ```
@@ -278,6 +299,7 @@ CLI 场景：
   - <按实际包含的章节列出>
   - 验收标准: N 项
   - 追溯自检: 每个 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/claude/commands/cf-task/archive.md

@@ -32,6 +32,13 @@
 
 ### 2. 归档前校验（Verify）
 
+**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 后，执行四维校验：
 
 **完整性**：

package/src/adapters/claude/commands/cf-task/plan.md

@@ -162,6 +162,13 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 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. 生成任务文件方案
 
 将拆解结果按以下格式组织，展示给用户确认：
@@ -209,6 +216,7 @@ AI 从设计文档中识别关键缺口，输出结构化分析并与用户交
 - **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
@@ -284,6 +292,14 @@ TASK-002: <标题> [P1]
 3. 如果输入为 docs/ 设计文档（无需求目录）→ 按当前日期创建需求目录 `.code-flow/tasks/<YYYY-MM-DD>/<需求>/` 并写入其中
 4. 用 Write 写入
 
+写入后用 `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. 输出摘要
 
 ```

package/src/adapters/claude/commands/cf-task/prd.md

@@ -34,6 +34,22 @@
 
 目的：**让 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 个问题**：
@@ -94,6 +110,7 @@
 | 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 用户故事表
@@ -116,6 +133,12 @@
 3. **重名检查**：需求目录已存在且非本次草稿时，目录名追加序号 `<name>-2`、`<name>-3`… 避免覆盖；恢复模式复用原目录、不改名
 4. 用 Write 写入 `.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. 输出摘要
@@ -128,6 +151,7 @@
   - 用户故事: 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/claude/commands/cf-task/start.md

@@ -58,12 +58,15 @@
 
 ### 3. 激活并准备验收测试
 
-1. 用 Edit 更新子任务 Status 为 `in-progress`
-2. 在 `### Log` 追加：`- [<当前日期>] started (in-progress)`
-3. 更新文件头 `Updated` 日期
-4. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
-5. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
-6. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
+在改状态或生产代码前，顺序固定且不得跳步：
+
+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. 只有前三步全部成功，才用 Edit 更新子任务 Status 为 `in-progress`、追加 started log 并更新文件头日期。
+5. 在修改任何生产代码前，为每个 Acceptance-Ref 填写测试文件、包含场景 ID 的测试用例名和可单独执行的命令
+6. 先编写验收测试。E2E 测试必须经过契约声明的真实边界，不得用 mock 绕过 Store、Resolver、Builder、Renderer、Browser 等指定组件
+7. 新功能或缺陷修复先执行一次测试并记录 RED：失败命令、失败用例和与预期缺陷对应的失败原因。纯重构或已有行为补测无法 RED 时，记录原因，不得伪造失败
 
 RED 证据写入 `Acceptance Evidence`：
 
@@ -87,15 +90,15 @@ RED 证据写入 `Acceptance Evidence`：
 4. 负责该场景的任务验证完成后，将全局 `Acceptance Coverage` 对应行改为 `verified`
 5. 测试文件存在但未被测试框架收集、命令未实际执行、只有场景 ID 没有关键断言，都视为未验证
 
-### 3.5 会话级临时约束（FEAT-08）
+### 3.5 TASK-bound Spec Session
 
 激活后，若任务文件头 Source 指向的 design 文档含验收条件章节（如 §2.5 验收条件 / 验收标准）：
 
-1. 只提取当前任务 `Acceptance-Refs` 对应的场景、测试层级、关键真实边界与 RULE/RISK，生成 `.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）；必须保留全部引用 ID、层级、边界和预期结果，不能为压缩而删除场景
-2. Spec Catalog 目录扫描自动纳入该文件，无需配置；编辑代码时的自动注入同样生效
-3. design 无验收章节时静默跳过；同名文件已存在则覆盖（同任务重复 start）
+2. 任务模式直接读取这个投影，禁止经 Spec Catalog 二次选择；同名文件已存在则原子覆盖。
+3. 50 Rule 等超预算任务按 required/当前阶段优先输出受控摘要，完整 Context 保留不丢失，并明确提示拆 TASK；不得用截断隐藏 required 缺口。
 
 > `_session/` 不入库（.gitignore 模板已覆盖）、不参与规范审计与预算。
 

package/src/adapters/claude/settings.local.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "d=\"${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}\"; f=\"$d/.code-flow/scripts/cf_inject_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
           }
         ]
@@ -24,16 +24,6 @@
         ]
       }
     ],
-    "SessionStart": [
-      {
-        "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"
-          }
-        ]
-      }
-    ],
     "UserPromptSubmit": [
       {
         "hooks": [

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 个问题）：
@@ -191,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` 实际章节）：
 
@@ -268,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. 输出摘要
 
 ```
@@ -279,6 +300,7 @@ CLI 场景：
   - <按实际包含的章节列出>
   - 验收标准: N 项
   - 追溯自检: 每个 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

@@ -33,6 +33,13 @@ description: Archive a completed task file after completeness, correctness, trac
 
 ### 2. 归档前校验（Verify）
 
+**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 后，执行四维校验：
 
 **完整性**：