agentflowctl 0.14.0 → 0.15.1

package/README.md

@@ -1,5 +1,8 @@
 # agentflowctl
 
+[![npm version](https://img.shields.io/npm/v/agentflowctl.svg)](https://www.npmjs.com/package/agentflowctl)
+[![GitHub release](https://img.shields.io/github/v/release/gogogohuang/agentflowctl)](https://github.com/gogogohuang/agentflowctl/releases)
+
 讓 Claude Code、Codex、Gemini CLI 等 agent 在同一個專案裡分工：整理需求、規劃、寫測試與程式、交叉審查，最後建立 PR。agentflowctl 負責推進流程，並用檔案、測試和檢查結果決定能否進到下一步。
 
 目前內建支援三種 LLM CLI：**Claude Code、Codex、Gemini CLI**。未來可擴充自定義 LLM adapter，讓其他模型供應商加入流程。目前若要串接其他 CLI，可使用 `command` adapter，自行提供執行命令；需要模型驗證時，也須提供探測命令。
@@ -31,13 +34,13 @@ npx agentflowctl run --req-file ./requirement.md
 ## 執行時會發生什麼
 
 1. agent 整理需求與驗收條件，接著寫計畫，交給其他 agent 審查。
-2. 依計畫逐個任務寫出會失敗的測試，再由另一位 agent 實作到測試通過；每個任務都會經過審查與驗證。
+2. 依計畫逐個任務寫出會失敗的測試，再由另一位 agent 實作到測試通過；每個任務都會經過審查與驗證。計畫 agent 會依改動內容在任務標記 `tdd`：建置流程、設定、文件、型別、純重構這類不適合先寫失敗測試的任務，會略過紅綠燈直接實作，改由任務審查與驗證把關。專案沒有測試框架時，所有任務都略過紅綠燈，也不跑 `test` 檢查。
 3. 全部任務完成後，再執行專案檢查與整體程式碼審查。未通過的項目會交回修正。
 4. 有 `origin` 時會推送分支；若 `gh` 可用，會嘗試建立 PR。沒有 `origin` 時，完成的分支留在本機。
 
 流程預設會自動往下走。想在計畫通過審查後親自確認，可加 `--manual-plan`；確認後執行 `agentflowctl approve <id>`。
 
-agentflowctl 會依專案的 `packageManager`、lockfile 與 `package.json` scripts 選擇安裝、測試及檢查指令。第一次執行時，請留意終端機印出的偵測結果；需要調整可在 `flow.config.json` 指定 `install`、`test` 或 `checks`。
+agentflowctl 會依專案的 `packageManager`、lockfile 與 `package.json` scripts 選擇安裝、測試及檢查指令。第一次執行時，請留意終端機印出的偵測結果；需要調整可在 `flow.config.json` 指定 `install`、`test` 或 `checks`。`package.json` 的依賴或 `test` script 看不出測試框架（且沒有手動設定 `test`）時，終端機會提示「未偵測到測試框架」，並略過紅綠燈；要改回來，在 `flow.config.json` 設定 `test`。
 
 ## 查看進度
 
@@ -59,7 +62,7 @@ agentflowctl resume f-xxxx         # 從暫停、中斷或失敗處接續
 
 `insights` 把所有 run 分成獨立區塊彙總：最終狀態、失敗原因（重試達上限、仲裁停止、agent 次數用完等）、用量（輸入／輸出／cache、強度占比、階段／agent，各 run 用量最高的任務）、各模型與步驟、步驟執行與失敗（與 `stats` 相同取 log 的檔頭檔尾，跨 run 不計總經過時間）、關卡重試原因。任務關卡與任務步驟不分 task id 合併計算。最後列出最多五則建議，規則由程式套門檻，不是再請 agent 分析。合計 token 不是主指標。覆蓋不足時會先警告占比可能失真。各分組是同一批呼叫的不同切片，不要跨組相加。舊 run 沒有重試或失敗原因紀錄，不會回填。單一 run 的全量明細仍用 `status <id>` 與 `stats <id>`。
 
-執行紀錄在 `.agentflowctl/runs/<id>/`，工作分支在 `.agentflowctl/worktrees/<id>/`。不再需要某次 run 時，可用 `agentflowctl clean <id>` 清除 worktree 與紀錄；`flow/<id>` 分支會保留。
+執行紀錄在 `.agentflowctl/runs/<id>/`，工作分支在 `.agentflowctl/worktrees/<id>/`。不再需要某次 run 時，可用 `agentflowctl clean <id>` 清除 worktree 與紀錄；`agentflowctl clean --all` 一次清除所有 done、failed 的 run，以及沒有紀錄的 worktree（進行中、暫停、等待核准的不動）。`flow/<id>` 分支會保留。
 
 ## 執行停下來時怎麼做
 
@@ -69,8 +72,8 @@ agentflowctl resume f-xxxx         # 從暫停、中斷或失敗處接續
 | --- | --- |
 | 按 Ctrl-C，或終端機意外關閉 | 執行 `agentflowctl resume <id>`；沒有結束紀錄的步驟會重跑 |
 | `awaiting_approval`：計畫等你確認 | 閱讀 `.agentflowctl/worktrees/<id>/.flow/plan.md`，確認後執行 `agentflowctl approve <id>` |
-| `paused`：agent 額度用完 | 等額度恢復後執行 `agentflowctl resume <id>`；審查步驟不會換 agent 代審 |
-| `paused`：仲裁沒有產生有效裁決 | 依 `status` 的原因查看 log；若有 `.flow/plan-arbiter.json`，也檢查其內容，處理後執行 `agentflowctl resume <id>`。resume 會直接回到仲裁，不重跑計畫審查；暫停期間若改了計畫檔，或在 `flow.config.json` 把 `planArbiter` 關掉，就改成重新審查 |
+| `paused`：agent 額度用完 | 等額度恢復後執行 `agentflowctl resume <id>`；審查步驟不會換 agent 代審。在仲裁途中暫停時，resume 直接回到仲裁，不重跑計畫審查；暫停期間若改了計畫檔，或在 `flow.config.json` 把 `planArbiter` 關掉，就改成重新審查 |
+| `failed`：仲裁連續沒有產生有效裁決 | 仲裁者沒寫出 `.flow/plan-arbiter.json`、格式錯誤或交接無效時不會暫停，會把原因寫進 `.flow/feedback.md` 並自動重跑仲裁（不重跑計畫審查）；無效的檔案移到 `.agentflowctl/runs/<id>/reviews/plan-arbiter-<輪>-<agent>-invalid.json`。連續達重試上限才失敗，查看 log 後執行 `agentflowctl resume <id>` 會再回到仲裁 |
 | `failed`：測試、檢查、審查或 agent 執行失敗 | 依 `status` 提示查看失敗的 log，處理原因後執行 `agentflowctl resume <id>`；失敗階段會重試 |
 | `failed`：已達 agent 執行次數上限 | 用 `agentflowctl resume <id> --max-agent-runs 100` 調高上限後接續，數字須大於已執行次數 |
 
@@ -97,6 +100,7 @@ agentflowctl resume f-xxxx
 | `run --cycle <名單>` | 指定這次參與的 agent，例如 `--cycle claude,codex`；優先於設定檔的 `cycle` |
 | `run --model-mode balanced\|adaptive` | 只覆蓋這次 run 的模型模式；`resume` 沿用建立時的模式 |
 | `run --base <分支>` | 指定起始分支；未設定時使用目前分支 |
+| `run --max-attempts <次數>` | 覆蓋這次的重試上限（至少 3；預設取 `AGENTFLOWCTL_MAX_ATTEMPTS`，未設定為 5）；失敗後可用 `resume <id> --max-attempts <次數>` 調高 |
 | `run --max-agent-runs <次數>` | 覆蓋這次的 `maxAgentRuns`；上限不夠時可用 `resume <id> --max-agent-runs <次數>` 調高 |
 | `-v` / `--verbose` | 執行時顯示 agent 文字、工具呼叫與專案指令，適用於 `run`、`resume`、`approve` |
 
@@ -105,6 +109,7 @@ agentflowctl resume f-xxxx
 ```bash
 agentflowctl run --req-file ./requirement.md --cycle claude,codex --max-agent-runs 80 --manual-plan
 agentflowctl resume f-xxxx --max-agent-runs 100
+agentflowctl resume f-xxxx --max-attempts 8
 ```
 
 ### Agent 設定
@@ -189,7 +194,7 @@ Codex 另有幾點差異：
 | `tddSplit` | `true` | 有多位 agent 時，`true` 會把同一任務的測試與實作分給不同 agent |
 | `reviewQuorum` | `1` | 任務與最終程式碼審查需要幾位不同審查者核准 |
 | `planReviewQuorum` | `1` | 計畫需要幾位不同審查者核准 |
-| `planArbiter` | `true` | 計畫審查僵持時是否啟用仲裁 |
+| `planArbiter` | `true` | 計畫審查僵持，或修訂一次後仍被要求修改時是否啟用仲裁 |
 | `planReviewLayers` | `{ "enabled": true, "minTasks": 7, "maxGroups": 5, "tasksPerGroup": 3 }` | 任務夠多時把計畫審查拆成索引與任務群；說明見表格下方 |
 | `tieBreak` | `"proceed"` | 兩位仲裁者意見分歧時，`"proceed"` 繼續、`"stop"` 停止 |
 | `maxAgentRuns` | `60` | 一次 run 最多執行幾次 agent；可用指令選項覆蓋 |
@@ -207,11 +212,23 @@ Codex 另有幾點差異：
 
 | 變數 | 預設 | 設定方式與用途 |
 | --- | --- | --- |
-| `AGENTFLOWCTL_MAX_ATTEMPTS` | `3` | 同一關連續失敗幾次後停止；例如 `AGENTFLOWCTL_MAX_ATTEMPTS=10 agentflowctl run --req "..."` |
+| `AGENTFLOWCTL_MAX_ATTEMPTS` | `5` | 同一關連續失敗幾次後停止，至少 3（設得更小以 3 計）；例如 `AGENTFLOWCTL_MAX_ATTEMPTS=10 agentflowctl run --req "..."` |
 | `AGENTFLOWCTL_VERBOSE` | 未開啟 | 設為 `1` 顯示詳細輸出，效果同 `-v` |
-| `AGENTFLOWCTL_MAX_TURNS` | `80` | 目前程式會讀取此值，但尚未用它限制 agent 執行 |
+| `AGENTFLOWCTL_MAX_TURNS` | `200` | 目前程式會讀取此值，但尚未用它限制 agent 執行 |
+
+環境變數對新啟動的 agentflowctl 程序生效。`AGENTFLOWCTL_MAX_ATTEMPTS` 是單一關卡的重試上限（至少 3），單一 run 可用 `run`／`resume` 的 `--max-attempts` 覆蓋；計畫審查何時交付仲裁與它無關：意見沒有變化，或第 2 輪（修訂過一次）仍被要求修改時就交付，兩家 agent 時自動進入雙盲交叉仲裁，有第三方時由第三方單獨仲裁；`maxAgentRuns` 則是整次 run 的 agent 執行次數上限。修正成功、或計畫審查與程式碼審查整組完成一輪有效審查後，該關的失敗次數會歸零，所以上限只計算連續失敗。分層計畫審查時，同一輪裡只要有一次審查呼叫真的執行成功，計畫審查的失敗次數也會歸零；所以索引與各群輪流各失敗一次、每次重跑都有進展時，不會因累計達上限而失敗。
+
+## 發版（維護者）
+
+在 clone 下來的 repo 裡用 `pnpm release <patch|minor|major|x.y.z> [--dry-run]` 發版，只能在 `main` 執行：
+
+```bash
+pnpm release patch --dry-run   # 只檢查與驗證，不建立 Release
+pnpm release minor             # 確認後建立 v0.x+1.0 的 GitHub Release
+pnpm release 1.0.0             # 指定版本，必須大於目前最新的 tag
+```
 
-環境變數對新啟動的 agentflowctl 程序生效。`AGENTFLOWCTL_MAX_ATTEMPTS` 是單一關卡的重試上限；`maxAgentRuns` 則是整次 run 的 agent 執行次數上限。修正成功、或計畫審查與程式碼審查整組完成一輪有效審查後，該關的失敗次數會歸零，所以上限只計算連續失敗。分層計畫審查時，同一輪裡只要有一次審查呼叫真的執行成功，計畫審查的失敗次數也會歸零；所以索引與各群輪流各失敗一次、每次重跑都有進展時，不會因累計達上限而失敗。
+腳本會先檢查目前在 `main`、工作區乾淨、與 `origin/main` 同步、`gh` 已登入、新 tag 不存在，再跑 typecheck、test、build，列出自上個 tag 以來的 commit 並等你輸入 `y` 確認，然後用 `gh release create --generate-notes` 建立 Release。npm 由 Release 觸發的 `npm-publish.yml` 發布；版本號取自 tag，腳本不會改 `package.json`。
 
 ## 更多文件
 

package/dist/cli.js

@@ -4,7 +4,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { stdin, stdout } from "node:process";
 import { createInterface } from "node:readline/promises";
-import { config } from "./config.js";
+import { MIN_ATTEMPTS, config } from "./config.js";
 import { advance, loadRepoConfig } from "./engine.js";
 import { probeAgent, resolveAgent, runCommand } from "./runner.js";
 import { addWorktree, git } from "./git.js";
@@ -35,6 +35,12 @@ function printUsage(title, rows) {
         console.log(`  ${key}: ${value}；${c.runs} 次（未回報 ${c.unreportedRuns}、舊紀錄不明 ${c.legacyRuns}）`);
     }
 }
+function positiveInt(text, flag, min = 1) {
+    const n = Number(text);
+    if (!Number.isInteger(n) || n < min)
+        throw new Error(`${flag} 必須是不小於 ${min} 的整數：${text}`);
+    return n;
+}
 function mustGetRun(id) {
     const run = getRun(id);
     if (!run)
@@ -121,6 +127,7 @@ program
     .option("--req-file <file>", "從檔案讀取需求")
     .option("--base <branch>", "基底分支（預設為目前的分支）")
     .option("--max-agent-runs <n>", "單一 run 最多執行幾次 agent（預設取 flow.config.json 的 maxAgentRuns）")
+    .option("--max-attempts <n>", "同一關連續失敗幾次後停止（預設取 AGENTFLOWCTL_MAX_ATTEMPTS，未設定為 5）")
     .option("--manual-plan", "計畫通過 AI 審查後，仍停下來等你確認", false)
     .option("--cycle <agents>", "參與的 agent，例如 claude,codex,gemini（順序不影響分工）")
     .option("--model-mode <mode>", "這次 run 的模型模式：balanced 或 adaptive")
@@ -154,6 +161,7 @@ program
         stage: "spec",
         autopilot: !opts.manualPlan,
         maxAgentRuns: opts.maxAgentRuns ? Number(opts.maxAgentRuns) : cfg.maxAgentRuns,
+        maxAttempts: opts.maxAttempts ? positiveInt(opts.maxAttempts, "--max-attempts", MIN_ATTEMPTS) : undefined,
         cycle,
         attempts: {},
         modelMode,
@@ -183,12 +191,15 @@ program
     .command("resume <id>")
     .description("從暫停、中斷或失敗的階段接續")
     .option("--max-agent-runs <n>", "調整 agent 執行次數上限")
+    .option("--max-attempts <n>", "調整同一關連續失敗的上限")
     .action(async (id, opts) => {
     let run = mustGetRun(id);
     if (run.modelMode === "adaptive")
         validateAdaptiveConfig(loadRepoConfig(), run.cycle);
     if (opts.maxAgentRuns)
         run = { ...run, maxAgentRuns: Number(opts.maxAgentRuns) };
+    if (opts.maxAttempts)
+        run = { ...run, maxAttempts: positiveInt(opts.maxAttempts, "--max-attempts", MIN_ATTEMPTS) };
     if (run.stage === "paused") {
         run = { ...run, stage: run.pausedStage ?? "spec", pausedStage: undefined, pauseReason: undefined };
     }

package/dist/config.js

@@ -1,8 +1,10 @@
+/** 重試上限的下限：低於這個值時，修正與審查來不及往返一輪 */
+export const MIN_ATTEMPTS = 3;
 export const config = {
     /** 單一 Agent 執行最多幾輪工具迴圈，避免卡在迴圈裡 */
-    maxTurns: Number(process.env.AGENTFLOWCTL_MAX_TURNS ?? 80),
-    /** 同一個關卡連續失敗幾次後停止 */
-    maxAttempts: Number(process.env.AGENTFLOWCTL_MAX_ATTEMPTS ?? 3),
+    maxTurns: Number(process.env.AGENTFLOWCTL_MAX_TURNS ?? 200),
+    /** 同一個關卡連續失敗幾次後停止；環境變數低於 3 時以 3 計 */
+    maxAttempts: Math.max(MIN_ATTEMPTS, Number(process.env.AGENTFLOWCTL_MAX_ATTEMPTS ?? 5) || 5),
     /** 終端機是否印出 agent 的文字、工具呼叫與專案指令；預設安靜，-v 或 AGENTFLOWCTL_VERBOSE=1 開啟 */
     verbose: process.env.AGENTFLOWCTL_VERBOSE === "1",
 };

package/dist/detect.js

@@ -24,6 +24,16 @@ const CHECK_SCRIPTS = {
     test: ["test"],
     build: ["build"],
 };
+/** 出現在依賴裡就代表專案有測試框架 */
+const TEST_FRAMEWORKS = ["vitest", "jest", "mocha", "ava", "jasmine", "tap", "uvu", "@playwright/test", "cypress"];
+function hasTestFramework(pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (TEST_FRAMEWORKS.some((name) => name in deps))
+        return true;
+    const script = pkg.scripts?.test;
+    // npm init 產生的佔位 script 不算
+    return typeof script === "string" && !/no test specified/i.test(script);
+}
 function readPackageJson(root) {
     try {
         const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
@@ -56,24 +66,31 @@ export function detectProjectDefaults(root) {
         const script = CHECK_SCRIPTS[name]?.find((s) => typeof scripts[s] === "string");
         return { name, cmd: script ? `${manager} run ${script}` : withExec(cmd, manager) };
     });
-    return { manager, source, install: INSTALL[manager], test: withExec(defaults.test, manager), checks };
+    return { manager, source, install: INSTALL[manager], test: withExec(defaults.test, manager), checks, testFramework: hasTestFramework(pkg) };
 }
+/** 手動設定 test 指令就當作有測試框架 */
+export const usesTestFramework = (raw, detected) => detected.testFramework || (!!raw && typeof raw === "object" && "test" in raw);
 /** 補上原始設定裡沒寫的 install、test、checks；不是物件就原樣回傳，交給 schema 報錯 */
 export function withProjectDefaults(raw, detected) {
     if (!raw || typeof raw !== "object" || Array.isArray(raw))
         return raw;
-    const { install, test, checks } = detected;
+    const { install, test } = detected;
+    // 沒有測試框架也沒手動設定 test 時，預設的檢查不含 test
+    const checks = usesTestFramework(raw, detected) ? detected.checks : detected.checks.filter((c) => c.name !== "test");
     return { install, test, checks, ...raw };
 }
 /** run 開始時印出的說明：只列出這次用了偵測結果的欄位 */
 export function describeDetected(raw, detected) {
     const lines = [];
+    const framework = usesTestFramework(raw, detected);
     if (!("install" in raw))
         lines.push(`   install：${detected.install}`);
-    if (!("test" in raw))
+    if (!("test" in raw) && framework)
         lines.push(`   test：${detected.test}`);
     if (!("checks" in raw))
-        lines.push(...detected.checks.map((c) => `   checks.${c.name}：${c.cmd}`));
+        lines.push(...detected.checks.filter((c) => framework || c.name !== "test").map((c) => `   checks.${c.name}：${c.cmd}`));
+    if (!framework)
+        lines.push("ℹ️  未偵測到測試框架，所有任務略過紅綠燈，也不跑 test 檢查（在 flow.config.json 設定 test 可改回來）");
     if (!lines.length)
         return [];
     const why = detected.source === "預設" ? "預設" : `依 ${detected.source}`;

package/dist/engine.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { z } from "zod";
 import { config } from "./config.js";
 import { arbitrationDecision } from "./arbitration.js";
-import { detectProjectDefaults, withProjectDefaults } from "./detect.js";
+import { detectProjectDefaults, usesTestFramework, withProjectDefaults } from "./detect.js";
 import { escapeXml, opinion, reviewIssue } from "./feedback.js";
 import { changedFiles, commitAll, discardChanges, git, headCommit, resetTo } from "./git.js";
 import { acceptHandoff, openActions, prepareHandoff, previewHandoff, readHandoff, recoverHandoff, reviewHandoffGate, validateHandoffResponse } from "./handoff.js";
@@ -125,18 +125,24 @@ function flowText(run, name) {
 function readFeedback(run) {
     return flowText(run, "feedback.md");
 }
+/** 計畫審查第幾輪仍有人要求修改時交付仲裁；固定值，不受重試上限影響 */
+const PLAN_ARBITRATION_ROUND = 2;
+/** 這個 run 的重試上限：`--max-attempts` 存在 run 裡，沒設定才用環境變數 */
+function attemptLimit(run) {
+    return run.maxAttempts ?? config.maxAttempts;
+}
 /** 關卡未通過：寫入 feedback.md 給下一次嘗試參考，並把原因分類記進 retries.jsonl；超過上限就讓整個 run 失敗 */
 function retry(run, key, reason, backTo, category) {
     const n = (run.attempts[key] ?? 0) + 1;
     const attempts = { ...run.attempts, [key]: n };
-    const final = n >= config.maxAttempts;
+    const final = n >= attemptLimit(run);
     mkdirSync(flowDir(run.id), { recursive: true });
     writeFileSync(flowFile(run, "feedback.md"), `# 前次嘗試未通過（第 ${n} 次）\n\n${reason}\n`);
     addRetry(run.id, { key, backTo, category, attempt: n, final }, run.updatedAt);
     if (final) {
         return { ...run, attempts, stage: "failed", failedStage: backTo, failureCategory: "retry_limit", failureReason: `${key} 連續失敗 ${n} 次：${tail(reason, 500)}` };
     }
-    info(run, `⚠️  ${key} 未通過，重試（${n}/${config.maxAttempts}）`);
+    info(run, `⚠️  ${key} 未通過，重試（${n}/${attemptLimit(run)}）`);
     return { ...run, attempts, stage: backTo };
 }
 function succeed(run, key, next) {
@@ -158,6 +164,17 @@ export function loadRepoConfig() {
         throw new Error(r.error);
     return r.data;
 }
+/** 專案有測試框架（偵測到或手動設定 test） */
+function hasTestFramework() {
+    const root = projectRoot();
+    const p = join(root, "flow.config.json");
+    const r = existsSync(p) ? readJsonFile(p, z.unknown()) : undefined;
+    return usesTestFramework(r?.ok ? r.data : {}, detectProjectDefaults(root));
+}
+/** 這個任務要不要走紅綠燈：沒有測試框架一律不走，其餘依 planner 標記（沒標視為要走） */
+function taskUsesTdd(task, framework) {
+    return framework && task.tdd !== false;
+}
 function loadOrderedTasks(run) {
     const r = readJsonFile(flowFile(run, "tasks.ordered.json"), TaskList);
     if (!r.ok)
@@ -236,9 +253,12 @@ function acceptPlan(run, ordered) {
 function announceTasks(run, ordered) {
     const cfg = loadRepoConfig();
     info(run, `📋 共 ${ordered.length} 個任務：${ordered.map((t) => t.id).join(" → ")}`);
+    const framework = hasTestFramework();
     ordered.forEach((t, i) => {
         const a = taskAgents(run.cycle, i, cfg.tddSplit, run.id);
-        info(run, `   ${t.id} 測試：${a.tests}　實作：${a.code}　審查：${a.review}`);
+        info(run, taskUsesTdd(t, framework)
+            ? `   ${t.id} 測試：${a.tests}　實作：${a.code}　審查：${a.review}`
+            : `   ${t.id} 略過 TDD　實作：${a.code}　審查：${a.review}`);
     });
 }
 /** 計畫定案後：預設直接開始實作；--manual-plan 時才停下來等人 */
@@ -346,7 +366,8 @@ async function concludePlanReview(run, cfg, round, calls) {
     const fingerprint = reviewFingerprint(issueLines);
     const stalled = existsSync(lastPath) && readFileSync(lastPath, "utf8") === fingerprint;
     writeFileSync(lastPath, fingerprint);
-    const exhausted = round >= config.maxAttempts;
+    // 修訂過一次仍被要求修改就交付仲裁，不等到重試上限
+    const exhausted = round >= PLAN_ARBITRATION_ROUND;
     if ((stalled || exhausted) && cfg.planArbiter) {
         // 雙盲：帶有審查者名稱的 feedback.md 不留在 worktree，完整報告另存到 worktree 外
         rmSync(flowFile(run, "feedback.md"), { force: true });
@@ -587,8 +608,14 @@ async function arbitratePlan(run) {
         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 category = handoffError ? "handoff_invalid" : !r.ok ? "agent_error" : "format_invalid";
+            info(run, `   ✗ ${arbiter} 未產生有效裁決：${reason}`);
+            // 無效的裁決移到 worktree 外保存，供事後查看；plan-arbitration.json 還在，重試時直接回到仲裁
+            if (existsSync(flowFile(run, "plan-arbiter.json"))) {
+                mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
+                renameSync(flowFile(run, "plan-arbiter.json"), join(runDir(run.id), "reviews", `plan-arbiter-${arbitrationRound}-${arbiter}-invalid.json`));
+            }
+            return retry(run, "plan-arbitration-run", `上次仲裁未產生有效裁決：${reason}`, "plan_review", category);
         }
         mkdirSync(join(runDir(run.id), "reviews"), { recursive: true });
         renameSync(flowFile(run, "plan-arbiter.json"), join(runDir(run.id), "reviews", `plan-arbiter-${arbitrationRound}-${arbiter}.json`));
@@ -600,6 +627,8 @@ async function arbitratePlan(run) {
     }
     rmSync(flowFile(run, "dispute.md"), { force: true });
     rmSync(planArbitrationPath(run.id), { force: true });
+    run = { ...run, attempts: { ...run.attempts } };
+    delete run.attempts["plan-arbitration-run"];
     const approvals = verdicts.filter((v) => v.verdict === "approve").length;
     const unanimous = approvals === verdicts.length;
     const decision = arbitrationDecision(verdicts.map((v) => v.verdict), cfg.tieBreak);
@@ -655,6 +684,13 @@ async function implementStage(run) {
     if (run.taskPhase === "fix")
         return taskFixStep(run, task, progress);
     const agents = taskAgents(run.cycle, run.taskIndex, cfg.tddSplit, run.id);
+    const framework = hasTestFramework();
+    const tdd = taskUsesTdd(task, framework);
+    // ── 不走 TDD：略過紅燈，實作前的 HEAD 就是這個任務的起點 ──
+    if (!tdd && run.taskPhase === "tests") {
+        info(run, `⏭️  [${progress}] 略過 TDD（${framework ? "planner 標記不適合先寫測試" : "專案沒有測試框架"}）`);
+        return { ...run, taskPhase: "code", taskBase: await headCommit(repo), testsCommit: undefined, lastTestsAuthor: undefined };
+    }
     // ── 紅燈：只寫測試，而且測試必須失敗 ──
     if (run.taskPhase === "tests") {
         const key = `${task.id}:tests`;
@@ -696,13 +732,16 @@ async function implementStage(run) {
     }
     // ── 綠燈：實作到測試通過，而且不可動測試 ──
     const key = `${task.id}:code`;
-    const testsCommit = run.testsCommit;
+    // 走 TDD 時以測試 commit 為基準；不走 TDD 時以任務起點為基準
+    const testsCommit = tdd ? run.testsCommit : run.taskBase;
     if (!testsCommit)
-        throw new Error("缺少 testsCommit，狀態不一致");
-    info(run, `🛠️  [${progress}] 實作（${agents.code}，測試由 ${run.lastTestsAuthor ?? agents.tests} 撰寫）`);
+        throw new Error(tdd ? "缺少 testsCommit，狀態不一致" : "缺少 taskBase，狀態不一致");
+    info(run, tdd ? `🛠️  [${progress}] 實作（${agents.code}，測試由 ${run.lastTestsAuthor ?? agents.tests} 撰寫）` : `🛠️  [${progress}] 實作（${agents.code}，不走 TDD）`);
     const redOutput = existsSync(flowFile(run, "red-output.txt")) ? readFileSync(flowFile(run, "red-output.txt"), "utf8") : "";
     const snap = snapshotPlan(run, LOCKED_FILES);
-    const outcome = await agentStep(run, agents.code, `${task.id}-code`, renderPrompt("implement-code", { task: taskJson, acceptance: acceptanceJson, testCmd, redOutput: tail(redOutput, 3000) }), { kind: "write", reset: async () => { await resetTo(repo, testsCommit); restorePlan(run, snap); } });
+    const outcome = await agentStep(run, agents.code, `${task.id}-code`, tdd
+        ? renderPrompt("implement-code", { task: taskJson, acceptance: acceptanceJson, testCmd, redOutput: tail(redOutput, 3000) })
+        : renderPrompt("implement-direct", { task: taskJson, acceptance: acceptanceJson, testCmd: framework ? testCmd : "" }), { kind: "write", reset: async () => { await resetTo(repo, testsCommit); restorePlan(run, snap); } });
     const { r, agent: codeAuthor } = outcome;
     const tampered = restorePlan(run, snap);
     if (!r.ok)
@@ -711,13 +750,16 @@ async function implementStage(run) {
         await resetTo(repo, testsCommit);
         return retry(run, key, planTamperedMessage(tampered), "implement", "plan_tampered");
     }
-    await commitAll(repo, `feat(${task.id}): ${task.title} [${codeAuthor}]`);
-    const touched = (await changedFiles(repo, testsCommit, await headCommit(repo))).filter((f) => testRe.test(f));
+    const codeCommit = await commitAll(repo, `feat(${task.id}): ${task.title} [${codeAuthor}]`);
+    if (!tdd && !codeCommit)
+        return retry(run, key, "沒有任何檔案變更，這個任務必須完成實作。", "implement", "code_not_written");
+    const touched = tdd ? (await changedFiles(repo, testsCommit, await headCommit(repo))).filter((f) => testRe.test(f)) : [];
     if (touched.length) {
         await resetTo(repo, testsCommit);
         return retry(run, key, `實作階段不可修改測試檔，已還原你的變更：${touched.join(", ")}`, "implement", "tests_modified");
     }
-    const green = await runCommand(target(run, `${task.id}-green`, CMD_AGENT), testCmd);
+    // 沒有測試框架時沒有東西可跑，後面的驗證與審查照常把關
+    const green = framework ? await runCommand(target(run, `${task.id}-green`, CMD_AGENT), testCmd) : { ok: true, output: "", seq: 0 };
     if (!green.ok) {
         info(run, `   ✗ 測試仍未通過${logHint(run, green.seq)}`);
         return retry(run, key, `測試仍未通過：\n\n\`\`\`\n${tail(green.output)}\n\`\`\``, "implement", "tests_not_green");
@@ -727,7 +769,7 @@ async function implementStage(run) {
         await resetTo(repo, testsCommit);
         return retry(run, key, handoffError, "implement", "handoff_invalid");
     }
-    info(run, `🟢 [${progress}] 測試通過`);
+    info(run, framework ? `🟢 [${progress}] 測試通過` : `✔️  [${progress}] 實作完成`);
     return { ...succeed(run, key, "implement"), taskPhase: "review", lastWriter: codeAuthor };
 }
 // ── 任務審查：只看這個任務的變更與驗收條件 ──

package/dist/insights.js

@@ -9,6 +9,7 @@ export const RETRY_LABEL = {
     arbitration_revise: "仲裁要求修訂",
     plan_tampered: "改動已鎖定的計畫檔",
     tests_not_written: "未寫測試",
+    code_not_written: "未實作",
     tests_not_red: "紅燈測試未失敗",
     tests_modified: "實作改了測試",
     tests_not_green: "測試仍未通過",

package/dist/schemas.js

@@ -72,6 +72,8 @@ export const TaskItem = z.object({
     dependsOn: z.array(z.string()).default([]),
     acceptance: z.array(z.string()).min(1, "每個任務至少要對應一條驗收條件"),
     complexity: z.enum(["low", "medium", "high"]).optional(),
+    /** false＝這個任務不適合先寫會失敗的測試（建置流程、設定、文件、純重構等），略過紅燈直接實作；沒寫視為 true */
+    tdd: z.boolean().optional(),
 });
 /** Agent 在 plan 階段產出的 .flow/tasks.json */
 export const TaskList = z.array(TaskItem).min(1);
@@ -181,6 +183,8 @@ export const FlowRun = z.object({
     autopilot: z.boolean(),
     /** 單一 run 最多執行幾次 agent */
     maxAgentRuns: z.number().int().positive(),
+    /** 這個 run 同一關連續失敗的上限；沒寫就用 AGENTFLOWCTL_MAX_ATTEMPTS（舊 state.json 沒有此欄位） */
+    maxAttempts: z.number().int().min(3).optional(),
     /** 暫停前所在的階段與原因（額度用完時） */
     pausedStage: Stage.optional(),
     pauseReason: z.string().optional(),

package/dist/store.js

@@ -112,7 +112,7 @@ export function listSubstitutions(id) {
 }
 export const RetryCategories = [
     "agent_error", "missing_artifact", "format_invalid", "handoff_invalid", "open_handoff",
-    "review_changes", "arbitration_revise", "plan_tampered", "tests_not_written", "tests_not_red", "tests_modified",
+    "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");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentflowctl",
   "license": "MIT",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "跨廠商 AI 開發 harness：Claude Code、Codex、Gemini 輪流實作、審查、修正",
   "keywords": [
     "ai",
@@ -41,7 +41,8 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "prepublishOnly": "pnpm run typecheck && pnpm test && pnpm run build"
+    "prepublishOnly": "pnpm run typecheck && pnpm test && pnpm run build",
+    "release": "bash scripts/release.sh"
   },
   "dependencies": {
     "commander": "^12.1.0",

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

@@ -24,6 +24,7 @@
 <inputs>
 - .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-review.md

@@ -30,7 +30,7 @@
 <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. **技術方向**：是否符合專案既有的架構與慣例？有沒有更簡單的做法，或明顯的風險？

package/prompts/plan.md

@@ -39,6 +39,7 @@
     "title": "建立表單驗證 schema",
     "description": "具體要做什麼、要動哪些檔案、測試要驗證什麼行為",
     "complexity": "low",
+    "tdd": true,
     "dependsOn": [],
     "acceptance": ["AC-1"]
   }
@@ -51,7 +52,8 @@
 - 每個任務是一個可獨立測試的垂直切片，小到一次 TDD 循環就能完成；只動少數幾個檔案，測試只驗證一兩個行為。
 - `title` 用一句話說出這件事；需要用「並且」「以及」串起來的，就是兩個任務。
 - `description` 寫清楚要動哪些檔案（寫含目錄的路徑，例如 `src/form.ts`，不要只寫檔名）、測試要驗證哪個行為，以及這個任務不做什麼。計畫審查會依這些路徑把任務分群。
-- 每個任務都必須能寫出「在實作前會失敗」的測試；純設定或重構類工作請併入相關任務。
+- 依改動內容標記 `tdd`：會改變程式行為、能寫出「在實作前會失敗」的測試的任務標 `true`（預設）；改動內容不適合先寫失敗測試的任務標 `false`，這類任務會略過紅燈直接實作，改由任務審查與驗證指令把關。適合標 `false` 的例子：建置流程與打包設定（build、CI、bundler、tsconfig）、依賴與版本設定、文件與 prompt 文字、樣式與靜態資源、型別宣告、不改變行為的重構與搬移檔案。能併入相關行為任務的設定或重構，仍請併入，不要獨立成任務。標 `false` 時要在 .flow/plan.md 該 task 的節裡寫明理由，以及這個任務要怎麼驗收（例如「`npm run build` 通過」）。
+- 專案沒有測試框架時，所有任務都會略過 TDD（程式會強制），此時仍請照實標記 `tdd`，並在 `description` 寫清楚驗收方式。
 - 每個任務先檢查預計修改的程式碼，再依「影響範圍、技術不確定性、失敗後果」三個面向判定 `complexity`，取其中最高的等級；不要只憑檔案數、程式碼行數或驗收條件數判定。
 - `low`：沿用現有做法，變更侷限在單一行為或模組，失敗容易由局部測試發現且不影響既有資料或對外契約。
 - `medium`：需要協調多個模組或既有介面、處理非典型邊界，或有相容性與狀態遷移風險，但可依已知做法實作與驗證。