feat(tdd): E1 — Task-local merge Gate + 解除全局 canMerge() 耦合

- canMergeTaskPR() 独立实现，不调用全局 canMerge()
  - 检查 Task reviewing + PR checkpoints + TDD compliance + Branch Protection
  - 不再要求全局 review Stage 为 pass
- canMerge() 语义变更为 Flow 收尾确认
  - 仅检查 FlowRun 状态 + 所有 Task 已 merged
  - 不再检查 review Stage
- mergeTaskPR() 支持 --match-head-commit 安全检查
- setMergeGhExecutor() 支持测试注入
- 测试覆盖 26 个 merge + 29 个 gate（双 Task 依赖全链路 + 全部阻断路径）

Author: devcxl

src/flowrun/gate.ts

@@ -152,14 +152,23 @@ export function canCreatePR(task: TaskState): GateResult {
   return ok()
 }
 
+/**
+ * 检查 FlowRun 是否满足合并收尾条件。
+ *
+ * 新语义（v2）：
+ * - FlowRun 状态为 running 或 merging
+ * - 所有 Task 状态均为 merged
+ * - 不再要求 review Stage 为 pass（Task-local merge 已独立）
+ *
+ * 用于 flow_run finalize。
+ */
 export function canMerge(flowRun: FlowRun): GateResult {
   if (flowRun.status !== "running" && flowRun.status !== "merging") {
     return block("FlowRun is not in a mergeable state")
   }
 
-  const reviewStage = flowRun.stages.review
-  if (reviewStage.status !== "pass") {
-    return block("Review stage is not complete")
+  if (!allTasksComplete(flowRun)) {
+    return block("Not all tasks merged (finalize requires all tasks to be merged first)")
   }
 
   return ok()

src/flowrun/index.ts

@@ -51,7 +51,7 @@ export {
 
 export {
   checkBranchProtection, validateCheckpoint, validatePRCheckpoints,
-  canAutoMergeTask, mergePR, createRevertPR,
+  canMergeTaskPR, mergePR, mergeTaskPR, createRevertPR, setMergeGhExecutor,
   type MergeGateResult,
 } from "./merge.js"
 

src/flowrun/merge.ts

@@ -1,8 +1,26 @@
 import type {
-  FlowRun, PRCheckpoints, Checkpoint, TaskState,
+  PRCheckpoints, Checkpoint, TaskState,
 } from "./types.js"
-import { canMerge } from "./gate.js"
-import { gh } from "../util/gh.js"
+
+// ─── 可替换的 gh executor（用于测试） ───
+
+type GhFn = (args: string) => Promise<{ stdout: string; stderr: string }>
+
+let mergeGhExecutor: GhFn | null = null
+
+export function setMergeGhExecutor(fn: GhFn) {
+  mergeGhExecutor = fn
+}
+
+async function gh(args: string): Promise<{ stdout: string; stderr: string }> {
+  if (mergeGhExecutor) {
+    return mergeGhExecutor(args)
+  }
+  const mod = await import("../util/gh.js")
+  return mod.gh(args)
+}
+
+// ─── 类型 ───
 
 export interface BranchProtectionStatus {
   exists: boolean
@@ -17,6 +35,8 @@ export interface MergeGateResult {
   checkpointResults: Record<string, "pending" | "pass" | "fail" | "skipped">
 }
 
+// ─── Branch Protection ───
+
 export async function checkBranchProtection(owner: string, repo: string): Promise<BranchProtectionStatus> {
   try {
     const { stdout } = await gh(`api repos/${owner}/${repo}/branches/main/protection`)
@@ -46,6 +66,8 @@ export async function checkBranchProtection(owner: string, repo: string): Promis
   }
 }
 
+// ─── Checkpoint 验证 ───
+
 export function validateCheckpoint(cp: Checkpoint): "pending" | "pass" | "fail" {
   if (cp.status === "pass") return "pass"
   if (cp.status === "fail") return "fail"
@@ -88,12 +110,22 @@ export function validatePRCheckpoints(checkpoints: PRCheckpoints): MergeGateResu
   return { allowed: true, checkpointResults: results }
 }
 
-export function canAutoMergeTask(flowRun: FlowRun, task: TaskState, protection: BranchProtectionStatus): MergeGateResult {
-  const flowGate = canMerge(flowRun)
-  if (!flowGate.allowed) {
-    return { allowed: false, reason: flowGate.reason, checkpointResults: {} }
-  }
-
+// ─── Task-local Merge Gate ───
+
+/**
+ * Task-local merge gate（不依赖全局 canMerge）。
+ *
+ * 检查条件（按顺序）：
+ * 1. Task 状态为 "reviewing"
+ * 2. 存在 PR Checkpoints
+ * 3. 所有 checkpoint 状态为 pass
+ * 4. TDD compliance 为 pass / waived / null（无 TDD 要求）
+ * 5. Branch Protection 已启用
+ *
+ * 不要求全局 review Stage 为 pass。
+ */
+export function canMergeTaskPR(task: TaskState, hasBranchProtection: boolean): MergeGateResult {
+  // 1. Task 状态检查
   if (task.status === "merged") {
     return { allowed: false, reason: "Task already merged", checkpointResults: {} }
   }
@@ -102,14 +134,32 @@ export function canAutoMergeTask(flowRun: FlowRun, task: TaskState, protection:
     return { allowed: false, reason: `Task status is ${task.status}, expected reviewing`, checkpointResults: {} }
   }
 
+  // 2. PR Checkpoints 存在性
   if (!task.prCheckpoints) {
     return { allowed: false, reason: "No PR checkpoints recorded", checkpointResults: {} }
   }
 
+  // 3. 标准 checkpoint 验证
   const prResult = validatePRCheckpoints(task.prCheckpoints)
   if (!prResult.allowed) return prResult
 
-  if (!protection.exists) {
+  // 4. TDD compliance 验证
+  const tdd = task.prCheckpoints.tddCompliance
+  if (tdd !== null && tdd.status === "fail") {
+    prResult.checkpointResults["tddCompliance"] = "fail"
+    return {
+      allowed: false,
+      reason: `TDD compliance failed: ${tdd.summary}`,
+      checkpointResults: prResult.checkpointResults,
+    }
+  }
+  // tdd === null → 无 TDD 要求，视为通过
+  // tdd.status === "pass" / "waived" → 通过
+  prResult.checkpointResults["tddCompliance"] =
+    tdd === null ? "skipped" : (tdd.status as "pass" | "fail" | "pending")
+
+  // 5. Branch Protection
+  if (!hasBranchProtection) {
     prResult.checkpointResults.branchProtection = "fail"
     return {
       allowed: false,
@@ -122,6 +172,11 @@ export function canAutoMergeTask(flowRun: FlowRun, task: TaskState, protection:
   return prResult
 }
 
+// ─── PR 合并操作 ───
+
+/**
+ * 标准化合并 PR（无安全检查，向后兼容）。
+ */
 export async function mergePR(prNumber: number): Promise<{ success: boolean; error?: string }> {
   try {
     await gh(`pr merge ${prNumber} --squash --delete-branch`)
@@ -131,6 +186,30 @@ export async function mergePR(prNumber: number): Promise<{ success: boolean; err
   }
 }
 
+/**
+ * Task-local PR 合并（带 --match-head-commit 安全检查）。
+ *
+ * 步骤：
+ * 1. 验证 verifiedSha 非空
+ * 2. 使用 gh pr merge --squash --delete-branch --match-head-commit <verifiedSha>
+ * 3. 失败时返回错误
+ */
+export async function mergeTaskPR(prNumber: number, verifiedSha: string): Promise<{ success: boolean; error?: string }> {
+  if (!verifiedSha) {
+    return { success: false, error: "verifiedSha is required for merge --match-head-commit" }
+  }
+
+  try {
+    // --match-head-commit 确保只有 verified 的 commit 才会被合并
+    await gh(`pr merge ${prNumber} --squash --delete-branch --match-head-commit ${verifiedSha}`)
+    return { success: true }
+  } catch (err) {
+    return { success: false, error: String(err) }
+  }
+}
+
+// ─── Revert ───
+
 export async function createRevertPR(prNumber: number, reason: string): Promise<{ prNumber?: number; error?: string }> {
   try {
     const { stdout } = await gh(`pr view ${prNumber} --json headRefName,headRepository,body,title`)

test/flowrun/gate.test.ts

@@ -187,14 +187,40 @@ describe("canCompleteTask", () => {
 })
 
 describe("canMerge", () => {
-  it("blocks if review stage not pass", () => {
-    const run = withStage(runningRun(), "review", "pending")
-    expect(canMerge(run).allowed).toBe(false)
+  it("allows when flow is running and all tasks are merged", () => {
+    const run = withTask(runningRun(), { id: "a", status: "merged", dependsOn: [], expectedFiles: [] } as any)
+    expect(canMerge(run).allowed).toBe(true)
   })
 
-  it("allows when review is pass", () => {
-    const run = withStage(runningRun(), "review", "pass")
-    expect(canMerge(run).allowed).toBe(true)
+  it("allows when flow is merging and all tasks merged", () => {
+    const run = withTask(runningRun(), { id: "a", status: "merged", dependsOn: [], expectedFiles: [] } as any)
+    const run2 = { ...run, status: "merging" as const }
+    expect(canMerge(run2).allowed).toBe(true)
+  })
+
+  it("blocks when some tasks not merged", () => {
+    const run = withTask(runningRun(), { id: "a", status: "merged", dependsOn: [], expectedFiles: [] } as any)
+    const run2 = withTask(run, { id: "b", status: "running", dependsOn: [], expectedFiles: [] } as any)
+    expect(canMerge(run2).allowed).toBe(false)
+    expect(canMerge(run2).reason).toContain("all tasks merged")
+  })
+
+  it("blocks when no tasks exist", () => {
+    expect(canMerge(runningRun()).allowed).toBe(false)
+  })
+
+  it("blocks when flow is not in mergeable state", () => {
+    const run = withTask(runningRun(), { id: "a", status: "merged", dependsOn: [], expectedFiles: [] } as any)
+    const run2 = { ...run, status: "completed" as const }
+    expect(canMerge(run2).allowed).toBe(false)
+  })
+
+  // 新语义：不再要求 review stage pass
+  it("allows merge even when review stage is not pass", () => {
+    const run = withTask(runningRun(), { id: "a", status: "merged", dependsOn: [], expectedFiles: [] } as any)
+    const run2 = withStage(run, "review", "pending")
+    // review stage pending 不应阻止 canMerge
+    expect(canMerge(run2).allowed).toBe(true)
   })
 })