@michaelxwb/code-flow 0.5.1 → 0.6.0

package/src/core/code-flow/specs/frontend/quality-standards.md

@@ -1,5 +1,14 @@
 ---
+id: frontend-quality-standards
 description: 写前端代码时适用：类型、lint、错误处理、测试、状态管理质量约束
+stages: [design, plan, code, review]
+enforcement: required
+verifiers:
+  - rule: RULE-frontend-quality-001
+    type: manual
+    config:
+      checklist: Confirm all Guidance and Avoid items for this Spec.
+      owner: project-owner
 ---
 
 # Frontend Quality Standards
@@ -27,6 +36,9 @@ render(data);
 ```
 
 ## Rules
+- [RULE-frontend-quality-001] The implementation must satisfy every applicable item in Guidance and avoid every item in Avoid.
+
+## Guidance
 - TypeScript 项目禁止使用 `any`，未知类型用 `unknown` 并显式收敛
 - 组件统一使用函数组件（React）/ 组合式 API（Vue 3），禁止类组件新增
 - 关键交互（提交 / 删除 / 支付）必须有错误提示与 loading 状态
@@ -39,7 +51,7 @@ render(data);
 - 网络请求统一处理 401 / 403 / 5xx，避免每个调用方重复
 - 关键路径补端到端测试或组件交互测试
 
-## Anti-Patterns
+## Avoid
 - 禁止在 render / setup 中发起未受控的副作用（用 `useEffect` / `onMounted`）
 - 禁止把后端错误直接抛给用户（如 SQL / stack trace）
 - 禁止用 `// @ts-ignore` 绕过类型错误，必须修复或改为 `@ts-expect-error` 加注释

package/src/core/code-flow/specs/shared/design/design-frontend.md

@@ -90,19 +90,19 @@
 
 ### 2.4 验收条件 [必填]
 
-> 交互层面的可验证场景，写到可转 e2e / 组件交互测试断言的粒度（明确操作与可观测 UI 结果）。场景 ID 即测试用例来源。
+> 交互层面的可验证场景，写到可转 E2E / 组件交互测试断言的粒度（明确操作与可观测 UI 结果）。场景 ID 即测试用例来源。测试层级只能填 `unit` / `integration` / `E2E` / `manual`；跨路由、服务请求、状态更新和最终 UI 的用户流程必须标为 `E2E`。关键真实边界列出不得 mock 的浏览器、路由、状态或服务边界。
 
 **正常场景**
 
-| 场景ID | 功能ID | 优先级 | 操作步骤 | 预期 UI 结果 |
-|--------|--------|--------|---------|-------------|
-| S-01 | FEAT-01 | P0 | 1. <操作> | <可见结果> |
+| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 操作步骤 | 预期 UI 结果 |
+|--------|--------|--------|---------|-------------|---------|-------------|
+| S-01 | FEAT-01 | P0 | E2E | Browser → Router → Service → UI | 1. <操作> | <可见结果> |
 
 **异常场景**
 
-| 场景ID | 功能ID | 触发条件 | UI 表现 |
-|--------|--------|---------|---------|
-| E-01 | FEAT-01 | （接口失败 / 空数据 / 校验不通过） | （错误提示 / 空态 / 字段定位） |
+| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | UI 表现 |
+|--------|--------|---------|-------------|---------|---------|
+| E-01 | FEAT-01 | integration | Service → UI | （接口失败 / 空数据 / 校验不通过） | （错误提示 / 空态 / 字段定位） |
 
 **非功能指标** [按需]
 
@@ -227,9 +227,19 @@
 
 ## 4. 风险与依赖 [按需]
 
-| 风险ID | 描述 | 影响 | 应对 |
-|--------|------|------|------|
-| | | | |
+| 风险ID | 描述 | 影响 | 应对 | 验证场景 |
+|--------|------|------|------|---------|
+| | | | | S-/E-/B- 或手动验证理由 |
+
+---
+
+## Spec Compliance Matrix
+
+> 从需求目录 `spec-context.yml` 继承并逐 Rule 回填。required Rule 必须有具体设计落点和 verifier/验收场景；N/A 只接受逐项用户确认。
+
+| Spec/Rule | enforcement | 设计影响 | 设计落点 | 验证场景 | 状态/N/A 理由 |
+|-----------|-------------|---------|---------|---------|----------------|
+| `{spec-id}#RULE-{domain}-001` | required / advisory | <对方案/交互的影响> | §<heading> / <item-id> | S-/E-/B- + verifier | applied / confirmed N/A |
 
 ---
 

package/src/core/code-flow/specs/shared/design/design-full.md

@@ -133,32 +133,34 @@
 
 #### 2.5.1 业务规则与约束
 
-| ID | 类型 | 描述 |
-|----|------|------|
-| RULE-01 | 业务规则 | |
-| RULE-02 | 系统约束 | 单次批量导入上限≤10000条 |
+| ID | 类型 | 描述 | 验证场景 |
+|----|------|------|---------|
+| RULE-01 | 业务规则 | | S-01 |
+| RULE-02 | 系统约束 | 单次批量导入上限≤10000条 | B-01 |
 
 #### 2.5.2 功能验收场景
 
-> 场景写到可转自动化测试断言的粒度（明确前置、输入、可观测输出）。场景 ID（S-/E-/B-）即测试用例来源，§6 追溯矩阵的 TC-XXX 直接引用这些场景 ID。
+> 场景写到可转自动化测试断言的粒度（明确前置、输入、可观测输出）。场景 ID（S-/E-/B-）即测试用例来源，§6 追溯矩阵直接引用这些场景 ID。
+>
+> **测试层级**只能填 `unit` / `integration` / `E2E` / `manual`。跨 API、存储、运行时生成、渲染或用户可见结果等多个边界的场景必须标为 `E2E`；`manual` 仅限无法自动化的外部条件，并记录原因。**关键真实边界**列出测试中不得 mock 的组件或最终可观测面，编码阶段不得自行降级。
 
 **正常场景**
 
-| 场景ID | 功能ID | 优先级 | 前置条件 | 操作步骤 | 预期结果 |
-|--------|--------|--------|---------|---------|---------|
-| S-01 | FEAT-01 | P0 | | | |
+| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 前置条件 | 操作步骤 | 预期结果 |
+|--------|--------|--------|---------|-------------|---------|---------|---------|
+| S-01 | FEAT-01 | P0 | E2E | API → Store → 最终输出 | | | |
 
 **异常场景**
 
-| 场景ID | 功能ID | 触发条件 | 系统行为 | 用户感知 |
-|--------|--------|---------|---------|---------|
-| E-01 | FEAT-01 | | | |
+| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | 系统行为 | 用户感知 |
+|--------|--------|---------|-------------|---------|---------|---------|
+| E-01 | FEAT-01 | integration | Service → Store | | | |
 
 **边界场景** [按需]
 
-| 场景ID | 字段/条件 | 边界值 | 预期行为 |
-|--------|----------|--------|---------|
-| B-01 | | | |
+| 场景ID | 测试层级 | 关键真实边界 | 字段/条件 | 边界值 | 预期行为 |
+|--------|---------|-------------|----------|--------|---------|
+| B-01 | unit | 校验函数 | | | |
 
 #### 2.5.3 非功能指标 [按需]
 
@@ -386,9 +388,9 @@ flowchart TD
 
 **风险 / 失效应对**（默认轻量表）
 
-| 风险ID | 失效模式 | 影响 | 应对措施 |
-|--------|---------|------|---------|
-| RISK-01 | | | |
+| 风险ID | 失效模式 | 影响 | 应对措施 | 验证场景 |
+|--------|---------|------|---------|---------|
+| RISK-01 | | | | E-01 |
 
 > 仅安全关键 / 高并发 / 强一致系统才升级为 FMEA：追加 S/O/D（1-10）与 RPN=S×O×D 三列，RPN≥200 上线前必须解决。普通功能用上表即可，不要为打分而打分。
 
@@ -457,19 +459,29 @@ flowchart TD
 
 ### 5.2 风险识别
 
-| 风险ID | 类型 | 描述 | 概率 | 影响 | 应对措施 |
-|--------|------|------|------|------|---------|
-| | | | | | |
+| 风险ID | 类型 | 描述 | 概率 | 影响 | 应对措施 | 验证场景 |
+|--------|------|------|------|------|---------|---------|
+| | | | | | | S-/E-/B- 或手动验证理由 |
 
 ---
 
 ## 6. 需求追溯矩阵
 
-| 用户故事 | 功能ID | 接口ID | 测试用例ID | 状态 |
-|---------|--------|--------|-----------|------|
-| US-01 | FEAT-01 | API-01 | TC-001 | ✅ |
+| 用户故事 | 功能ID | 接口ID | 测试用例ID | 测试层级 | 状态 |
+|---------|--------|--------|-----------|---------|------|
+| US-01 | FEAT-01 | API-01 | S-01 | E2E | 待实现 |
 
-> 用户故事一列引用 PRD 中的 US-XX（无 PRD 时填"需求描述"）；测试用例 ID 列引用 §2.5.2 的场景 ID（S-/E-/B-），不要另造编号。
+> 用户故事一列引用 PRD 中的 US-XX（无 PRD 时填"需求描述"）；测试用例 ID 列引用 §2.5.2 的场景 ID（S-/E-/B-），不要另造编号。RULE 与高影响 RISK 必须映射到场景；无法自动化时写明手动验证原因，不得留空。
+
+---
+
+## Spec Compliance Matrix
+
+> 从需求目录 `spec-context.yml` 继承并逐 Rule 回填。required Rule 必须有具体设计落点和 verifier/验收场景；N/A 只接受逐项用户确认。
+
+| Spec/Rule | enforcement | 设计影响 | 设计落点 | 验证场景 | 状态/N/A 理由 |
+|-----------|-------------|---------|---------|---------|----------------|
+| `{spec-id}#RULE-{domain}-001` | required / advisory | <对方案的影响> | §<heading> / <item-id> | S-/E-/B- + verifier | applied / confirmed N/A |
 
 ---
 

package/src/core/code-flow/specs/shared/design/design-lite.md

@@ -109,18 +109,20 @@
 #### 2.4.1 功能验收场景
 
 > 每个 P0/P1 FEAT 至少 1 条正常 + 1 条异常场景；"操作步骤/预期结果"写到可直接转为自动化测试断言的粒度（明确输入与可观测输出）。场景 ID（S-/E-/B-）即测试用例编号，供 plan 拆解引用。
+>
+> **测试层级**只能填 `unit` / `integration` / `E2E` / `manual`。跨 API、存储、运行时生成、渲染或用户可见结果等多个边界的场景必须标为 `E2E`；`manual` 仅限无法自动化的外部条件，并记录原因。**关键真实边界**列出测试中不得 mock 的组件或最终可观测面，编码阶段不得自行降级。
 
 **正常场景**
 
-| 场景ID | 功能ID | 优先级 | 操作步骤 | 预期结果 |
-|--------|--------|--------|---------|---------|
-| S-01 | FEAT-01 | P0 | 1. <步骤><br>2. <步骤> | <结果> |
+| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 操作步骤 | 预期结果 |
+|--------|--------|--------|---------|-------------|---------|---------|
+| S-01 | FEAT-01 | P0 | E2E | API → Store → 最终输出 | 1. <步骤><br>2. <步骤> | <结果> |
 
 **异常场景**
 
-| 场景ID | 功能ID | 触发条件 | 系统行为 |
-|--------|--------|---------|---------|
-| E-01 | FEAT-01 | | |
+| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | 系统行为 |
+|--------|--------|---------|-------------|---------|---------|
+| E-01 | FEAT-01 | integration | Service → Store | | |
 
 #### 2.4.2 非功能指标 [按需]
 
@@ -274,9 +276,19 @@ flowchart TD
 
 ### 4.2 风险识别
 
-| 风险ID | 描述 | 影响 | 应对措施 |
-|--------|------|------|---------|
-| | | | |
+| 风险ID | 描述 | 影响 | 应对措施 | 验证场景 |
+|--------|------|------|---------|---------|
+| | | | | S-/E-/B- 或手动验证理由 |
+
+---
+
+## Spec Compliance Matrix
+
+> 从需求目录 `spec-context.yml` 继承并逐 Rule 回填。required Rule 必须有具体设计落点和 verifier/验收场景；N/A 只接受逐项用户确认。
+
+| Spec/Rule | enforcement | 设计影响 | 设计落点 | 验证场景 | 状态/N/A 理由 |
+|-----------|-------------|---------|---------|---------|----------------|
+| `{spec-id}#RULE-{domain}-001` | required / advisory | <对方案的影响> | §<heading> / <item-id> | S-/E-/B- + verifier | applied / confirmed N/A |
 
 ---
 

package/src/core/code-flow/specs/shared/prd-template.md

@@ -7,10 +7,10 @@
 > **状态**: 草稿 / 评审中 / 已批准 / 开发中 / 已上线
 
 **评审边界说明**:
-- **需求基线**: 第 2-6 章（背景/用户/功能/非功能/范围）→ 通过后锁定
-- **设计输入**: 第 3-6 章 → 为 `cf-task:align` 提供 US / FEAT / NFR / 范围
+- **需求基线**: 第 2-8 章（背景/用户/功能/非功能/范围/依赖/已有规范约束）→ 通过后锁定
+- **设计输入**: 第 3-8 章 → 为 `cf-task:align` 提供 US / FEAT / NFR / 范围 / Spec refs
 
-**ID 体系**: US（用户故事）、FEAT（功能）、NFR（非功能指标）
+**ID 体系**: US（用户故事）、FEAT（功能）、NFR（非功能指标）、Spec/Rule（已有规范引用）
 
 **适用场景**: 需求早期阶段，在设计之前
 **不适用**: 已有明确技术方案（请直接用 cf-task:align）
@@ -34,6 +34,7 @@
 - [5. 非功能需求](#5-非功能需求-可选)
 - [6. 范围与边界](#6-范围与边界-必填)
 - [7. 依赖与风险](#7-依赖与风险-可选)
+- [8. Existing Spec Constraints](#8-existing-spec-constraints)
 - [附录：术语表](#附录术语表)
 
 ---
@@ -172,6 +173,16 @@
 
 ---
 
+## 8. Existing Spec Constraints
+
+> 仅列出 `stages` 含 `prd` 且已绑定到 `spec-context.yml` 的 Rule。required Rule 必须明确落到范围、FEAT 验收或 NFR；不适用必须逐条记录用户确认，不能由 Agent 自行填写 N/A。
+
+| Spec/Rule | 约束 | 对范围/验收的影响 | 状态 |
+|-----------|------|------------------|------|
+| `{spec-id}#RULE-{domain}-001` | <规则摘要> | <In/Out Scope、FEAT-XX 验收或 NFR-XX> | applied / confirmed N/A |
+
+---
+
 ## 附录：术语表
 
 | 术语 | 定义 |

package/src/migrate/spec-workflow.js

@@ -0,0 +1,238 @@
+"use strict";
+
+const childProcess = require("node:child_process");
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const PREFLIGHT = path.join(__dirname, "../core/code-flow/scripts/cf_spec_migrate.py");
+
+function walkFiles(root, directory = root) {
+  const files = [];
+  if (!fs.existsSync(directory)) return files;
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const full = path.join(directory, entry.name);
+    const relative = path.relative(root, full);
+    if (entry.isDirectory() && relative === path.join(".code-flow", "migrations")) continue;
+    if (entry.isDirectory()) files.push(...walkFiles(root, full));
+    else files.push(relative);
+  }
+  return files.sort();
+}
+
+function migrationFiles(root) {
+  const entries = [".code-flow", ".claude", ".codex", ".costrict", ".opencode", ".agents", "AGENTS.md", "CLAUDE.md"];
+  const files = [];
+  for (const entry of entries) {
+    const target = path.join(root, entry);
+    if (!fs.existsSync(target)) continue;
+    if (fs.statSync(target).isDirectory()) files.push(...walkFiles(root, target));
+    else files.push(entry);
+  }
+  return [...new Set(files)].sort();
+}
+
+function hash(data) {
+  return crypto.createHash("sha256").update(data).digest("hex");
+}
+
+function sourceHashes(root) {
+  const result = {};
+  for (const relative of migrationFiles(root)) {
+    result[relative] = hash(fs.readFileSync(path.join(root, relative)));
+  }
+  return result;
+}
+
+function pythonCommand() {
+  return process.env.PYTHON || "python3";
+}
+
+function preview(root) {
+  const project = fs.realpathSync(root);
+  const result = childProcess.spawnSync(
+    pythonCommand(), [PREFLIGHT, "preflight", "--root", project, "--json"],
+    { encoding: "utf8", shell: false }
+  );
+  if (result.status !== 0) throw new Error(result.stderr || result.stdout || "preflight failed");
+  return JSON.parse(result.stdout);
+}
+
+function migrationId(root, hashes) {
+  const seed = `${root}\0${JSON.stringify(hashes)}\0${Date.now()}`;
+  return `spec-workflow-${hash(seed).slice(0, 12)}`;
+}
+
+function copyBackup(root, backup, hashes) {
+  for (const relative of Object.keys(hashes)) {
+    const target = path.join(backup, relative);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(path.join(root, relative), target);
+  }
+}
+
+function writeJson(target, value) {
+  fs.writeFileSync(target, `${JSON.stringify(value, null, 2)}\n`, "utf8");
+}
+
+function prepare(root) {
+  const project = fs.realpathSync(root);
+  const plan = preview(project);
+  const hashes = sourceHashes(project);
+  const id = migrationId(project, hashes);
+  const workspace = path.join(project, ".code-flow", "migrations", id);
+  const backup = path.join(workspace, "backup");
+  const staging = path.join(workspace, "staging");
+  fs.mkdirSync(backup, { recursive: true });
+  fs.mkdirSync(staging, { recursive: true });
+  copyBackup(project, backup, hashes);
+  const preparedPlan = { ...plan, migration_id: id, project_root: project, source_hashes: hashes };
+  const status = plan.unresolved.length ? "prepared_blocked" : "prepared";
+  writeJson(path.join(workspace, "migration-plan.json"), preparedPlan);
+  writeJson(path.join(workspace, "journal.json"), { version: 1, migration_id: id, status, operations: [] });
+  return { migration_id: id, status, workspace, plan: path.join(workspace, "migration-plan.json") };
+}
+
+function readJson(target) {
+  return JSON.parse(fs.readFileSync(target, "utf8"));
+}
+
+function journalPaths(planPath) {
+  const workspace = path.dirname(planPath);
+  return { workspace, journal: path.join(workspace, "journal.json"), staging: path.join(workspace, "staging"), backup: path.join(workspace, "backup") };
+}
+
+function sameHashes(first, second) {
+  return JSON.stringify(first) === JSON.stringify(second);
+}
+
+function runStaging(planPath, locations) {
+  const result = childProcess.spawnSync(
+    pythonCommand(), [PREFLIGHT, "stage", "--plan", planPath, "--staging", locations.staging, "--json"],
+    { encoding: "utf8", shell: false }
+  );
+  if (result.status !== 0) throw new Error(result.stdout || result.stderr || "staging failed");
+  return JSON.parse(result.stdout);
+}
+
+function verifyStaging(staging, manifest) {
+  for (const item of manifest.targets) {
+    const target = path.join(staging, item.path);
+    if (!fs.existsSync(target) || hash(fs.readFileSync(target)) !== item.sha256) {
+      throw new Error(`staging hash mismatch: ${item.path}`);
+    }
+  }
+}
+
+function persistJournal(target, journal, status) {
+  journal.status = status;
+  writeJson(target, journal);
+}
+
+function targetEntries(manifest) {
+  return manifest.targets.filter((item) => item.path !== ".code-flow/.version");
+}
+
+function commitEntry(project, staging, item, journal, journalPath) {
+  const source = path.join(staging, item.path);
+  const target = path.join(project, item.path);
+  journal.operations.push({ path: item.path, status: "renaming" });
+  writeJson(journalPath, journal);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  if (fs.existsSync(target)) fs.rmSync(target, { recursive: true, force: true });
+  fs.renameSync(source, target);
+  journal.operations[journal.operations.length - 1].status = "committed";
+  writeJson(journalPath, journal);
+}
+
+function obsoletePaths(plan, manifest) {
+  const targets = new Set(manifest.targets.map((item) => item.path));
+  return Object.keys(plan.source_hashes).filter((item) => item.startsWith(".code-flow/") && item !== ".code-flow/.version" && !targets.has(item));
+}
+
+function removeObsolete(project, paths) {
+  for (const relative of paths) fs.rmSync(path.join(project, relative), { recursive: true, force: true });
+}
+
+function restoreBackup(plan, locations, manifest) {
+  for (const item of manifest.targets || []) {
+    if (item.path !== ".code-flow/.version") fs.rmSync(path.join(plan.project_root, item.path), { recursive: true, force: true });
+  }
+  for (const relative of Object.keys(plan.source_hashes)) {
+    const source = path.join(locations.backup, relative);
+    const target = path.join(plan.project_root, relative);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.copyFileSync(source, target);
+  }
+}
+
+function rollback(planPath, error = "requested") {
+  const plan = readJson(planPath);
+  const locations = journalPaths(planPath);
+  const journal = readJson(locations.journal);
+  try {
+    restoreBackup(plan, locations, journal.manifest || { targets: [] });
+    journal.error = String(error);
+    persistJournal(locations.journal, journal, "rolled_back");
+    return { status: "rolled_back", migration_id: plan.migration_id };
+  } catch (restoreError) {
+    journal.error = String(restoreError);
+    persistJournal(locations.journal, journal, "recovery_required");
+    return { status: "recovery_required", migration_id: plan.migration_id };
+  }
+}
+
+function targetsMatch(project, manifest) {
+  return targetEntries(manifest).every((item) => {
+    const target = path.join(project, item.path);
+    return fs.existsSync(target) && hash(fs.readFileSync(target)) === item.sha256;
+  });
+}
+
+function finishVersion(plan, journal, journalPath) {
+  fs.writeFileSync(path.join(plan.project_root, ".code-flow/.version"), "0.6.0", "utf8");
+  persistJournal(journalPath, journal, "committed");
+  return { status: "committed", migration_id: plan.migration_id };
+}
+
+function recoverCommitting(plan, journal, locations, options) {
+  if (!targetsMatch(plan.project_root, journal.manifest)) return rollback(path.join(locations.workspace, "migration-plan.json"), "target hash mismatch");
+  if (options.interruptBeforeVersion) return { status: "committing", migration_id: plan.migration_id };
+  return finishVersion(plan, journal, locations.journal);
+}
+
+function apply(planPath, options = {}) {
+  const plan = readJson(planPath);
+  const locations = journalPaths(planPath);
+  const versionPath = path.join(plan.project_root, ".code-flow/.version");
+  if (fs.existsSync(versionPath) && fs.readFileSync(versionPath, "utf8").trim() === "0.6.0") return { status: "already_migrated", migration_id: plan.migration_id };
+  const journal = readJson(locations.journal);
+  if (journal.status === "committing") return recoverCommitting(plan, journal, locations, options);
+  if (plan.unresolved.length) throw new Error("migration plan has unresolved items");
+  if (!sameHashes(sourceHashes(plan.project_root), plan.source_hashes)) throw new Error("source hash drift");
+  try {
+    const manifest = runStaging(planPath, locations);
+    verifyStaging(locations.staging, manifest);
+    journal.manifest = manifest;
+    persistJournal(locations.journal, journal, "committing");
+    let completed = 0;
+    for (const item of targetEntries(manifest)) {
+      if (options.failAfter === completed) throw new Error(`injected rename failure ${completed}`);
+      if (options.exdevAfter === completed) {
+        const exdev = new Error("injected EXDEV");
+        exdev.code = "EXDEV";
+        throw exdev;
+      }
+      commitEntry(plan.project_root, locations.staging, item, journal, locations.journal);
+      completed += 1;
+    }
+    removeObsolete(plan.project_root, obsoletePaths(plan, manifest));
+    removeObsolete(plan.project_root, manifest.deletions || []);
+    if (options.interruptBeforeVersion) return { status: "committing", migration_id: plan.migration_id };
+    return finishVersion(plan, journal, locations.journal);
+  } catch (error) {
+    return rollback(planPath, error);
+  }
+}
+
+module.exports = { apply, preview, prepare, rollback, sourceHashes, walkFiles };

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

@@ -1,55 +0,0 @@
-# cf-inject
-
-强制重新注入指定领域的编码规范（通常不需要手动调用）。
-
-## 自动注入机制
-
-本项目的规范注入是**全自动**的，通过两层机制保障：
-
-1. **CLAUDE.md 指令**：Claude 根据问题自动判断领域，读取 `_map.md` 导航地图理解项目结构
-2. **PreToolUse Hook**：编辑代码文件时根据文件路径标签自动注入匹配的约束 specs
-
-两层职责分离：CLAUDE.md 负责导航（Tier 0），Hook 负责约束注入（Tier 1）。
-
-正常情况下**无需手动调用**此命令。
-
-## 何时使用
-
-- 需要强制刷新已注入的规范（如 spec 文件刚被修改）
-- 想要预览某个领域的完整规范内容
-- 自动注入未生效时的排查手段
-- Hook 标签匹配遗漏了某些 spec，需要手动补充
-
-## 输入
-
-- `/project:cf-inject frontend` — 强制加载前端全部 specs
-- `/project:cf-inject backend` — 强制加载后端全部 specs
-
-## 执行步骤
-
-1. 用 Read 读取 `.code-flow/config.yml`，获取指定领域的 `specs` 列表
-2. 提取所有 spec 的 `path` 字段（兼容新旧格式）
-3. 按 tier 排序：tier 0（`_map.md`）在前，tier 1 按列表顺序
-4. 用 Read 逐个读取 `.code-flow/specs/` 下的匹配文件
-5. 将规范内容直接输出到对话中，格式：
-
-```
-## Active Specs (manual inject)
-
-### Navigation (Retrieval Map)
-
-#### [domain]/_map.md
-[导航地图内容]
-
-### Constraints (all specs for domain)
-
-#### [spec-path]
-[spec 内容]
-
----
-以上规范是本次开发的约束条件，生成代码必须遵循。
-```
-
-6. 用 Write 更新 `.code-flow/.inject-state`，将该域所有 spec 路径标记为已注入，防止 Hook 重复注入
-
-> 注：手动 inject 会加载该域的**全部** spec，不做标签过滤。这是与 Hook 自动注入的区别——Hook 按标签精准匹配，手动注入用于全量预览或强制刷新。

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

@@ -1,56 +0,0 @@
----
-name: cf-inject
-description: Manually force-load all specs for a domain. Use when auto-injection hasn't triggered, you want to preview a domain's complete spec content, spec files were recently edited and need refresh, or hook tag matching missed some specs.
----
-
-## 自动注入机制
-
-本项目的规范注入是**全自动**的，通过两层机制保障：
-
-1. **AGENTS.md 指令**：根据问题自动判断领域，读取 `_map.md` 导航地图理解项目结构
-2. **UserPromptSubmit Hook**：每轮对话开始时，根据 prompt 中引用的文件路径标签自动注入匹配的约束 specs
-
-两层职责分离：AGENTS.md 负责导航（Tier 0），Hook 负责约束注入（Tier 1）。
-
-正常情况下**无需手动调用**此命令。
-
-## 何时使用
-
-- 需要强制刷新已注入的规范（如 spec 文件刚被修改）
-- 想要预览某个领域的完整规范内容
-- 自动注入未生效时的排查手段（例如 prompt 中未明确引用文件路径）
-- Hook 标签匹配遗漏了某些 spec，需要手动补充
-
-## 输入
-
-- `cf-inject frontend` — 强制加载前端全部 specs
-- `cf-inject backend` — 强制加载后端全部 specs
-
-## 执行步骤
-
-1. 读取 `.code-flow/config.yml`，获取指定领域的 `specs` 列表
-2. 提取所有 spec 的 `path` 字段（兼容新旧格式）
-3. 按 tier 排序：tier 0（`_map.md`）在前，tier 1 按列表顺序
-4. 逐个读取 `.code-flow/specs/` 下的匹配文件
-5. 将规范内容直接输出到对话中，格式：
-
-```
-## Active Specs (manual inject)
-
-### Navigation (Retrieval Map)
-
-#### [domain]/_map.md
-[导航地图内容]
-
-### Constraints (all specs for domain)
-
-#### [spec-path]
-[spec 内容]
-
----
-以上规范是本次开发的约束条件，生成代码必须遵循。
-```
-
-6. 用 apply_patch 更新 `.code-flow/.inject-state`，将该域所有 spec 路径标记为已注入，防止 Hook 重复注入
-
-> 注：手动 inject 会加载该域的**全部** spec，不做标签过滤。这是与 Hook 自动注入的区别——UserPromptSubmit Hook 按 prompt 中的文件路径推断标签精准匹配，手动注入用于全量预览或强制刷新。