agentflowctl 0.9.0 → 0.10.0

package/README.md

@@ -3,7 +3,7 @@
 讓 Claude Code、Codex、Gemini CLI（或任何 agent CLI）在同一條流程裡輪流寫規格、寫計畫、寫測試、寫實作、互相審查、互相修正，一路做到開 PR。
 
 ```
-需求 → spec → plan ⇄ plan_review ⇄ plan_fix →（僵持時）仲裁 → implement（測試 A → 實作 B）→ verify ⇄ fix → review ⇄ fix → pr
+需求 → spec → plan ⇄ plan_review ⇄ plan_fix →（僵持時）仲裁 → implement（每個任務：測試 A → 實作 B → 任務審查 ⇄ 修正 → 任務驗證 ⇄ 修正）→ verify ⇄ fix → review ⇄ fix → pr
 ```
 
 從需求到 PR 全程由程式推進。每個步驟都是一次獨立的 agent 執行，用 `.flow/` 裡的檔案交接。是否通過一律由程式檢查：跑測試、比對 git diff、驗證 JSON。兩家模型就能完整運作；有第三家時，仲裁會交給沒參與討論的那一家。
@@ -120,7 +120,7 @@ agentflowctl clean --all           # 清掉所有已結束的 run 與中斷留
 | `--manual-plan` | 計畫通過審查後進入 `awaiting_approval`，等 `approve` 才開始實作 |
 | `-v` / `--verbose` | 執行時印出 agent 的文字、工具呼叫與專案指令；`run`、`resume`、`approve` 都適用，也可設 `AGENTFLOWCTL_VERBOSE=1` |
 
-`status` 會列出任務。進行中的任務會標出正在寫測試還是正在寫實作。
+`status` 會列出任務。進行中的任務會標出目前的步驟：🧪 寫測試、🛠️ 寫實作、👀 任務審查、🔍 任務驗證、🩹 任務修正。
 
 ### 清除 worktree
 
@@ -268,7 +268,7 @@ run 因 Ctrl-C、失敗、額度暫停或等待核准而停下時，終端機會
 | `defaultModels` | `{}` | 依 `claude`、`codex`、`gemini` adapter 指定全域預設 model；agent 的 `model` 優先，兩者都沒設時使用各 CLI 的預設。`command` adapter 不套用 |
 | `fixStrategy` | `ring` | `ring`：審查意見隨機交給審查者以外的一家；`author`：交回最後作者 |
 | `tddSplit` | `true` | 測試與實作是否分開 |
-| `reviewQuorum` | `1` | 程式碼需要幾位不同審查者都 `approve` |
+| `reviewQuorum` | `1` | 程式碼需要幾位不同審查者都 `approve`（任務審查與最後的程式碼審查都適用） |
 | `planReviewQuorum` | `1` | 計畫需要幾位不同審查者都 `approve` |
 | `planArbiter` | `true` | 計畫審查僵持時交付仲裁。關掉之後，僵持會直接讓 run 失敗 |
 | `tieBreak` | `proceed` | 兩家仲裁意見分歧時：`proceed` 繼續並記錄爭議；`stop` 停下 |
@@ -337,7 +337,7 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 | 兩家 | 兩家各自在全新 context 裡判斷 | 都核准就繼續；都不核准就依裁決意見修訂並重新審查；分歧依 `tieBreak` |
 | 一家 | 同一家 | 由它自己仲裁 |
 
-兩家時的仲裁是雙盲的。仲裁者只看計畫，以及一份不含審查者名稱的爭議清單（`.flow/dispute.md`）。爭議清單用 `<issue>` 包住每則意見；給修訂者的 `.flow/feedback.md` 則用 `<opinion author="…">` 包住每位審查者的意見，避免意見內文與外層結構混淆。帶有名稱的審查紀錄移到 worktree 以外。`tieBreak` 預設 `proceed`，因為後面還有測試紅燈、綠燈、verify 與程式碼審查。
+兩家時的仲裁是雙盲的。仲裁者只看計畫，以及一份不含審查者名稱的爭議清單（`.flow/dispute.md`）。爭議清單用 `<issue>` 包住每則意見；給修訂者的 `.flow/feedback.md` 則用 `<opinion author="…">` 包住每位審查者的意見，避免意見內文與外層結構混淆。帶有名稱的審查紀錄移到 worktree 以外。`tieBreak` 預設 `proceed`，因為後面還有測試紅燈、綠燈、任務審查、verify 與程式碼審查。
 
 計畫定案或仲裁最終停止時，裁決與每位仲裁者的理由附在 `plan.md` 最後的「仲裁紀錄」。需再修訂時，裁決理由寫進 `.flow/feedback.md`，供修訂者處理；重新審查會從第一輪計數。原始審查與每輪仲裁紀錄在 `.agentflowctl/runs/<id>/reviews/`。兩家都要求修改時不因仲裁輪數而直接失敗；整個 run 仍受 `maxAgentRuns` 限制。
 
@@ -355,6 +355,9 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 | 人工確認 | 你（只有 `--manual-plan`） | `agentflowctl approve` | — |
 | implement 紅燈 | 洗牌輪流，每家各一次 | 有測試變更，而且測試執行後失敗；規格與計畫檔沒有被修改 | 還原並重試 |
 | implement 綠燈 | 測試作者以外隨機一位 | 測試檔與規格、計畫檔都沒有被修改，而且測試通過 | 還原，或帶著輸出重試 |
+| implement 任務審查 | 作者以外隨機挑（可多位，不重複） | 所有審查者都 `approve` 這個任務的變更 | 進入任務修正 |
+| implement 任務驗證 | — | `install` 與所有 `checks` 通過，才換下一個任務 | 進入任務修正 |
+| implement 任務修正 | 與 fix 相同 | 與 fix 相同；修完重新任務審查、任務驗證 | 還原並重試 |
 | verify | — | `install` 與所有 `checks` 通過 | 交回作者修正 |
 | fix | verify 失敗交回作者；審查意見依 `fixStrategy` | 沒有刪除測試檔，也沒有修改規格與計畫檔 | 還原並重試 |
 | review | 作者以外隨機挑（可多位，不重複） | 所有審查者都 `approve`（審查者對程式碼與規格、計畫檔的修改一律還原） | 依 `fixStrategy` 交給他人修正 |
@@ -363,11 +366,12 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 驗收條件寫在 `.flow/acceptance.json`（`AC-1`…），任務寫在 `.flow/tasks.json`（`T-1`…）。
 每個任務的寫測試與寫實作 prompt 只帶入該任務對應的驗收條件；agent 優先讀任務與相關程式碼，遇到資訊不足或矛盾才查規格、計畫的相關段落。agent 可先跑相關測試，紅燈與完整測試仍由外部流程執行與判定，減少重複讀取文件和全套測試輸出所用的 token。
 計畫定案後（實作、修正、程式碼審查）不可修改 `.flow/` 裡的規格與計畫檔（`spec.md`、`acceptance.json`、`plan.md`、`tasks.json`、`tasks.ordered.json`）；實作與修正時被改就還原並重試，因為寫出的程式碼可能依賴被改過的規格，必須重寫；審查者只交出審查結果，修改直接還原即可，不必重跑審查。對規格有疑慮要寫進交接事項。
+每個任務綠燈後先做任務審查：審查者只看這個任務寫測試前到目前的 diff（`.flow/diff.patch`）與這個任務的驗收條件，審查紀錄存成 `.flow/review-<任務>-<審查者>.json`。審查者避開最後實作者；有第三家可選時，也優先避開測試作者，只有兩家或審查人數不足時才由測試作者審查。任務審查不要求結清所有交接事項（可能屬於後面的任務），最後的程式碼審查才會擋。審查通過後執行任務驗證（與 verify 相同的 `install` 與 `checks`）。審查要求修改或驗證失敗都進入任務修正，修正者的挑法與 fix 相同，修完回到任務審查再驗證。審查執行或任務修正若先失敗、後成功，會清除各自的連續失敗次數。所有任務完成後，仍照原本流程對整份變更跑一次 verify 與程式碼審查。
 程式碼審查仍逐條核對所有驗收條件，但只在 `review.json` 列出未通過或其他重要問題；先看 diff 與相關檔案，驗收條件不清楚時才查規格。修正階段先依 `feedback.md` 定位問題並執行相關檢查，完整檢查仍由後續 verify 執行，以減少反覆讀取完整文件與測試輸出。
 
 ## Prompt 結構
 
-每個階段的 prompt 都有專屬角色：需求分析師、軟體架構師、計畫審查者、計畫修訂者、中立仲裁者、測試工程師、實作工程師、除錯工程師、程式碼審查者。內容用 XML 標籤分段：`<role>`、`<context>`、`<inputs>`、`<steps>`、`<constraints>`、`<output_format>`、`<reply_format>`。
+每個階段的 prompt 都有專屬角色：需求分析師、軟體架構師、計畫審查者、計畫修訂者、中立仲裁者、測試工程師、實作工程師、任務審查者、除錯工程師、程式碼審查者。內容用 XML 標籤分段：`<role>`、`<context>`、`<inputs>`、`<steps>`、`<constraints>`、`<output_format>`、`<reply_format>`。
 
 Agent 的最後回覆要附上 XML 中繼資料：
 

package/dist/cli.js

@@ -88,6 +88,8 @@ async function resolveCycle(flag) {
         throw new Error(`設定的 agent（${defined.join("、")}）都沒有偵測到已安裝的 CLI，可用 agentflowctl doctor 檢查`);
     return found;
 }
+/** status 任務清單中，進行中任務的標記 */
+const TASK_PHASE_MARK = { tests: "🧪", code: "🛠️ ", review: "👀", verify: "🔍", fix: "🩹" };
 const program = new Command()
     .name("agentflowctl")
     .description("在專案資料夾內執行的 Agent 開發流程：規格 → 計畫 → TDD 實作 → 驗證 → 審查 → PR")
@@ -228,7 +230,7 @@ program
     console.log("\n任務");
     tasks.data.forEach((t, i) => {
         const active = i === run.taskIndex && run.stage === "implement";
-        const mark = i < run.taskIndex ? "✅" : active ? (run.taskPhase === "tests" ? "🧪" : "🛠️ ") : "⬜";
+        const mark = i < run.taskIndex ? "✅" : active ? TASK_PHASE_MARK[run.taskPhase] : "⬜";
         console.log(`  ${mark} ${t.id} ${t.title}`);
     });
 });

package/dist/engine.js

@@ -433,6 +433,12 @@ async function implementStage(run) {
     if (!acceptance.ok)
         throw new Error(acceptance.error);
     const acceptanceJson = JSON.stringify(taskAcceptance(task, acceptance.data), null, 2);
+    if (run.taskPhase === "review")
+        return taskReviewStep(run, task, progress, taskJson, acceptanceJson);
+    if (run.taskPhase === "verify")
+        return taskVerifyStep(run, task, progress);
+    if (run.taskPhase === "fix")
+        return taskFixStep(run, task, progress);
     const agents = taskAgents(run.cycle, run.taskIndex, cfg.tddSplit, run.id);
     // ── 紅燈：只寫測試，而且測試必須失敗 ──
     if (run.taskPhase === "tests") {
@@ -471,7 +477,7 @@ async function implementStage(run) {
         }
         writeFileSync(flowFile(run, "red-output.txt"), red.output);
         info(run, `🔴 [${progress}] 測試如預期失敗`);
-        return { ...succeed(run, key, "implement"), taskPhase: "code", testsCommit: commit, lastTestsAuthor: testsAuthor };
+        return { ...succeed(run, key, "implement"), taskPhase: "code", taskBase: before, testsCommit: commit, lastTestsAuthor: testsAuthor };
     }
     // ── 綠燈：實作到測試通過，而且不可動測試 ──
     const key = `${task.id}:code`;
@@ -506,28 +512,83 @@ async function implementStage(run) {
         await resetTo(repo, testsCommit);
         return retry(run, key, handoffError, "implement");
     }
-    info(run, `🟢 [${progress}] 完成`);
+    info(run, `🟢 [${progress}] 測試通過`);
+    return { ...succeed(run, key, "implement"), taskPhase: "review", lastWriter: codeAuthor };
+}
+// ── 任務審查：只看這個任務的變更與驗收條件 ──
+async function taskReviewStep(run, task, progress, taskJson, acceptanceJson) {
+    const key = `${task.id}:review`;
+    const base = run.taskBase ?? (run.testsCommit && `${run.testsCommit}~1`);
+    if (!base)
+        throw new Error("缺少 taskBase，狀態不一致");
+    const result = await codeReview(run, {
+        base,
+        seed: `${run.id}:review:${task.id}:${run.attempts[key] ?? 0}`,
+        label: `[${progress}] 任務審查`,
+        step: `${task.id}-review`,
+        prompt: (reviewer, authors) => renderPrompt("task-review", { reviewer, authors, task: taskJson, acceptance: acceptanceJson }),
+        saveAs: (reviewer) => `review-${task.id}-${reviewer}.json`,
+        testAuthor: run.lastTestsAuthor,
+        // 未結交接事項可能屬於後面的任務，由最後的整體審查把關
+        gate: false,
+        runKey: `${task.id}:review-run`,
+        backTo: "implement",
+    });
+    if ("run" in result)
+        return result.run;
+    const reviewed = succeed(run, `${task.id}:review-run`, "implement");
+    if (!result.objector)
+        return { ...succeed(reviewed, key, "implement"), taskPhase: "verify" };
+    return {
+        ...retry(reviewed, key, `任務審查要求修改：\n\n${result.issues.join("\n\n")}`, "implement"),
+        taskPhase: "fix",
+        fixSource: "review",
+        lastReviewer: result.objector,
+    };
+}
+// ── 任務驗證：通過才進入下一個任務 ──
+async function taskVerifyStep(run, task, progress) {
+    const key = `${task.id}:verify`;
+    info(run, `🔍 [${progress}] 執行驗證`);
+    const report = await runChecks(run, `${task.id}-`);
+    if (report)
+        return { ...retry(run, key, report, "implement"), taskPhase: "fix", fixSource: "verify" };
+    info(run, `✅ [${progress}] 完成`);
     return {
         ...succeed(run, key, "implement"),
         taskIndex: run.taskIndex + 1,
         taskPhase: "tests",
+        taskBase: undefined,
         testsCommit: undefined,
         lastTestsAuthor: undefined,
-        lastWriter: codeAuthor,
     };
 }
-async function verifyStage(run) {
-    info(run, "🔍 執行驗證");
+// ── 任務修正：修完重新審查、驗證 ──
+async function taskFixStep(run, task, progress) {
+    const result = await applyFix(run, {
+        seed: `${run.id}:fix:${task.id}:${run.attempts[`${task.id}:review`] ?? 0}`,
+        label: `[${progress}] `,
+        step: `${task.id}-fix`,
+        commitScope: `fix(${task.id})`,
+        key: `${task.id}:fix`,
+        backTo: "implement",
+    });
+    if ("run" in result)
+        return result.run;
+    return { ...succeed(run, `${task.id}:fix`, "implement"), taskPhase: "review", lastWriter: result.agent };
+}
+/** 執行 install 與所有 checks，結果寫入 verify.json；有失敗時回傳給修正者的報告 */
+async function runChecks(run, stepPrefix = "") {
     const cfg = loadRepoConfig();
     const results = [];
-    const install = await runCommand(target(run, "install", CMD_AGENT), cfg.install);
+    const install = await runCommand(target(run, `${stepPrefix}install`, CMD_AGENT), cfg.install);
     if (!install.ok) {
         info(run, `   ✗ install${logHint(run, install.seq)}`);
         results.push({ name: "install", ok: false, output: tail(install.output) });
     }
     else {
         for (const check of cfg.checks) {
-            const r = await runCommand(target(run, check.name, CMD_AGENT), check.cmd);
+            const r = await runCommand(target(run, `${stepPrefix}${check.name}`, CMD_AGENT), check.cmd);
             info(run, `   ${r.ok ? "✓" : "✗"} ${check.name}${r.ok ? "" : logHint(run, r.seq)}`);
             results.push({ name: check.name, ok: r.ok, output: tail(r.output, 3000) });
         }
@@ -535,11 +596,18 @@ async function verifyStage(run) {
     writeFileSync(flowFile(run, "verify.json"), JSON.stringify(results, null, 2));
     const failed = results.filter((r) => !r.ok);
     if (failed.length === 0)
+        return undefined;
+    return failed.map((f) => `## ${f.name} 失敗\n\n\`\`\`\n${f.output}\n\`\`\``).join("\n\n");
+}
+async function verifyStage(run) {
+    info(run, "🔍 執行驗證");
+    const report = await runChecks(run);
+    if (!report)
         return succeed(run, "verify", "review");
-    const report = failed.map((f) => `## ${f.name} 失敗\n\n\`\`\`\n${f.output}\n\`\`\``).join("\n\n");
     return { ...retry(run, "verify", report, "fix"), fixSource: "verify" };
 }
-async function fixStage(run) {
+/** 修正驗證錯誤或審查意見；成功時回傳實際修正者，未通過時回傳重試後的 run */
+async function applyFix(run, opts) {
     const cfg = loadRepoConfig();
     const source = run.fixSource ?? "verify";
     const agent = fixAgent(run.cycle, {
@@ -547,55 +615,74 @@ async function fixStage(run) {
         strategy: cfg.fixStrategy,
         lastWriter: run.lastWriter,
         lastReviewer: run.lastReviewer,
-        seed: `${run.id}:fix:${run.attempts.review ?? 0}`,
+        seed: opts.seed,
     });
     const why = source === "review" ? `依 ${run.lastReviewer ?? "reviewer"} 的審查意見` : "修正驗證錯誤";
-    info(run, `🩹 ${why}（${agent}）`);
+    info(run, `🩹 ${opts.label}${why}（${agent}）`);
     const repo = worktreeDir(run.id);
     const feedback = readFeedback(run);
     const before = await headCommit(repo);
     const snap = snapshotPlan(run, LOCKED_FILES);
-    const outcome = await agentStep(run, agent, "fix", renderPrompt("fix", { testPattern: cfg.testPattern }), {
+    const outcome = await agentStep(run, agent, opts.step, renderPrompt("fix", { testPattern: cfg.testPattern }), {
         kind: "write",
         reset: async () => { await resetTo(repo, before); restorePlan(run, snap); },
     });
     const { r, agent: actual } = outcome;
     const tampered = restorePlan(run, snap);
+    const again = (reason) => ({ run: retry(run, opts.key, reason, opts.backTo) });
     if (!r.ok)
-        return retry(run, "fix", `${feedback}\n\n（上次修正時 Agent 執行失敗：${r.summary}）`, "fix");
+        return again(`${feedback}\n\n（上次修正時 Agent 執行失敗：${r.summary}）`);
     if (tampered.length) {
         await resetTo(repo, before);
-        return retry(run, "fix", `${feedback}\n\n另外：${planTamperedMessage(tampered)}`, "fix");
+        return again(`${feedback}\n\n另外：${planTamperedMessage(tampered)}`);
     }
-    await commitAll(repo, `fix: ${why} [${actual}]`);
+    await commitAll(repo, `${opts.commitScope}: ${why} [${actual}]`);
     const testRe = new RegExp(cfg.testPattern);
     const deleted = (await changedFiles(repo, before, await headCommit(repo), "D")).filter((f) => testRe.test(f));
     if (deleted.length) {
         await resetTo(repo, before);
-        return retry(run, "fix", `${feedback}\n\n另外：不可刪除測試檔來讓檢查通過，已還原：${deleted.join(", ")}`, "fix");
+        return again(`${feedback}\n\n另外：不可刪除測試檔來讓檢查通過，已還原：${deleted.join(", ")}`);
     }
     const handoffError = finishHandoff(run, outcome, "writer");
     if (handoffError) {
         await resetTo(repo, before);
-        return retry(run, "fix", handoffError, "fix");
+        return again(handoffError);
     }
+    return { agent: actual };
+}
+async function fixStage(run) {
+    const result = await applyFix(run, {
+        seed: `${run.id}:fix:${run.attempts.review ?? 0}`,
+        label: "",
+        step: "fix",
+        commitScope: "fix",
+        key: "fix",
+        backTo: "fix",
+    });
+    if ("run" in result)
+        return result.run;
     // 修正者成為新的作者，下一輪審查會換成別人
-    return { ...to(run, "verify"), lastWriter: actual };
+    return { ...to(run, "verify"), lastWriter: result.agent };
 }
-async function reviewStage(run) {
+/**
+ * 由作者以外的審查小組審查 base 之後的變更；回傳第一位要求修改的審查者與所有意見，
+ * 審查本身未完成（執行失敗、格式錯誤、交接不合格）時回傳重試後的 run。
+ * gate 為 true 時，核准前必須結清所有程式碼類的未結交接事項。
+ */
+async function codeReview(run, opts) {
     const cfg = loadRepoConfig();
     const repo = worktreeDir(run.id);
-    const panel = reviewers(run.cycle, run.lastWriter, cfg.reviewQuorum, `${run.id}:review:${run.attempts.review ?? 0}`);
-    writeFileSync(flowFile(run, "diff.patch"), await git(repo, "diff", `${run.baseBranch}...HEAD`));
-    const authors = [...new Set((await git(repo, "log", "--format=%s", `${run.baseBranch}..HEAD`)).match(/\[[^\]]+\]$/gm) ?? [])]
+    const panel = reviewers(run.cycle, run.lastWriter, cfg.reviewQuorum, opts.seed, opts.testAuthor);
+    writeFileSync(flowFile(run, "diff.patch"), await git(repo, "diff", `${opts.base}...HEAD`));
+    const authors = [...new Set((await git(repo, "log", "--format=%s", `${opts.base}..HEAD`)).match(/\[[^\]]+\]$/gm) ?? [])]
         .map((s) => s.slice(1, -1));
     const issues = [];
-    let firstObjector;
+    let objector;
     for (const [slot, reviewer] of panel.entries()) {
-        info(run, `👀 程式碼審查（${reviewer}）`);
+        info(run, `👀 ${opts.label}（${reviewer}）`);
         rmSync(flowFile(run, "review.json"), { force: true });
         const snap = snapshotPlan(run, LOCKED_FILES);
-        const outcome = await agentStep(run, reviewer, "review", renderPrompt("review", { reviewer, authors: authors.join("、") || "未知" }), {
+        const outcome = await agentStep(run, reviewer, opts.step, opts.prompt(reviewer, authors.join("、") || "未知"), {
             kind: "review", slot, reset: async () => { await discardChanges(repo); restorePlan(run, snap); },
         });
         const { r } = outcome;
@@ -604,30 +691,47 @@ async function reviewStage(run) {
         if (tampered.length)
             info(run, `   ↩️  已還原審查者修改的檔案：${tampered.join(", ")}`);
         if (!r.ok)
-            return retry(run, "review-run", `Agent 執行失敗：${r.summary}`, "review");
+            return { run: retry(run, opts.runKey, `Agent 執行失敗：${r.summary}`, opts.backTo) };
         const review = readJsonFile(flowFile(run, "review.json"), ConsistentReviewResult);
         if (!review.ok)
-            return retry(run, "review-run", review.error, "review");
-        const handoffError = finishHandoff(run, outcome, "reviewer", { target: "code", verdict: review.data.verdict });
+            return { run: retry(run, opts.runKey, review.error, opts.backTo) };
+        const gate = opts.gate ? { target: "code", verdict: review.data.verdict } : undefined;
+        const handoffError = finishHandoff(run, outcome, "reviewer", gate);
         if (handoffError)
-            return retry(run, "review-run", handoffError, "review");
-        renameSync(flowFile(run, "review.json"), flowFile(run, `review-${reviewer}.json`));
+            return { run: retry(run, opts.runKey, handoffError, opts.backTo) };
+        renameSync(flowFile(run, "review.json"), flowFile(run, opts.saveAs(reviewer)));
         if (review.data.verdict === "approve") {
             info(run, `   ✓ ${reviewer} 核准`);
             continue;
         }
         info(run, `   ✗ ${reviewer} 要求修改`);
-        firstObjector ??= reviewer;
+        objector ??= reviewer;
         issues.push(opinion(reviewer, review.data.items
             .filter((i) => i.status !== "met")
             .map((i) => reviewIssue(i.criterion, i.status, i.note))));
     }
-    if (!firstObjector)
+    return { objector, issues };
+}
+async function reviewStage(run) {
+    const result = await codeReview(run, {
+        base: run.baseBranch,
+        seed: `${run.id}:review:${run.attempts.review ?? 0}`,
+        label: "程式碼審查",
+        step: "review",
+        prompt: (reviewer, authors) => renderPrompt("review", { reviewer, authors }),
+        saveAs: (reviewer) => `review-${reviewer}.json`,
+        gate: true,
+        runKey: "review-run",
+        backTo: "review",
+    });
+    if ("run" in result)
+        return result.run;
+    if (!result.objector)
         return succeed(run, "review", "pr");
     return {
-        ...retry(run, "review", `程式碼審查要求修改：\n\n${issues.join("\n\n")}`, "fix"),
+        ...retry(run, "review", `程式碼審查要求修改：\n\n${result.issues.join("\n\n")}`, "fix"),
         fixSource: "review",
-        lastReviewer: firstObjector,
+        lastReviewer: result.objector,
     };
 }
 async function prStage(run) {

package/dist/roles.js

@@ -64,9 +64,12 @@ export function taskAgents(cycle, taskIndex, tddSplit, seed) {
     const tests = taskBag(cycle, seed, Math.floor(taskIndex / n))[taskIndex % n];
     return { tests, code: tddSplit ? pick(cycle, `${seed}:code:${taskIndex}`, [tests]) : tests };
 }
-/** 隨機挑出 quorum 位彼此不重複、而且不是作者的 reviewer */
-export function reviewers(cycle, lastWriter, quorum, seed) {
-    const picked = shuffled(cycle.filter((c) => c !== lastWriter), seed).slice(0, quorum);
+/** 隨機挑出 quorum 位彼此不重複、而且不是最後作者的 reviewer；任務審查優先避開測試作者 */
+export function reviewers(cycle, lastWriter, quorum, seed, testAuthor) {
+    const candidates = shuffled(cycle.filter((c) => c !== lastWriter), seed);
+    const preferred = testAuthor ? candidates.filter((c) => c !== testAuthor) : candidates;
+    const fallback = testAuthor ? candidates.filter((c) => c === testAuthor) : [];
+    const picked = [...preferred, ...fallback].slice(0, quorum);
     return picked.length ? picked : [lastWriter ?? cycle[0]];
 }
 /**

package/dist/schemas.js

@@ -172,7 +172,10 @@ export const FlowRun = z.object({
     /** 各關卡的連續失敗次數 */
     attempts: z.record(z.string(), z.number()),
     taskIndex: z.number().int().nonnegative(),
-    taskPhase: z.enum(["tests", "code"]),
+    /** 目前任務進行到哪一步：寫測試 → 實作 → 審查 → 驗證，審查或驗證未通過時進入修正 */
+    taskPhase: z.enum(["tests", "code", "review", "verify", "fix"]),
+    /** 目前任務寫測試前的 commit，任務審查只看這之後的變更 */
+    taskBase: z.string().optional(),
     testsCommit: z.string().optional(),
     /** 目前任務的測試實際由誰撰寫（可能是代打） */
     lastTestsAuthor: z.string().optional(),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentflowctl",
   "license": "MIT",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "跨廠商 AI 開發 harness：Claude Code、Codex、Gemini 輪流實作、審查、修正",
   "keywords": [
     "ai",

package/prompts/task-review.md

@@ -0,0 +1,77 @@
+<role>
+你是任務審查者（{{reviewer}}），負責在單一任務完成後、進入下一個任務前，獨立審查這個任務的變更。本任務的作者：{{authors}}。若你曾撰寫本任務的測試，仍須重新檢查測試是否真正驗證驗收條件；不要預設測試或實作正確。
+</role>
+
+<context>
+目前的工作目錄就是專案（agentflowctl 為這次任務建立的專用 git worktree）。這個任務的測試已由外部流程確認通過；完整的自動化檢查會在你審查之後才執行，所有任務完成後還有一次整體審查。
+</context>
+
+<handoff>
+先閱讀 .flow/handoff-context.md，處理與本任務有關的待辦事項；與本任務無關的事項留給後續任務或整體審查。完成時寫入 .flow/handoff-response.json；即使沒有事項也必須寫出空陣列：
+
+```json
+{ "newIssues": [], "dispositions": [] }
+```
+
+新增事項格式：{ "kind": "action 或 info", "summary": "具體問題", "evidence": "檔案位置或檢查證據", "targetStage": "plan 或 code" }。
+處置格式：{ "id": "既有事項 ID", "status": "proposed_resolved、resolved 或 accepted", "reason": "具體處理理由", "evidence": "檔案、commit 或檢查結果" }。撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+</handoff>
+
+<inputs>
+<task>
+{{task}}
+</task>
+
+<acceptance>
+{{acceptance}}
+</acceptance>
+
+- 本任務的變更：.flow/diff.patch（先看變更，再按需讀相關程式碼與測試）
+- 規格與計畫：.flow/spec.md、.flow/plan.md（任務或驗收條件不清楚、互相矛盾時，才查相關段落）
+</inputs>
+
+<review_focus>
+1. 逐條確認上面每個驗收條件是否真的被實作，而且有對應的測試真正驗證它（不是空洞的測試）。
+2. 是否有明顯的錯誤、邊界情況遺漏、安全問題或效能問題。
+3. 是否符合專案既有的架構與慣例，以及任務說明的範圍（沒有做到一半，也沒有做了其他任務的事）。
+
+只審查本任務的變更；其他任務的驗收條件不在這次審查範圍內。先根據 diff 與驗收條件定位需要查閱的檔案，只在證據不足時讀取其他檔案。不必為了審查重跑全套檢查。
+
+風格偏好與無關緊要的小問題不需要要求修改。
+</review_focus>
+
+<output_format>
+寫入 .flow/review.json：
+
+```json
+{
+  "verdict": "changes_requested",
+  "items": [
+    { "criterion": "AC-1", "status": "not_met", "note": "src/form.tsx 缺少 API 失敗時的錯誤訊息，請在 catch 中顯示錯誤並補測試" }
+  ]
+}
+```
+
+- `verdict`：逐條核對本任務的驗收條件後，全部通過且沒有嚴重問題時為 `approve`，否則為 `changes_requested`。
+- `items` 只列未通過的驗收條件與額外發現的重要問題，每筆的 `status` 為 `not_met` 或 `partial`，`note` 請寫出具體位置與修正方向。
+- `approve` 時 `items` 為空陣列；`changes_requested` 時至少要有一筆。兩者不一致會被視為格式錯誤並重新審查。
+</output_format>
+
+<constraints>
+- 只能寫入 .flow/review.json 與 .flow/handoff-response.json，不可修改任何程式碼，其他變更都會被捨棄。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明這次做了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>每個新增或修改的檔案路徑各一行</file>
+  </files_changed>
+  <concerns>對需求、規格、計畫或測試的疑慮；沒有就留空</concerns>
+</result>
+```
+</reply_format>