---
name: devflow:delivery
description: 通过可审计 Delivery Line 将需求推进到验证完成的 integrationRef 和交付包
---

# Delivery Line

使用 `mcp__devflow__delivery_*` 工具推进一个持久化交付案件。案件状态和 `nextActions` 是唯一的流程事实来源。

## 开始案件

收到新的交付需求时，调用 `mcp__devflow__delivery_create_case`。使用当前项目绝对路径；默认 `baseRef=HEAD`、`targetRef=main`，除非用户明确指定其他值。为 actor、session、execution 和每次写操作生成稳定且可追踪的标识与幂等键。
- 若上下文检索发现同名组件、同一路由或多个框架实现，将候选路径通过 `existingImplementations` 传入创建案件参数，让案件先进入阻塞澄清；不要自行选择复用或替换。

## 推进规则

- 调用 `mcp__devflow__get_project_context` 后必须等待该 MCP 返回，再进行任何 Read/Grep/Glob/Bash/Write/Edit；不要并发发起上下文请求和直接工具调用。
- 每次写操作后读取返回状态；状态不明确或发生 stale turn 时调用 `mcp__devflow__delivery_status`。
- 读取 `contextQuality.channelAvailability` 时区分三种结果：`available` 表示有可用证据，
  `empty_valid` 表示 producer 正常但项目没有匹配记录，可带降级说明继续；`unavailable`
  表示 producer 失败。Memory/Knowledge 默认是辅助通道，只有案件策略明确将其设为 required
  时才因 unavailable 阻塞；不得把 `empty_valid` 解释为 producer 异常。
- `delivery_status` 返回的 `currentTurn` 是唯一 canonical turn；所有后续 `answer`、`compare_options` 和
  `approve` 都原样使用该值。审批不会自动递增 turn，只有 `answer`/`revise` 打开新交互时才会变化。
- 只执行当前 `nextActions` 允许的操作。
- `designing` 阶段没有 `design` 审批动作。设计方案确认后，必须使用当前状态返回的
  `currentTurn` 调用 `delivery_compare_options`，由它生成 `spec_ready`；随后才可调用
  `delivery_approve(stage=spec)`。不得调用 `delivery_approve(stage=design)`，也不得用
  `delivery_advance` 代替 `compare_options`。
- `delivery_compare_options` 必须提交 `optionId`、与之匹配的 `selectedLabel`，以及包含该
  `id`/`label` 对的完整 `optionsSnapshot`。例如：
  `{ "turn": <status.currentTurn>, "questionId": "<caseId>:design:<status.currentTurn>", "optionId": "option-1",
  "selectedLabel": "Ant Design Form + Tailwind CSS", "optionsSnapshot": [
  { "id": "option-1", "label": "Ant Design Form + Tailwind CSS" },
  { "id": "option-2", "label": "原生 form" } ] }`。
  `option` 仅是兼容别名，只有在它精确等于 `optionsSnapshot` 中的某个 `id` 时才有效。
  若返回 `MISSING_PREREQUISITE`，根据 `error.details.expectedOptions` 修正字段后重试，
  不得因此取消案件。
- `delivery_advance` 仅允许在 `plan_approved` 阶段使用；其他阶段返回失败时必须按
  `nextActions` 恢复，不得把无推进当作成功。
- 澄清与设计交互使用当前 turn；后续写操作携带案件当前 context receipt。
- 只有用户明确同意时才能调用 `mcp__devflow__delivery_approve`；不得代替用户批准。
- 审批返回后不要结束会话：立即读取同一次返回的 `stage` 和 `nextActions`，按其允许的下一步继续推进；只有 `nextActions` 为空或用户明确暂停时才结束。
- `mcp__devflow__delivery_advance` 用于推进已满足的状态，`mcp__devflow__delivery_resume` 只恢复已经具备运行条件的 gate 或 task。
- 失败任务只通过 `mcp__devflow__delivery_retry_task` 重试；取消和导出分别使用 `mcp__devflow__delivery_cancel` 与 `mcp__devflow__delivery_export`。
- Claude 在当前工作区产生的修改不是 Delivery 输出；只能先调用 `mcp__devflow__delivery_import_external_change`，由系统校验 base/candidate、允许文件、context receipt 和验证证据后再进入 integration。

## 可用操作

- 澄清和设计：`delivery_answer`、`delivery_revise`、`delivery_compare_options`
- Gate 决策：`delivery_approve`、`delivery_reject`
- 状态和执行：`delivery_status`、`delivery_advance`、`delivery_resume`、`delivery_retry_task`
- 外部变更：`delivery_import_external_change`
- 交付收尾：`delivery_export`、`delivery_cancel`

## 错误处理

- MCP 返回 `ok: false` 时，该操作已经失败。向用户呈现 `error.code` 和 `error.message`，不得把 transport 成功误报为交付成功。
- `error.retryable=false` 时不得自动重试；`error.recoveryAction` 是下一步建议，不是已完成的动作。
- 遇到 `HELD`、`WORKER_UNAVAILABLE`、`REQUIRED_CONTEXT_MISSING` 或 producer/stale 警告时，先刷新 `delivery_status` 并保留阻塞状态；不得通过普通 Write/Edit/Bash/git commit 绕过 Delivery authority。
- 遇到 `STALE_INTERACTION_TURN`、`MISSING_PREREQUISITE` 或 `INVALID_TRANSITION` 时，先调用 `mcp__devflow__delivery_status` 刷新案件状态；只有新的 `nextActions` 明确允许时才继续。
- Delivery 工具失败后不得为了绕过写入限制调用 `delivery_cancel`；只有用户明确要求取消时才可取消。取消或拒绝后的同一会话仍禁止直接 Write/Edit/Bash，必须新建 Delivery 案件或开启新会话。
- 用户拒绝审批，或遇到 `UNAUTHORIZED_ROLE`、权限失败、`PROJECT_ROOT_MISMATCH` 时不得自动重试；保留案件当前状态并请求用户处理。
- 不通过更换 actor、project root、turn、context receipt 或幂等键来规避失败。

## 禁止

- 不直接修改 Delivery Line 数据库或状态文件。
- 不绕过 Facade 写入受保护的 target ref。
- 不把 `/devflow:workflow` 当作 Delivery Line 的替代路径。
- 不伪造 context receipt、interaction turn、审批或成功结果。