agentflowctl 0.5.0 → 0.6.0

package/README.md

@@ -307,12 +307,14 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 | 有幾家 | 誰來仲裁 | 結果 |
 | --- | --- | --- |
 | 三家以上 | 沒參與這次討論的那一家 | 核准就繼續，否則 run 失敗 |
-| 兩家 | 兩家各自在全新 context 裡判斷 | 都核准就繼續；都不核准就依裁決意見修訂並重新審查，仲裁達重試上限才停下；分歧依 `tieBreak` |
+| 兩家 | 兩家各自在全新 context 裡判斷 | 都核准就繼續；都不核准就依裁決意見修訂並重新審查；分歧依 `tieBreak` |
 | 一家 | 同一家 | 由它自己仲裁 |
 
 兩家時的仲裁是雙盲的。仲裁者只看計畫，以及一份不含模型名稱的爭議清單（`.flow/dispute.md`）。帶有名稱的審查紀錄移到 worktree 以外。`tieBreak` 預設 `proceed`，因為後面還有測試紅燈、綠燈、verify 與程式碼審查。
 
-計畫定案或仲裁最終停止時，裁決與每位仲裁者的理由附在 `plan.md` 最後的「仲裁紀錄」。需再修訂時，裁決理由寫進 `.flow/feedback.md`，供修訂者處理；重新審查會從第一輪計數。原始審查與每輪仲裁紀錄在 `.agentflowctl/runs/<id>/reviews/`。仲裁最多進行 `AGENTFLOWCTL_MAX_ATTEMPTS` 次，預設三次。
+計畫定案或仲裁最終停止時，裁決與每位仲裁者的理由附在 `plan.md` 最後的「仲裁紀錄」。需再修訂時，裁決理由寫進 `.flow/feedback.md`，供修訂者處理；重新審查會從第一輪計數。原始審查與每輪仲裁紀錄在 `.agentflowctl/runs/<id>/reviews/`。兩家都要求修改時不因仲裁輪數而直接失敗；整個 run 仍受 `maxAgentRuns` 限制。
+
+仲裁 JSON 的 `verdict` 應為 `approve` 或 `changes_requested`；若模型寫成 `reject`，程式會當成 `changes_requested` 並保留理由。缺少檔案、JSON 格式錯誤或其他不合法輸出不算反對票，run 會暫停並顯示驗證錯誤；檢查 `agentflowctl logs <id>` 與 `.flow/plan-arbiter.json` 後可用 `resume` 重新執行。
 
 ## 階段與通過條件
 
@@ -322,7 +324,7 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 | plan | 與 spec 同一位 | zod、相依存在、無循環、每條驗收條件都有任務 | 重試 |
 | plan_review | 計畫作者以外隨機挑（可多位，不重複） | 所有審查者都 `approve` | 進入 plan_fix |
 | plan_fix | 依 `fixStrategy` | 修改後仍通過 plan 的格式與 DAG 檢查 | 還原並重試 |
-| 仲裁 | 見上一節 | 一致核准；分歧依 `tieBreak` | 兩家都不核准時先進入 plan_fix，達仲裁上限才失敗；第三方不核准或 `tieBreak: stop` 時失敗 |
+| 仲裁 | 見上一節 | 一致核准；分歧依 `tieBreak` | 兩家都不核准時進入 plan_fix 再審查；第三方不核准或 `tieBreak: stop` 時失敗 |
 | 人工確認 | 你（只有 `--manual-plan`） | `agentflowctl approve` | — |
 | implement 紅燈 | 洗牌輪流，每家各一次 | 有測試變更，而且測試執行後失敗 | 還原並重試 |
 | implement 綠燈 | 測試作者以外隨機一位 | 測試檔沒有任何修改，而且測試通過 | 還原，或帶著輸出重試 |
@@ -349,6 +351,14 @@ Agent 的最後回覆要附上 XML 中繼資料：
 
 `blocked` 與 `concerns` 會印在終端機上，完整回覆留在 log，可用 `agentflowctl logs` 查看。這份中繼資料只給人看；缺少或格式錯誤都不影響流程，是否通過仍由上表的程式檢查決定。
 
+### Agent 交接紀錄
+
+每次 agent 執行前，程式會把與當前階段有關的未結事項寫入 `.flow/handoff-context.md`。agent 完成時必須寫 `.flow/handoff-response.json`，包含 `newIssues` 和 `dispositions` 兩個陣列；沒有事項也要明確寫成 `{ "newIssues": [], "dispositions": [] }`。缺少檔案或 JSON 格式不合法，會依該步驟的重試規則處理。
+
+程式只在原有關卡通過後接收交接回覆，並將正式紀錄原子儲存於 `.agentflowctl/runs/<id>/handoff.json`。`action` 是需要後續處理的事項；`info` 只供參考。作者只能提出已修正並附證據，審查者才能確認結案或附理由接受。XML `<concerns>` 可以供人閱讀，但重要疑慮必須寫進交接 JSON，才能交給下一位 agent。額度代打與重試不會接收失敗呼叫的交接內容；中斷後可用 `resume` 接續。
+
+計畫審查或程式碼審查若核准，但該階段仍有未結的 `action`，程式會視為互相矛盾的審查結果並重試。計畫定案和開 PR 前也會再檢查一次；`info` 會提供給目標階段閱讀，但不阻擋通關。
+
 ## Adapter
 
 | adapter | 執行方式 | 權限 |

package/dist/arbitration.js

@@ -1,10 +1,12 @@
-/** 仲裁沒有共識時，兩家先依裁決意見修訂計畫；重複仲裁仍受次數上限約束。 */
-export function arbitrationDecision(verdicts, tieBreak, round, maxAttempts) {
+/** 兩家仲裁都要求修改時交回計畫修訂；整體執行次數由 maxAgentRuns 限制。 */
+export function arbitrationDecision(verdicts, tieBreak) {
+    if (verdicts.includes("abstain"))
+        return "invalid";
     const approvals = verdicts.filter((v) => v === "approve").length;
     if (approvals === verdicts.length)
         return "proceed";
     if (approvals > 0)
         return tieBreak;
-    return verdicts.length === 2 && round < maxAttempts ? "revise" : "stop";
+    return verdicts.length === 2 ? "revise" : "stop";
 }
 //# sourceMappingURL=arbitration.js.map

package/dist/engine.js

@@ -5,12 +5,13 @@ import { config } from "./config.js";
 import { arbitrationDecision } from "./arbitration.js";
 import { detectProjectDefaults, withProjectDefaults } from "./detect.js";
 import { changedFiles, commitAll, discardChanges, git, headCommit, resetTo } from "./git.js";
+import { acceptHandoff, openActions, prepareHandoff, previewHandoff, readHandoff, recoverHandoff, reviewHandoffGate, validateHandoffResponse } from "./handoff.js";
 import { flowDir, logDir, projectRoot, runDir, worktreeDir } from "./paths.js";
 import { CMD_AGENT, nextLogFile } from "./logs.js";
 import { exec } from "./proc.js";
 import { arbiterPanel, availableAgent, fixAgent, planAgent, planFixAgent, reviewers, specAgent, taskAgents } from "./roles.js";
 import { resolveAgent, runAgent, runCommand } from "./runner.js";
-import { AcceptanceList, RepoConfig, ReviewResult, TaskList, } from "./schemas.js";
+import { AcceptanceList, ArbiterResult, RepoConfig, ReviewResult, TaskList, } from "./schemas.js";
 import { addSubstitution, addUsage, agentRuns, saveRun } from "./store.js";
 import { orderTasks } from "./tasks.js";
 import { readJsonFile, renderPrompt, tail } from "./util.js";
@@ -30,6 +31,14 @@ export class QuotaPause extends Error {
 }
 /** 這次執行中已確認額度用完的 agent；程序結束即清空，resume 時會重新嘗試 */
 const exhausted = new Set();
+function handoffTarget(run) {
+    return ["spec", "plan", "plan_review", "plan_fix"].includes(run.stage) ? "plan" : "code";
+}
+/** 同一輪重跑使用相同 key；重試次數或 panel 位置改變時使用新 key。 */
+function handoffKey(run, step, slot, agent) {
+    const attempts = Object.entries(run.attempts).sort(([a], [b]) => a.localeCompare(b));
+    return JSON.stringify([run.id, run.stage, step, run.taskIndex, run.taskPhase, attempts, slot, agent]);
+}
 async function agentStep(run, planned, step, prompt, mode) {
     const cfg = loadRepoConfig();
     const reset = mode.reset ?? (() => discardChanges(worktreeDir(run.id)));
@@ -47,11 +56,13 @@ async function agentStep(run, planned, step, prompt, mode) {
             info(run, `🔁 ${agent} 額度已用完，${step} 由 ${sub} 代打${note ? `（注意：${note}）` : ""}`);
             agent = sub;
         }
+        const callKey = handoffKey(run, step, mode.slot ?? 0, agent);
+        prepareHandoff(run.id, callKey, handoffTarget(run), mode.blind ?? false);
         const r = await runAgent(agent, resolveAgent(cfg, agent), target(run, step, agent), prompt);
         addUsage(run.id, { stage: step, agent, inputTokens: r.inputTokens, outputTokens: r.outputTokens });
         if (!r.quotaExhausted) {
             reportMeta(run, agent, r);
-            return { r, agent };
+            return { r, agent, step, callKey };
         }
         info(run, `⛽ ${agent} 的額度已用完`);
         exhausted.add(agent);
@@ -59,6 +70,28 @@ async function agentStep(run, planned, step, prompt, mode) {
         // 迴圈回到開頭：review 會停下，write 會找代打
     }
 }
+/** 原有關卡已通過後才接受交接；失敗回覆不進入正式紀錄。 */
+function finishHandoff(run, outcome, role, gate) {
+    const parsed = validateHandoffResponse(run.id);
+    if (!parsed.ok)
+        return parsed.error;
+    try {
+        const source = {
+            stage: run.stage, step: outcome.step, agent: outcome.agent, callKey: outcome.callKey,
+        };
+        const preview = previewHandoff(readHandoff(run.id), outcome.callKey, source, parsed.data, role);
+        if (gate) {
+            const error = reviewHandoffGate(preview, gate.target, gate.verdict);
+            if (error)
+                return error;
+        }
+        acceptHandoff(run.id, outcome.callKey, source, parsed.data, role);
+        return undefined;
+    }
+    catch (error) {
+        return error.message;
+    }
+}
 /** 印出回覆裡的 XML 中繼資料；只供人檢視，關卡仍由程式檢查決定 */
 function reportMeta(run, agent, r) {
     if (!r.meta)
@@ -113,7 +146,8 @@ function loadOrderedTasks(run) {
 async function specStage(run) {
     const agent = specAgent(run.cycle, run.id);
     info(run, `📝 產生規格（${agent}）`);
-    const { r } = await agentStep(run, agent, "spec", renderPrompt("spec", { requirement: run.requirement }), { kind: "write" });
+    const outcome = await agentStep(run, agent, "spec", renderPrompt("spec", { requirement: run.requirement }), { kind: "write" });
+    const { r } = outcome;
     await discardChanges(worktreeDir(run.id)); // 這個階段只允許寫 .flow/
     if (!r.ok)
         return retry(run, "spec", `Agent 執行失敗：${r.summary}`, "spec");
@@ -125,6 +159,9 @@ async function specStage(run) {
     const ids = ac.data.map((a) => a.id);
     if (new Set(ids).size !== ids.length)
         return retry(run, "spec", "驗收條件 id 有重複", "spec");
+    const handoffError = finishHandoff(run, outcome, "writer");
+    if (handoffError)
+        return retry(run, "spec", handoffError, "spec");
     return succeed(run, "spec", "plan");
 }
 // ── 規格與計畫檔案：審查者與仲裁者只能讀，不能改 ──
@@ -177,6 +214,9 @@ function announceTasks(run, ordered) {
 }
 /** 計畫定案後：預設直接開始實作；--manual-plan 時才停下來等人 */
 function planSettled(run, key) {
+    const pending = openActions(readHandoff(run.id), "plan");
+    if (pending.length)
+        return retry(run, "plan-handoff", `計畫仍有未結交接事項：${pending.map((item) => item.id).join("、")}`, "plan_fix");
     const next = run.autopilot ? "implement" : "awaiting_approval";
     const ordered = loadOrderedTasks(run);
     announceTasks(run, ordered);
@@ -192,13 +232,17 @@ async function planStage(run) {
     const agent = planAgent(run.cycle, run.id);
     info(run, `🗺️  拆解任務（${agent}）`);
     const cfg = loadRepoConfig();
-    const { r, agent: actual } = await agentStep(run, agent, "plan", renderPrompt("plan", { testPattern: cfg.testPattern }), { kind: "write" });
+    const outcome = await agentStep(run, agent, "plan", renderPrompt("plan", { testPattern: cfg.testPattern }), { kind: "write" });
+    const { r, agent: actual } = outcome;
     await discardChanges(worktreeDir(run.id));
     if (!r.ok)
         return retry(run, "plan", `Agent 執行失敗：${r.summary}`, "plan");
     const ordered = validatePlan(run);
     if (typeof ordered === "string")
         return retry(run, "plan", ordered, "plan");
+    const handoffError = finishHandoff(run, outcome, "writer");
+    if (handoffError)
+        return retry(run, "plan", handoffError, "plan");
     acceptPlan(run, ordered);
     rmSync(flowFile(run, "plan-review-last.txt"), { force: true });
     return { ...succeed(run, "plan", "plan_review"), planWriter: actual };
@@ -215,7 +259,8 @@ async function planReviewStage(run) {
         info(run, `🧐 計畫審查第 ${round} 輪（${reviewer}，作者 ${author}）`);
         const snap = snapshotPlan(run);
         rmSync(flowFile(run, "plan-review.json"), { force: true });
-        const { r } = await agentStep(run, reviewer, "plan-review", renderPrompt("plan-review", { reviewer, author, requirement: run.requirement }), { kind: "review", reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); } });
+        const outcome = await agentStep(run, reviewer, "plan-review", renderPrompt("plan-review", { reviewer, author, requirement: run.requirement }), { kind: "review", slot: panel.indexOf(reviewer), reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); } });
+        const { r } = outcome;
         await discardChanges(worktreeDir(run.id));
         const tampered = restorePlan(run, snap);
         if (tampered.length)
@@ -225,6 +270,9 @@ async function planReviewStage(run) {
         const review = readJsonFile(flowFile(run, "plan-review.json"), ReviewResult);
         if (!review.ok)
             return retry(run, "plan-review-run", review.error, "plan_review");
+        const handoffError = finishHandoff(run, outcome, "reviewer", { target: "plan", verdict: review.data.verdict });
+        if (handoffError)
+            return retry(run, "plan-review-run", handoffError, "plan_review");
         // 審查紀錄移到 worktree 外面：之後的仲裁者看不到是哪一家提的意見
         mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
         renameSync(flowFile(run, "plan-review.json"), join(runDir(run.id), "reviews", `plan-review-${round}-${reviewer}.json`));
@@ -272,7 +320,8 @@ async function planFixStage(run) {
     info(run, `✏️  依 ${run.planReviewer ?? "審查者"} 的意見修改計畫（${agent}）`);
     const feedback = readFeedback(run);
     const snap = snapshotPlan(run);
-    const { r, agent: actual } = await agentStep(run, agent, "plan-fix", renderPrompt("plan-fix", { requirement: run.requirement, testPattern: cfg.testPattern }), { kind: "write", reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); } });
+    const outcome = await agentStep(run, agent, "plan-fix", renderPrompt("plan-fix", { requirement: run.requirement, testPattern: cfg.testPattern }), { kind: "write", reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); } });
+    const { r, agent: actual } = outcome;
     await discardChanges(worktreeDir(run.id)); // 只允許改 .flow/
     if (!r.ok) {
         restorePlan(run, snap);
@@ -283,6 +332,11 @@ async function planFixStage(run) {
         restorePlan(run, snap);
         return retry(run, "plan-fix", `${feedback}\n\n另外，修改後的計畫沒有通過格式檢查，已還原：\n${ordered}`, "plan_fix");
     }
+    const handoffError = finishHandoff(run, outcome, "writer");
+    if (handoffError) {
+        restorePlan(run, snap);
+        return retry(run, "plan-fix", handoffError, "plan_fix");
+    }
     acceptPlan(run, ordered);
     writeFileSync(flowFile(run, "feedback.md"), feedback); // 保留審查意見，讓下一輪審查者知道上次提了什麼
     const attempts = { ...run.attempts };
@@ -299,30 +353,38 @@ async function arbitratePlan(run) {
     const panel = arbiterPanel(run.cycle, `${run.id}:arbiter`, run.planWriter, run.planReviewer);
     const mode = panel.length > 1 ? "雙盲交叉仲裁" : "第三方仲裁";
     const verdicts = [];
-    for (const arbiter of panel) {
+    for (const [slot, arbiter] of panel.entries()) {
         info(run, `⚖️  ${mode}（${arbiter}）`);
         const snap = snapshotPlan(run);
         rmSync(flowFile(run, "plan-arbiter.json"), { force: true });
-        const { r } = await agentStep(run, arbiter, "plan-arbiter", renderPrompt("plan-arbiter", { requirement: run.requirement }), {
-            kind: "review",
+        const outcome = await agentStep(run, arbiter, "plan-arbiter", renderPrompt("plan-arbiter", { requirement: run.requirement }), {
+            kind: "review", slot, blind: true,
             reset: async () => { await discardChanges(worktreeDir(run.id)); restorePlan(run, snap); },
         });
+        const { r } = outcome;
         await discardChanges(worktreeDir(run.id));
         restorePlan(run, snap);
-        const result = r.ok ? readJsonFile(flowFile(run, "plan-arbiter.json"), ReviewResult) : undefined;
-        if (result?.ok) {
-            mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
-            renameSync(flowFile(run, "plan-arbiter.json"), join(runDir(run.id), "reviews", `plan-arbiter-${arbitrationRound}-${arbiter}.json`));
+        const result = r.ok ? readJsonFile(flowFile(run, "plan-arbiter.json"), ArbiterResult) : undefined;
+        const handoffError = result?.ok ? finishHandoff(run, outcome, "reviewer", { target: "plan", verdict: result.data.verdict }) : undefined;
+        if (!result?.ok || handoffError) {
+            const outputError = !r.ok ? `Agent 執行失敗：${r.summary}` : !result ? "未產生有效裁決" : result.ok ? "未產生有效裁決" : result.error;
+            const reason = handoffError ?? outputError;
+            info(run, `   ⏸️  ${arbiter} 未產生有效裁決：${reason}`);
+            return { ...run, stage: "paused", pausedStage: "plan_review", pauseReason: `${arbiter} 仲裁未產生有效裁決：${reason}` };
         }
-        const verdict = result?.ok ? result.data.verdict : "abstain";
-        const notes = result?.ok ? result.data.items.map((i) => `- ${i.criterion}：${i.note}`) : [`- 未產生有效裁決（${r.ok ? "輸出格式錯誤" : r.summary}）`];
-        info(run, `   ${verdict === "approve" ? "✓" : verdict === "abstain" ? "…" : "✗"} ${arbiter}：${verdict === "approve" ? "可以執行" : verdict === "abstain" ? "未裁決" : "不可執行"}`);
+        mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
+        renameSync(flowFile(run, "plan-arbiter.json"), join(runDir(run.id), "reviews", `plan-arbiter-${arbitrationRound}-${arbiter}.json`));
+        const verdict = result.data.verdict;
+        const notes = result.data.items.map((i) => `- ${i.criterion}：${i.note}`);
+        info(run, `   ${verdict === "approve" ? "✓" : "✗"} ${arbiter}：${verdict === "approve" ? "可以執行" : "不可執行"}`);
         verdicts.push({ arbiter, verdict, notes });
     }
     rmSync(flowFile(run, "dispute.md"), { force: true });
     const approvals = verdicts.filter((v) => v.verdict === "approve").length;
     const unanimous = approvals === verdicts.length;
-    const decision = arbitrationDecision(verdicts.map((v) => v.verdict), cfg.tieBreak, arbitrationRound, config.maxAttempts);
+    const decision = arbitrationDecision(verdicts.map((v) => v.verdict), cfg.tieBreak);
+    if (decision === "invalid")
+        throw new Error("仲裁結果缺少有效裁決");
     const summary = unanimous
         ? `${mode}一致核准`
         : approvals === 0
@@ -363,7 +425,8 @@ async function implementStage(run) {
         const key = `${task.id}:tests`;
         info(run, `🧪 [${progress}] 撰寫測試（${agents.tests}）`);
         const before = await headCommit(repo);
-        const { r, agent: testsAuthor } = await agentStep(run, agents.tests, `${task.id}-tests`, renderPrompt("implement-tests", { task: taskJson, testPattern: cfg.testPattern, testCmd }), { kind: "write", reset: () => resetTo(repo, before) });
+        const outcome = await agentStep(run, agents.tests, `${task.id}-tests`, renderPrompt("implement-tests", { task: taskJson, testPattern: cfg.testPattern, testCmd }), { kind: "write", reset: () => resetTo(repo, before) });
+        const { r, agent: testsAuthor } = outcome;
         if (!r.ok) {
             await resetTo(repo, before);
             return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement");
@@ -381,6 +444,11 @@ async function implementStage(run) {
             await resetTo(repo, before);
             return retry(run, key, "測試在功能尚未實作前就全部通過，代表測試沒有驗證到新行為。請撰寫會因功能尚未實作而失敗的測試。", "implement");
         }
+        const handoffError = finishHandoff(run, outcome, "writer");
+        if (handoffError) {
+            await resetTo(repo, before);
+            return retry(run, key, handoffError, "implement");
+        }
         writeFileSync(flowFile(run, "red-output.txt"), red.output);
         info(run, `🔴 [${progress}] 測試如預期失敗`);
         return { ...succeed(run, key, "implement"), taskPhase: "code", testsCommit: commit, lastTestsAuthor: testsAuthor };
@@ -392,7 +460,8 @@ async function implementStage(run) {
         throw new Error("缺少 testsCommit，狀態不一致");
     info(run, `🛠️  [${progress}] 實作（${agents.code}，測試由 ${run.lastTestsAuthor ?? agents.tests} 撰寫）`);
     const redOutput = existsSync(flowFile(run, "red-output.txt")) ? readFileSync(flowFile(run, "red-output.txt"), "utf8") : "";
-    const { r, agent: codeAuthor } = await agentStep(run, agents.code, `${task.id}-code`, renderPrompt("implement-code", { task: taskJson, testCmd, redOutput: tail(redOutput, 3000) }), { kind: "write", reset: () => resetTo(repo, testsCommit) });
+    const outcome = await agentStep(run, agents.code, `${task.id}-code`, renderPrompt("implement-code", { task: taskJson, testCmd, redOutput: tail(redOutput, 3000) }), { kind: "write", reset: () => resetTo(repo, testsCommit) });
+    const { r, agent: codeAuthor } = outcome;
     if (!r.ok)
         return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement");
     await commitAll(repo, `feat(${task.id}): ${task.title} [${codeAuthor}]`);
@@ -406,6 +475,11 @@ async function implementStage(run) {
         info(run, `   ✗ 測試仍未通過${logHint(run, green.seq)}`);
         return retry(run, key, `測試仍未通過：\n\n\`\`\`\n${tail(green.output)}\n\`\`\``, "implement");
     }
+    const handoffError = finishHandoff(run, outcome, "writer");
+    if (handoffError) {
+        await resetTo(repo, testsCommit);
+        return retry(run, key, handoffError, "implement");
+    }
     info(run, `🟢 [${progress}] 完成`);
     return {
         ...succeed(run, key, "implement"),
@@ -454,10 +528,11 @@ async function fixStage(run) {
     const repo = worktreeDir(run.id);
     const feedback = readFeedback(run);
     const before = await headCommit(repo);
-    const { r, agent: actual } = await agentStep(run, agent, "fix", renderPrompt("fix", { testPattern: cfg.testPattern }), {
+    const outcome = await agentStep(run, agent, "fix", renderPrompt("fix", { testPattern: cfg.testPattern }), {
         kind: "write",
         reset: () => resetTo(repo, before),
     });
+    const { r, agent: actual } = outcome;
     if (!r.ok)
         return retry(run, "fix", `${feedback}\n\n（上次修正時 Agent 執行失敗：${r.summary}）`, "fix");
     await commitAll(repo, `fix: ${why} [${actual}]`);
@@ -467,6 +542,11 @@ async function fixStage(run) {
         await resetTo(repo, before);
         return retry(run, "fix", `${feedback}\n\n另外：不可刪除測試檔來讓檢查通過，已還原：${deleted.join(", ")}`, "fix");
     }
+    const handoffError = finishHandoff(run, outcome, "writer");
+    if (handoffError) {
+        await resetTo(repo, before);
+        return retry(run, "fix", handoffError, "fix");
+    }
     // 修正者成為新的作者，下一輪審查會換成別人
     return { ...to(run, "verify"), lastWriter: actual };
 }
@@ -479,18 +559,22 @@ async function reviewStage(run) {
         .map((s) => s.slice(1, -1));
     const issues = [];
     let firstObjector;
-    for (const reviewer of panel) {
+    for (const [slot, reviewer] of panel.entries()) {
         info(run, `👀 程式碼審查（${reviewer}）`);
         rmSync(flowFile(run, "review.json"), { force: true });
-        const { r } = await agentStep(run, reviewer, "review", renderPrompt("review", { reviewer, authors: authors.join("、") || "未知" }), {
-            kind: "review",
+        const outcome = await agentStep(run, reviewer, "review", renderPrompt("review", { reviewer, authors: authors.join("、") || "未知" }), {
+            kind: "review", slot,
         });
+        const { r } = outcome;
         await discardChanges(repo); // 審查者不可改程式碼
         if (!r.ok)
             return retry(run, "review-run", `Agent 執行失敗：${r.summary}`, "review");
         const review = readJsonFile(flowFile(run, "review.json"), ReviewResult);
         if (!review.ok)
             return retry(run, "review-run", review.error, "review");
+        const handoffError = finishHandoff(run, outcome, "reviewer", { target: "code", verdict: review.data.verdict });
+        if (handoffError)
+            return retry(run, "review-run", handoffError, "review");
         renameSync(flowFile(run, "review.json"), flowFile(run, `review-${reviewer}.json`));
         if (review.data.verdict === "approve") {
             info(run, `   ✓ ${reviewer} 核准`);
@@ -513,6 +597,9 @@ async function reviewStage(run) {
     };
 }
 async function prStage(run) {
+    const pending = openActions(readHandoff(run.id));
+    if (pending.length)
+        return { ...run, stage: "failed", failedStage: "pr", failureReason: `仍有未結交接事項：${pending.map((item) => item.id).join("、")}` };
     const repo = worktreeDir(run.id);
     const remotes = (await git(repo, "remote")).split("\n").filter(Boolean);
     if (!remotes.includes("origin")) {
@@ -546,6 +633,7 @@ const STAGES = {
 /** 一路推進到需要人介入（awaiting_approval、paused）或結束（done / failed）為止；每一步都寫回檔案，中斷後可接續 */
 export async function advance(initial) {
     let run = initial;
+    recoverHandoff(run.id);
     for (;;) {
         if (["done", "failed", "awaiting_approval", "paused"].includes(run.stage))
             return run;

package/dist/handoff.js

@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { flowDir, handoffPath, runDir } from "./paths.js";
+import { HandoffLedger, HandoffResponse, HandoffSource } from "./schemas.js";
+import { readJsonFile } from "./util.js";
+const responsePath = (id) => join(flowDir(id), "handoff-response.json");
+const receiptsDir = (id) => join(runDir(id), "handoff-receipts");
+const keyHash = (key) => createHash("sha256").update(key).digest("hex").slice(0, 16);
+const receiptPath = (id, key) => join(receiptsDir(id), `${keyHash(key)}.json`);
+const Receipt = z.object({ callKey: z.string(), source: HandoffSource, response: HandoffResponse, role: z.enum(["writer", "reviewer"]) });
+function writeAtomic(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, path);
+}
+export function readHandoff(id) {
+    const path = handoffPath(id);
+    if (!existsSync(path))
+        return { version: 1, issues: [] };
+    return HandoffLedger.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+export function openActions(ledger, target) {
+    return ledger.issues.filter((item) => item.kind === "action"
+        && (item.status === "open" || item.status === "proposed_resolved")
+        && (!target || item.targetStage === target));
+}
+export function reviewHandoffGate(ledger, target, verdict) {
+    if (verdict !== "approve")
+        return undefined;
+    const pending = openActions(ledger, target);
+    return pending.length ? `審查核准與未結交接事項矛盾：${pending.map((item) => item.id).join("、")}` : undefined;
+}
+export function previewHandoff(ledger, callKey, source, response, role) {
+    source = HandoffSource.parse(source);
+    response = HandoffResponse.parse(response);
+    if (source.callKey !== callKey)
+        throw new Error("交接呼叫識別碼不一致");
+    if (ledger.appliedCalls?.includes(callKey))
+        return ledger;
+    const now = new Date().toISOString();
+    const issues = ledger.issues.map((item) => ({ ...item }));
+    for (const [index, item] of response.newIssues.entries()) {
+        const id = createHash("sha256").update(`${callKey}:${index}`).digest("hex").slice(0, 16);
+        if (issues.some((existing) => existing.id === id))
+            throw new Error(`交接事項 id 重複：${id}`);
+        issues.push({ id, source, ...item, status: "open", updatedAt: now });
+    }
+    for (const disposition of response.dispositions) {
+        const issue = issues.find((item) => item.id === disposition.id);
+        if (!issue)
+            throw new Error(`找不到交接事項：${disposition.id}`);
+        if (issue.kind !== "action")
+            throw new Error(`參考資訊不可結案：${disposition.id}`);
+        if (issue.status === "resolved" || issue.status === "accepted")
+            throw new Error(`交接事項已結案：${disposition.id}`);
+        if (role === "writer" && disposition.status !== "proposed_resolved")
+            throw new Error("作者只能提出已修正，不能自行結案");
+        if (role === "reviewer" && disposition.status === "proposed_resolved")
+            throw new Error("審查者須明確結案或接受風險");
+        issue.status = disposition.status;
+        issue.resolution = { agent: source.agent, reason: disposition.reason, evidence: disposition.evidence };
+        issue.updatedAt = now;
+    }
+    return HandoffLedger.parse({ version: 1, issues, appliedCalls: [...(ledger.appliedCalls ?? []), callKey] });
+}
+export function mergeHandoff(id, callKey, source, response, role) {
+    const next = previewHandoff(readHandoff(id), callKey, source, response, role);
+    writeAtomic(handoffPath(id), JSON.stringify(next, null, 2));
+    return next;
+}
+/** 只把目前步驟需要處理的事項投影給 agent。 */
+export function prepareHandoff(id, _callKey, target, blind) {
+    const items = readHandoff(id).issues.filter((item) => item.targetStage === target && (item.kind === "info" || item.status === "open" || item.status === "proposed_resolved"));
+    const lines = items.map((item) => {
+        const source = blind ? "" : `\n來源：${item.source.stage}／${item.source.agent}`;
+        const resolution = item.resolution ? `\n處理理由：${item.resolution.reason}\n處理證據：${item.resolution.evidence}` : "";
+        return `## ${item.id}：${item.summary}\n證據：${item.evidence}\n狀態：${item.status}${resolution}${source}`;
+    });
+    mkdirSync(flowDir(id), { recursive: true });
+    writeFileSync(join(flowDir(id), "handoff-context.md"), `# 待處理交接事項\n\n${lines.length ? lines.join("\n\n") : "目前沒有待處理事項。"}\n`);
+    rmSync(responsePath(id), { force: true });
+}
+export function validateHandoffResponse(id) {
+    return readJsonFile(responsePath(id), HandoffResponse);
+}
+/** 已通過原有關卡的回覆先記收據，再合併；中斷後可重播。 */
+export function acceptHandoff(id, callKey, source, response, role) {
+    const checked = Receipt.parse({ callKey, source, response, role });
+    previewHandoff(readHandoff(id), callKey, source, response, role);
+    const path = receiptPath(id, callKey);
+    writeAtomic(path, JSON.stringify(checked));
+    mergeHandoff(id, callKey, source, response, role);
+    rmSync(path, { force: true });
+}
+export function recoverHandoff(id) {
+    const dir = receiptsDir(id);
+    if (!existsSync(dir))
+        return;
+    for (const name of readdirSync(dir).filter((f) => f.endsWith(".json"))) {
+        const path = join(dir, name);
+        const receipt = Receipt.parse(JSON.parse(readFileSync(path, "utf8")));
+        mergeHandoff(id, receipt.callKey, receipt.source, receipt.response, receipt.role);
+        rmSync(path);
+    }
+}
+//# sourceMappingURL=handoff.js.map

package/dist/paths.js

@@ -17,6 +17,7 @@ export const agentflowctlDir = () => join(projectRoot(), ".agentflowctl");
 export const runsDir = () => join(agentflowctlDir(), "runs");
 export const runDir = (id) => join(runsDir(), id);
 export const logDir = (id) => join(runDir(id), "logs");
+export const handoffPath = (id) => join(runDir(id), "handoff.json");
 /** 每個 run 一個 git worktree，Agent 只在這裡工作，不碰你正在編輯的檔案 */
 export const worktreesDir = () => join(agentflowctlDir(), "worktrees");
 export const worktreeDir = (id) => join(worktreesDir(), id);

package/dist/schemas.js

@@ -14,6 +14,50 @@ export const Stage = z.enum([
     "done",
     "failed",
 ]);
+export const HandoffSource = z.object({
+    stage: Stage,
+    step: z.string().min(1),
+    agent: z.string().min(1),
+    callKey: z.string().min(1),
+});
+const HandoffKind = z.enum(["action", "info"]);
+const HandoffTarget = z.enum(["plan", "code"]);
+const HandoffStatus = z.enum(["open", "proposed_resolved", "resolved", "accepted"]);
+export const HandoffResponse = z.object({
+    newIssues: z.array(z.object({
+        kind: HandoffKind,
+        summary: z.string().trim().min(1),
+        evidence: z.string().trim().min(1),
+        targetStage: HandoffTarget,
+    })),
+    dispositions: z.array(z.object({
+        id: z.string().min(1),
+        status: z.enum(["proposed_resolved", "resolved", "accepted"]),
+        reason: z.string().trim().min(1),
+        evidence: z.string().trim().min(1),
+    })),
+});
+export const HandoffIssue = z.object({
+    id: z.string().min(1),
+    source: HandoffSource,
+    kind: HandoffKind,
+    summary: z.string().min(1),
+    evidence: z.string().min(1),
+    targetStage: HandoffTarget,
+    status: HandoffStatus,
+    resolution: z.object({
+        agent: z.string(),
+        reason: z.string(),
+        evidence: z.string(),
+    }).optional(),
+    updatedAt: z.string(),
+});
+export const HandoffLedger = z.object({
+    version: z.literal(1),
+    issues: z.array(HandoffIssue),
+    /** 用來辨識沒有新增事項的回覆是否已經合併。 */
+    appliedCalls: z.array(z.string()).optional(),
+});
 /** Agent 在 spec 階段產出的 .flow/acceptance.json */
 export const AcceptanceList = z
     .array(z.object({
@@ -39,6 +83,11 @@ export const ReviewResult = z.object({
         note: z.string().default(""),
     })),
 });
+/** 仲裁者可能用 reject 表示否決；讀取時正規化，保留相同的理由欄位。 */
+export const ArbiterResult = ReviewResult.extend({
+    verdict: z.enum(["approve", "changes_requested", "reject"])
+        .transform((verdict) => verdict === "reject" ? "changes_requested" : verdict),
+});
 /** 一個 agent 的定義；名稱（agents 的 key）用在 cycle 裡 */
 export const AgentDef = z.object({
     adapter: z.enum(["claude", "codex", "gemini", "command"]),

package/package.json

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

package/prompts/fix.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（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>
 - .flow/feedback.md：失敗的檢查（型別、lint、測試、建置）或審查意見
 - .flow/spec.md 與 .flow/acceptance.json：規格

package/prompts/implement-code.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（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>
+
 <task>
 ```json
 {{task}}

package/prompts/implement-tests.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（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>
+
 <task>
 ```json
 {{task}}

package/prompts/plan-arbiter.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（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>
+
 <requirement>
 {{requirement}}
 </requirement>
@@ -36,10 +47,11 @@
 ```
 
 dispute.md 裡的每一條意見都要列一筆並說明你的判斷。
+`verdict` 只能寫 `approve` 或 `changes_requested`。若計畫有會導致錯誤結果、遺漏需求或無法驗收的問題，請寫 `changes_requested`，不要寫 `reject`。
 </output_format>
 
 <constraints>
-- 只能寫入 .flow/plan-arbiter.json，不可修改規格、計畫或任何程式碼。
+- 只能寫入 .flow/plan-arbiter.json 與 .flow/handoff-response.json，不可修改規格、計畫或任何程式碼。
 </constraints>
 
 <reply_format>

package/prompts/plan-fix.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（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>
+
 <requirement>
 {{requirement}}
 </requirement>

package/prompts/plan-review.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（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>
+
 <requirement>
 {{requirement}}
 </requirement>
@@ -46,7 +57,7 @@
 </output_format>
 
 <constraints>
-- 只能寫入 .flow/plan-review.json，不可修改規格、計畫或任何程式碼，其他變更都會被還原。
+- 只能寫入 .flow/plan-review.json 與 .flow/handoff-response.json，不可修改規格、計畫或任何程式碼，其他變更都會被還原。
 </constraints>
 
 <reply_format>

package/prompts/plan.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（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>
 - .flow/spec.md
 - .flow/acceptance.json

package/prompts/review.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（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>
 - 規格：.flow/spec.md
 - 驗收條件：.flow/acceptance.json
@@ -39,7 +50,7 @@
 </output_format>
 
 <constraints>
-- 只能寫入 .flow/review.json，不可修改任何程式碼，其他變更都會被捨棄。
+- 只能寫入 .flow/review.json 與 .flow/handoff-response.json，不可修改任何程式碼，其他變更都會被捨棄。
 </constraints>
 
 <reply_format>

package/prompts/spec.md

@@ -6,6 +6,17 @@
 目前的工作目錄就是專案（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>
+
 <requirement>
 {{requirement}}
 </requirement>