@chenguangyao/devflow-kit 0.1.43

package/docs/workflow-orchestration.md

@@ -0,0 +1,695 @@
+# Workflow Orchestration
+
+devflow 的 skill 编排从固定 phase 链升级为 workflow recipe。`level` 只表示风险和验证强度；本次需求实际走哪些 skill，由 workflow 决定。
+
+## 三层模型
+
+### 1. builtin recipes
+
+`builtin recipes` 是 devflow 随 CLI 发布的默认流程库。它解决的是“没有项目配置时也能安全工作”的问题。
+
+内置 recipe 示例：
+
+- `standard`：普通功能开发。
+- `micro`：小改动、文案、低风险配置。
+- `dependency-upgrade`：依赖升级。
+- `ci-fix`：CI / 构建修复。
+- `frontend-quality`：前端体验、可访问性、视觉回归。
+- `security-hardening`：安全加固。
+- `refactor`：不改变外部行为的重构。
+
+builtin recipe 由 devflow CLI 维护，项目和 change 都不直接修改它。它的最低责任是保证质量闸存在：
+
+```text
+review -> verify -> deliver
+```
+
+这三个 step 是 protected gates：
+
+- `review` 负责独立审查实现是否满足需求和设计。
+- `verify` 负责测试、回归、自测报告和验证汇总。
+- `deliver` 负责最终交付动作，例如 PR、merge、keep 或 discard。
+
+所以 builtin recipe 的定位不是“适配每个团队的最佳流程”，而是“任何团队的安全默认轨道”。项目没有配置时，devflow 仍然能用；项目配置写坏时，也可以退回 builtin。
+
+### 2. project recipes
+
+`project recipes` 是项目维护者定义的团队默认流程，配置在项目仓库的 `devflow/config.json`：
+
+```json
+{
+  "workflows": {
+    "recipes": {
+      "backend-api-change": {
+        "label": "后端接口改动",
+        "extends": "standard",
+        "insertAfter": {
+          "apply": [
+            {
+              "id": "contract-sync",
+              "skill": "test-spec",
+              "optional": true
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+project recipe 解决的是“团队默认路径不同”的问题。比如后端接口改动可能默认增加契约检查；前端改动可能默认增加可访问性、视觉回归或交互自测；安全相关改动可能默认增加安全审查。
+
+project recipe 通常 `extends` 一个 builtin recipe，再做有限编排：
+
+- `insertBefore`：在某个 step 前插入已安装 skill。
+- `insertAfter`：在某个 step 后插入已安装 skill。
+- `replaceStep`：用项目认可的 step 替换默认 step。
+- `disableStep`：禁用可选 step。
+
+这里刻意只开放有限操作，而不是完整 DAG 或任意 shell。原因是 project recipe 是团队默认轨道，应该保持可解释、可验证、可审计：
+
+- 编排对象只能是已安装 skill。
+- 默认不能删除或降级 protected gates。
+- 项目级变更要能在上线前静态校验。
+- 展开后的 step 顺序要能被人读懂。
+
+项目维护者上线配置前使用：
+
+```bash
+devflow flow validate
+devflow flow preview backend-api-change
+```
+
+`validate` 用于检查所有 project recipes 是否能展开、是否引用了合法 step、是否破坏质量闸。`preview` 用于查看某个 recipe 最终展开后的 step 列表，避免配置看起来正确、实际执行顺序错误。
+
+project recipe 的使用者主要是项目维护者。普通需求实现者通常不改项目配置，只消费它生成自己的 change workflow。
+
+### 3. change workflow
+
+`change workflow` 是每个需求真正执行的流程快照。它解决的是“同一个项目里，每次需求仍然可能有局部差异”的问题。
+
+需求进入 devflow 后，先基于上下文推荐 recipe：
+
+```bash
+devflow flow recommend --slug=<slug>
+```
+
+然后生成本次 workflow 草案：
+
+```bash
+devflow flow draft --slug=<slug>
+```
+
+draft 会把 base recipe 展开并写入 `state.workflow`。典型结构如下：
+
+```json
+{
+  "workflow": {
+    "status": "draft",
+    "baseRecipe": {
+      "id": "backend-api-change",
+      "source": "project",
+      "extends": "standard"
+    },
+    "baseSteps": [
+      { "id": "requirement", "skill": "requirement-analysis" },
+      { "id": "design", "skill": "tech-spec" },
+      { "id": "plan", "skill": "plan" },
+      { "id": "apply", "skill": "apply" },
+      { "id": "contract-sync", "skill": "test-spec", "optional": true },
+      { "id": "review", "skill": "code-review", "gate": true },
+      { "id": "verify", "skill": "verify", "gate": true },
+      { "id": "deliver", "skill": "deliver", "gate": true }
+    ],
+    "steps": [],
+    "overrides": [],
+    "audit": []
+  }
+}
+```
+
+实现者可以在 draft 阶段基于模板局部调整：
+
+```bash
+devflow flow add-step security-hardening --slug=<slug> --after=apply
+devflow flow disable-step contract-sync --slug=<slug> --reason="no API contract changed"
+devflow flow move-step frontend-quality --slug=<slug> --after=plan
+devflow flow set-verify --slug=<slug> --reports=unit,integration,smoke,self-test,e2e
+devflow flow diff --slug=<slug>
+devflow flow explain --slug=<slug>
+devflow flow check --slug=<slug> --json
+```
+
+调整完成后确认：
+
+```bash
+devflow flow confirm --slug=<slug>
+```
+
+confirm 后，`state.workflow.steps` 就成为本次 change 的执行真源。后续项目维护者即使修改了 `devflow/config.json` 中的 recipe，也不会影响已经 confirm 的 change。这样可以保证进行中的需求稳定、可复现、可审计。
+
+change workflow 的自由度是“基于模板改”，不是“从零手写 DAG”：
+
+- 可以添加本次需要的专项检查。
+- 可以禁用 optional step，但必须写明 reason。
+- 可以移动非 gate step。
+- 可以增强 verify 所需报告集合，例如给前端改动追加 e2e。
+- 可以通过 `flow diff` 看相对 base recipe 的差异；IDE / agent 可以用 `devflow flow diff --json` 获取机器可读 diff。
+- 可以通过 `flow explain` 解释每个 step 来自 builtin、project 还是 change override，并展示 open risk signals、verify 报告原因和本次 overrides 明细；IDE / agent 可以用 `devflow flow explain --json` 获取机器可读说明。
+- 可以通过 `flow check --json` 在 confirm 前做结构化预检，判断是否还存在 pending workflow policy、protected gate 问题、缺失 skill、风险信号未覆盖或 verify 降级。
+- 不能静默删除 `review`、`verify`、`deliver`。
+- 不能直接执行任意 shell。
+- 不能无确认地降低验证强度或绕过质量闸。
+
+三层模型的生效关系如下：
+
+```text
+builtin recipe
+  -> project recipe extends / overrides
+    -> change workflow draft
+      -> change overrides
+        -> confirmed state.workflow.steps
+```
+
+`builtin` 和 `project` 负责给出默认轨道，`change workflow` 负责把默认轨道冻结为本次需求的执行快照。
+
+## 状态结构
+
+`state.workflow` 是本次 change 的执行账本：
+
+```json
+{
+  "status": "draft",
+  "baseRecipe": {
+    "id": "standard",
+    "label": "标准研发",
+    "source": "builtin",
+    "reason": "default workflow"
+  },
+  "baseSteps": [],
+  "steps": [],
+  "overrides": [],
+  "verify": {
+    "requiredReports": ["unit-test.md", "integration-test.md", "smoke-test.md", "self-test.md"]
+  },
+  "currentStep": "requirement",
+  "audit": []
+}
+```
+
+- `baseRecipe` 记录来自 builtin 还是 project。
+- `baseSteps` 是未被 change override 修改前的展开结果。
+- `steps` 是本次 change 的实际执行快照。
+- `verify.requiredReports` 是本次 change 的 verify 报告强度 override；不存在时按 level 默认要求。
+- `overrides` 记录实现者本次 add / disable / move / set-verify。
+- `audit` 记录 workflow 操作流水。
+
+## Workflow Picker
+
+`devflow flow picker --json` 是给 IDE / Web UI 渲染“线形 + 分组”编排选项卡的只读协议。它不会修改 `state.workflow`，只把当前 draft 展开为适合用户确认的选择模型：
+
+```bash
+devflow flow picker --slug=<slug> --json
+```
+
+输出使用 `type: "workflow_picker_surface"` 和 `layout: "linear-grouped"`，默认分为三组：
+
+- `core`：核心流程，例如 requirement / design / plan / apply。
+- `quality`：专项检查，例如 frontend-quality / security-hardening / dependency-upgrade / ci-fix。
+- `delivery`：质量闸与交付，例如 review / verify / deliver / archive。
+
+每个 item 会标记 `selected`、`recommended`、`locked`、`required`、`protected`、`installed`、`source` 和可执行的 `command`。系统推荐 recipe 中的 step 会自动 `selected=true`；open risk signal 对应但尚未选中的专项 skill 会显示 `recommended=true` 和原因，例如 `open frontend_change risk signal`。`review`、`verify`、`deliver` 这类 protected gate 会显示 `locked=true`，UI 可以渲染为不可取消。
+
+这份 picker 协议的 schema 真源是 `schemas/workflow-picker.schema.json`。UI 不应依赖 CLI 人类输出解析，而应使用 `flow picker --json` 中的 `groups[].items[]` 渲染线性选项卡。典型 picker 输出样例固定在 `test/fixtures/workflow-surfaces/picker-*.json`，覆盖默认推荐和 risk signal 推荐专项 skill 两种场景。
+
+静态 UI 原型固定在 `docs/workflow-ui-prototype.html`，由 `npm run prototype:workflow` 从 `test/fixtures/workflow-surfaces/*.json` 生成。它展示线性 skill 选项卡、推荐勾选态、locked gate 和 workflow 确认卡，不需要 dev server，直接打开 HTML 即可检查交互形态。
+
+如果要用真实 change state 生成实时原型，可以运行 `npm run prototype:workflow -- --slug=<slug> --cwd=<repo>`。脚本会调用 `devflow flow picker --slug=<slug> --json` 和 `devflow flow card --slug=<slug> --json`，默认写到系统临时目录的 `devflow-workflow-ui-<slug>.html`，避免覆盖仓库内的静态 fixture 原型；需要指定位置时加 `--out=<file>`。
+
+picker 只负责展示候选和推荐，不直接保存用户选择。用户确认推荐流程时优先运行 `devflow flow card --slug=<slug> --json` 再执行 `devflow flow confirm --slug=<slug>`；脚本仍可直接运行 `devflow flow check --slug=<slug> --json` 做底层预检。如果用户在选项卡里勾选额外专项 skill 或取消 optional step，UI 可以把选择结果交给：
+
+```bash
+devflow flow apply-selection --slug=<slug> --selection='{"items":[...]}' --json
+```
+
+picker 的 `actions` 会返回 UI 可直接使用的入口：
+
+- `card`：打开统一 workflow 确认面，命令为 `devflow flow card --slug=<slug> --json`。
+- `check`：执行底层预检，适合脚本或调试入口。
+- `applySelection`：提交选项卡勾选结果。
+- `confirm`：确认当前 workflow 快照。
+- `suggest`：基于自然语言意图生成编排建议。
+
+`apply-selection` 会把安全选择转换成 `flow add-step` / `flow disable-step` 等 draft override，并复用 CLI 的 policy engine。添加检查型 step、禁用无风险 optional step 会直接写入 draft；取消 `review` / `verify` / `deliver` 这类 locked gate，或禁用风险相关专项检查时，会生成 `workflow_policy` checkpoint 并保持 workflow 不变。成功后返回 `nextAction: "devflow flow card --slug=<slug> --json"`，调用方再进入统一确认面。
+
+如果 `apply-selection --json` 触发了风险确认，它不会输出人类文本，而是返回 `workflow_policy_confirmation_surface`，供 UI 直接渲染“保留当前流程 / 接受风险”确认卡：
+
+```json
+{
+  "ok": false,
+  "type": "workflow_policy_confirmation_surface",
+  "slug": "<slug>",
+  "checkpoint": {
+    "id": "workflow_policy-xxxx",
+    "type": "workflow_policy",
+    "phase": "workflow",
+    "status": "pending",
+    "summary": "禁用 required workflow step: verify"
+  },
+  "confirmationCard": {
+    "type": "workflow_policy_confirm",
+    "title": "确认 workflow 风险",
+    "primaryAction": {
+      "id": "accept-risk",
+      "label": "接受风险",
+      "command": "devflow checkpoint resolve --id=workflow_policy-xxxx --decision=accept-risk"
+    },
+    "secondaryActions": [
+      {
+        "id": "keep",
+        "label": "保留当前流程",
+        "command": "devflow status --slug=<slug>"
+      }
+    ]
+  },
+  "actions": {
+    "show": "devflow checkpoint show --slug=<slug> --json",
+    "card": "devflow flow card --slug=<slug> --json"
+  }
+}
+```
+
+## 常用命令
+
+```bash
+devflow flow recommend --slug=<slug>
+devflow flow draft --slug=<slug>
+devflow flow draft --slug=<slug> --recipe=dependency-upgrade
+devflow flow suggest --slug=<slug> --intent="这是前端改动，还涉及安全校验"
+devflow flow add-step frontend-quality --slug=<slug> --after=apply
+devflow flow disable-step frontend-quality --slug=<slug> --reason="no UI diff"
+devflow flow move-step frontend-quality --slug=<slug> --after=plan
+devflow flow set-verify --slug=<slug> --reports=unit,integration,smoke,self-test,e2e
+devflow flow diff --slug=<slug>
+devflow flow picker --slug=<slug> --json
+devflow flow apply-selection --slug=<slug> --selection='{"items":[...]}' --json
+devflow flow explain --slug=<slug>
+devflow flow card --slug=<slug> --json
+devflow flow check --slug=<slug> --json
+devflow flow confirm --slug=<slug>
+```
+
+项目级命令不需要已有 change：
+
+```bash
+devflow flow validate
+devflow flow preview backend-api-change
+```
+
+## 安全边界
+
+- `review`、`verify`、`deliver` 是 protected gates，默认不可删除或降级。
+- 禁用 required step、移动 protected gate 到非法位置、弱化验证要求，都必须生成 checkpoint 或直接拒绝。
+- 添加检查型 step、移动 optional step、禁用 optional step、增强 verify 报告集合只记录 audit，不额外阻断。
+- 自定义 step 只能引用已安装 skill，不能直接执行任意 shell。
+
+## 风险感知 Policy Engine
+
+workflow 修改先经过 policy engine 分类，再决定是否直接落盘：
+
+- `safe`：增加检查型 step，不会降低流程强度，直接通过并记录 audit。
+- `audit-only`：禁用普通 optional step、增强 verify 报告集合，只记录 reason 和 audit。
+- `checkpoint-required`：禁用 required step、禁用质量闸、降低 level 默认 verify 报告要求、或在存在对应风险信号时禁用专项检查，会生成 `workflow_policy` checkpoint。
+- `rejected`：破坏 protected gate 顺序、移动质量闸到非法位置、引用未知 skill、任意 shell 等直接拒绝。
+
+风险信号和专项 step 的默认映射：
+
+```text
+frontend_change     -> frontend-quality
+security_sensitive  -> security-hardening
+dependency_change   -> dependency-upgrade
+ci_failure          -> ci-fix
+```
+
+例如当前 change 存在 `frontend_change`，禁用 `frontend-quality` 不会直接生效，而是生成确认卡：
+
+```bash
+devflow flow disable-step frontend-quality --slug=<slug> --reason="..."
+```
+
+这会留下 `workflow_policy` checkpoint，让用户明确选择保留流程或接受风险。相反，增加一个额外检查 step 不会阻断：
+
+```bash
+devflow flow add-step security-hardening --slug=<slug> --after=apply
+```
+
+verify 强度也是 workflow override。比如 L2 默认需要 `unit`、`integration`、`smoke`、`self-test`；增加 e2e 会直接落盘：
+
+```bash
+devflow flow set-verify --slug=<slug> --reports=unit,integration,smoke,self-test,e2e
+```
+
+如果改成只要 `unit,smoke`，因为少了 L2 默认的 `integration` 和 `self-test`，会生成 `workflow_policy` checkpoint。确认后才允许带风险继续。
+
+`workflow_policy` checkpoint 的确认只表示“用户接受这次风险变化”，不会暗中替用户改 workflow。用户 resolve 后需要重跑原来的 `flow` 命令；CLI 会识别同一条已 `accept-risk` 的 workflow policy checkpoint，放行这次修改并写入审计。这个机制适用于禁用 required gate、禁用风险相关专项检查、降低 verify 要求等风险变高的 workflow 修改：
+
+```bash
+devflow checkpoint resolve --id=<checkpoint-id> --decision=accept-risk
+devflow flow set-verify --slug=<slug> --reports=unit,smoke --reason="fast path"
+```
+
+IDE / Web UI 也可以随时调用 `devflow checkpoint show --slug=<slug> --json` 获取最新 pending checkpoint。JSON 输出会带 `checkpoint_confirmation_surface` 和通用 `confirmationCard`；当 checkpoint 类型是 `workflow_policy` 时，卡片类型为 `workflow_policy_confirm`，主操作是 `accept-risk`，次操作保留当前流程：
+
+```json
+{
+  "type": "checkpoint_confirmation_surface",
+  "pending": { "type": "workflow_policy", "status": "pending" },
+  "confirmationCard": {
+    "type": "workflow_policy_confirm",
+    "primaryAction": { "id": "accept-risk" },
+    "secondaryActions": [{ "id": "keep" }]
+  }
+}
+```
+
+## AI 辅助编排草案
+
+`devflow flow suggest` 把实现者的自然语言意图转换为可解释的 workflow override 草案。第一版是规则型 intent parser，不调用模型，也不直接修改 `state.workflow`：
+
+```bash
+devflow flow suggest --slug=<slug> --intent="这是前端改动，还涉及安全校验"
+```
+
+输出示例：
+
+```text
+suggested overrides
+  - add-step frontend-quality: intent mentions frontend or UI quality risk
+    command: devflow flow add-step frontend-quality --slug=<slug> --after=apply
+  - add-step security-hardening: intent mentions security-sensitive behavior
+    command: devflow flow add-step security-hardening --slug=<slug> --after=frontend-quality
+  - set-verify: intent mentions core path or e2e verification
+    command: devflow flow set-verify --slug=<slug> --reports=unit,integration,smoke,self-test,e2e
+```
+
+规则型识别范围：
+
+- 前端 / UI / 页面 / 样式 / 交互 / React / Vue / Next / Vite → 建议 `frontend-quality`。
+- 安全 / 权限 / 鉴权 / token / cookie / auth / 校验 → 建议 `security-hardening`。
+- 依赖 / 升级 / lockfile / `package-lock` / `go.sum` / `pom.xml` → 建议切到 `dependency-upgrade` recipe。
+- CI / 构建 / Jenkins / GitHub Actions / GitLab CI / 失败 → 建议切到 `ci-fix` recipe。
+- 核心链路 / 主链路 / 关键路径 / 端到端 / e2e → 建议通过 `flow set-verify` 追加 `e2e` 报告要求。
+
+如果不传 `--intent`，`suggest` 会读取 `state.riskSignals` 里的 open 风险信号：
+
+- `frontend_change` → 建议 `frontend-quality`，并通过 `flow set-verify` 追加 `e2e`。
+- `security_sensitive` → 建议 `security-hardening`，并追加 `contract` 验证报告。
+- `dependency_change` → 建议切到 `dependency-upgrade` recipe。
+- `ci_failure` → 建议切到 `ci-fix` recipe。
+
+`suggest` 默认只输出命令草案。实现者确认后手动运行对应 `flow add-step`、`flow set-verify` 或 `flow draft --recipe=...`，后续仍会经过 policy engine 和 workflow gate。
+
+如果想减少复制命令，可以显式让 suggest 把安全增强型 override 写入 draft：
+
+```bash
+devflow flow suggest --slug=<slug> --intent="这是前端核心链路改动，还涉及安全校验" --apply-draft
+```
+
+`--apply-draft` 只会自动应用 `add-step` 和增强型 `set-verify`，并继续经过 policy engine。它不会自动 confirm workflow，也不会自动应用 recipe replacement；例如 dependency / ci 的 recipe 建议仍必须手动运行 `devflow flow draft --recipe=...` 才会替换草案。
+
+熟练用户或自动化场景可以再显式加 `--confirm`：
+
+```bash
+devflow flow suggest --slug=<slug> --intent="这是前端核心链路改动，还涉及安全校验" --apply-draft --confirm
+```
+
+`--apply-draft --confirm` 只在没有 recipe replacement 建议、且安全增强型 override 成功写入 draft 时才会尝试确认 workflow。真正冻结前会复用 `devflow flow confirm` 的同一套预检：如果 `flow check` 返回 `ok=false`，例如仍有缺失 skill、未覆盖的 risk signal、待确认的 `workflow_policy` checkpoint，confirm 会被拒绝，draft 保持未确认。确认后仍然只是冻结本次 `state.workflow.steps`，不会执行任何 phase 命令。
+
+## Confirm 前预检
+
+`devflow flow check` 是给 CLI、IDE 和 agent 共用的 confirm 前安全预检。它只读取当前 `state.workflow`，不修改状态：
+
+```bash
+devflow flow check --slug=<slug> --json
+```
+
+workflow check 是 core 能力，由 `src/core/workflow-check.js` 维护；flow/status/phase gate 这类 CLI 入口只负责渲染、阻断和提示下一步。这样后续 IDE 面板、自动 draft 或其它入口都能复用同一套预检语义，而不是各自复制规则。
+
+JSON 输出固定包含：
+
+```json
+{
+  "ok": false,
+  "status": "draft",
+  "errors": [],
+  "warnings": [
+    {
+      "code": "missing-risk-step",
+      "riskSignal": "security_sensitive",
+      "recommendedSteps": ["security-hardening"],
+      "message": "open security_sensitive risk signal has no active recommended workflow step: security-hardening"
+    }
+  ],
+  "nextAction": "devflow flow suggest --slug=<slug> --apply-draft"
+}
+```
+
+当 `ok=true` 时，输出还会包含 `confirmationCard`，供 IDE / Web UI 直接渲染“确认本次编排”的卡片。它不会写入 state，只是把本次 workflow 快照、确认命令和回到 picker 调整的命令放在同一个协议对象里：
+
+```json
+{
+  "confirmationCard": {
+    "type": "workflow_confirm",
+    "title": "确认本次 workflow",
+    "question": "是否确认本次 change workflow，并按当前快照执行？",
+    "steps": [
+      { "id": "requirement", "skill": "requirement-analysis", "status": "pending" },
+      { "id": "review", "skill": "code-review", "required": true, "protected": true }
+    ],
+    "primaryAction": {
+      "id": "confirm",
+      "label": "确认 workflow",
+      "command": "devflow flow confirm --slug=<slug>"
+    },
+    "secondaryActions": [
+      {
+        "id": "edit",
+        "label": "调整编排",
+        "command": "devflow flow picker --slug=<slug> --json"
+      }
+    ]
+  }
+}
+```
+
+IDE / Web UI 如果只想渲染确认面，优先调用统一协议入口：
+
+```bash
+devflow flow card --slug=<slug> --json
+```
+
+`card` 不修改 state，只复用 `flow check` 的同一套预检结果，并把确认卡和常用动作聚合成 `workflow_confirmation_surface`：
+
+```json
+{
+  "type": "workflow_confirmation_surface",
+  "slug": "<slug>",
+  "ok": true,
+  "status": "draft",
+  "baseRecipe": { "id": "standard", "source": "builtin" },
+  "confirmationCard": { "type": "workflow_confirm" },
+  "actions": {
+    "picker": "devflow flow picker --slug=<slug> --json",
+    "applySelection": "devflow flow apply-selection --slug=<slug> --selection='<json>' --json",
+    "check": "devflow flow check --slug=<slug> --json",
+    "confirm": "devflow flow confirm --slug=<slug>"
+  },
+  "nextAction": "devflow flow confirm --slug=<slug>"
+}
+```
+
+这份确认面协议的 schema 真源是 `schemas/workflow-confirmation-surface.schema.json`。UI 可以把它作为“推荐编排确认卡”的稳定边界：`ok=true` 时展示 `confirmationCard.primaryAction`，`ok=false` 时按 `errors` / `warnings` / `nextAction` 引导用户回 picker 或 checkpoint。典型确认卡输出样例固定在 `test/fixtures/workflow-surfaces/confirmation-card.json`。
+
+非 JSON 输出在 `ok=true` 时也会渲染同一张确认卡的紧凑摘要，方便纯 CLI 用户直接确认，或回到 picker 调整：
+
+```text
+workflow check: ok
+确认本次 workflow
+question: 是否确认本次 change workflow，并按当前快照执行？
+steps: requirement -> design -> plan -> apply -> review -> verify -> deliver -> archive
+confirm: devflow flow confirm --slug=<slug>
+edit: devflow flow picker --slug=<slug> --json
+next: devflow flow confirm --slug=<slug>
+```
+
+`ok=true` 表示可以安全执行 `devflow flow confirm --slug=<slug>`。`ok=false` 时，调用方应先处理 `nextAction`：
+
+- `workflow-missing`：先运行 `devflow flow draft`。
+- `pending-workflow-policy`：先展示或处理 `workflow_policy` checkpoint。
+- `missing-protected-gate` / `disabled-protected-gate` / `invalid-gate-order`：先回到 `flow explain` 查看结构问题。
+- `missing-skill`：安装或修正 step 引用的 skill。
+- `missing-risk-step`：建议运行 `devflow flow suggest --apply-draft`，把 open risk signal 对应的专项 step 补进 draft。
+- `verify-below-level-default`：把 verify reports 恢复到当前 level 默认要求，或通过 policy checkpoint 明确接受风险。
+
+如果某个风险修改已经有同 summary 的 `workflow_policy` checkpoint，并且 decision 是 `accept-risk`，`flow check` 会把它视为已确认风险，不再重复阻断同一条 workflow override。
+
+`devflow flow confirm` 本身也会执行同一套预检；如果 `ok=false`，confirm 会拒绝冻结 workflow，并输出对应的 error / warning 和 `nextAction`。
+
+推荐 IDE 使用顺序是：
+
+```bash
+devflow flow diff --slug=<slug> --json
+devflow flow explain --slug=<slug> --json
+devflow flow card --slug=<slug> --json
+devflow flow confirm --slug=<slug>
+```
+
+这样 `diff` 回答“改了什么”，`explain` 回答“为什么这样编排”，`card` 回答“现在能不能安全 confirm，以及该如何确认或回到 picker 调整”。
+
+## 推荐的入口顺序
+
+新需求入口仍先做 intake / brainstorm 和问题卡确认。`devflow new` 和 `devflow ingest` 成功创建 change 后，会立即基于推荐 recipe 自动生成本次 `state.workflow` 草案；用户不用再手动跑 `recommend` / `draft` 才能看到流程。
+
+```bash
+devflow ingest "<url-or-file>" --project-root=<repo>
+devflow checkpoint resolve --id=<problem-card-id> --decision=accept
+devflow flow picker --slug=<slug> --json
+devflow flow apply-selection --slug=<slug> --selection='<json>' --json
+devflow flow explain --slug=<slug>
+devflow flow card --slug=<slug> --json
+devflow flow confirm --slug=<slug>
+```
+
+入口命令会直接打印这组 workflow selection guidance：`picker` 用于渲染“线形 + 分组”的选项卡，`apply-selection` 用于提交用户勾选结果，`card` 是 UI 优先使用的统一确认面，内部包含 check 结果、确认卡和可执行 action，`check` 保留给脚本做 Confirm 前预检，`confirm` 冻结快照。用户如果接受推荐编排，可以跳过 `apply-selection`，直接看 `card` 并 `confirm`；如果调整了选项卡，再先提交 selection。
+
+如果入口阶段因为缺失 skill、recipe 配置错误或旧项目配置无法自动生成草案，CLI 会退回显示 `devflow flow recommend` / `devflow flow draft` 的手动补救命令。之后 orchestrator 按 `state.workflow.steps` 决定下一步 skill，而不是按固定 phase 表硬跳。
+
+## 执行约束
+
+confirmed workflow 会参与阶段命令的运行时 gate：
+
+- `state.workflow.status` 仍是 `draft` 时，`requirement` / `design` / `plan` / `apply` / `review` / `verify` / `deliver` 会被 phase gate 挡住，并提示先运行 `devflow flow card --slug=<slug> --json`；如果确认面 `ok=true`，phase gate 也会渲染紧凑版 `确认本次 workflow` 卡片，包含 `steps:`、`confirm:` 和 `edit:`，让误跑 phase 命令的用户也能直接确认或调整。脚本仍可调用 `devflow flow check --slug=<slug> --json` 做底层预检。
+- `state.workflow.status=confirmed` 时，阶段命令必须匹配 `state.workflow.currentStep`；例如当前 step 是 `requirement` 时，直接运行 `devflow plan` 会被拒绝。
+- 阶段命令成功后，当前 step 会标记为 `completed`，并把 `currentStep` 推进到下一个未 disabled、未 completed 的 step。
+- `apply` 只有在所有 plan task 都完成或跳过后，才会把 workflow 推进到 `review`。
+- `verify` 在 `devflow verify finalize` 成功后推进到 `deliver`；普通 `devflow verify` 只进入验证中，不提前放行交付。
+- 旧 change 如果没有 `state.workflow`，仍按旧 phase 兼容路径运行。
+
+`devflow status` 会展示 workflow 的 recipe、状态、当前 step、下一 step，以及本次 change 的 override 摘要。对于尚未 confirm 的 draft，它会优先提示 `flow card`，并显示 `ok/errors/warnings/nextAction`；当 `ok=true` 时，status 也会渲染紧凑版 `确认本次 workflow` 卡片，包含 `steps:`、`confirm:` 和 `edit:`，让用户可以直接确认，或回到 picker 调整。如果存在 `missing-risk-step` 这类未覆盖风险，status 的 `next:` 会直接指向 `devflow flow suggest --apply-draft`，而不是笼统提示继续当前 phase。
+
+IDE / Web UI 可以调用 `devflow status --slug=<slug> --json` 作为当前 change 页面入口。JSON 输出是 `change_status_surface`，包含 change 基本信息、`phases` 进度、`artifacts` 产物、`apply` task 摘要、`review` 轮次、`verify` 报告缺口、`riskSignals`、`workflow.check`、`workflow.actions`、`pendingCheckpoint`、`checkpointConfirmationCard`、`primaryPanel`、`blockingReason`、`availableActions` 和 `nextAction`。UI 推荐按这三个字段渲染主操作区：
+
+- `primaryPanel`：当前页面主面板类型，例如 `checkpoint`、`workflow_confirm`、`workflow_check`、`review_blocked`、`verify_start`、`current_step`。
+- `blockingReason`：如果当前需要用户确认或存在硬阻塞，给出结构化原因；没有阻塞时为 `null`。
+- `availableActions`：可直接渲染的按钮列表，包含 `id`、`label`、`command`、`primary`、`danger`、`requiresReason`。
+
+这份 JSON contract 的 schema 真源是 `schemas/status-surface.schema.json`。UI 集成或插件适配时，应以该 schema 作为字段兼容边界；新增字段可以向后兼容追加，但 `primaryPanel` / `blockingReason` / `availableActions` 的核心字段不应随意改名。
+典型输出样例固定在 `test/fixtures/status-surfaces/*.json`，覆盖 workflow draft、pending checkpoint、review blocked、verify missing reports 和 confirmed current step。修改 `status --json` UI 字段时，应同步更新这些 golden snapshots。
+
+如果当前 workflow draft 被 `workflow_policy` checkpoint 阻塞，`nextAction` 会指向 `devflow checkpoint show --slug=<slug> --json`，UI 可以直接渲染 `checkpointConfirmationCard`：
+
+```json
+{
+  "type": "change_status_surface",
+  "slug": "<slug>",
+  "phases": {
+    "current": { "id": "apply", "status": "in_progress" },
+    "summary": { "total": 9, "completed": 1, "inProgress": 1, "pending": 7 }
+  },
+  "artifacts": {
+    "core": [{ "name": "requirement.md", "exists": true }],
+    "directories": { "reports": { "count": 1, "files": ["test-report.md"] } }
+  },
+  "review": { "status": "blocked", "latestRound": { "round": 2, "outcome": "blocked" } },
+  "verify": {
+    "requiredReports": ["unit-test.md", "e2e-test.md"],
+    "presentReports": ["unit-test.md"],
+    "missingReports": ["e2e-test.md"]
+  },
+  "riskSignals": { "summary": { "total": 1, "open": 1 } },
+  "workflow": {
+    "status": "draft",
+    "currentStep": "requirement",
+    "check": { "ok": false },
+    "actions": {
+      "card": "devflow flow card --slug=<slug> --json",
+      "picker": "devflow flow picker --slug=<slug> --json"
+    }
+  },
+  "pendingCheckpoint": { "type": "workflow_policy" },
+  "checkpointConfirmationCard": { "type": "workflow_policy_confirm" },
+  "primaryPanel": {
+    "type": "checkpoint",
+    "reasonCode": "pending-checkpoint",
+    "actionIds": ["show-checkpoint", "accept-risk", "keep"]
+  },
+  "blockingReason": {
+    "code": "pending-checkpoint",
+    "source": "checkpoint",
+    "severity": "blocker"
+  },
+  "availableActions": [
+    {
+      "id": "show-checkpoint",
+      "label": "查看确认卡",
+      "command": "devflow checkpoint show --slug=<slug> --json",
+      "primary": true
+    }
+  ],
+  "nextAction": "devflow checkpoint show --slug=<slug> --json"
+}
+```
+
+`devflow flow explain` 更适合在 confirm 前做人工复核。它会展示：
+
+- base recipe 的来源和推荐原因。
+- 每个 step 的 skill、source、required / optional / protected / disabled 状态。
+- workflow verify required reports，以及这些报告是因为什么 override 设置的。
+- 当前仍 open 的 `state.riskSignals`。
+- 本次 change workflow 的 add / disable / move / set-verify overrides。
+
+## 示例：后端接口改动
+
+项目配置：
+
+```json
+{
+  "workflows": {
+    "recipes": {
+      "backend-api-change": {
+        "label": "后端接口改动",
+        "extends": "standard",
+        "insertAfter": {
+          "apply": [
+            {
+              "id": "contract-sync",
+              "skill": "test-spec",
+              "optional": true
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+预览：
+
+```bash
+devflow flow validate
+devflow flow preview backend-api-change
+```
+
+用于 change：
+
+```bash
+devflow flow draft --slug=<slug> --recipe=backend-api-change
+devflow flow confirm --slug=<slug>
+```
+
+## 下一轮方向
+
+- 把 `flow suggest` 从规则型 intent parser 升级为可选 AI 辅助，但仍只生成草案或安全增强型 draft override，不直接执行任意 shell 或绕过 policy engine。
+- 支持更多 `--apply-draft` 可应用项，例如按风险信号追加 contract / joint / perf 报告，但 recipe replacement 仍保持显式手动。