feat(tdd): E3 — Goal/FlowRun 终态绑定 + flow_run finalize + 文档同步

- Add  transition: marks code→test→review→merge stages as pass,
  sets FlowRun to completed. Idempotent.
- Add  op to flow_control tool.
- Goal complete validates FlowRun terminal state via .
  Blocks completion if FlowRunRef exists and FlowRun is not finalized.
- Add  hook to createGoalTool for pre-complete validation.
- Export  for testing.
- Add 13 new tests (6 finalize + 7 blockers).
- Update docs: architecture.md, configuration.md.

Closes #80

Author: devcxl

docs/guides/architecture.md

@@ -66,6 +66,7 @@ FlowRun 已实现完整的阶段/任务/Gate/Checkpoint 状态机，经 Spike 
 | `github.ts` | Issue CRUD + 标签管理 + 乐观锁 |
 | `gate.ts` | 阶段/任务准入准出检查 |
 | `merge.ts` | PR 合并 + 分支保护 + 回滚 |
+| `transitions.ts` | 状态迁移函数（flowRunStart、flowRunFinalize 等） |
 | `validator.ts` | JSON Schema 校验 |
 | `resilience.ts` | 运行时检查 + 背压检测 |
 | `audit.ts` | 审计评论发布 |
@@ -194,6 +195,7 @@ FlowRun 写入时检测 Issue body 是否被其他进程修改，防止并发冲
 
 - 子 agent 禁止调用 `goal({op:"create"|"pause"|"resume"|"cancel"})` — 生命周期操作限制在主 session
 - 只有 `@goal-verify` 可以调用 `goal({op:"complete"})` — 防止过早完成
+- `goal({op:"complete"})` 内部验证 FlowRun 终态：如绑定 FlowRunRef，要求 FlowRun 必须先由 `flow_control({op:"run-finalize"})` 完成终态绑定
 - Agent 工具权限由 frontmatter 控制（reviewer 只读，backend/frontend 读写）
 
 ## 依赖关系

docs/guides/configuration.md

@@ -99,6 +99,16 @@ FlowRun 是插件的自动编排引擎，状态存储在 GitHub Issue body 中
 planned → running → blocked/merging → completed/cancelled
 ```
 
+### `flow_control` 操作
+
+| 操作 | 说明 |
+|------|------|
+| `run-start` | 启动 FlowRun: planned → running，并绑定 Goal |
+| `stage-start` | 启动阶段（requirements/design/tasks/code） |
+| `stage-complete` | 完成阶段（requirements/design/tasks），验证所有 checkpoints |
+| `task-start` | 启动任务（pending/ready → running），冻结 TDD policy |
+| `run-finalize` | **终态绑定**：所有 Task merged 后，顺序标记 code→test→review→merge 为 pass，设置 FlowRun 为 completed。幂等。 |
+
 ### 7 个阶段
 
 `requirements → design → tasks → code → test → review → merge`

src/flowrun/index.ts

@@ -46,6 +46,7 @@ export {
 
 export {
   flowRunStart, flowStageStart, flowStageComplete, flowTaskStart,
+  flowRunFinalize,
   type TransitionError, type TransitionResult,
 } from "./transitions.js"
 

src/flowrun/transitions.ts

@@ -3,7 +3,7 @@ import type {
   FlowRunStatus, StageStatus, TaskStatus,
 } from "./types.js"
 import {
-  canStartStage, canCompleteStage, canStartTask,
+  canStartStage, canCompleteStage, canStartTask, canMerge,
 } from "./gate.js"
 import type { GateResult } from "./gate.js"
 
@@ -170,3 +170,50 @@ export function flowTaskStart(
 
   return { ok: true, value: { flowRun, task } }
 }
+
+// ─── FlowRun Finalize ───
+
+/**
+ * FlowRun 终态绑定：所有 Task merged 后，顺序标记 code→test→review→merge 为 pass，
+ * 并将 FlowRun 状态设为 completed。
+ *
+ * 规则：
+ * - canMerge() 必须通过（所有 Task merged + FlowRun status 为 running/merging）
+ * - 对 code/test/review/merge 四个 stage：若未 pass 则逐个标记 pass
+ * - FlowRun status → completed，设置 completedAt
+ *
+ * 幂等：已经是 completed 则直接返回（不修改任何字段）。
+ */
+export function flowRunFinalize(flowRun: FlowRun): TransitionResult<FlowRun> {
+  // 幂等：已 completed
+  if (flowRun.status === "completed") {
+    return { ok: true, value: flowRun }
+  }
+
+  // 前置检查：canMerge（所有 Task merged + FlowRun 状态正确）
+  const mergeGate = canMerge(flowRun)
+  if (!mergeGate.allowed) {
+    return { ok: false, error: gateToError(mergeGate) }
+  }
+
+  // 顺序标记 finalize stages
+  const finalizeStages: FlowStage[] = ["code", "test", "review", "merge"]
+
+  for (const stage of finalizeStages) {
+    const stageState = flowRun.stages[stage]
+    if (!stageState) continue
+
+    // 已经是 pass → 跳过
+    if (stageState.status === "pass") continue
+
+    // 标记 pass
+    stageState.status = "pass"
+    stageState.completedAt = new Date().toISOString()
+  }
+
+  // FlowRun → completed
+  flowRun.status = "completed"
+  flowRun.completedAt = new Date().toISOString()
+
+  return { ok: true, value: flowRun }
+}

src/flowrun/types.ts

@@ -357,6 +357,7 @@ export type FlowControlOp =
   | "stage-complete"
   | "task-start"
   | "pr-create"
+  | "run-finalize"
 
 export interface FlowControlRequest {
   op: FlowControlOp

src/plugin/goal.ts

@@ -205,7 +205,28 @@ export function formatFlowRunRef(ref: GoalFlowRunRef): string {
   return `${ref.repo}#${ref.parentIssueNumber} (${ref.flowRunId})`
 }
 
-export function createGoalTool(client: ReturnType<typeof createOpencodeClient>) {
+/**
+ * 验证 FlowRun 终态 — 检查是否满足 Goal complete 的前提条件。
+ *
+ * 返回 null 表示允许完成；
+ * 返回错误信息字符串表示阻止完成。
+ *
+ * @param flowRunStatus FlowRun 当前状态，null 表示无绑定的 FlowRun
+ */
+export function checkFlowRunBlockers(flowRunStatus: string | null): string | null {
+  if (flowRunStatus === null) return null // 无 FlowRun 绑定，允许完成
+
+  if (flowRunStatus !== "completed" && flowRunStatus !== "cancelled") {
+    return `FlowRun is not in terminal state (status: ${flowRunStatus}). Run flow_control({op:"run-finalize"}) to finalize first.`
+  }
+
+  return null
+}
+
+export function createGoalTool(
+  client: ReturnType<typeof createOpencodeClient>,
+  onBeforeComplete?: (parentSessionID: string) => Promise<string | null>,
+) {
   return tool({
     description: `Manage the active goal-mode objective.
 
@@ -242,6 +263,15 @@ Use a single op field:
         if (parent.goal.status !== "active") {
           return `Parent session goal is not active (status: ${parent.goal.status}).`
         }
+
+        // 验证 FlowRun 终态（如绑定了 FlowRunRef）
+        if (onBeforeComplete) {
+          const blockReason = await onBeforeComplete(targetSessionID)
+          if (blockReason !== null) {
+            return `Goal completion blocked: ${blockReason}`
+          }
+        }
+
         parent.goal.status = "complete"
         await writeGoal(client, targetSessionID, parent.goal, parent.session)
         return `Goal completed and verified: "${parent.goal.objective}"`

src/plugin/server.ts

@@ -10,16 +10,18 @@ import { loadCommands } from "./commands.js"
 import { setupSkillsDir } from "./skills.js"
 import { loadAgents } from "./agents.js"
 import { createIsolatedShellEnv, detectAmbientCredentials } from "./shell.js"
-import { createGoalClient, createGoalTool, readGoal, writeGoal, bindFlowRunRef, MAX_CONTINUATIONS, continuationPrompt, verifyAgentPrompt, formatGoal } from "./goal.js"
+import { createGoalClient, createGoalTool, readGoal, writeGoal, bindFlowRunRef, readFlowRunRef, checkFlowRunBlockers, MAX_CONTINUATIONS, continuationPrompt, verifyAgentPrompt, formatGoal } from "./goal.js"
 import { FlowBroker } from "./broker.js"
 import {
   flowRunStart,
   flowStageStart,
   flowStageComplete,
   flowTaskStart,
+  flowRunFinalize,
 } from "../flowrun/transitions.js"
 import type { TaskExecutionBinding, FlowControlResponse } from "../flowrun/types.js"
 import { handleFlowPrCreateWithBroker } from "./flow-pr-tool.js"
+import { readFlowRun } from "../flowrun/github.js"
 
 const abortedSessions = new Set<string>()
 const errorRetryCount = new Map<string, number>()
@@ -184,15 +186,16 @@ function createFlowControlTool(
   goalClient: ReturnType<typeof createGoalClient>,
 ) {
   return tool({
-    description: `Control the FlowRun lifecycle: start a FlowRun, transition stages, and start tasks.
+    description: `Control the FlowRun lifecycle: start a FlowRun, transition stages, start tasks, and finalize completed runs.
 
 Operations:
 - run-start: Transition FlowRun from planned → running. Binds Goal to FlowRun.
 - stage-start: Start a stage (requirements/design/tasks/code). Requires prerequisites met.
 - stage-complete: Complete a stage (requirements/design/tasks). Requires all checks pass.
-- task-start: Start a task (pending/ready → running). Freezes TDD policy and sets execution binding.`,
+- task-start: Start a task (pending/ready → running). Freezes TDD policy and sets execution binding.
+- run-finalize: Mark code→test→review→merge stages as pass, set FlowRun to completed. Requires all Tasks merged. Idempotent.`,
     args: {
-      op: tool.schema.enum(["run-start", "stage-start", "stage-complete", "task-start"]).describe("Flow control operation"),
+      op: tool.schema.enum(["run-start", "stage-start", "stage-complete", "task-start", "run-finalize"]).describe("Flow control operation"),
       parent_issue_number: tool.schema.number().describe("Parent GitHub Issue number containing the FlowRun"),
       stage: tool.schema.enum(["requirements", "design", "tasks", "code", "test", "review", "merge"]).optional().describe("Stage name (for stage-start/stage-complete)"),
       task_id: tool.schema.string().optional().describe("Task ID (for task-start)"),
@@ -220,6 +223,8 @@ Operations:
             return handleStageComplete(broker, parentIssueNumber, args.stage as string)
           case "task-start":
             return handleTaskStart(broker, parentIssueNumber, args.task_id as string, args.execution_binding as TaskExecutionBinding | undefined, args.tdd_policy_json as string | undefined)
+          case "run-finalize":
+            return handleRunFinalize(broker, parentIssueNumber)
           default:
             return errorResponse("UNKNOWN_OP", `Unknown operation: "${op}"`)
         }
@@ -409,6 +414,36 @@ async function handleTaskStart(
   })
 }
 
+async function handleRunFinalize(
+  broker: FlowBroker,
+  parentIssueNumber: number,
+): Promise<string> {
+  const writeResult = await broker.writeFlowRunWithLock<unknown>(parentIssueNumber, (flowRun) => {
+    const res = flowRunFinalize(flowRun)
+    if (!res.ok) {
+      return { flowRun, result: res.error, shouldPersist: false }
+    }
+    return {
+      flowRun: res.value,
+      result: { status: res.value.status, completedAt: res.value.completedAt },
+      shouldPersist: true,
+    }
+  })
+
+  if (!writeResult.ok) {
+    return errorResponse(writeResult.code, writeResult.message)
+  }
+
+  if (!writeResult.persisted && writeResult.result && typeof writeResult.result === "object" && "code" in writeResult.result) {
+    const err = writeResult.result as { code: string; message: string }
+    return errorResponse(err.code, err.message)
+  }
+
+  return okResponse({
+    flowRunStatus: writeResult.flowRun.status,
+  })
+}
+
 // ─── Flow PR Tool ───
 
 function createFlowPRTool(broker: FlowBroker) {
@@ -476,7 +511,18 @@ export function createOpencodeCabbage(packageRoot: string): Plugin {
     const projectDir = ctx.worktree || ctx.directory
     const v1Client = (ctx.client as unknown as V1ClientContainer)._client
     const goalClient = createGoalClient(ctx.serverUrl, v1Client)
-    const goalTool = createGoalTool(goalClient)
+    const goalTool = createGoalTool(goalClient, async (parentSessionID) => {
+      // 验证绑定的 FlowRun 是否已终态
+      const ref = await readFlowRunRef(goalClient, parentSessionID)
+      if (!ref) return null // 无 FlowRun 绑定，允许完成
+
+      // 读取 FlowRun 状态
+      const flowResult = await readFlowRun(ref.parentIssueNumber)
+      if (!flowResult.ok) {
+        return `Failed to read FlowRun #${ref.parentIssueNumber}: ${flowResult.code}`
+      }
+      return checkFlowRunBlockers(flowResult.data.status)
+    })
     const broker = new FlowBroker()
     const flowControlTool = createFlowControlTool(broker, goalClient)
     const flowPRTool = createFlowPRTool(broker)