checkpoint

工作流检查点技能

概述

保存并修改持久化的工作流状态，使其在上下文自动摘要后仍能保留。

状态文件存储：任务详情、工作树位置、PR URL 和审查状态。此技能负责工作流状态的写入：初始化工作流、更新字段、转换阶段以及记录结构化交接。关于读取/恢复（中断后恢复、与 git 核对、验证工作流是否存在），请参阅 @skills/rehydrate/SKILL.md。

触发条件

在以下情况启用此技能：

• 启动新的工作流（ideate）
• 在工作流阶段之间转换
• 保存进度以便之后继续（checkpoint）

阶段转换

所有工作流类型的有效转换、守卫条件和先决条件均记录在 references/phase-transitions.md 中。**重要：**阶段变更与字段变更是分开的操作。当转换有守卫条件时，先使用 action: "update" 更新先决字段，再使用 action: "transition"——守卫会读取最新状态，因此更新会先于守卫求值生效。尝试通过 action: "update" 修改 phase 会返回 RESERVED_FIELD 错误，并指向 transition（见下文“保留字段”）。

架构发现

使用 exarchos_workflow({ action: "describe", actions: ["update", "init", "get"] }) 查询参数架构，使用 exarchos_workflow({ action: "describe", playbook: "feature" }) 查询阶段转换、守卫条件和操作手册指导。对于轻量级 oneshot 变体（其 implementing → synthesize|completed 选择状态由 synthesisPolicy 驱动），调用 exarchos_workflow({ action: "describe", playbook: "oneshot" })——oneshot 与 feature/debug/refactor 一样，都是一等操作手册。使用 exarchos_event({ action: "describe", eventTypes: ["workflow.transition", "task.completed"] }) 查询事件数据架构。

状态位置

工作流状态存储在 MCP 事件存储中，而非文件系统中。使用 exarchos_workflow get 读取状态，使用 exarchos_view pipeline 查找活跃工作流。默认情况下，pipeline 视图限定在当前仓库范围内——只显示调用方所在仓库的工作流；当响应中的 unscopedTotal 大于 page.total 时，其他仓库中的工作流会被隐藏——请使用 scope: "all" 重新查询以显示这些工作流。不要扫描 ~/.claude/workflow-state/*.state.json——该路径已废弃，可能包含过期数据或为空。

状态操作

关于完整的 MCP 工具签名、错误处理和反模式，请参阅 references/mcp-tool-reference.md。

初始化状态

在 ideate 开始时，使用 exarchos:exarchos_workflow 并设置 action: "init"，传入：

• featureId：工作流标识符（例如，"user-authentication"）
• workflowType：以下之一："feature"、"debug"、"refactor"、"oneshot"
• synthesisPolicy （可选，仅适用于 oneshot）：以下之一："always"、"never"、"on-request"（默认值为 "on-request"）——对非 oneshot 类型会被静默忽略

这会创建一个新的工作流状态条目。初始阶段取决于 workflowType：

• feature → 从 plan 阶段开始
• debug → 从 triage 阶段开始
• refactor → 从 explore 阶段开始
• oneshot → 从 plan 阶段开始

工作流类型一览

• feature — 完整流程 plan → plan-review → delegate → review → synthesize，适用于需要子 Agent 调度和审查的实际功能
• debug — triage → investigate → (thorough | hotfix)，适用于需要选择路径的 Bug 工作流
• refactor — explore → brief → (polish | overhaul)，适用于代码改进；小规模改进使用 polish，多任务改进使用 overhaul
• oneshot — plan → implementing → (completed | synthesize)，适用于简单变更；默认直接提交，也可选择 PR 路径，该路径通过 synthesisPolicy 驱动的选择状态守卫和 synthesize.requested 事件来确定

关于轻量级变体的完整说明，包括选择状态机制和 finalize_oneshot 触发条件，请参阅 @skills/oneshot/SKILL.md。

更新状态（仅字段）

使用 exarchos:exarchos_workflow，设置 action: "update"，并提供 featureId 和 updates。此操作仅修改非阶段字段——phase、workflowType、featureId、createdAt 和 version 为保留字段（见下文“保留字段”）。

• 设置制品路径：updates: { "artifacts.spec": "docs/specs/2026-01-05-feature.md" }
• 完成任务：不要使用 update。任务的门禁通过后，调用 exarchos:exarchos_orchestrate，并设置 action: "task_complete"；也可以让 settle 标记任务。只有 task_complete 和 settle 会将任务标记为已完成。
• 添加工作树：updates: { "worktrees.wt-001": { "branch": "feature/001-types", "taskId": "001", "status": "active" } }

工作树状态值：'active' | 'merged' | 'removed'

转换阶段

使用 exarchos:exarchos_workflow，设置 action: "transition"，并提供 featureId 和 target：

• 推进阶段：target: "delegate"

转换会经过 HSM 验证，并发出 workflow.transition 事件。受守卫条件控制的转换会读取最近一次 update 之后的状态，因此，守卫条件所依赖的任何 updates: {...} 都必须先写入。

编辑 tasks 数组

update（其 updates 参数）使用的点路径解析器只识别数字数组索引（tasks[0]、tasks[1]……）。不支持 tasks[id=T-001] 这类键控形式，现在会抛出带有明确说明的 INVALID_INPUT 错误——较早版本会静默写入错误的顶层键，并返回 success: true，但实际任务并未更改。支持以下三种模式：

1. 替换整个数组（在需要整体修订计划时使用此方式）：

   exarchos_workflow({
     action: "update",
     featureId: "<id>",
     updates: { tasks: [
       { id: "T-001", title: "...", status: "pending" },
       { id: "T-002", title: "...", status: "pending" },
     ]},
   })
   

2. 按数组索引编辑单个任务：

   exarchos_workflow({
     action: "update",
     featureId: "<id>",
     updates: { "tasks[0].status": "in_progress", "tasks[0].startedAt": "<ts>" },
   })
   

   首先读取 tasks（action: "get", query: "tasks"）以找到要编辑任务的索引，然后按该索引设置。不要以此方式将状态设为 "complete"：只有 task_complete 和 settle 会将任务标记为已完成。

3. 通过写入下一个空闲索引来追加新任务。如果数组当前长度为 N，则写入 tasks[N]：

   // Suppose tasks already contains T-001 and T-002 (length 2). To append:
   exarchos_workflow({
     action: "update",
     featureId: "<id>",
     updates: { "tasks[2]": { id: "T-003", title: "Follow-up", status: "pending" } },
   })
   

   解析器允许写入超出当前长度一个位置（MAX_ARRAY_GAP = 1）；如果写入位置超出更多（例如，数组长度为 2 时写入 tasks[5]），则会抛出 INVALID_INPUT。追加前请读取当前 tasks 的长度。

集成节点

何时更新状态

事件	状态更新
ideate 启动	对工作流执行 init（初始阶段为 plan）
编写设计与依据	update: { "artifacts.spec": "<path>" }（不进行阶段转换——plan 是初始阶段）
添加分解	update: { "artifacts.plan": "<path>", "tasks": [...] }，然后执行 transition target: "plan-review"
发现计划审查问题	update: { "planReview.gapsFound": true, "planReview.gaps": [...] }，自动循环回到计划阶段
计划审查通过	update: { "planReview.approved": true }，然后执行 transition target: "delegate"
分派任务	将任务的 status 设为 "in_progress"，并设置 startedAt
完成任务	不使用 update：由 task_complete 或 settle 将任务标记为已完成
创建工作树	添加到 worktrees 对象
完成审查	更新 reviews 对象
创建 PR	设置 artifacts.pr、synthesis.prUrl
PR 反馈	追加到 synthesis.prFeedback

Oneshot 专属状态更新

Oneshot 是一流的工作流类型，生命周期经过压缩，并提供可选的 PR 流程。下表与上方的功能工作流表对应。

阶段	状态更新	发出的事件
plan（oneshot）	oneshot.planSummary、artifacts.plan、可选的 oneshot.synthesisPolicy	workflow.transition
implementing（oneshot）	tasks[].status、artifacts.tests	task.*、可选的 synthesize.requested（通过 request_synthesize）
synthesize（oneshot）	synthesis.prUrl、artifacts.pr	workflow.transition、stack.submitted
completed（oneshot）	—	workflow.transition（转到 completed）

implementing → synthesize | completed 分支是一个选择状态，由 finalize_oneshot 解析；它会读取 synthesisOptedIn 保护条件 （synthesisPolicy + synthesize.requested 事件）。完整的选择加入机制请参阅 @skills/oneshot/SKILL.md。

自动状态更新

技能应在关键时刻更新状态：

ideate/SKILL.md：

After authoring the Design & Rationale section of the unified docs/specs/ artifact:
- `action: "update"` — `updates: { "artifacts.spec": "<path>" }`
  (no transition — `plan` is the initial phase; continue to decomposition in the same phase)

plan/SKILL.md：

After saving plan:
1. `action: "update"` — `updates: { "artifacts.plan": "<path>", "tasks": [...] }`
2. `action: "transition"` — `target: "plan-review"`

delegate/SKILL.md：

On task dispatch:
- Update task status to "in_progress"
- Add worktree to state if created

On task complete:
- Call task_complete after the gates of the task pass (it marks the task complete)
- Check if all tasks done, suggest checkpoint

状态架构

完整架构请参阅 docs/schemas/workflow-state.schema.json。

主要部分：

• version：架构版本（当前为 "1.1"）
• featureId：唯一的工作流标识符
• workflowType：必填。取值为 "feature"、"debug"、"refactor" 或 "oneshot"
• phase：当前工作流阶段
• artifacts：设计、计划和 PR 的路径
• tasks：包含状态的任务列表
• worktrees：活动的 git 工作树
• planReview：计划审查差异分析结果（gaps、approved）
• reviews：审查结果
• synthesis：合并/PR 状态

保留字段

exarchos:exarchos_workflow 在 action: "update" 时，会对两类路径返回 RESERVED_FIELD：

1. 顶层不可变键 — phase、workflowType、featureId、createdAt、version。在初始化时设置一次；之后不得直接修改。
2. 以下划线开头的路径 — 顶层键或任意片段以下划线 _ 开头的点分隔路径（例如 _version、_checkpoint.summary、_eventHints）。这些是投影或事件存储元数据。

替代写入路径：

• phase → 使用 action: "transition" 和 target: "<phase>" 调用 exarchos:exarchos_workflow。状态转换经过 HSM 验证，并会发出转换事件。
• 以下划线开头的路径 → 通过 exarchos:exarchos_event 使用 action: "append" 发出类型化事件（例如 checkpoint、state.patched）。下一次读取时，投影会将事件折叠到该字段中。
• workflowType、featureId、createdAt、version → 不可迁移。如果需要其他工作流类型，请初始化一个新工作流。

现在，RESERVED_FIELD 错误封装会携带一个类型化的 data 块：

{
  "success": false,
  "error": {
    "code": "RESERVED_FIELD",
    "message": "Cannot update reserved field: phase",
    "data": {
      "rejectedPath": "phase",
      "rule": "`phase` is top-level immutable — set once at init, never directly mutated thereafter.",
      "alternateWritePath": "Use `exarchos:exarchos_workflow` with `action: \"transition\"` and `target: \"<phase>\"` — phase changes are HSM-validated and emit transition events."
    }
  }
}

通过 exarchos:exarchos_workflow 使用 action: "describe" 和 actions: ["update"]，读取完整描述信息（包括针对以下划线路径的正则兜底规则）。返回的 reservedFields 块是唯一可信来源。

结构化交接输出

捕获交接信息时（checkpoint 命令界面），请输出此结构化摘要，以便恢复工作的 Agent 在上下文清除后，仍能看到你之前遵循的同一约定。### House Rules 块与 rehydrate 的输出保持一致（请参阅 @skills/rehydrate/SKILL.md），以确保正确性信号对称——生成检查点的 Agent 看到的 house rules，与恢复上下文的 Agent 看到的相同。

## Checkpoint Saved

**Feature:** <feature-id>
**Phase:** <current-phase>
### Progress
- Tasks: X/Y complete
- Current: <what's in progress>
- Next: <suggested next action>

### House Rules (apply every action this turn forward)
**Skill:** <phasePlaybook.skillRef or "(no playbook for this phase)">
**Tools:** <phasePlaybook.tools rendered as bullets>
**Required model-emitted events:** <phasePlaybook.events rendered as bullets — e.g. `task.progressed`, `phase.advanced`>
**Auto-emitted events (runtime fires these):** <phasePlaybook.autoEmittedEvents rendered as bullets>
**Transition:** <phasePlaybook.transitionCriteria> | Guard: <phasePlaybook.guardPrerequisites>
**Validation scripts:** <phasePlaybook.validationScripts joined>

### Event Emission Hints
<_eventHints.missing rendered as bullets, or "(none — phase machinery satisfied)">

### Resume Instructions

To continue this workflow in a new session, run `rehydrate` — or start the harness fresh, and the SessionStart hook will auto-discover active workflows.

> **Discipline reminder:** every task transition this turn forward MUST land on the workflow event stream via `exarchos_event.append` or `delegate` subagent emission. Direct `Edit` / `Bash` / `git` actions on task branches without corresponding events will desync the workflow tracker (see RCA `docs/rca/2026-05-08-rehydrate-behavioral-gap.md`).

自动检查点触发条件

出现以下情况时，建议创建检查点：

1. delegate 完成后 — 所有任务均已完成，尚未开始审查
2. 创建 PR 后 — 在 synthesize 阶段、反馈循环开始前
3. 反馈迭代达到 3 次或更多后 — 存在上下文累积风险
4. 用户提到上下文问题时 — 主动保存

最佳实践

1. 经常更新 - 状态应始终反映实际情况
2. 使用 MCP 工具 - 优先使用检查点 MCP 工具，而不是手动编辑 JSON
3. 恢复时对账 - 务必确认状态与 git 状态一致（参见 @skills/rehydrate/SKILL.md）
4. 在边界处创建检查点 - 在可能耗尽上下文之前保存状态
5. 读取状态，而非依靠记忆 - 总结后，从状态中读取信息（参见 @skills/rehydrate/SKILL.md）

故障排除

MCP 工具调用失败

如果 Exarchos MCP 工具返回错误：

1. 查看错误消息 — 通常其中包含具体指导
2. 验证工作流状态是否存在：调用 exarchos:exarchos_workflow，并使用 action: "get" 和 featureId
3. 如果出现“version mismatch”：其他进程更新了状态 — 重试操作
4. 如果状态已损坏：调用 exarchos:exarchos_workflow，并使用 action: "cancel" 和 dryRun: true

检查点缺失

如果在没有活动工作流时调用 checkpoint：

1. 先进行发现：调用 exarchos:exarchos_workflow，并使用 action: "list" 枚举活动工作流；如果列表为空，那么检查点命令报告“no active workflow”是正确的 — 正常退出
2. 如果 list 返回候选项，请验证它：调用 exarchos:exarchos_workflow，并使用 action: "get" 和相应的 featureId
3. 如果工作流存在但检查点失败：检查事件存储的磁盘空间和权限

工作流示例

1. 启动新工作流：使用 exarchos:exarchos_workflow，并设置 action: "init"、featureId: "user-authentication"、workflowType: "feature"

2. 编写完 Design & Rationale 部分后（plan 已是初始阶段 — 无需转换）：

   • action: "update"、featureId: "user-authentication"、updates: { "artifacts.spec": "docs/specs/2026-01-05-user-auth.md" }

3. 休息前保存进度：使用 checkpoint 创建结构化交接；稍后使用 rehydrate 恢复（参见 @skills/rehydrate/SKILL.md）。