agentflowctl 0.13.1 → 0.15.0

package/dist/store.js

@@ -36,9 +36,21 @@ export function addUsage(id, entry) {
     appendFileSync(usagePath(id), `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
 }
 const emptySummary = () => ({ tokens: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, runs: 0, reportedRuns: 0, unreportedRuns: 0, legacyRuns: 0, legacyTokens: 0 });
+/** 逐行讀取 jsonl；寫到一半被中斷的殘行直接略過，不讓 status、insights 整個讀不出來 */
+function readJsonl(p) {
+    if (!existsSync(p))
+        return [];
+    return readFileSync(p, "utf8").split("\n").filter(Boolean).flatMap((l) => {
+        try {
+            return [JSON.parse(l)];
+        }
+        catch {
+            return [];
+        }
+    });
+}
 export function listUsage(id) {
-    const p = usagePath(id);
-    return existsSync(p) ? readFileSync(p, "utf8").split("\n").filter(Boolean).map((line) => JSON.parse(line)) : [];
+    return readJsonl(usagePath(id));
 }
 function addSummary(acc, e) {
     acc.runs += 1;
@@ -58,23 +70,37 @@ function addSummary(acc, e) {
     }
 }
 /** 只加總明確回報的 token，舊資料的 0 不視為已回報。 */
-function groupUsage(id, keyOf) {
+export function totalUsage(entries) {
+    const acc = emptySummary();
+    for (const e of entries)
+        addSummary(acc, e);
+    return acc;
+}
+export function summarizeUsage(entries, keyOf) {
     const out = {};
-    for (const e of listUsage(id))
+    for (const e of entries)
         addSummary(out[keyOf(e)] ??= emptySummary(), e);
     return out;
 }
-export const usageByAgent = (id) => groupUsage(id, (e) => e.agent);
-export const usageByModelStage = (id) => groupUsage(id, (e) => `${e.model ?? "CLI 預設（名稱未知）"} / ${e.stage}`);
-export const usageByStrength = (id) => groupUsage(id, (e) => e.strength ?? "未知");
-/** 依階段鍵加總（所有任務的同一步合在一起）；認不得的步驟歸為「其他」。 */
-export const usageByStage = (id) => groupUsage(id, (e) => stageOfStep(e.stage) ?? "其他");
-/** 依任務加總寫測試、實作、任務審查與任務修正；規格、計畫與整體階段歸為「非任務步驟」。 */
-export const usageByTask = (id) => groupUsage(id, (e) => /^(T-\d+)-/.exec(e.stage)?.[1] ?? "非任務步驟");
+export const usageKeyAgent = (e) => e.agent;
+export const usageKeyStrength = (e) => e.strength ?? "未知";
+export const usageKeyStage = (e) => stageOfStep(e.stage) ?? "其他";
+export const usageKeyTask = (e) => /^(T-\d+)-/.exec(e.stage)?.[1] ?? "非任務步驟";
+const modelName = (e) => e.model ?? "CLI 預設（名稱未知）";
+export const usageKeyModelStage = (e) => `${modelName(e)} / ${e.stage}`;
+/** 跨 run 用：任務步驟換成步驟種類（T-1-code → taskCode），不同 run 的 task id 不互相合併 */
+export const usageKeyModelStageKind = (e) => `${modelName(e)} / ${stageOfStep(e.stage) ?? e.stage}`;
+function groupUsage(id, keyOf) {
+    return summarizeUsage(listUsage(id), keyOf);
+}
+export const usageByAgent = (id) => groupUsage(id, usageKeyAgent);
+export const usageByModelStage = (id) => groupUsage(id, usageKeyModelStage);
+export const usageByStrength = (id) => groupUsage(id, usageKeyStrength);
+export const usageByStage = (id) => groupUsage(id, usageKeyStage);
+export const usageByTask = (id) => groupUsage(id, usageKeyTask);
 /** 這個 run 已執行 agent 的次數（每次執行都會記一筆用量） */
 export function agentRuns(id) {
-    const p = usagePath(id);
-    return existsSync(p) ? readFileSync(p, "utf8").split("\n").filter(Boolean).length : 0;
+    return listUsage(id).length;
 }
 const subPath = (id) => join(runDir(id), "substitutions.jsonl");
 export function addSubstitution(id, s) {
@@ -82,9 +108,28 @@ export function addSubstitution(id, s) {
     appendFileSync(subPath(id), `${JSON.stringify({ at: new Date().toISOString(), ...s })}\n`);
 }
 export function listSubstitutions(id) {
-    const p = subPath(id);
-    if (!existsSync(p))
-        return [];
-    return readFileSync(p, "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l));
+    return readJsonl(subPath(id));
+}
+export const RetryCategories = [
+    "agent_error", "missing_artifact", "format_invalid", "handoff_invalid", "open_handoff",
+    "review_changes", "arbitration_revise", "plan_tampered", "tests_not_written", "code_not_written", "tests_not_red", "tests_modified",
+    "tests_not_green", "tests_deleted", "checks_failed",
+];
+const retryPath = (id) => join(runDir(id), "retries.jsonl");
+/**
+ * savedAt 是目前 state.json 的 updatedAt。上一筆同 key、同 attempt 的紀錄若晚於它，
+ * 代表上次寫入重試後還沒存到 state 就中斷了，resume 重跑同一步時不再重複記一筆。
+ */
+export function addRetry(id, entry, savedAt) {
+    if (savedAt) {
+        const last = listRetries(id).filter((r) => r.key === entry.key).at(-1);
+        if (last && last.attempt === entry.attempt && last.at > savedAt)
+            return;
+    }
+    mkdirSync(runDir(id), { recursive: true });
+    appendFileSync(retryPath(id), `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`);
+}
+export function listRetries(id) {
+    return readJsonl(retryPath(id));
 }
 //# sourceMappingURL=store.js.map

package/dist/usageInsights.js

@@ -0,0 +1,156 @@
+import { retryLabel } from "./insights.js";
+import { RetryCategories } from "./store.js";
+import { summarizeUsage, totalUsage, usageKeyAgent, usageKeyModelStageKind, usageKeyStage, usageKeyStrength, usageKeyTask } from "./store.js";
+import { mergeStats } from "./stats.js";
+export const FindingCodes = [
+    "coverage_low", "high_strength_share", "retry_waste", "input_heavy",
+    "hot_stage", "hot_task", "substitution_waste", "cache_unread",
+    "hot_model_step", "hot_failing_step",
+];
+export const FINDING_LABEL = {
+    coverage_low: "用量回報不完整",
+    high_strength_share: "高強度模型占比偏高",
+    retry_waste: "重試可能比單次 prompt 更耗 token",
+    input_heavy: "輸入遠大於輸出",
+    hot_stage: "單一階段佔用量過高",
+    hot_task: "單一任務佔用量過高",
+    substitution_waste: "額度代打造成重做",
+    cache_unread: "cache 寫入多、讀取少",
+    hot_model_step: "單一模型與步驟佔用量過高",
+    hot_failing_step: "單一執行步驟失敗次數過多",
+};
+/** 會算進 retry_waste 的重試：排除審查要求修改與仲裁要求修訂這類正常往返 */
+const WASTEFUL_RETRY = (r) => r.category !== "review_changes" && r.category !== "arbitration_revise";
+export function topTaskOf(usage) {
+    const entries = Object.entries(summarizeUsage(usage, usageKeyTask)).filter(([key, v]) => key !== "非任務步驟" && v.tokens > 0);
+    const taskTotal = entries.reduce((n, [, v]) => n + v.tokens, 0);
+    const top = entries.sort((a, b) => b[1].tokens - a[1].tokens)[0];
+    return top ? { task: top[0], tokens: top[1].tokens, share: top[1].tokens / taskTotal, tasks: entries.length } : undefined;
+}
+const pct = (part, whole) => (whole ? `${(part / whole * 100).toFixed(1)}%` : "無法計算");
+function topByTokens(record) {
+    return Object.entries(record)
+        .filter(([, v]) => v.tokens > 0)
+        .sort((a, b) => b[1].tokens - a[1].tokens)[0];
+}
+export function usageFindings(input) {
+    const { total, byStrength, byStage, substitutions, topTasks = [], byModelStage = {}, steps = [] } = input;
+    const retries = input.retries.filter(WASTEFUL_RETRY);
+    const out = [];
+    const avg = total.reportedRuns ? Math.round(total.tokens / total.reportedRuns) : 0;
+    const unknownCalls = total.unreportedRuns + total.legacyRuns;
+    if (total.runs >= 5 && unknownCalls / total.runs >= 0.3) {
+        out.push({
+            code: "coverage_low", impactTokens: 0, title: FINDING_LABEL.coverage_low,
+            detail: `${unknownCalls} / ${total.runs} 次呼叫沒有明確 token。強度占比可能失真，先看未回報的 agent。`,
+        });
+    }
+    const high = byStrength.high;
+    if (total.tokens > 0 && high && high.tokens / total.tokens >= 0.4) {
+        out.push({
+            code: "high_strength_share", impactTokens: high.tokens, title: FINDING_LABEL.high_strength_share,
+            detail: `high 佔已回報 token 的 ${pct(high.tokens, total.tokens)}，呼叫 ${high.runs} 次。合計 token 不是主指標；可查 model stage 與任務 complexity。`,
+        });
+    }
+    if (retries.length >= 2) {
+        const cat = new Map();
+        for (const r of retries)
+            cat.set(r.category, (cat.get(r.category) ?? 0) + 1);
+        const top = [...cat.entries()].sort((a, b) => b[1] - a[1] || RetryCategories.indexOf(a[0]) - RetryCategories.indexOf(b[0]))[0];
+        const waste = avg * retries.length;
+        out.push({
+            code: "retry_waste", impactTokens: waste, title: FINDING_LABEL.retry_waste,
+            detail: `重試 ${retries.length} 次（不含審查要求修改與仲裁要求修訂），最多「${top ? retryLabel(top[0]) : "未知"}」（${top?.[1] ?? 0} 次）。以平均每次 ${avg} tokens 估算，重試約 ${waste} tokens。先改該關卡，再縮 prompt。`,
+        });
+    }
+    if (total.tokens >= 5000 && total.inputTokens / total.tokens >= 0.85) {
+        out.push({
+            code: "input_heavy", impactTokens: total.inputTokens, title: FINDING_LABEL.input_heavy,
+            detail: `輸入 ${total.inputTokens}、輸出 ${total.outputTokens}（輸入佔 ${pct(total.inputTokens, total.tokens)}）。上下文可能太大：規格、計畫、測試輸出或一次讀太多檔。`,
+        });
+    }
+    const stagesWithTokens = Object.values(byStage).filter((s) => s.tokens > 0).length;
+    const topStage = topByTokens(byStage);
+    if (total.tokens > 0 && stagesWithTokens >= 2 && topStage && topStage[1].tokens / total.tokens >= 0.35) {
+        out.push({
+            code: "hot_stage", impactTokens: topStage[1].tokens, title: FINDING_LABEL.hot_stage,
+            detail: `${topStage[0]} 佔 ${pct(topStage[1].tokens, total.tokens)}（${topStage[1].tokens} tokens，${topStage[1].runs} 次）。改該階段 prompt 或最低強度。`,
+        });
+    }
+    const hotTask = topTasks
+        .filter((r) => !!r.topTask && r.topTask.tasks >= 2 && r.topTask.share >= 0.4)
+        .sort((a, b) => b.topTask.tokens - a.topTask.tokens)[0];
+    if (hotTask) {
+        const t = hotTask.topTask;
+        out.push({
+            code: "hot_task", impactTokens: t.tokens, title: FINDING_LABEL.hot_task,
+            detail: `${hotTask.id} 的 ${t.task} 佔該 run 任務用量 ${(t.share * 100).toFixed(1)}%（${t.tokens} tokens）。考慮切小任務或降低 complexity。`,
+        });
+    }
+    if (substitutions >= 2) {
+        out.push({
+            code: "substitution_waste", impactTokens: avg * substitutions, title: FINDING_LABEL.substitution_waste,
+            detail: `代打 ${substitutions} 次。寫入步驟額度用完會還原半成品再換人，等於重跑。`,
+        });
+    }
+    if (total.cacheWriteTokens >= 1000 && total.cacheReadTokens < total.cacheWriteTokens * 0.5) {
+        out.push({
+            code: "cache_unread", impactTokens: total.cacheWriteTokens, title: FINDING_LABEL.cache_unread,
+            detail: `cache 寫 ${total.cacheWriteTokens}、讀 ${total.cacheReadTokens}。合計 token 含 cache，讀取少時較不像在吃快取。`,
+        });
+    }
+    const modelGroups = Object.values(byModelStage).filter((s) => s.tokens > 0).length;
+    const topModel = topByTokens(byModelStage);
+    if (total.tokens > 0 && modelGroups >= 2 && topModel && topModel[1].tokens / total.tokens >= 0.35) {
+        out.push({
+            code: "hot_model_step", impactTokens: topModel[1].tokens, title: FINDING_LABEL.hot_model_step,
+            detail: `${topModel[0]} 佔 ${pct(topModel[1].tokens, total.tokens)}（${topModel[1].tokens} tokens，${topModel[1].runs} 次）。可換模型或只調該步驟強度。`,
+        });
+    }
+    const topFail = (() => {
+        const candidates = steps.filter((s) => s.failed >= 3).sort((a, b) => b.failed - a.failed || b.runs - a.runs);
+        return candidates.find((s) => s.kind === "agent") ?? candidates[0];
+    })();
+    if (topFail) {
+        const kindLabel = topFail.kind === "cmd" ? "專案指令" : "agent";
+        out.push({
+            code: "hot_failing_step",
+            impactTokens: topFail.kind === "agent" ? avg * topFail.failed : 0,
+            title: FINDING_LABEL.hot_failing_step,
+            detail: `${topFail.step}（${kindLabel}）失敗 ${topFail.failed} / ${topFail.runs} 次。先看該步驟的 stats 與 logs，再改 prompt 或檢查指令。`,
+        });
+    }
+    const coverage = out.filter((f) => f.code === "coverage_low");
+    const rest = out
+        .filter((f) => f.code !== "coverage_low")
+        .sort((a, b) => b.impactTokens - a.impactTokens || FindingCodes.indexOf(a.code) - FindingCodes.indexOf(b.code));
+    return [...coverage, ...rest].slice(0, 5);
+}
+export function computeUsageInsights(runs) {
+    const usage = runs.flatMap((r) => r.usage);
+    const retries = runs.flatMap((r) => r.retries);
+    const substitutions = runs.reduce((n, r) => n + r.substitutions, 0);
+    const emptyStats = () => ({ steps: [], agentMs: 0, cmdMs: 0, wallMs: 0, unfinished: 0 });
+    const stepStats = mergeStats(runs.map((r) => r.stats ?? emptyStats()));
+    const total = totalUsage(usage);
+    const byStrength = summarizeUsage(usage, usageKeyStrength);
+    const byStage = summarizeUsage(usage, usageKeyStage);
+    const byAgent = summarizeUsage(usage, usageKeyAgent);
+    const byModelStage = summarizeUsage(usage, usageKeyModelStageKind);
+    const perRun = runs.map((r) => {
+        const t = totalUsage(r.usage);
+        return { id: r.id, tokens: t.tokens, calls: t.runs, reportedCalls: t.reportedRuns, topTask: topTaskOf(r.usage) };
+    });
+    return {
+        total,
+        byStrength,
+        byStage,
+        byAgent,
+        byModelStage,
+        stepStats,
+        substitutions,
+        findings: usageFindings({ total, byStrength, byStage, topTasks: perRun, byModelStage, retries, substitutions, steps: stepStats.steps }),
+        runs: perRun,
+    };
+}
+//# sourceMappingURL=usageInsights.js.map

package/dist/util.js

@@ -30,4 +30,16 @@ export function readJsonFile(path, schema) {
         ? { ok: true, data: parsed.data }
         : { ok: false, error: `${path} 格式錯誤：\n${z.prettifyError(parsed.error)}` };
 }
+// 中日韓文字與全形符號在終端機占兩格
+const WIDE = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꥠ-꥿가-힣豈-﫿︰-﹏＀-｠￠-￦]/u;
+export function displayWidth(s) {
+    let w = 0;
+    for (const ch of s)
+        w += WIDE.test(ch) ? 2 : 1;
+    return w;
+}
+/** 依終端機顯示寬度補空白，讓中英混排的欄位對齊 */
+export function padDisplay(s, width) {
+    return s + " ".repeat(Math.max(0, width - displayWidth(s)));
+}
 //# sourceMappingURL=util.js.map

package/examples/flow.config.json

@@ -5,6 +5,7 @@
   "reviewQuorum": 1,
   "planReviewQuorum": 1,
   "planArbiter": true,
+  "planReviewLayers": { "enabled": true, "minTasks": 7, "maxGroups": 5, "tasksPerGroup": 3 },
   "tieBreak": "proceed",
   "maxAgentRuns": 60,
   "defaultModels": { "claude": "Claude 模型名稱", "codex": "Codex 模型名稱" },

package/package.json

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

package/prompts/implement-direct.md

@@ -0,0 +1,67 @@
+<role>
+你是任務實作者，負責完成一個**不走 TDD** 的任務。這個任務不適合先寫會失敗的測試（例如建置流程、設定、文件、型別或純重構），或專案沒有測試框架，所以沒有紅燈測試可依循。你要依任務描述與驗收條件，用符合專案風格的最小改動完成它。
+</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 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+</handoff>
+
+<no_tdd>
+這個任務略過紅綠燈：沒有事先寫好的失敗測試，完成後由任務審查與專案的驗證指令（typecheck、lint、build 等）把關。
+</no_tdd>
+
+<task>
+```json
+{{task}}
+```
+</task>
+
+<acceptance>
+這個任務負責的驗收條件：
+```json
+{{acceptance}}
+```
+</acceptance>
+
+<inputs>
+先依上面的任務與驗收條件工作。只有資訊不足或互相矛盾時，再閱讀 .flow/spec.md、.flow/plan.md 的相關段落，並在交接中指出問題；不必通讀整份文件。
+</inputs>
+
+<steps>
+1. 若 .flow/feedback.md 存在，先閱讀，並依內容修正。
+2. 完成任務：最小改動、符合專案既有的程式風格與架構，並確保每一條驗收條件都能用具體的檔案或指令輸出證明。
+3. 自行執行能證明成果的指令（例如建置、型別檢查、執行腳本）並確認結果。
+4. 若專案有測試，外部流程會再執行 `{{testCmd}}` 確認既有測試沒有被破壞（空白代表專案沒有測試指令），不需要自行重跑全套測試。
+</steps>
+
+<constraints>
+- 必須實際修改檔案；沒有任何變更會被視為失敗。
+- 不要執行 git commit（權限設定已禁止）。
+- **不可修改** .flow/spec.md、.flow/acceptance.json、.flow/plan.md、.flow/tasks.json、.flow/tasks.ordered.json，修改會被自動還原並視為失敗。若認為規格或驗收條件有誤，請寫進 .flow/handoff-response.json 的 newIssues。
+</constraints>
+
+<reply_format>
+完成後，回覆的最後必須附上以下 XML 中繼資料（只附一次，標籤名稱不可更改）：
+
+```xml
+<result>
+  <status>done 或 blocked</status>
+  <summary>一兩句說明這次做了什麼；blocked 時說明卡在哪裡</summary>
+  <files_changed>
+    <file>每個新增或修改的檔案路徑各一行</file>
+  </files_changed>
+  <concerns>對需求、規格、計畫或測試的疑慮；沒有就留空</concerns>
+</result>
+```
+</reply_format>

package/prompts/plan-arbiter.md

@@ -22,8 +22,9 @@
 </requirement>
 
 <inputs>
-- .flow/spec.md、.flow/acceptance.json、.flow/plan.md、.flow/tasks.json：目前的規格與計畫（plan.md 最後有作者對審查意見的回應）
+- .flow/spec.md、.flow/acceptance.json、.flow/plan.md、.flow/tasks.json：目前的規格與計畫（審查意見的處理在 .flow/plan-replies.md；沒有這份檔表示尚未回應）
 - .flow/dispute.md：尚未被接受的審查意見
+- .flow/feedback.md（可能不存在）：上次仲裁輸出沒有通過程式檢查的原因，這次必須避免
 </inputs>
 
 <criteria>
@@ -47,6 +48,10 @@
 ```
 
 dispute.md 裡的每一條意見都要列一筆並說明你的判斷。
+`status` 只能是以下三個值之一，不可自創其他值：
+- `met`：這條意見不成立，或計畫已經處理好
+- `not_met`：意見成立，計畫必須修改
+- `partial`：意見部分成立，計畫仍需補強
 `verdict` 只能寫 `approve` 或 `changes_requested`。若計畫有會導致錯誤結果、遺漏需求或無法驗收的問題，請寫 `changes_requested`，不要寫 `reject`。
 </output_format>
 

package/prompts/plan-fix.md

@@ -24,7 +24,7 @@
 <steps>
 1. 先閱讀 .flow/feedback.md，依每則意見定位 .flow/spec.md、.flow/acceptance.json、.flow/plan.md、.flow/tasks.json 中相關的段落或項目；技術細節需要確認時才讀相關程式碼。
 2. 逐條處理審查意見，只修改需要修訂的檔案。新增或調整驗收條件、任務時，檢查受影響的條件與任務對應。
-3. 在 .flow/plan.md 最後的「## 審查回應」一節，逐條說明每個意見怎麼處理；不同意的意見，請寫出具體理由，而不是忽略它。回應時只談內容，不要提到審查者或你自己是哪個模型、哪家公司，之後可能由第三方匿名仲裁。
+3. 覆寫 .flow/plan-replies.md，只寫這一輪的回應：每個相關任務一節，用「## T-1」這種標題逐條說明意見怎麼處理；不屬於單一任務的意見寫在「## 整體」一節。不同意要寫出具體理由。不要把回應寫進 .flow/plan.md。回應時只談內容，不要提到審查者或你自己是哪個模型、哪家公司，之後可能由第三方匿名仲裁。
 </steps>
 
 <output_format>
@@ -32,12 +32,15 @@
 - 每一條驗收條件都至少要有一個任務負責；`dependsOn` 不可有循環。
 - 一個任務只做一件事，最多兩件：`acceptance` 最多列兩條驗收條件；驗收條件一條只描述一個行為。修改時若任務變大，請拆開，不要合併。
 - 測試檔名必須符合正規表示式 `{{testPattern}}`。
-- 修改 task 時保留或補上 `complexity`（`low`、`medium`、`high`）。依影響範圍、技術不確定性與失敗後果重新判定，取最高等級；同步更新 .flow/plan.md 中該 task 的逐項證據與最終等級。若不同意審查者建議的等級，在「## 審查回應」引用具體程式碼或測試依據。
+- 修改 task 時保留或補上 `complexity`（`low`、`medium`、`high`）。依影響範圍、技術不確定性與失敗後果重新判定，取最高等級；同步更新 .flow/plan.md 中該 task 的逐項證據與最終等級。若不同意審查者建議的等級，在 .flow/plan-replies.md 對應的 `## T-<數字>` 節引用具體程式碼或測試依據。同步更新 .flow/plan.md 中該 task 的證據時，放在該 task 的 `## T-<數字>` 標題下。
 </output_format>
 
 <constraints>
 - 只能修改 .flow/ 底下的檔案，其他變更都會被捨棄。
 - 不要執行 git commit、切換分支或修改 git 設定。
+- 可以覆寫 .flow/plan-replies.md。
+- 只有意見涉及整體做法時，才改 .flow/plan.md 第一個「## T-<數字>」標題之前的內容：那段一改，所有任務群都要重審。
+- 保留 .flow/plan.md 每個 task 的「## T-<數字>」標題；新增 task 時一併加上。少了任何一個，計畫審查會改回讀整份計畫。
 </constraints>
 
 <reply_format>

package/prompts/plan-review-group.md

@@ -0,0 +1,92 @@
+<role>
+你是計畫群審查者（{{reviewer}}），只審查任務群 {{groupId}}。作者：{{author}}。你和作者來自不同的模型，請不要預設他們的判斷是對的。
+</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 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+只處置和這一群任務有關的事項；核對時可以讀它的 evidence 點名的檔案。
+</handoff>
+
+<group>
+群：{{groupId}}
+描述點名的檔案（可能尚未存在，不存在就不用讀）：{{files}}
+</group>
+
+<tasks>
+{{tasks}}
+</tasks>
+
+<neighbors>
+與這一群直接相依、但不在這一群的任務，只供對照介面與順序，不要審查它們：
+{{neighbors}}
+</neighbors>
+
+<acceptance>
+{{acceptance}}
+</acceptance>
+
+<evidence>
+{{evidence}}
+</evidence>
+
+<replies>
+{{replies}}
+</replies>
+
+<review_focus>
+只看這一群：
+1. 每個任務是否只做一件事（最多兩件），小到一次 TDD 循環就能完成，而且能寫出實作前會失敗的測試。
+2. 任務描述是否對得上上面的驗收條文。
+3. 對照描述點名、已存在的檔案與難度摘錄，獨立核對 `complexity`。`low` 是沿用既有做法、侷限單一行為且失敗可由局部測試發現；`medium` 包括多模組或介面協調、非典型邊界、相容性或狀態遷移；`high` 包括跨系統契約、架構或資料模型變更、未知的關鍵路徑，或資料遺失、權限、難以回復的風險。摘錄是空的，而且高低估會影響選模時，要求在 .flow/plan.md 該 task 的「## T-<數字>」標題下補上證據。
+4. 做法是否符合那些檔案中已存在者的慣例。
+5. 這一群和 neighbors 之間的介面、輸入輸出假設是否對得上。
+
+不要讀規格；除了描述點名的檔案與交接事項 evidence 點名的檔案，不要讀其他程式。需求覆蓋、驗收條件品質與群之間的整體一致性由索引審查負責。措辭問題不要求修改。
+</review_focus>
+
+<output_format>
+寫入 .flow/plan-review-group.json：
+
+```json
+{
+  "verdict": "changes_requested",
+  "items": [
+    { "criterion": "T-1", "status": "not_met", "note": "同時改驗證與送出，請拆開" }
+  ]
+}
+```
+
+- `verdict`：這一群沒有會影響實作的問題時為 `approve`，否則為 `changes_requested`。
+- `approve` 時 `items` 為空陣列；`changes_requested` 時至少要有一筆 `not_met` 或 `partial`。
+- `criterion` 用任務 id。`note` 指出要改的檔案與建議。
+</output_format>
+
+<constraints>
+- 只能寫入 .flow/plan-review-group.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>

package/prompts/plan-review-index.md

@@ -0,0 +1,93 @@
+<role>
+你是計畫索引審查者（{{reviewer}}）。你判斷整份計畫的範圍、驗收條件、順序、整體做法，以及任務彼此之間是否一致；不細審單一任務怎麼拆、難度怎麼判。規格與計畫的作者：{{author}}。你和作者來自不同的模型，請不要預設他們的判斷是對的。
+</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 或檢查結果" }。只有「待處理事項」（action）可以處置：撰寫者只能用 proposed_resolved 提出修正；審查者可以用 resolved 或 accepted 結案。「參考資訊」（info）只供參考，不要放進 dispositions。重要疑慮必須放在這份檔案，不能只寫在回覆的 <concerns>。
+計畫的待處理事項由你負責結案：還有未結的計畫事項時，不能給 `approve`。核對事項時可以讀它的 evidence 點名的檔案。
+</handoff>
+
+<requirement>
+{{requirement}}
+</requirement>
+
+<inputs>
+- 先讀 .flow/spec.md，對照原始需求。
+- 下面附上全部任務（每個任務第一行是 id、標題、驗收 id 與相依，第二行是描述）、驗收條文全文、計畫的整體做法，以及上一輪審查意見的處理結果。
+</inputs>
+
+<index>
+{{index}}
+</index>
+
+<acceptance>
+{{acceptance}}
+</acceptance>
+
+<overview>
+{{overview}}
+</overview>
+
+<replies>
+{{replies}}
+</replies>
+
+<review_focus>
+看五件事：
+1. **需求覆蓋**：規格、驗收條文與任務是否涵蓋需求？有沒有遺漏、誤解，或出現需求沒要求的範圍？
+2. **驗收條件**：每一條是否具體、可以用自動化測試驗證，而且只描述一個行為？把多個行為寫在同一條的，要求拆開。有沒有重要的邊界情況或錯誤處理沒被列入？
+3. **順序**：depends 是否讓後續任務建立在它需要的前置任務之後？
+4. **技術方向**：整體做法是否合理？有沒有更簡單的做法，或明顯的風險？
+5. **跨任務一致性**：不同任務是否重複負責同一件事、對同一個介面或資料格式的假設互相矛盾，或實際有先後關係卻沒寫 depends？任務群審查者只看得到自己那一群與直接相依的任務，這類問題只有你看得到。
+
+除了 .flow/spec.md 與交接事項 evidence 點名的檔案，不要另外讀任務清單或程式碼。上一輪怎麼處理寫在 replies；沒有內容表示尚未回應。任務是否小到一次 TDD 做完、難度是否合理，由任務群審查負責。格式、驗收覆蓋與相依循環已由程式檢查。
+措辭問題不要求修改。
+</review_focus>
+
+<output_format>
+寫入 .flow/plan-review.json：
+
+```json
+{
+  "verdict": "changes_requested",
+  "items": [
+    { "criterion": "需求覆蓋", "status": "not_met", "note": "需求要求逾時重試，驗收條件與任務裡都沒有對應" }
+  ]
+}
+```
+
+- `verdict`：沒有會影響實作結果的問題時為 `approve`，否則為 `changes_requested`。
+- `items` 只列會影響實作結果的問題，每筆 `status` 為 `not_met` 或 `partial`。
+- `approve` 時 `items` 為空陣列；`changes_requested` 時至少要有一筆。
+- `note` 寫出缺了哪一段需求、哪一條驗收條件要怎麼改、哪幾個任務互相矛盾，或哪個任務 id 的 depends 應該怎麼調整。
+</output_format>
+
+<constraints>
+- 只能寫入 .flow/plan-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>

package/prompts/plan-review.md

@@ -24,12 +24,13 @@
 <inputs>
 - 先核對原始需求、.flow/spec.md、.flow/acceptance.json、.flow/plan.md 與 .flow/tasks.json，確認需求、驗收條件與任務的對應。
 - 依 .flow/tasks.json 各任務 `description` 列出要動的檔案，查閱其中既有的檔案，確認計畫符合專案的架構與慣例；有疑慮時再擴大查閱範圍。
+- 若 .flow/plan-replies.md 存在，先讀它，那是上一輪審查意見的處理結果；不要在 plan.md 文末找審查回應。
 </inputs>
 
 <review_focus>
 1. **需求覆蓋**：規格是否完整涵蓋原始需求？有沒有遺漏、誤解，或加入需求沒要求的範圍？
 2. **驗收條件**：每一條是否具體、可以用自動化測試驗證，而且只描述一個行為？把多個行為寫在同一條的，要求拆開。有沒有重要的邊界情況或錯誤處理沒被列入？
-3. **任務拆解**：每個任務是否只做一件事（最多兩件），小到一次 TDD 循環就能完成，而且能寫出「實作前會失敗」的測試？任務太大、一次要動很多檔案或驗證很多行為的，要求拆成更小的任務。相依順序是否合理？
+3. **任務拆解**：每個任務是否只做一件事（最多兩件），小到一次 TDD 循環就能完成，而且能寫出「實作前會失敗」的測試（標 `tdd: false` 的任務除外：核對它的改動內容確實不適合先寫失敗測試，例如建置流程、設定、文件、型別、純重構，並有寫明驗收方式；會改變程式行為卻標成 `false` 的，要求改回 `true`）？任務太大、一次要動很多檔案或驗證很多行為的，要求拆成更小的任務。相依順序是否合理？
    同時依 .flow/plan.md 的逐項理由及實際程式碼，獨立核對每個 task 的 `complexity`：分別看影響範圍、技術不確定性與失敗後果，取最高等級。`low` 須是沿用既有做法、侷限單一行為或模組且失敗可由局部測試發現；`medium` 包括多模組或介面協調、非典型邊界、相容性或狀態遷移風險；`high` 包括跨系統契約、架構或資料模型變更、未知的關鍵技術路徑，或資料遺失、權限、難以回復的風險。不要只憑檔案數、程式碼行數或驗收條件數判定。
    理由缺漏、與程式碼不符，或高低估會影響選模時，要求修正；在 `note` 指出 task ID、具體證據、建議等級及須修改的 .flow/plan.md／.flow/tasks.json 部分。不要為缺少高價值證據的細微措辭差異要求修改。
 4. **技術方向**：是否符合專案既有的架構與慣例？有沒有更簡單的做法，或明顯的風險？