@house365/comate 0.9.5 → 0.9.7

package/bin/init.mjs

@@ -256,9 +256,9 @@ function pruneDeprecatedSkills(
   return removed;
 }
 
-// True only when the pinned `skills` dependency resolves locally. A postinstall
-// must never reach the network, so this gates syncComateSkills: if resolution
-// fails we skip rather than let skillsInvocation fall back to `npx skills@latest`.
+// True only when the pinned `skills` dependency resolves locally. This keeps a
+// postinstall from downloading an arbitrary CLI through the npx fallback. The
+// CLI may still fetch declared skill sources such as obra/superpowers.
 function skillsResolvesLocally(pkgRoot) {
   try {
     createRequire(join(pkgRoot, 'package.json')).resolve('skills/package.json');
@@ -268,19 +268,40 @@ function skillsResolvesLocally(pkgRoot) {
   }
 }
 
-// Copy comate's own skills into ~/.agents/skills via the bundled skills CLI —
-// the exact command `comate init` runs, so the layout is identical. Local-only:
-// skips (never goes to network) when the skills dep can't be resolved, leaving
-// `comate init` as the fallback. Returns { ok, skipped }.
-function syncComateSkills(pkgRoot, { home = process.env.HOME ?? process.env.USERPROFILE ?? '', runner = run } = {}) {
+// Install the user-level skills needed by comate via the bundled skills CLI.
+// Superpowers is fetched only when its marker is absent; comate's bundled skills
+// are always refreshed on npm upgrades. `comate init` remains the diagnostic
+// fallback when this best-effort postinstall sync cannot complete.
+function syncComateSkills(
+  pkgRoot,
+  {
+    home = process.env.HOME ?? process.env.USERPROFILE ?? '',
+    runner = run,
+    exists = existsSync,
+  } = {},
+) {
   if (!skillsResolvesLocally(pkgRoot)) return { ok: false, skipped: 'no-local-cli' };
-  const r = runner(
+
+  const superpowersMarker = join(home, '.agents', 'skills', 'using-superpowers', 'SKILL.md');
+  let superpowers = { ok: true };
+  if (!exists(superpowersMarker)) {
+    superpowers = runner(
+      skillsInvocation(pkgRoot, ['add', 'obra/superpowers', '-g', '-y']),
+      SKILLS_TIMEOUT_MS,
+      { quiet: true },
+    );
+  }
+
+  const comate = runner(
     skillsInvocation(pkgRoot, ['add', pkgRoot, '--skill', '*', '-g', '-y']),
     SKILLS_TIMEOUT_MS,
     { quiet: true },
   );
-  const landed = existsSync(join(home, '.agents', 'skills', 'comate', 'SKILL.md'));
-  return { ok: r.ok && landed, skipped: null };
+  const comateMarker = join(home, '.agents', 'skills', 'comate', 'SKILL.md');
+  return {
+    ok: superpowers.ok && exists(superpowersMarker) && comate.ok && exists(comateMarker),
+    skipped: null,
+  };
 }
 
 export {

package/docs/COMATE_MANUAL.md

@@ -368,7 +368,7 @@ bash "$COMATE" doctor
 1. **进入验证与分类**：检查脏工作树，运行 guard，运行构建/测试命令。将失败分类为 SPEC、REGRESSION、COVERAGE、SECURITY、STYLE、OTHER。
 2. **验证失败决策（决策点 4）**：验证失败时，暂停让用户决定：全部修复 / 逐项处理 / 接受偏差。包括 Spec 漂移处理（设计文档与 delta spec 冲突）。CRITICAL 级别的失败必须修复。仅在用户选择修复后才执行 `state transition <name> verify-fail` 并返回 build。
 3. **验证通过**：全部通过或用户接受偏差后，写入 `verify_result: pass`，将验证报告路径写入 `verification_report`。
-4. **分支收尾（决策点 5）**：调用 `superpowers:finishing-a-development-branch`。暂停让用户选择：本地合并 / 推送为 PR / 保留分支 / 丢弃工作。仅在用户选择且对应操作完成后写入 `branch_status: handled`。
+4. **分支收尾（决策点 5）**：调用 `superpowers:finishing-a-development-branch`。暂停让用户选择：本地合并 / 推送为 PR / 保留分支 / 丢弃工作。前三项完成后写 `branch_status: handled`；丢弃写 `branch_status: discarded` 并停止，不得验证通过或归档。
 5. **退出**：运行 `bash $COMATE guard <name> verify --apply`，通过后自动推进到 archive。
 
 ### 5.5 阶段 5：归档（/comate-archive）
@@ -432,7 +432,7 @@ bash "$COMATE" doctor
 | 需新增 capability | 超出局部优化 |
 | 需 delta spec | 影响已有规格 |
 
-暂停等待用户确认升级（决策点 6）。用户确认后先 `state set <name> workflow full`，然后进入完整流程。
+提问前写 `phase_step: fix.upgrade-awaiting`。用户确认后执行 `state transition <name> fix-upgrade`，原子清理 fix 默认值并进入 design。
 
 ---
 
@@ -445,14 +445,15 @@ bash "$COMATE" doctor
 | 字段 | 含义 |
 |-------|---------|
 | `schema_version` | 状态文件格式版本（当前：1） |
-| `workflow` | `full` / `fix` |
-| `phase` | `open` / `design` / `build` / `verify` / `archive` |
+| `workflow` | `full` / `fix` |
+| `phase` | `open` / `design` / `build` / `verify` / `archive` |
+| `phase_step` / `phase_step_data` | 当前阶段内的恢复标记和附加数据；阶段转换时自动清空 |
 | `build_mode` | `subagent-driven-development` / `executing-plans` / `direct` |
 | `isolation` | `branch` / `worktree`（必须在 build->verify 之前设置） |
 | `verify_mode` | `light` / `full`（由规模评估写入） |
 | `verify_result` | `pending` / `pass` / `fail` |
 | `verification_report` | 验证报告路径，在 verify-pass 前必须指向真实文件 |
-| `branch_status` | `pending` / `handled` |
+| `branch_status` | `pending` / `handled` / `discarded` |
 | `handoff_context` / `handoff_hash` | 设计交接包路径 + 源文件 sha256 |
 | `impl_context` / `impl_hash` | 构建交接包路径 + plan+tasks sha256 |
 | `direct_override` | 对于使用 `direct` 的 full 流程必须显式为 `true` |
@@ -486,9 +487,9 @@ bash "$COMATE" doctor
 
 **4. 验证失败决策**（verify）：验证失败时，暂停让用户决定：全部修复 / 逐项处理 / 接受偏差。包括 Spec 漂移处理（设计文档与 delta spec 冲突）。CRITICAL 级别的失败必须修复。仅在用户选择修复后才执行 `state transition <name> verify-fail` 并返回 build。
 
-**5. 分支收尾选择**（verify/收尾开发分支）：暂停让用户选择：本地合并 / 推送为 PR / 保留分支 / 丢弃工作。仅在用户选择且对应操作完成后写入 `branch_status: handled`。
+**5. 分支收尾选择**（verify/收尾开发分支）：暂停让用户选择：本地合并 / 推送为 PR / 保留分支 / 丢弃工作。前三项成功后写 `handled`；丢弃写 `discarded` 并终止当前流程。
 
-**6. 预设升级确认**（fix -> full）：当升级条件满足时（bug 模式 3+ 文件等，调整模式 5+ 文件等），暂停让用户确认升级到完整的 `/comate`。不要直接进入 `/comate-design`，不要自动填充设计文档。用户确认后，先 `state set <name> workflow full`，然后进入完整流程。
+**6. 预设升级确认**（fix -> full）：当升级条件满足时，先写 `fix.upgrade-awaiting` 再暂停确认。确认后执行 `state transition <name> fix-upgrade`，由脚本清理 fix 默认构建选项并进入 design。
 
 **7. 构建范围扩展**（build）：如果实现过程揭示需要重新设计或拆分为新变更，暂停。判定标准：基于初始 tasks.md 任务数，新增任务超过总数一半（50% 阈值）视为超出范围。询问用户是否拆分。中等规模（接口变更、新组件）：确认后加载 `superpowers:brainstorming` 更新设计。大规模（新能力）：确认后使用 `/comate-open` 创建独立变更。
 
@@ -552,7 +553,8 @@ bash "$COMATE" doctor
 | `state <name> init <full|fix>` | 初始化 `.comate.yaml` |
 | `state <name> set <key> <value>` | 设置单个状态字段 |
 | `state <name> get <key>` | 读取单个状态字段 |
-| `state <name> transition <event>` | 执行状态转换 |
+| `state <name> transition <event>` | 执行状态转换 |
+| `dependency <name> archived` | 严格检查指定 change 已归档且状态为 `archived: true` |
 | `state <name> check <phase> [--json]` | 检查阶段进入条件 |
 | `state <name> recover <phase>` | 从文件状态推断并修复 `.comate.yaml` |
 | `state <name> scale` | 评估变更规模并写入 `verify_mode` |
@@ -592,7 +594,7 @@ bash "$COMATE" doctor
 |---------|-------------|
 | `gate <prd> review` | 建/刷新 gate.yaml，钉当前 PRD sha256，回显评审报告路径。PRD 变了则状态重置为 `reviewing` |
 | `gate <prd> set <field> <value>` | 写字段：`score` / `blocking_open` / `gate_status` 等 |
-| `gate <prd> pass [--tbd]` | 置 `passed`（`--tbd` 置 `passed-with-tbd`）。硬校验 `blocking_open=0` 且评审报告非空，并重钉哈希 |
+| `gate <prd> pass [--tbd]` | 校验评分、拆分映射和报告。普通 pass 要求 `blocking_open=0`；`--tbd` 要求至少一个经用户接受的未解决阻断项 |
 | `gate <prd> spawned <change>` | 记录据此 PRD 扇出的 change（逗号拼接） |
 | `gate <prd> status [--json]` | 查状态；哈希漂移时自动判 `stale`（不改文件） |
 | `gate <prd> check` | comate-open 建 change 前的前置守卫。PASS 要求 gate 存在、状态 ∈ {passed, passed-with-tbd}、哈希未漂移；否则退出码 1 阻塞 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@house365/comate",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "comate —— SDD (规约驱动开发) 的 AI 开发编排器（Agent Skills）",
   "type": "module",
   "license": "MIT",

package/skills/comate/SKILL.md

@@ -16,24 +16,131 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 
 ### 自动阶段探测
 
-**Step 0：活跃 change 发现 + 意图探测**
-
-1. 先探测预设；命中 fix 条件则直接调用 `/comate-fix`，不进入普通 open 分支。
-2. 无预设命中时，运行 `openspec list --json` 获取所有活跃 change。
-
-**预设探测优先级最高**：
-- 用户明确描述 bug 修复或文案/配置/文档/prompt 小调整 + 满足 fix 条件 → 直接调用 `/comate-fix`
-- **用户输入指向一份原始 PRD**（给了 PRD 路径/编号，或明确说「这是 PRD / 从这份需求文档开始」，典型路径 `docs/knowledge-base/**/PRD-*.md`）**且无对应活跃 change** → 直接调用 `/comate-gate`（阶段 0：先过门禁，再拆分建 change）。不要直接调 `/comate-open`——PRD 必须先过质量门禁。
-- 无预设命中 → 按下表处理
-
-| 活跃 change | 用户输入 | 行为 |
-|-------------|----------|------|
-| 无 | 指向原始 PRD | → 调用 `/comate-gate` |
-| 无 | 非预设输入 | → 调用 `/comate-open` |
-| 恰好 1 个 | `/comate <描述>` | → **询问**：继续该 change 还是新建 |
-| 多个 | `/comate <描述>` | → **询问**：继续已有还是新建；继续则列出供选择 |
-| 恰好 1 个 | `/comate` 无描述 | → 自动选中，进入 Step 1 |
-| 多个 | `/comate` 无描述 | → 列出 change 供用户选择 |
+**Step 0：活跃 change 发现 + 决策状态优先检查**
+
+<CRITICAL>
+**执行顺序不可颠倒**：先识别用户是否明确要求新建 change；否则读取状态检查明确的 `*-awaiting` 决策标记，再做普通意图过滤和 change 匹配。
+若用户正在回答已持久化的决策问题（如"worktree + TDD"、"确认方案A"），直接路由到对应子 skill。
+</CRITICAL>
+
+1. **活跃 change 快速发现**：
+   
+   运行 `openspec list --json` 获取所有活跃 change。
+   
+   - **无活跃 change** → 跳到步骤 3（意图快速过滤 + 预设探测）
+   - **有活跃 change** → 继续步骤 2
+
+2. **待决策状态检查**（防止决策答复被误判为新任务）：
+   
+   a. **确定目标 change**：
+      - 恰好 1 个活跃 change → 自动选中
+      - 多个活跃 change 且用户指定了 change 名称（`/comate <name>`）→ 选中该 change
+      - 多个活跃 change 且用户未指定 → **暂存待选列表，继续检查**（稍后在步骤 3.2 处理）
+   
+   b. **读取状态（若已确定目标 change）**：
+      
+      读取 `openspec/changes/<name>/.comate.yaml`，获取 `phase` 和 `phase_step`。
+   
+   c. **检查是否在等待决策**：
+      
+      只有 `phase_step` 是当前阶段的明确等待标记时，才说明子 skill 正在等待用户答复：
+      - `open.review-awaiting`
+      - `design.approval-awaiting`
+      - `build.options-awaiting` / `build.scope-awaiting` / `fix.upgrade-awaiting`
+      - `verify.failure-awaiting` / `verify.spec-drift-awaiting` / `verify.branch-awaiting`
+
+      兼容 `bd16c0f` 产生的活跃状态：仅在 phase 对应时，把 `open:4`、`design:1b`、`build:2` 分别视为上述等待标记；恢复后立即写入新格式。其它旧值只是普通进度。
+
+      普通进度（如 `design.brainstorm-complete`）、已确认状态和依赖阻塞状态都**不是**待决策，不得抢占用户的新请求。用户明确说“新建 change”时也优先按新建意图处理。
+      
+      **立即路由到对应子 skill**（根据 `phase` 字段）：
+      - `phase: open` → 调用 `/comate-open`
+      - `phase: design` → 调用 `/comate-design`
+      - `phase: build` → 调用 `/comate-build`
+      - `phase: verify` → 调用 `/comate-verify`
+      - `phase: archive` → 调用 `/comate-archive`
+      
+      子 skill 的**幂等性检查**会：
+      1. 读取 `phase_step` 的值
+      2. 验证该步骤是否与当前 `phase` 匹配
+      3. 恢复到正确的步骤（跳过已完成的步骤，直接进入下一步）
+      
+      **结束 Step 0，不执行后续逻辑**。
+   
+   d. **若没有匹配当前阶段的等待标记**：
+      
+      说明没有未完成的决策点，继续步骤 3（意图过滤）。
+
+3. **意图快速过滤 + 幂等性匹配**：
+
+   3.1. **意图快速过滤**（仅当步骤 2 未命中时执行）：
+
+   先检查用户输入是否**明确表达了希望进入某个特定阶段**。如果用户没有明确指示，则无条件自动探测当前阶段，不询问不推测。
+
+   **明确意图的识别规则**：用户消息中包含以下**动作关键词 + 阶段名**的直接组合之一时，才算明确意图：
+   
+   | 阶段 | 明确意图的关键词组合（任一命中即算） |
+   |------|-------------------------------------|
+   | open | "开题"/"创建 change"/"新建 change"/"起草 proposal" |
+   | design | "设计"/"写设计文档"/"brainstorming"/"开始设计" |
+   | build | "实施"/"开始构建"/"执行计划"/"写代码"/"开始 build" |
+   | verify | "验证"/"检查实现"/"运行测试"/"开始 verify" |
+   | archive | "归档"/"完成收尾"/"合并 delta spec"/"开始 archive" |
+
+   **不算明确意图的情况**（这些都应自动探测，不询问）：
+   - 仅提及问题、需求、想法，无阶段动作词："修复这个 bug" / "优化性能" / "加个功能"
+   - 仅描述当前状态："设计做完了" / "代码写好了" / "测试通过了"
+   - 询问式："现在该做什么" / "下一步是什么" / "继续"
+   - 澄清式："刚才的设计有问题" / "build 阶段遇到错误"
+   - **决策答复**："worktree + TDD" / "选择方案 A" / "确认" / "继续构建"（这些应在步骤 2 被拦截）
+
+   **过滤结果**：
+   - **明确意图命中** → 直接跳到对应阶段的 skill（不运行后续步骤）
+   - **无明确意图** → 继续步骤 3.2
+
+   3.2. **活跃 change 匹配**（防止重复创建 change）：
+   
+   **前置条件**：有活跃 change 且用户输入无明确意图。
+   
+   **处理逻辑**：
+   
+   a. **用户输入仅为 `/comate` 无任何描述**：
+      - 恰好 1 个活跃 change → 已在步骤 2 选中，进入 Step 1
+      - 多个活跃 change → 列出所有 change 供用户选择，选中后进入 Step 1
+   
+   b. **用户输入包含任务描述但未指定 change 名称**（`/comate <描述>`）：
+      - **关键幂等检查**（防止重复创建 change）：
+        1. 遍历所有活跃 change
+        2. 对每个 change，读取 `proposal.md` 和 `specs/*/spec.md`
+        3. 检查用户描述是否与该 change 的需求高度匹配（关键词重叠、问题域相同、目标一致）
+        4. **若找到匹配的 change**：
+           - 自动选中该 change
+           - 说明「检测到您的描述与活跃 change <name> 的需求匹配，将继续该 change」
+           - 进入 Step 1（读取该 change 的状态）
+        5. **若所有 change 都不匹配**：
+           - **AskUserQuestion 询问**：「检测到 {N} 个活跃 change：{列表及简要描述}。您的任务是：继续某个已有 change，还是新建 change？」
+           - 选项 1：「继续已有 change」→ 让用户选择具体哪个 change，进入 Step 1
+           - 选项 2：「新建 change」→ 进入步骤 4（预设探测）
+
+4. **预设探测**（决定新 change 的入口）：
+
+   当确定需要新建 change 时（无活跃 change，或用户选择新建），按以下优先级探测：
+   
+   a. **fix 预设**：
+      - 用户明确描述 bug 修复或文案/配置/文档/prompt 小调整
+      - 且满足 fix 条件（见 `/comate-fix` skill）
+      - → 直接调用 `/comate-fix`，不进入普通 open 分支
+   
+   b. **gate 预设**（原始 PRD 入口）：
+      - 用户输入指向一份原始 PRD（给了 PRD 路径/编号，或明确说「这是 PRD / 从这份需求文档开始」）
+      - 典型路径：`docs/knowledge-base/**/PRD-*.md`
+      - **且无对应活跃 change**
+      - → 直接调用 `/comate-gate`（阶段 0：先过门禁，再拆分建 change）
+      - **不要直接调 `/comate-open`**——PRD 必须先过质量门禁
+   
+   c. **普通 open**（默认）：
+      - 无预设命中
+      - → 调用 `/comate-open`
 
 <IMPORTANT>
 用户选择「新建 change」时，**必须调用 `/comate-open`**，不要直接调 `/opsx:new`。
@@ -41,10 +148,26 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 直接调 `/opsx:new` 会导致 `.comate.yaml` 缺失，破坏后续阶段探测。
 </IMPORTANT>
 
-**Step 1：读取 `.comate.yaml` 状态元数据**
+**Step 1：读取 `.comate.yaml` 状态元数据**（仅在 Step 0 未直接路由时执行）
 
 优先读 `openspec/changes/<name>/.comate.yaml`。不可用时回落到 `openspec status --change "<name>" --json`、`tasks.md`、`docs/superpowers/` 文件检查。
 
+**关键字段**：
+- `phase`：当前阶段（`open` / `design` / `build` / `verify` / `archive`）
+- `phase_step`：当前阶段内的步骤标记（如 `design.approval-awaiting`、`build.options-confirmed`）
+- `workflow`：流程类型（`full` / `fix`）
+- `build_mode`、`isolation`、`tdd_mode`：build 阶段的决策字段
+- `verify_result`：验证结果（`pending` / `pass` / `fail`）
+
+**phase_step 语义说明**：
+
+`phase_step` 记录**当前阶段**内的步骤，用于断点恢复和幂等性检查：
+- 非空值表示"已完成到该步骤"，恢复时从**下一步**开始
+- `*-awaiting` 表示正在等待用户答复，只有这类值触发决策优先路由
+- `*-confirmed` 表示用户已确认的决策点
+- `build.blocked-by-<dependency>` 表示被依赖阻塞，但不是等待当前用户决策
+- 空值或 `null` 表示该阶段尚未开始或已完成所有步骤
+
 **断点恢复规则**：
 - 每次上下文恢复都重跑 Step 0、Step 1；不要信任对话历史做阶段探测。
 - 有活跃 change 且工作树有未提交改动时，按 `comate/reference/dirty-worktree.md` 协议处理。
@@ -53,6 +176,10 @@ agent 做决策只需读本节，其余参见末尾「参考附录」。决策
 - 若 `phase: open` 但 proposal/design/tasks 已完成，先 `bash "$COMATE" guard <name> open --apply` 修复状态，再继续探测。
 - 若 `phase: archive`，只调用 `/comate-archive`；归档成功后 change 移入 archive 目录，不要再对旧活跃目录跑 guard。
 
+**phase_step 生命周期**：
+
+`phase_step` 严格属于当前阶段。所有 `state transition` 在切换 `phase` 时原子清空 `phase_step` 和 `phase_step_data`。禁止跨阶段保留或比较步骤编号；跨阶段事实必须记录在专用字段或落盘产物中。
+
 **Step 2：阶段判定**（按顺序检查，首个命中者生效）
 
 1. `archived: true` 或 change 已移入 archive → 流程完成
@@ -148,9 +275,10 @@ bash "$COMATE" state   <name> validate
 bash "$COMATE" guard   <name> <phase> [--apply] [--json]
 bash "$COMATE" handoff <name> <design|build> --write [--full]
 bash "$COMATE" sources <name> track <file...> [--note <text>]
-bash "$COMATE" sources <name> check | list
-bash "$COMATE" sources find <file>
-bash "$COMATE" archive <name> [--dry-run]
+bash "$COMATE" sources <name> check | list
+bash "$COMATE" sources find <file>
+bash "$COMATE" dependency <name> archived
+bash "$COMATE" archive <name> [--dry-run]
 bash "$COMATE" status
 bash "$COMATE" doctor
 ```
@@ -172,7 +300,7 @@ bash "$COMATE" doctor
 | `verify_mode` | `light` / `full`（由 scale 评估写入） |
 | `verify_result` | `pending` / `pass` / `fail` |
 | `verification_report` | 验证报告路径，verify-pass 前必须指向真实文件 |
-| `branch_status` | `pending` / `handled` |
+| `branch_status` | `pending` / `handled` / `discarded` |
 | `handoff_context` / `handoff_hash` | design 交接包路径 + 源文件 sha256 |
 | `impl_context` / `impl_hash` | build 交接包路径 + plan+tasks 的 sha256（防漂移） |
 | `direct_override` | full 流程用 `direct` 需显式 `true` |

package/skills/comate/reference/decision-points.md

@@ -61,11 +61,11 @@
    引用：`comate-verify` Step 1b、Step 2b 的 Spec 漂移处理。
 
 5. **分支收尾方式选择**（verify / finishing-a-development-branch）
-   暂停请用户选择：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。仅在用户选择且对应操作完成后，才写 `branch_status: handled`。
+   暂停请用户选择：本地合并 / 推送建 PR / 保持分支 / 丢弃工作。前三项操作成功后写 `branch_status: handled`；丢弃工作写 `branch_status: discarded` 并停止流程，禁止执行 verify guard 或归档。
    引用：`comate-verify` Step 3。
 
 6. **预设升级确认**（fix → full）
-   命中升级条件（见 `comate-fix` SKILL 的「升级条件」，bug 模式与调整模式各有阈值）时，暂停请用户确认升级为完整 `/comate`。不得直接进入 `/comate-design`，不得自动补 Design Doc。用户确认后先 `state set <name> workflow full` 再进入完整流程。
+   命中升级条件（见 `comate-fix` SKILL 的「升级条件」，bug 模式与调整模式各有阈值）时，先写 `phase_step: fix.upgrade-awaiting`，再暂停请用户确认。用户确认后执行原子转换 `state transition <name> fix-upgrade`，由脚本清除 fix 默认构建选项并进入 design。
    引用：`comate-fix`「升级条件」。
 
 7. **构建期范围扩张**（build）

package/skills/comate/scripts/comate-lib.sh

@@ -50,6 +50,8 @@ FIELD_ORDER=(
   schema_version
   workflow
   phase
+  phase_step
+  phase_step_data
   build_mode
   tdd_mode
   isolation
@@ -88,7 +90,7 @@ declare -A ENUMS=(
   [isolation]="branch worktree"
   [verify_mode]="light full"
   [verify_result]="pending pass fail"
-  [branch_status]="pending handled"
+  [branch_status]="pending handled discarded"
   [direct_override]="true false"
   [archived]="true false"
   [source_kind]="conversation file"
@@ -111,6 +113,8 @@ declare -A FREEFORM_KEYS=(
   [verify_command]=1
   [created_at]=1
   [verified_at]=1
+  [phase_step]=1
+  [phase_step_data]=1
 )
 
 # --- Path location ---