@michaelxwb/code-flow 0.6.4 → 0.8.1

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

@@ -1,5 +1,7 @@
 # {模块名称} 前端模块需求与设计简报
 
+> **生成约定**：产出文档的 frontmatter 声明 `design_template: frontend`。浏览器 E2E 必须有匹配的 env/components/boundary，expected 逐条用 expected_refs 关联步骤或断言；deferred 补原因、owner 与 target_phase。API/CLI/后台全链路用 system，容量用 capacity；非 E2E 不写 why_e2e。完成后运行 scenarios parse --quality 与 design lint；计划再校验真实测试登记/收集。完整示例见工具文档 `docs/acceptance-contract.md`。
+
 > **文档编号**: FE-{模块代号}-{版本号}
 > **文档版本**: v1.0
 > **创建日期**: YYYY-MM-DD
@@ -24,6 +26,7 @@
   - [2.2 功能方案](#22-功能方案-必填)
   - [2.3 范围与边界](#23-范围与边界-必填)
   - [2.4 验收条件](#24-验收条件-必填)
+    - [2.4.1 验证环境假设](#241-验证环境假设-必填)
 - [3. 前端技术设计](#3-前端技术设计)
   - [3.1 技术选型](#31-技术选型-必填)
   - [3.2 页面与路由结构](#32-页面与路由结构-必填)
@@ -90,25 +93,25 @@
 
 ### 2.4 验收条件 [必填]
 
-> 交互层面的可验证场景，写到可转 E2E / 组件交互测试断言的粒度（明确操作与可观测 UI 结果）。场景 ID 即测试用例来源。测试层级只能填 `unit` / `integration` / `E2E` / `manual`；跨路由、服务请求、状态更新和最终 UI 的用户流程必须标为 `E2E`。关键真实边界列出不得 mock 的浏览器、路由、状态或服务边界。
-
-**正常场景**
-
-| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 操作步骤 | 预期 UI 结果 |
-|--------|--------|--------|---------|-------------|---------|-------------|
-| S-01 | FEAT-01 | P0 | E2E | Browser → Router → Service → UI | 1. <操作> | <可见结果> |
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。本节只保留场景引用和前端设计影响，不复制完整场景表；优先级、执行方式、环境、输入等执行元数据以 scenarios 源为准；没有可执行命令的场景必须显式标为 aspirational；plan 阶段投影到 manifest check；测试层级（unit / component / contract / integration / system / capacity / E2E / manual）与关键真实边界定义在 scenarios 源中。
+>
+> **前端 E2E 精度**：表单交互、布局、文案、字段顺序、空态和错误提示用 component + mock API；E2E 只保留真实浏览器 + 真实后端 + 鉴权/DB 的关键用户旅程。E2E 必须有 `why_e2e`、非 smoke 的 `trigger_paths` 和可观察结果，禁止源码字符串/CSS/宽度断言。
 
-**异常场景**
+| 场景ID | 前端设计影响 / 备注 |
+|--------|--------------------|
+| S-01 | 正常交互路径；涉及的页面、组件与真实边界 |
+| E-01 | 异常/空态路径；涉及的组件状态与用户可见反馈 |
 
-| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | UI 表现 |
-|--------|--------|---------|-------------|---------|---------|
-| E-01 | FEAT-01 | integration | Service → UI | （接口失败 / 空数据 / 校验不通过） | （错误提示 / 空态 / 字段定位） |
+#### 2.4.1 验证环境假设 [必填]
 
-**非功能指标** [按需]
+> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行期缺失时应返回 `env_blocked` 并列出 owner，不得伪装成产品失败。
 
-| 指标ID | 指标名称 | 目标值 | 测量方法 |
-|--------|---------|-------|---------|
-| NFR-PERF-01 | 首屏 / 交互响应 | 待定 | Lighthouse / 实测 |
+| 维度 | 假设 | 验证方式 / 参数 | 不满足时 |
+|------|------|----------------|---------|
+| 容量 | （页面/组件规模、并发用户、浏览器矩阵；无实测填"待定"） | Playwright projects / 基准 fixture | 标记 `incomplete` 或拆分批次 |
+| 硬件 | （CI runner / 设备 / 视口规格） | preflight 检查 | 返回 `env_blocked` |
+| 依赖 | （后端 API / 浏览器版本 / 测试账号 / 字体与静态资源） | `preflight` 命令（health check） | 返回 `env_blocked` 并列出缺失项 |
+| profile 参数 | （smoke / changed / full、浏览器矩阵、重试与超时） | `verify --layers e2e --profile ...` | 显式报 `incomplete`，不自动降级 |
 
 ---
 

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

@@ -1,5 +1,7 @@
 # {模块名称} 模块需求与设计一体化文档
 
+> **生成约定**：产出文档的 frontmatter 声明 `design_template: full`。浏览器 E2E 必须有匹配的 env/components/boundary，expected 逐条用 expected_refs 关联步骤或断言；deferred 补原因、owner 与 target_phase。API/CLI/后台全链路用 system，容量用 capacity；非 E2E 不写 why_e2e。完成后运行 scenarios parse --quality 与 design lint；计划再校验真实测试登记/收集。完整示例见工具文档 `docs/acceptance-contract.md`。
+
 > **文档编号**: MOD-{模块代号}-{版本号}
 > **文档版本**: v1.0
 > **创建日期**: YYYY-MM-DD
@@ -28,6 +30,7 @@
   - [2.3 功能方案](#23-功能方案-必填)
   - [2.4 范围与边界](#24-范围与边界-必填)
   - [2.5 验收条件](#25-验收条件-必填)
+    - [2.5.4 验证环境假设](#254-验证环境假设-必填)
 - [3. 技术设计](#3-技术设计)
   - [3.1 方案选型](#31-方案选型-必填)
   - [3.2 架构设计](#32-架构设计-必填)
@@ -131,6 +134,8 @@
 
 ### 2.5 验收条件 [必填]
 
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。本节只保留业务规则、设计影响和场景引用；不要在此复制完整全局场景表。
+
 #### 2.5.1 业务规则与约束
 
 | ID | 类型 | 描述 | 验证场景 |
@@ -140,27 +145,17 @@
 
 #### 2.5.2 功能验收场景
 
-> 场景写到可转自动化测试断言的粒度（明确前置、输入、可观测输出）。场景 ID（S-/E-/B-）即测试用例来源，§6 追溯矩阵直接引用这些场景 ID。
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。设计文档只引用全局场景 ID，并说明设计影响，不复制完整场景字段；优先级、执行方式、环境、输入等执行元数据以 scenarios 源为准；没有可执行命令的场景必须显式标为 aspirational；plan 阶段投影到 manifest check；测试层级（unit / component / contract / integration / system / capacity / E2E / manual）与关键真实边界定义在 scenarios 源中。
 >
-> **测试层级**只能填 `unit` / `integration` / `E2E` / `manual`。跨 API、存储、运行时生成、渲染或用户可见结果等多个边界的场景必须标为 `E2E`；`manual` 仅限无法自动化的外部条件，并记录原因。**关键真实边界**列出测试中不得 mock 的组件或最终可观测面，编码阶段不得自行降级。
-
-**正常场景**
-
-| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 前置条件 | 操作步骤 | 预期结果 |
-|--------|--------|--------|---------|-------------|---------|---------|---------|
-| S-01 | FEAT-01 | P0 | E2E | API → Store → 最终输出 | | | |
-
-**异常场景**
-
-| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | 系统行为 | 用户感知 |
-|--------|--------|---------|-------------|---------|---------|---------|
-| E-01 | FEAT-01 | integration | Service → Store | | | |
-
-**边界场景** [按需]
+> **E2E 精度**：E2E 只用于 P0/P1 关键用户旅程，且必须有 `why_e2e`（低层测试为什么不够）、非 smoke 的 `trigger_paths`（哪些源码变化才触发）和可观察结果。UI 布局/文案/字段顺序用 component，DTO/错误码用 contract，鉴权/事务/模块边界用 integration；不要用 E2E 覆盖所有用户可见结果。
+>
+> ✅ CAS 409：contract 验响应、component 验表单保留、integration 用真实存储验并发；聚合补零与关系绑定同样优先采用相应低层组合。Cookie 隔离和 SSE 恢复保留必要的跨边界关键验证。❌ 设固定 E2E 数量或比例；比例和任务耗时仅作诊断，零 E2E 的完整覆盖合法。
 
-| 场景ID | 测试层级 | 关键真实边界 | 字段/条件 | 边界值 | 预期行为 |
-|--------|---------|-------------|----------|--------|---------|
-| B-01 | unit | 校验函数 | | | |
+| 场景ID | 设计影响 / 备注 |
+|--------|----------------|
+| S-01 | 正常路径；涉及的设计组件与真实边界 |
+| E-01 | 异常路径；涉及的设计组件与失败表现 |
+| B-01 | 边界条件；按需 |
 
 #### 2.5.3 非功能指标 [按需]
 
@@ -184,6 +179,17 @@
 | NFR-SEC-01 | 认证鉴权 | 未授权用户无法访问 |
 | NFR-SEC-02 | 数据加密 | 敏感字段不可明文 |
 
+#### 2.5.4 验证环境假设 [必填]
+
+> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行期缺失时应由 runner 返回 `env_blocked` 并列出 owner，不得伪装成产品失败。
+
+| 维度 | 假设 | 验证方式 / 参数 | 不满足时 |
+|------|------|----------------|---------|
+| 容量 | （数据量、并发数、场景规模，如 119 任务 / 62 E2E；无实测填"待定"） | 基准 fixture / 压测命令 | 标记 `incomplete` 或拆分批次 |
+| 硬件 | （CPU / 内存 / 磁盘 / 网络规格，如 8C16G） | preflight 检查 | 返回 `env_blocked` 并列出缺失项 |
+| 依赖 | （数据库 / 浏览器 / API / CI runner / 端口 / 测试账号） | `preflight` 命令（health check、端口探测） | 返回 `env_blocked` 并列出 owner |
+| profile 参数 | （smoke / changed / full 选择、deadline、并行度、重试与超时） | `verify --layers ... --profile ... --deadline ...` | 显式报 `incomplete`，不自动降级 |
+
 ---
 
 ## 3. 技术设计
@@ -465,11 +471,15 @@ flowchart TD
 
 ---
 
-## 6. 需求追溯矩阵
+## 6. 需求追溯矩阵（生成式）
+
+> 本节由 `cf_traceability.py --design <design.md> --manifest <.acceptance-manifest.json>` 从 §2.5 与 manifest **生成，不手工维护**；不要直接编辑下面的表格，提交前用生成结果替换。
+>
+> 生成矩阵会列出每个场景的优先级、测试层级、执行方式、环境、输入、追溯 check、执行命令、owner 与状态；没有 check 且未显式标为 `aspirational` 的场景会让生成命令返回 block。
 
-| 用户故事 | 功能ID | 接口ID | 测试用例ID | 测试层级 | 状态 |
-|---------|--------|--------|-----------|---------|------|
-| US-01 | FEAT-01 | API-01 | S-01 | E2E | 待实现 |
+| 用户故事 | 功能ID | 接口ID | 测试用例ID | 测试层级 | 执行方式 | 追溯 check | 状态 |
+|---------|--------|--------|-----------|---------|---------|-----------|------|
+| US-01 | FEAT-01 | API-01 | S-01 | E2E | auto | CHK-xxxx | 待实现 |
 
 > 用户故事一列引用 PRD 中的 US-XX（无 PRD 时填"需求描述"）；测试用例 ID 列引用 §2.5.2 的场景 ID（S-/E-/B-），不要另造编号。RULE 与高影响 RISK 必须映射到场景；无法自动化时写明手动验证原因，不得留空。
 

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

@@ -1,5 +1,7 @@
 # {模块名称} 模块需求与设计简报
 
+> **生成约定**：产出文档的 frontmatter 声明 `design_template: lite`。浏览器 E2E 必须有匹配的 env/components/boundary，expected 逐条用 expected_refs 关联步骤或断言；deferred 补原因、owner 与 target_phase。API/CLI/后台全链路用 system，容量用 capacity；非 E2E 不写 why_e2e。完成后运行 scenarios parse --quality 与 design lint；计划再校验真实测试登记/收集。完整示例见工具文档 `docs/acceptance-contract.md`。
+
 > **文档编号**: MOD-{模块代号}-{版本号}
 > **文档版本**: v1.0
 > **创建日期**: YYYY-MM-DD
@@ -29,6 +31,7 @@
   - [2.2 功能方案](#22-功能方案-必填)
   - [2.3 范围与边界](#23-范围与边界-必填)
   - [2.4 验收条件](#24-验收条件-必填)
+    - [2.4.3 验证环境假设](#243-验证环境假设-必填)
 - [3. 技术设计](#3-技术设计)
   - [3.1 技术选型](#31-技术选型-必填)
   - [3.2 架构设计](#32-架构设计-必填)
@@ -106,23 +109,19 @@
 
 ### 2.4 验收条件 [必填]
 
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。本节只保留业务规则、设计影响和场景引用；不要在此复制完整全局场景表。
+
 #### 2.4.1 功能验收场景
 
-> 每个 P0/P1 FEAT 至少 1 条正常 + 1 条异常场景；"操作步骤/预期结果"写到可直接转为自动化测试断言的粒度（明确输入与可观测输出）。场景 ID（S-/E-/B-）即测试用例编号，供 plan 拆解引用。
+> **场景唯一源**：验收场景定义在 `<需求>.scenarios.md`。设计文档只引用全局场景 ID，并说明设计影响，不复制完整场景字段；优先级、执行方式、环境、输入等执行元数据以 scenarios 源为准；没有可执行命令的场景必须显式标为 aspirational；plan 阶段投影到 manifest check；测试层级（unit / component / contract / integration / system / capacity / E2E / manual）与关键真实边界定义在 scenarios 源中。
 >
-> **测试层级**只能填 `unit` / `integration` / `E2E` / `manual`。跨 API、存储、运行时生成、渲染或用户可见结果等多个边界的场景必须标为 `E2E`；`manual` 仅限无法自动化的外部条件，并记录原因。**关键真实边界**列出测试中不得 mock 的组件或最终可观测面，编码阶段不得自行降级。
-
-**正常场景**
-
-| 场景ID | 功能ID | 优先级 | 测试层级 | 关键真实边界 | 操作步骤 | 预期结果 |
-|--------|--------|--------|---------|-------------|---------|---------|
-| S-01 | FEAT-01 | P0 | E2E | API → Store → 最终输出 | 1. <步骤><br>2. <步骤> | <结果> |
+> **E2E 精度**：E2E 只用于 P0/P1 关键用户旅程，且必须有 `why_e2e`、非 smoke 的 `trigger_paths` 和可观察结果。UI 布局/文案/字段顺序用 component，DTO/错误码用 contract，鉴权/事务/模块边界用 integration。
 
-**异常场景**
-
-| 场景ID | 功能ID | 测试层级 | 关键真实边界 | 触发条件 | 系统行为 |
-|--------|--------|---------|-------------|---------|---------|
-| E-01 | FEAT-01 | integration | Service → Store | | |
+| 场景ID | 设计影响 / 备注 |
+|--------|----------------|
+| S-01 | 正常路径；涉及的设计组件与真实边界 |
+| E-01 | 异常路径；涉及的设计组件与失败表现 |
+| B-01 | 边界条件；按需 |
 
 #### 2.4.2 非功能指标 [按需]
 
@@ -131,6 +130,17 @@
 | NFR-PERF-01 | 响应时间（P95） | ≤200ms | APM监控 |
 | NFR-REL-01 | 可用性（SLA） | ≥99.9% | 年度可用时长 |
 
+#### 2.4.3 验证环境假设 [必填]
+
+> 验收场景依赖的容量、硬件、外部依赖与 profile 参数必须在设计阶段写清；执行期缺失时应返回 `env_blocked` 并列出 owner，不得伪装成产品失败。
+
+| 维度 | 假设 | 验证方式 / 参数 | 不满足时 |
+|------|------|----------------|---------|
+| 容量 | （数据量、并发数、场景规模；无实测填"待定"） | 基准 fixture / 压测命令 | 标记 `incomplete` 或拆分批次 |
+| 硬件 | （CPU / 内存 / 磁盘 / 网络规格） | preflight 检查 | 返回 `env_blocked` |
+| 依赖 | （数据库 / 浏览器 / API / 端口 / 测试账号） | `preflight` 命令 | 返回 `env_blocked` 并列出缺失项 |
+| profile 参数 | （smoke / changed / full、deadline、并行度、重试） | `verify --profile ... --deadline ...` | 显式报 `incomplete`，不自动降级 |
+
 ---
 
 ## 3. 技术设计

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

@@ -0,0 +1,55 @@
+---
+id: scenarios-template
+description: Scenario-first acceptance source template (not auto-injected)
+stages: [design]
+enforcement: advisory
+---
+
+# {需求名} 验收场景
+
+> 本文件是验收场景的唯一源。design 文档只写实现逻辑并引用场景 ID；任务文件只登记 owner 与执行命令。
+>
+> 以下是可通过场景质量检查的订单示例，使用时替换为本需求的真实行为与路径。将 YAML 放到 `<需求>.scenarios.md` 的 frontmatter 或作为整个 YAML 文件保存；不要把模板自身的 Spec 元数据当成场景源。`checks` 在 plan 生成真实 check ID 后绑定，空列表不能通过需要测试登记的 verify-plan。
+
+```yaml
+schema: 1
+requirement: 订单创建
+scenarios:
+  - id: S-01
+    title: 登录用户通过浏览器创建订单
+    priority: P0            # P0 / P1 / P2；E2E 只允许 P0/P1 关键旅程
+    level: e2e              # unit / component / contract / integration / system / capacity / e2e / manual
+    exec: deferred          # auto / deferred / manual / aspirational
+    env: browser            # none / local / local-api / browser / external / staging / capacity / ci / production
+    components: [browser, frontend, api, db]
+    boundary: 真实浏览器 → 订单 API → 数据库
+    preconditions: [用户已登录，购物车含一件库存充足的商品]
+    steps: [在浏览器点击提交订单]
+    expected: [订单列表新增一条状态为 created 的订单]
+    expected_refs: [{expected: 1, steps: [1]}]  # 从 1 开始，逐个 expected 引用步骤或已声明断言 ID
+    why_e2e: 真实浏览器登录态与订单持久化跨前后端，需要联合验证
+    trigger_paths: [src/frontend/*, src/orders/*]
+    smoke: true             # check 与收集到的测试都必须登记 smoke marker
+    defer_reason: 在需求终验阶段运行真实浏览器链路
+    owner: TASK-001
+    target_phase: review    # plan / code / review / ci / release
+    features: [FEAT-01]
+    design_refs: [API-01]    # 对应设计必须定义 FEAT-01 / API-01
+    rules: []
+    checks: []              # plan 阶段绑定；一个场景可多个 check
+```
+
+> **测试层级决策**：UI 交互/布局/字段顺序 → `component`；DTO/OpenAPI/错误码 →
+> `contract`；鉴权/事务/模块边界/进程内 API → `integration`；API/CLI/后台全链路 →
+> `system`；容量 → `capacity` 或 capacity 标签；只有真实浏览器 +
+> 真实后端 + 真实 DB/鉴权的关键旅程才用 `E2E`。E2E 不是“用户可见结果”的默认层。
+
+> CAS 409 示例：contract 检查冲突响应，component 检查表单保留，integration 用真实存储验证并发写入；分别登记 check，按 expected 映射必要成员。低层覆盖完整时可以不新增 E2E；仅为剩余跨边界接线风险选择 E2E，说明独特故障、已有低层覆盖及剩余风险，由设计评审判断理由。
+>
+> ✅ CAS 用 contract + component + 真实存储 integration；聚合补零用数据 contract + component；关系绑定用真实存储 integration。Cookie 身份隔离与 SSE 断线恢复仍可保留针对性的浏览器 E2E，验证低层无法证明的跨边界接线。
+>
+> ❌ 因用户看得到结果就为每个表单、聚合或关系操作新增一条 E2E；也不要只改旧 E2E 的层级后继承历史通过证据。
+>
+> **质量门禁**：E2E 必须声明浏览器 env/组件、匹配的 boundary、why_e2e、步骤和具体预期；非 smoke 必须有 trigger_paths。每个 expected 必须引用存在的步骤或断言，deferred 必须有原因、owner 与 target_phase。
+>
+> `scenarios parse --quality` 检查语义，`design lint` 检查设计 ID 闭环，`acceptance manifest --verify-plan` 还检查 Spec Gate 与真实测试登记/收集。start 按当前 TASK 的 E2E 与全局 smoke 生成 e2e_plan，不额外扩大本任务验收范围。收集通过不能替代真实执行证据；配置示例见工具文档 `docs/acceptance-contract.md`。

package/src/core/code-flow/validation.yml

@@ -1,6 +1,7 @@
 # validators 在每次 Stop 按“会话内编辑过的文件”匹配执行（quality_loop.stop_check）。
-# 全量测试 / e2e 等慢命令标 `heavy: true`：Stop 每轮跳过，任务 finish 自动执行
-# 一次，也可显式运行 /cf-validate；避免每个任务都重跑多遍。
+# 全量测试 / e2e 等慢命令标 `heavy: true`：Stop 与任务 finish 都跳过（deferred_heavy），
+# 只由需求终验 verify-e2e / 归档与显式 /cf-validate 全量执行一次；结果按工作树内容指纹
+# 缓存，同一内容不会重复执行。
 validators:
     - name: "Python 语法检查"
       trigger: "**/*.py"
@@ -12,24 +13,28 @@ validators:
       trigger: "**/*.{ts,tsx}"
       command: "npx tsc --noEmit"
       timeout: 30000
+      skip_if_missing: true  # 未安装 typescript 时跳过（degrade 记录），不阻断
       on_fail: "检查类型定义，参见 specs/frontend/quality-standards.md"
 
     - name: "Vue 类型检查"
       trigger: "**/*.vue"
       command: "npx vue-tsc --noEmit"
       timeout: 30000
+      skip_if_missing: true
       on_fail: "检查 Vue 组件类型定义，参见 specs/frontend/component-specs.md"
 
     - name: "ESLint"
       trigger: "**/*.{ts,tsx,js,jsx,vue}"
       command: "npx eslint {files}"
       timeout: 15000
+      skip_if_missing: true
       on_fail: "运行 npx eslint --fix 自动修复，参见 specs/frontend/quality-standards.md"
 
     - name: "Stylelint"
       trigger: "**/*.{css,scss,less}"
       command: "npx stylelint {files}"
       timeout: 15000
+      skip_if_missing: true
       on_fail: "运行 npx stylelint --fix 自动修复，参见 specs/frontend/component-specs.md"
 
     - name: "前端单元测试"
@@ -43,11 +48,12 @@ validators:
       trigger: "**/*.py"
       command: "python3 -m mypy {files}"
       timeout: 30000
+      skip_if_missing: true  # 未安装 mypy 时跳过（degrade 记录），新项目不再被阻断
       on_fail: "检查类型注解，参见 specs/backend/code-quality-performance.md"
 
     - name: "Pytest"
       trigger: "**/*.py"
       command: "python3 -m pytest --tb=short -q"
-      timeout: 60000
+      timeout: 600000
       heavy: true
       on_fail: "测试失败，检查断言和 mock 是否需要更新"

package/src/migrate/runtime.js

@@ -0,0 +1,213 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const runtime = require('../runtime');
+const pkg = require('../../package.json');
+
+function guardVersion(root) {
+  const version = fs.readFileSync(path.join(root, '.code-flow/.version'), 'utf8').trim();
+  if (!/^\d+\.\d+\.\d+$/.test(version)) throw new Error(`Invalid installed runtime version: ${version}`);
+  const installed = version.split('.').map(Number);
+  const target = pkg.version.split('.').map(Number);
+  for (let index = 0; index < 3; index++) {
+    if (installed[index] > target[index]) throw new Error(`Refusing runtime downgrade from ${version} to ${pkg.version}; update the CLI.`);
+    if (installed[index] < target[index]) return;
+  }
+}
+
+function walk(root, directory = '') {
+  const target = path.join(root, directory);
+  if (!fs.existsSync(target)) return [];
+  return fs.readdirSync(target, { withFileTypes: true }).flatMap(entry => {
+    if (entry.name === '__pycache__') return [];
+    const relative = path.join(directory, entry.name);
+    return entry.isDirectory() ? walk(root, relative) : [relative];
+  });
+}
+
+function platforms(root) {
+  const markers = { claude: '.claude/commands/cf-init.md', codex: '.agents/skills/cf-init/SKILL.md',
+    costrict: '.costrict/commands/cf-init.md', opencode: '.opencode/commands/cf-init.md' };
+  const found = Object.entries(markers).filter(([, marker]) => fs.existsSync(path.join(root, marker))).map(([name]) => name);
+  if (!found.length) throw new Error('No installed platform found; run code-flow init first.');
+  return found;
+}
+
+function inputs(root, installed) {
+  const core = path.join(__dirname, '../core/code-flow');
+  const files = [...Object.keys(runtime.artifactSources(installed)), ...walk(core).map(file => `.code-flow/${file}`),
+    '.code-flow/scripts/cf_codex_user_prompt_hook.py',
+    '.code-flow/.version', '.code-flow/.adapter-versions.json', '.code-flow/.runtime-install.json',
+    '.code-flow/.gitignore', 'AGENTS.md', 'CLAUDE.md', 'opencode.json', '.codex/config.toml',
+    ...Object.keys(runtime.hookContracts(installed))];
+  return [...new Set(files)].filter(file => fs.existsSync(path.join(root, file)));
+}
+
+function copyFile(root, target, relative) {
+  const destination = path.join(target, relative);
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  fs.copyFileSync(path.join(root, relative), destination);
+}
+
+function writeJson(file, value) {
+  fs.writeFileSync(`${file}.tmp`, JSON.stringify(value, null, 2) + '\n');
+  fs.renameSync(`${file}.tmp`, file);
+}
+
+function staleScripts(root, installed) {
+  // 0.9 moved the flat cf_*.py implementation modules under codeflow/{hooks,cli};
+  // upgrades must remove the old flat files, keeping the 22 path-frozen shims.
+  const current = new Set(Object.keys(runtime.artifactSources(installed)));
+  return walk(root, '.code-flow/scripts')
+    .filter(file => file.endsWith('.py'))
+    .filter(file => !current.has(file.replace(/\\/g, '/')));
+}
+
+function prepare(root, locked = false) {
+  guardVersion(root);
+  const installed = platforms(root);
+  const id = `runtime-${Date.now()}-${process.pid}`;
+  const workspace = path.join(root, '.code-flow/migrations', id);
+  const staging = path.join(workspace, 'staging');
+  fs.mkdirSync(staging, { recursive: true });
+  fs.mkdirSync(path.join(workspace, 'backup'));
+  const stale = staleScripts(root, installed);
+  const original = [...new Set([...inputs(root, installed), ...stale])];
+  const sources = Object.fromEntries(original.map(file => [file, runtime.digest(path.join(root, file))]));
+  const journal = { schema_version: 1, id, root, platforms: installed,
+    status: 'staging', sources, hashes: {}, deletions: [], written: [] };
+  writeJson(path.join(workspace, 'journal.json'), journal);
+  if (locked) writeJson(path.join(root, '.code-flow/.runtime-migration.lock/owner.json'), { pid: process.pid, id });
+  for (const relative of original) {
+    copyFile(root, staging, relative);
+    copyFile(root, path.join(workspace, 'backup'), relative);
+  }
+  writeJson(path.join(staging, '.runtime-stage.json'), { root, id });
+  for (const platform of installed) {
+    const result = spawnSync(process.execPath, [path.join(__dirname, '../cli.js'), 'init', `--platform=${platform}`], {
+      cwd: staging, encoding: 'utf8', env: { ...process.env, CODE_FLOW_RUNTIME_STAGE: staging },
+    });
+    if (result.error || result.status !== 0) throw new Error(`Runtime staging failed: ${result.error || result.stderr || result.stdout}`);
+  }
+  for (const relative of stale) fs.rmSync(path.join(staging, relative), { force: true });
+  runtime.verify(staging);
+  const targets = walk(staging).filter(file => file !== '.runtime-stage.json' && !file.startsWith('.code-flow/backups/'));
+  const hashes = Object.fromEntries(targets.map(file => [file, runtime.digest(path.join(staging, file))]));
+  journal.deletions = original.filter(file => !fs.existsSync(path.join(staging, file)));
+  journal.hashes = hashes;
+  journal.status = 'prepared';
+  writeJson(path.join(workspace, 'journal.json'), journal);
+  return { workspace, journal, staging };
+}
+
+function restore(workspace, journal) {
+  const order = [...journal.written].reverse();
+  for (const relative of order) {
+    const target = path.join(journal.root, relative);
+    const backup = path.join(workspace, 'backup', relative);
+    if (fs.existsSync(backup)) copyFile(path.join(workspace, 'backup'), journal.root, relative);
+    else fs.rmSync(target, { force: true });
+  }
+  journal.status = 'rolled_back';
+  writeJson(path.join(workspace, 'journal.json'), journal);
+  return { status: journal.status, migration_id: journal.id };
+}
+
+function apply(root) {
+  let repairReason;
+  try {
+    runtime.verify(root, true);
+    return { status: 'already_migrated' };
+  } catch (error) {
+    repairReason = error.message;
+  }
+  const { workspace, journal, staging } = prepare(root, true);
+  try {
+    for (const [relative, hash] of Object.entries(journal.sources)) {
+      if (runtime.digest(path.join(root, relative)) !== hash) throw new Error(`Source changed during staging: ${relative}`);
+    }
+    journal.status = 'applying';
+    writeJson(path.join(workspace, 'journal.json'), journal);
+    const targets = Object.keys(journal.hashes).filter(file => file !== '.code-flow/.version');
+    for (const relative of journal.deletions) {
+      journal.written.push(relative);
+      writeJson(path.join(workspace, 'journal.json'), journal);
+      fs.rmSync(path.join(root, relative));
+    }
+    targets.push('.code-flow/.version');
+    for (const relative of targets) {
+      if (!journal.sources[relative] && fs.existsSync(path.join(root, relative))) throw new Error(`New target appeared: ${relative}`);
+      if (runtime.digest(path.join(staging, relative)) !== journal.hashes[relative]) throw new Error(`Staging drift: ${relative}`);
+      journal.written.push(relative);
+      writeJson(path.join(workspace, 'journal.json'), journal);
+      copyFile(staging, root, relative);
+    }
+    runtime.verify(root, true);
+    journal.status = 'committed';
+    writeJson(path.join(workspace, 'journal.json'), journal);
+    return { status: journal.status, migration_id: journal.id, platforms: journal.platforms, repair_reason: repairReason };
+  } catch (error) {
+    const result = restore(workspace, journal);
+    return { ...result, error: error.message };
+  }
+}
+
+function rollback(root, id) {
+  if (!/^runtime-\d+-\d+$/.test(id)) throw new Error('Invalid runtime migration id.');
+  const workspace = path.join(root, '.code-flow/migrations', id);
+  const journal = JSON.parse(fs.readFileSync(path.join(workspace, 'journal.json'), 'utf8'));
+  if (journal.root !== root) throw new Error('Migration belongs to a different project.');
+  if (journal.status === 'rolled_back') return { status: 'rolled_back', migration_id: id };
+  if (journal.status === 'committed') {
+    for (const [relative, hash] of Object.entries(journal.hashes)) {
+      if (runtime.digest(path.join(root, relative)) !== hash) throw new Error(`Rollback would overwrite subsequent changes: ${relative}`);
+    }
+  }
+  return restore(workspace, journal);
+}
+
+function withLock(root, values) {
+  const lock = path.join(root, '.code-flow/.runtime-migration.lock');
+  try {
+    fs.mkdirSync(lock);
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    const owner = JSON.parse(fs.readFileSync(path.join(lock, 'owner.json'), 'utf8'));
+    let live = true;
+    try { process.kill(owner.pid, 0); } catch (signalError) {
+      if (signalError.code !== 'ESRCH') throw signalError;
+      live = false;
+    }
+    if (live) throw new Error('Another runtime migration is running.');
+    if (values[0] !== '--rollback' || values[1] !== owner.id) {
+      throw new Error(`Interrupted migration; run code-flow migrate --runtime --rollback ${owner.id}`);
+    }
+    fs.rmSync(lock, { recursive: true });
+    fs.mkdirSync(lock);
+  }
+  writeJson(path.join(lock, 'owner.json'), { pid: process.pid, id: '' });
+  try {
+    return values[0] === '--apply' ? apply(root) : rollback(root, values[1]);
+  } finally {
+    fs.rmSync(lock, { recursive: true });
+  }
+}
+
+function run(root, values) {
+  if (values.length === 1 && values[0] === '--dry-run') {
+    const { workspace, journal } = prepare(root);
+    fs.rmSync(path.join(workspace, 'staging'), { recursive: true });
+    fs.rmSync(path.join(workspace, 'backup'), { recursive: true });
+    journal.status = 'previewed';
+    writeJson(path.join(workspace, 'journal.json'), journal);
+    return { status: journal.status, migration_id: journal.id, platforms: journal.platforms,
+      files: Object.keys(journal.hashes), apply: 'code-flow migrate --runtime --apply' };
+  }
+  if (values.length === 1 && values[0] === '--apply') return withLock(root, values);
+  if (values.length === 2 && values[0] === '--rollback') return withLock(root, values);
+  throw new Error('Choose --dry-run, --apply, or --rollback <id>.');
+}
+
+module.exports = { run };

package/src/migrate/spec-workflow.js

@@ -5,7 +5,7 @@ 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");
+const PREFLIGHT = path.join(__dirname, "../core/code-flow/scripts/codeflow/spec/cf_spec_migrate.py");
 
 function walkFiles(root, directory = root) {
   const files = [];
@@ -172,7 +172,12 @@ function rollback(planPath, error = "requested") {
   const journal = readJson(locations.journal);
   try {
     restoreBackup(plan, locations, journal.manifest || { targets: [] });
+    // A rolled-back plan must be re-appliable: stale staging content makes the
+    // next `stage` refuse ("staging root must be a pre-created empty directory").
+    if (fs.existsSync(locations.staging)) fs.rmSync(locations.staging, { recursive: true, force: true });
+    fs.mkdirSync(locations.staging, { recursive: true });
     journal.error = String(error);
+    journal.operations = [];
     persistJournal(locations.journal, journal, "rolled_back");
     return { status: "rolled_back", migration_id: plan.migration_id };
   } catch (restoreError) {
@@ -204,6 +209,16 @@ function recoverCommitting(plan, journal, locations, options) {
 function apply(planPath, options = {}) {
   const plan = readJson(planPath);
   const locations = journalPaths(planPath);
+  // Guard: a plan carries an absolute project_root; applying a plan from a
+  // different project (e.g. a copy or a stale path) would hash-check and
+  // mutate that other project instead of cwd. The CLI always passes
+  // projectRoot; direct library callers keep the previous behavior.
+  if (options.projectRoot) {
+    const expectedRoot = fs.realpathSync(options.projectRoot);
+    if (fs.realpathSync(plan.project_root) !== expectedRoot) {
+      throw new Error(`migration plan targets ${plan.project_root}, not ${expectedRoot}`);
+    }
+  }
   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);