agentflowctl 0.4.0 → 0.6.0

package/dist/roles.js

@@ -2,78 +2,109 @@
  * 決定每個步驟由哪個 agent 執行。
  *
  * 規則只有三條：
- * 1. 審查者不能是最後寫程式的 agent。
+ * 1. 審查者不能是最後寫程式的 agent，多位審查者彼此不重複。
  * 2. 開啟 tddSplit 時，同一個任務的測試與實作由不同 agent 負責。
- * 3. 所有選擇都沿著同一個輪替順序（cycle）前進，所以不同公司的模型會輪流扮演各個角色。
+ * 3. 人選隨機決定，不依 cycle 的順序。cycle 只代表有哪些 agent 參與。
+ *
+ * 隨機以 seed（run id 加上步驟與輪次）決定：同一個 run 的同一步驟重算時會得到同樣的人，
+ * 所以 resume、或同一步驟在不同地方重算時結果一致。
  */
-/** 從 from 的下一位開始，找第一個不在 exclude 裡的 agent；全部被排除時退回下一位（單一 agent 也能運作） */
-export function nextAfter(cycle, from, exclude = []) {
-    const n = cycle.length;
-    const start = from === undefined ? -1 : cycle.indexOf(from);
-    for (let i = 1; i <= n; i++) {
-        const candidate = cycle[(start + i + n) % n];
-        if (!exclude.includes(candidate))
-            return candidate;
+/** FNV-1a 雜湊：把 seed 字串轉成 32 位元整數 */
+function hash(seed) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < seed.length; i++) {
+        h ^= seed.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
     }
-    return cycle[(start + 1 + n) % n];
+    return h >>> 0;
 }
-export const specAgent = (cycle) => cycle[0];
-export const planAgent = (cycle) => cycle[0];
-/** 第 i 個任務的測試由輪替順序的第 i 位負責，實作交給下一位 */
-export function taskAgents(cycle, taskIndex, tddSplit) {
-    const tests = cycle[taskIndex % cycle.length];
-    return { tests, code: tddSplit ? nextAfter(cycle, tests, [tests]) : tests };
+/** mulberry32：由 seed 決定的亂數產生器 */
+function rng(seed) {
+    let a = hash(seed);
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = a;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
 }
-/** 從最後寫程式的 agent 之後，依序挑出 quorum 位不重複、而且不是作者的 reviewer */
-export function reviewers(cycle, lastWriter, quorum) {
-    const picked = [];
-    let cursor = lastWriter;
-    for (let i = 0; i < cycle.length && picked.length < quorum; i++) {
-        const next = nextAfter(cycle, cursor, [...(lastWriter ? [lastWriter] : []), ...picked]);
-        if (picked.includes(next) || (next === lastWriter && cycle.length > 1))
-            break;
-        picked.push(next);
-        cursor = next;
+/** 由 seed 決定的洗牌，不改動原陣列 */
+export function shuffled(items, seed) {
+    const out = [...items];
+    const rand = rng(seed);
+    for (let i = out.length - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        [out[i], out[j]] = [out[j], out[i]];
     }
-    return picked.length ? picked : [nextAfter(cycle, lastWriter)];
+    return out;
+}
+/** 隨機挑一位不在 exclude 裡的 agent；全部被排除時退回任一位（單一 agent 也能運作） */
+export function pick(cycle, seed, exclude = []) {
+    const order = shuffled(cycle, seed);
+    return order.find((c) => !exclude.includes(c)) ?? order[0];
+}
+/** 規格與計畫由同一位撰寫，計畫審查才能同時避開兩者的作者 */
+export const specAgent = (cycle, seed) => pick(cycle, `${seed}:author`);
+export const planAgent = specAgent;
+/**
+ * 每 cycle.length 個任務為一輪，每輪洗一次牌，所以每家輪完一次才會再輪到；
+ * 換輪時若新一輪第一位和上一輪最後一位相同，就把它往後移，避免同一家連續撰寫測試。
+ */
+function taskBag(cycle, seed, bag) {
+    const order = shuffled(cycle, `${seed}:tasks:${bag}`);
+    if (bag === 0 || order.length < 2)
+        return order;
+    const prevLast = taskBag(cycle, seed, bag - 1).at(-1);
+    return order[0] === prevLast ? [...order.slice(1), order[0]] : order;
+}
+/** 第 i 個任務的測試作者從洗好的牌依序取；實作者隨機挑一位測試作者以外的 agent */
+export function taskAgents(cycle, taskIndex, tddSplit, seed) {
+    const n = cycle.length;
+    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);
+    return picked.length ? picked : [lastWriter ?? cycle[0]];
 }
 /**
  * 誰來修正：
  * - verify 失敗（型別、lint、建置這類機械性錯誤）：交給最後寫程式的 agent
- * - review 要求修改：ring 策略輪到 reviewer 的下一位；author 策略交回作者
+ * - review 要求修改：ring 策略隨機挑一位 reviewer 以外的 agent；author 策略交回作者
  */
 export function fixAgent(cycle, opts) {
     if (opts.source === "verify" || opts.strategy === "author")
         return opts.lastWriter ?? cycle[0];
-    return nextAfter(cycle, opts.lastReviewer, opts.lastReviewer ? [opts.lastReviewer] : []);
+    return pick(cycle, opts.seed, opts.lastReviewer ? [opts.lastReviewer] : []);
 }
-/** 計畫修正者：ring 策略輪到審查者的下一位；author 策略交回計畫作者 */
+/** 計畫修正者：ring 策略隨機挑一位審查者以外的 agent；author 策略交回計畫作者 */
 export function planFixAgent(cycle, opts) {
     if (opts.strategy === "author")
         return opts.planWriter ?? cycle[0];
-    return nextAfter(cycle, opts.planReviewer, opts.planReviewer ? [opts.planReviewer] : []);
+    return pick(cycle, opts.seed, opts.planReviewer ? [opts.planReviewer] : []);
 }
 /**
  * 仲裁小組：
- * - 有第三方（作者與最後審查者以外的 agent）→ 由第三方單獨仲裁
+ * - 有第三方（作者與最後審查者以外的 agent）→ 隨機挑一位第三方單獨仲裁
  * - 只有兩家 → 兩家各自在全新 context 中雙盲仲裁，避免讓一直反對的審查者同時當裁判
  * - 只有一家 → 只能由它自己仲裁
  */
-export function arbiterPanel(cycle, writer, reviewer) {
+export function arbiterPanel(cycle, seed, writer, reviewer) {
     const involved = [writer, reviewer].filter((x) => Boolean(x));
-    const third = cycle.find((c) => !involved.includes(c));
+    const third = shuffled(cycle, seed).find((c) => !involved.includes(c));
     if (third)
         return [third];
     return [...new Set(cycle)];
 }
 /**
- * 代打人選：原本的 agent 可用就用它；額度用完時，沿輪替順序找下一位還有額度的 agent。
+ * 代打人選：原本的 agent 可用就用它；額度用完時，隨機挑一位還有額度的 agent。
  * 全部都用完時回傳 undefined。
  */
-export function availableAgent(cycle, preferred, exhausted) {
+export function availableAgent(cycle, preferred, exhausted, seed) {
     if (!exhausted.includes(preferred))
         return preferred;
-    const next = nextAfter(cycle, preferred, exhausted);
-    return exhausted.includes(next) ? undefined : next;
+    return shuffled(cycle, seed).find((c) => !exhausted.includes(c));
 }
 //# sourceMappingURL=roles.js.map

package/dist/runner.js

@@ -59,7 +59,8 @@ export function resolveAgent(cfg, name) {
     const def = cfg.agents[name];
     if (!def)
         throw new Error(`未定義的 agent：${name}（請先用 agent add ${name} --adapter <adapter> 新增）`);
-    return def;
+    const defaultModel = def.adapter === "command" ? undefined : cfg.defaultModels[def.adapter];
+    return { ...def, model: def.model ?? defaultModel };
 }
 /** 確認某個 agent 的 CLI 是否可以執行 */
 export async function probeAgent(def) {

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,7 +83,12 @@ export const ReviewResult = z.object({
         note: z.string().default(""),
     })),
 });
-/** 一個 agent 的定義；名稱（agents 的 key）用在輪替順序裡 */
+/** 仲裁者可能用 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"]),
     model: z.string().optional(),
@@ -51,7 +100,13 @@ export const AgentDef = z.object({
 export const RepoConfig = z.object({
     /** 可用的 agent；沒有內建，全部都要在這裡定義（通常用 agent add） */
     agents: z.record(z.string(), AgentDef).default({}),
-    /** 輪替順序；未設定時依 agents 的順序，取已安裝的 CLI */
+    /** 各 CLI adapter 的預設模型；agent 自己指定 model 時優先使用個別設定 */
+    defaultModels: z.strictObject({
+        claude: z.string().trim().min(1).optional(),
+        codex: z.string().trim().min(1).optional(),
+        gemini: z.string().trim().min(1).optional(),
+    }).default({}),
+    /** 參與的 agent（順序不影響分工）；未設定時取 agents 裡已安裝的 CLI */
     cycle: z.array(z.string()).min(1).optional(),
     /** review 後的修正由誰做：ring＝輪到下一位；author＝最後寫程式的 agent */
     fixStrategy: z.enum(["ring", "author"]).default("ring"),
@@ -94,7 +149,7 @@ export const FlowRun = z.object({
     /** 暫停前所在的階段與原因（額度用完時） */
     pausedStage: Stage.optional(),
     pauseReason: z.string().optional(),
-    /** 這個 run 的 agent 輪替順序（建立時決定，resume 時沿用） */
+    /** 這個 run 參與的 agent（建立時決定，resume 時沿用） */
     cycle: z.array(z.string()).min(1),
     /** 最後一個寫程式的 agent，reviewer 不可以是它 */
     lastWriter: z.string().optional(),

package/dist/setup.js

@@ -46,7 +46,7 @@ export async function runSetup(initial, deps) {
         return null;
     }
     for (;;) {
-        const list = (await ask("輪替順序，用逗號分隔", chosen.join(","))).split(",").map((s) => s.trim()).filter(Boolean);
+        const list = (await ask("參與的 agent，用逗號分隔", chosen.join(","))).split(",").map((s) => s.trim()).filter(Boolean);
         try {
             cfg = setCycle(cfg, list).cfg;
             break;
@@ -59,7 +59,7 @@ export async function runSetup(initial, deps) {
     log("\n即將寫入：");
     for (const name of chosen)
         log(`  ${name.padEnd(14)} adapter=${agents[name].adapter}${agents[name].model ? ` model=${agents[name].model}` : ""}`);
-    log(`  輪替順序：${cfg.cycle.join(" → ")}`);
+    log(`  參與的 agent：${cfg.cycle.join("、")}`);
     log("  需要自訂指令的 CLI 請改用 agent add <name> --adapter command -- <指令>");
     if (!(await confirm("寫入 flow.config.json？", true))) {
         log("已取消，設定沒有變更");

package/examples/flow.config.json

@@ -7,6 +7,7 @@
   "planArbiter": true,
   "tieBreak": "proceed",
   "maxAgentRuns": 60,
+  "defaultModels": { "claude": "Claude 模型名稱", "codex": "Codex 模型名稱" },
   "agents": {
     "claude": { "adapter": "claude" },
     "codex": { "adapter": "codex" }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentflowctl",
   "license": "MIT",
-  "version": "0.4.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>