agentflowctl 0.8.0 → 0.9.0

package/README.md

@@ -17,7 +17,7 @@ claude    # 完成登入
 codex     # 完成登入
 ```
 
-沒有內建的 agent，只會使用 `flow.config.json` 的 `agents` 裡設定的。用 `agent setup` 互動設定：它會偵測本機的 `claude`、`codex`、`gemini`，逐一詢問要不要加入、名稱與 model，再設定參與的 agent；確認後才一次寫入，最後自動跑一次 `doctor`：
+沒有內建的 agent，只會使用 `flow.config.json` 的 `agents` 裡設定的。用 `agent setup` 互動設定：它會先列出已設定的 agent 與 CLI 是否可以執行，再偵測本機裝了哪些支援的 CLI（目前是 `claude`、`codex`、`gemini`），只針對已安裝的逐一詢問要不要加入、名稱與 model，再設定參與的 agent；沒偵測到的只列出、不詢問。確認後才一次寫入，最後自動跑一次 `doctor`：
 
 ```bash
 npx agentflowctl agent setup
@@ -300,7 +300,7 @@ verify 失敗（型別、lint、建置）一律交回最後作者。審查意見
 `agents` 與 `cycle` 也可以用 `agent` 指令修改，不必手動編輯 JSON。每次寫入前都會先驗證整份設定：
 
 ```bash
-agentflowctl agent setup                                  # 互動設定 claude、codex、gemini 與參與的 agent
+agentflowctl agent setup                                  # 偵測已安裝的 agent CLI，互動設定與參與的 agent
 agentflowctl agent list                                   # 設定的 agent、是否已安裝、是否參與
 agentflowctl agent add claude-strong --adapter claude --model opus
 agentflowctl agent add aider --adapter command -- aider --yes-always --message {prompt}
@@ -315,7 +315,7 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 - `set --adapter` 換 adapter 時，會清掉舊 adapter 的 `model`、`extraArgs`、`command`，這次有重新指定的除外。
 - `remove` 會一併從 `cycle` 移除。`cycle` 變空就刪除這個欄位，改回從 `agents` 自動偵測。
 - `--extra-arg` 可以重複指定，會整個取代原本的 `extraArgs`。參數以 `-` 開頭時，寫成 `--extra-arg=--sandbox`。
-- `setup` 遇到已存在的名稱會先問要不要覆寫；不覆寫時保留原設定，但仍會參與。在非互動式環境（CI、管線）裡請改用 `agent add`。`command` adapter 要自己寫指令，不在 `setup` 裡。
+- `setup` 只詢問偵測到已安裝的 CLI，一個都沒有就不變更設定。遇到已存在的名稱會先問要不要覆寫；不覆寫時保留原設定，但仍會參與。在非互動式環境（CI、管線）裡請改用 `agent add`。`command` adapter 要自己寫指令，不在 `setup` 裡。
 
 已建立的 run 會沿用建立時參與的 agent，不受這些修改影響。
 
@@ -327,6 +327,8 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 
 **跨模型審查。** 審查看需求覆蓋、驗收條件能不能測且一條只寫一個行為、任務是否只做一件事（最多兩件）與技術方向。審查者只能寫意見。若改了規格或計畫，檔案會被還原。修改者要在 `plan.md` 的「審查回應」逐條回覆；不同意要寫理由。
 
+計畫審查先核對需求與四份計畫交接檔，再查閱任務說明中要修改的既有檔案，有疑慮時才擴大範圍；審查紀錄只列會影響實作的問題，不逐條列已通過項目。計畫修訂先依 `feedback.md` 定位需要改的段落，修改驗收條件或任務時再檢查受影響的對應關係。檔案格式、任務對驗收條件的覆蓋與任務相依仍由程式驗證；原始需求的語意覆蓋由審查者判斷，以減少反覆讀取文件的 token 用量。
+
 **僵持時仲裁。** 兩種情況會觸發：這輪審查意見和上一輪一樣，或已達重試上限。仲裁者只判斷一件事：照這份計畫實作，能不能滿足需求。
 
 | 有幾家 | 誰來仲裁 | 結果 |
@@ -351,13 +353,17 @@ agentflowctl agent cycle claude-strong,codex,gemini       # 不帶參數時顯
 | plan_fix | 依 `fixStrategy` | 修改後仍通過 plan 的格式與 DAG 檢查 | 還原並重試 |
 | 仲裁 | 見上一節 | 一致核准；分歧依 `tieBreak` | 兩家都不核准時進入 plan_fix 再審查；第三方不核准或 `tieBreak: stop` 時失敗 |
 | 人工確認 | 你（只有 `--manual-plan`） | `agentflowctl approve` | — |
-| implement 紅燈 | 洗牌輪流，每家各一次 | 有測試變更，而且測試執行後失敗 | 還原並重試 |
-| implement 綠燈 | 測試作者以外隨機一位 | 測試檔沒有任何修改，而且測試通過 | 還原，或帶著輸出重試 |
+| implement 紅燈 | 洗牌輪流，每家各一次 | 有測試變更，而且測試執行後失敗；規格與計畫檔沒有被修改 | 還原並重試 |
+| implement 綠燈 | 測試作者以外隨機一位 | 測試檔與規格、計畫檔都沒有被修改，而且測試通過 | 還原，或帶著輸出重試 |
 | verify | — | `install` 與所有 `checks` 通過 | 交回作者修正 |
-| review | 作者以外隨機挑（可多位，不重複） | 所有審查者都 `approve` | 依 `fixStrategy` 交給他人修正 |
+| fix | verify 失敗交回作者；審查意見依 `fixStrategy` | 沒有刪除測試檔，也沒有修改規格與計畫檔 | 還原並重試 |
+| review | 作者以外隨機挑（可多位，不重複） | 所有審查者都 `approve`（審查者對程式碼與規格、計畫檔的修改一律還原） | 依 `fixStrategy` 交給他人修正 |
 | pr | — | push 成功；有 `gh` 就開 PR | — |
 
 驗收條件寫在 `.flow/acceptance.json`（`AC-1`…），任務寫在 `.flow/tasks.json`（`T-1`…）。
+每個任務的寫測試與寫實作 prompt 只帶入該任務對應的驗收條件；agent 優先讀任務與相關程式碼，遇到資訊不足或矛盾才查規格、計畫的相關段落。agent 可先跑相關測試，紅燈與完整測試仍由外部流程執行與判定，減少重複讀取文件和全套測試輸出所用的 token。
+計畫定案後（實作、修正、程式碼審查）不可修改 `.flow/` 裡的規格與計畫檔（`spec.md`、`acceptance.json`、`plan.md`、`tasks.json`、`tasks.ordered.json`）；實作與修正時被改就還原並重試，因為寫出的程式碼可能依賴被改過的規格，必須重寫；審查者只交出審查結果，修改直接還原即可，不必重跑審查。對規格有疑慮要寫進交接事項。
+程式碼審查仍逐條核對所有驗收條件，但只在 `review.json` 列出未通過或其他重要問題；先看 diff 與相關檔案，驗收條件不清楚時才查規格。修正階段先依 `feedback.md` 定位問題並執行相關檢查，完整檢查仍由後續 verify 執行，以減少反覆讀取完整文件與測試輸出。
 
 ## Prompt 結構
 
@@ -382,7 +388,7 @@ Agent 的最後回覆要附上 XML 中繼資料：
 
 程式只在原有關卡通過後接收交接回覆，並將正式紀錄原子儲存於 `.agentflowctl/runs/<id>/handoff.json`。`action` 是需要後續處理的事項；`info` 只供參考。作者只能提出已修正並附證據，審查者才能確認結案或附理由接受。XML `<concerns>` 可以供人閱讀，但重要疑慮必須寫進交接 JSON，才能交給下一位 agent。額度代打與重試不會接收失敗呼叫的交接內容；中斷後可用 `resume` 接續。
 
-計畫審查或程式碼審查若核准，但該階段仍有未結的 `action`，程式會視為互相矛盾的審查結果並重試。計畫定案和開 PR 前也會再檢查一次；`info` 會提供給目標階段閱讀，但不阻擋通關。
+計畫審查或程式碼審查若核准，但該階段仍有未結的 `action`，程式會視為互相矛盾的審查結果並重試。計畫定案和開 PR 前也會再檢查一次；`info` 會提供給目標階段閱讀，但不阻擋通關。審查結果本身也要一致：核准時 `items` 不可有未通過的項目，要求修改時至少要列一筆，否則視為格式錯誤並重新審查。
 
 ## Adapter
 

package/dist/cli.js

@@ -312,17 +312,27 @@ agent
 });
 agent
     .command("setup")
-    .description("互動式設定：偵測已安裝的 claude、codex、gemini，逐一選擇要不要加入並設定參與的 agent")
+    .description("互動式設定：偵測本機已安裝的 agent CLI，逐一選擇要不要加入並設定參與的 agent")
     .action(async () => {
     if (!stdin.isTTY)
         throw new Error("agent setup 需要互動式終端機，請改用 agent add");
     const detected = {};
     for (const a of SETUP_ADAPTERS)
         detected[a] = await probeAgent({ adapter: a, extraArgs: [] });
+    let configured;
+    try {
+        const cfg = loadRepoConfig();
+        configured = {};
+        for (const name of Object.keys(cfg.agents))
+            configured[name] = await probeAgent(resolveAgent(cfg, name));
+    }
+    catch {
+        // 設定檔不合法時照樣進精靈，只是不列出已設定的 agent
+    }
     const rl = createInterface({ input: stdin, output: stdout });
     let edit;
     try {
-        edit = await runSetup(readRawConfig(configPath()), { ask: (q) => rl.question(q), detected, log: (l) => console.log(l) });
+        edit = await runSetup(readRawConfig(configPath()), { ask: (q) => rl.question(q), detected, configured, log: (l) => console.log(l) });
     }
     finally {
         rl.close();

package/dist/engine.js

@@ -12,9 +12,9 @@ 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, ArbiterResult, RepoConfig, ReviewResult, TaskList, } from "./schemas.js";
+import { AcceptanceList, ArbiterResult, ConsistentReviewResult, RepoConfig, TaskList, } from "./schemas.js";
 import { addSubstitution, addUsage, agentRuns, saveRun } from "./store.js";
-import { orderTasks } from "./tasks.js";
+import { orderTasks, taskAcceptance } from "./tasks.js";
 import { readJsonFile, renderPrompt, tail } from "./util.js";
 // ───────────────────────── 共用工具 ─────────────────────────
 const info = (run, msg) => console.log(`[${run.id}] ${msg}`);
@@ -168,15 +168,17 @@ async function specStage(run) {
         return retry(run, "spec", handoffError, "spec");
     return succeed(run, "spec", "plan");
 }
-// ── 規格與計畫檔案：審查者與仲裁者只能讀，不能改 ──
+// ── 規格與計畫檔案：計畫審查、仲裁與計畫定案後的所有階段只能讀，不能改 ──
 const PLAN_FILES = ["spec.md", "acceptance.json", "plan.md", "tasks.json"];
-function snapshotPlan(run) {
-    return Object.fromEntries(PLAN_FILES.map((f) => [f, existsSync(flowFile(run, f)) ? readFileSync(flowFile(run, f), "utf8") : undefined]));
+/** 計畫定案後（實作、修正、程式碼審查）另外依賴排好的任務順序，同樣不能被改 */
+const LOCKED_FILES = [...PLAN_FILES, "tasks.ordered.json"];
+function snapshotPlan(run, files = PLAN_FILES) {
+    return Object.fromEntries(files.map((f) => [f, existsSync(flowFile(run, f)) ? readFileSync(flowFile(run, f), "utf8") : undefined]));
 }
-/** 把被審查者動過的計畫檔案還原成審查前的內容 */
+/** 把被動過的計畫檔案還原成快照的內容，回傳被改的檔名 */
 function restorePlan(run, snap) {
     const changed = [];
-    for (const f of PLAN_FILES) {
+    for (const f of Object.keys(snap)) {
         const now = existsSync(flowFile(run, f)) ? readFileSync(flowFile(run, f), "utf8") : undefined;
         if (now === snap[f])
             continue;
@@ -271,7 +273,7 @@ async function planReviewStage(run) {
             info(run, `   ↩️  已還原審查者修改的檔案：${tampered.join(", ")}`);
         if (!r.ok)
             return retry(run, "plan-review-run", `Agent 執行失敗：${r.summary}`, "plan_review");
-        const review = readJsonFile(flowFile(run, "plan-review.json"), ReviewResult);
+        const review = readJsonFile(flowFile(run, "plan-review.json"), ConsistentReviewResult);
         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 });
@@ -411,6 +413,9 @@ async function arbitratePlan(run) {
     }
     return { ...run, stage: "failed", failedStage: "plan_review", failureReason: `${summary}，需要人工決定（見 plan.md 的仲裁紀錄）` };
 }
+function planTamperedMessage(files) {
+    return `計畫定案後不可修改規格與計畫檔，已還原你的變更：${files.map((f) => `.flow/${f}`).join(", ")}。若認為規格或驗收條件有誤，請寫進 .flow/handoff-response.json 的 newIssues。`;
+}
 async function implementStage(run) {
     const tasks = loadOrderedTasks(run);
     const task = tasks[run.taskIndex];
@@ -424,18 +429,28 @@ async function implementStage(run) {
     const testCmd = `${cfg.install} && ${cfg.test}`;
     const progress = `${run.taskIndex + 1}/${tasks.length} ${task.id} ${task.title}`;
     const taskJson = JSON.stringify(task, null, 2);
+    const acceptance = readJsonFile(flowFile(run, "acceptance.json"), AcceptanceList);
+    if (!acceptance.ok)
+        throw new Error(acceptance.error);
+    const acceptanceJson = JSON.stringify(taskAcceptance(task, acceptance.data), null, 2);
     const agents = taskAgents(run.cycle, run.taskIndex, cfg.tddSplit, run.id);
     // ── 紅燈：只寫測試，而且測試必須失敗 ──
     if (run.taskPhase === "tests") {
         const key = `${task.id}:tests`;
         info(run, `🧪 [${progress}] 撰寫測試（${agents.tests}）`);
         const before = await headCommit(repo);
-        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 snap = snapshotPlan(run, LOCKED_FILES);
+        const outcome = await agentStep(run, agents.tests, `${task.id}-tests`, renderPrompt("implement-tests", { task: taskJson, acceptance: acceptanceJson, testPattern: cfg.testPattern, testCmd }), { kind: "write", reset: async () => { await resetTo(repo, before); restorePlan(run, snap); } });
         const { r, agent: testsAuthor } = outcome;
+        const tampered = restorePlan(run, snap);
         if (!r.ok) {
             await resetTo(repo, before);
             return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement");
         }
+        if (tampered.length) {
+            await resetTo(repo, before);
+            return retry(run, key, planTamperedMessage(tampered), "implement");
+        }
         const commit = await commitAll(repo, `test(${task.id}): ${task.title} [${testsAuthor}]`);
         if (!commit)
             return retry(run, key, "沒有任何檔案變更，這個階段必須撰寫測試。", "implement");
@@ -465,10 +480,16 @@ 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 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 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 { r, agent: codeAuthor } = outcome;
+    const tampered = restorePlan(run, snap);
     if (!r.ok)
         return retry(run, key, `Agent 執行失敗：${r.summary}`, "implement");
+    if (tampered.length) {
+        await resetTo(repo, testsCommit);
+        return retry(run, key, planTamperedMessage(tampered), "implement");
+    }
     await commitAll(repo, `feat(${task.id}): ${task.title} [${codeAuthor}]`);
     const touched = (await changedFiles(repo, testsCommit, await headCommit(repo))).filter((f) => testRe.test(f));
     if (touched.length) {
@@ -533,13 +554,19 @@ async function fixStage(run) {
     const repo = worktreeDir(run.id);
     const feedback = readFeedback(run);
     const before = await headCommit(repo);
+    const snap = snapshotPlan(run, LOCKED_FILES);
     const outcome = await agentStep(run, agent, "fix", renderPrompt("fix", { testPattern: cfg.testPattern }), {
         kind: "write",
-        reset: () => resetTo(repo, before),
+        reset: async () => { await resetTo(repo, before); restorePlan(run, snap); },
     });
     const { r, agent: actual } = outcome;
+    const tampered = restorePlan(run, snap);
     if (!r.ok)
         return retry(run, "fix", `${feedback}\n\n（上次修正時 Agent 執行失敗：${r.summary}）`, "fix");
+    if (tampered.length) {
+        await resetTo(repo, before);
+        return retry(run, "fix", `${feedback}\n\n另外：${planTamperedMessage(tampered)}`, "fix");
+    }
     await commitAll(repo, `fix: ${why} [${actual}]`);
     const testRe = new RegExp(cfg.testPattern);
     const deleted = (await changedFiles(repo, before, await headCommit(repo), "D")).filter((f) => testRe.test(f));
@@ -567,14 +594,18 @@ async function reviewStage(run) {
     for (const [slot, reviewer] of panel.entries()) {
         info(run, `👀 程式碼審查（${reviewer}）`);
         rmSync(flowFile(run, "review.json"), { force: true });
+        const snap = snapshotPlan(run, LOCKED_FILES);
         const outcome = await agentStep(run, reviewer, "review", renderPrompt("review", { reviewer, authors: authors.join("、") || "未知" }), {
-            kind: "review", slot,
+            kind: "review", slot, reset: async () => { await discardChanges(repo); restorePlan(run, snap); },
         });
         const { r } = outcome;
         await discardChanges(repo); // 審查者不可改程式碼
+        const tampered = restorePlan(run, snap); // .flow/ 不受 git 管理，要另外還原
+        if (tampered.length)
+            info(run, `   ↩️  已還原審查者修改的檔案：${tampered.join(", ")}`);
         if (!r.ok)
             return retry(run, "review-run", `Agent 執行失敗：${r.summary}`, "review");
-        const review = readJsonFile(flowFile(run, "review.json"), ReviewResult);
+        const review = readJsonFile(flowFile(run, "review.json"), ConsistentReviewResult);
         if (!review.ok)
             return retry(run, "review-run", review.error, "review");
         const handoffError = finishHandoff(run, outcome, "reviewer", { target: "code", verdict: review.data.verdict });

package/dist/schemas.js

@@ -83,6 +83,14 @@ export const ReviewResult = z.object({
         note: z.string().default(""),
     })),
 });
+/** 計畫與程式碼審查的結果：verdict 必須和 items 一致，否則視為格式錯誤重試 */
+export const ConsistentReviewResult = ReviewResult.superRefine((review, ctx) => {
+    const unmet = review.items.filter((i) => i.status !== "met");
+    if (review.verdict === "approve" && unmet.length)
+        ctx.addIssue({ code: "custom", message: `verdict 為 approve，但 items 仍有未通過的項目：${unmet.map((i) => i.criterion).join("、")}` });
+    if (review.verdict === "changes_requested" && !unmet.length)
+        ctx.addIssue({ code: "custom", message: "verdict 為 changes_requested，但 items 沒有列出任何未通過的項目" });
+});
 /** 仲裁者可能用 reject 表示否決；讀取時正規化，保留相同的理由欄位。 */
 export const ArbiterResult = ReviewResult.extend({
     verdict: z.enum(["approve", "changes_requested", "reject"])

package/dist/setup.js

@@ -1,9 +1,11 @@
 import { addAgent, setAgent, setCycle } from "./agentConfig.js";
+import { ADAPTERS } from "./agents/index.js";
 /**
  * `agentflowctl agent setup` 的互動精靈。
  * 問答與偵測結果由外部注入，這裡只負責流程；所有修改都在記憶體裡完成，確認後才交給呼叫端寫入。
  */
-export const SETUP_ADAPTERS = ["claude", "codex", "gemini"];
+/** 不需自訂指令就能加入的 adapter；新增 adapter 時會自動出現在精靈裡 */
+export const SETUP_ADAPTERS = Object.keys(ADAPTERS).filter((a) => a !== "command");
 /** 回傳要寫入的設定；使用者沒選任何 agent 或最後沒確認時回傳 null */
 export async function runSetup(initial, deps) {
     const { detected, log } = deps;
@@ -16,9 +18,26 @@ export async function runSetup(initial, deps) {
     const changes = [];
     const chosen = [];
     const existing = () => Object.keys((cfg.agents ?? {}));
-    for (const adapter of SETUP_ADAPTERS) {
-        log(`${detected[adapter] ? "✅" : "❌"} ${adapter}${detected[adapter] ? "" : "（沒有偵測到 CLI）"}`);
-        if (!(await confirm(`  加入 ${adapter}？`, detected[adapter])))
+    const configured = Object.entries(deps.configured ?? {});
+    if (configured.length) {
+        const defs = (cfg.agents ?? {});
+        log("已設定的 agent：");
+        for (const [name, ok] of configured) {
+            log(`  ${ok ? "✅" : "⚠️ "} ${name}（${defs[name]?.adapter ?? "?"}${ok ? "" : "，找不到可執行的 CLI"}）`);
+        }
+    }
+    const installed = Object.keys(detected).filter((a) => detected[a]);
+    const missing = Object.keys(detected).filter((a) => !detected[a]);
+    if (missing.length)
+        log(`沒有偵測到：${missing.join("、")}（安裝後可重跑 agent setup）`);
+    if (!installed.length) {
+        log("沒有偵測到可加入的 agent CLI，設定沒有變更");
+        log("需要自訂指令的 CLI 請改用 agent add <name> --adapter command -- <指令>");
+        return null;
+    }
+    for (const adapter of installed) {
+        log(`✅ ${adapter}`);
+        if (!(await confirm(`  加入 ${adapter}？`, true)))
             continue;
         let name;
         for (;;) {

package/dist/tasks.js

@@ -1,5 +1,15 @@
 /** 一個任務最多做兩件事：對應的驗收條件超過這個數量就要再拆 */
 export const MAX_TASK_ACCEPTANCE = 2;
+/** 只取目前任務負責的驗收條件，避免每次實作都重讀整份清單。 */
+export function taskAcceptance(task, acceptance) {
+    const byId = new Map(acceptance.map((item) => [item.id, item]));
+    return task.acceptance.map((id) => {
+        const item = byId.get(id);
+        if (!item)
+            throw new Error(`${task.id} 對應的驗收條件 ${id} 不存在`);
+        return item;
+    });
+}
 /**
  * 檢查任務清單並依相依關係排序（Kahn 演算法）。
  * 回傳排序後的任務，或回傳一段可以直接回饋給 Agent 的錯誤說明。

package/package.json

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

package/prompts/fix.md

@@ -18,19 +18,21 @@
 </handoff>
 
 <inputs>
-- .flow/feedback.md：失敗的檢查（型別、lint、測試、建置）或審查意見
-- .flow/spec.md 與 .flow/acceptance.json：規格
+- .flow/feedback.md：先讀取，確認失敗的檢查或審查意見與其證據
+- 相關程式碼與測試：依 feedback 指出的檔案和問題範圍查閱
+- .flow/acceptance.json 與 .flow/spec.md：預期行為不清楚或互相矛盾時，才查相關條件或段落
 </inputs>
 
 <steps>
-1. 找出每個問題的根本原因再修正，不要只針對症狀打補丁。
-2. 在沙箱內自行執行相關檢查，確認問題已解決且沒有造成新的錯誤。
+1. 優先處理 feedback 與交接事項指出的問題；先定位相關程式碼和測試，找出根本原因再修正。
+2. 在沙箱內執行與修改相關的檢查，確認問題已解決。完整檢查由後續 verify 階段執行；需要判斷跨模組影響時再自行擴大檢查範圍。
 </steps>
 
 <constraints>
 - 不可刪除測試檔（檔名符合 `{{testPattern}}`），也不可用 skip、放寬斷言、`@ts-ignore`、`eslint-disable` 等方式讓檢查通過。
 - 如果測試本身確實有誤，可以修正測試，但必須在回覆的 `<concerns>` 說明理由。
 - 不要執行 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>

package/prompts/implement-code.md

@@ -23,8 +23,15 @@
 ```
 </task>
 
+<acceptance>
+這個任務負責的驗收條件：
+```json
+{{acceptance}}
+```
+</acceptance>
+
 <inputs>
-完整規格與計畫請參考 .flow/spec.md、.flow/plan.md。
+先依上面的任務、驗收條件與現有測試工作。只有資訊不足或互相矛盾時，再閱讀 .flow/spec.md、.flow/plan.md 的相關段落，並在交接中指出問題；不必通讀整份文件。
 </inputs>
 
 <red_output>
@@ -36,13 +43,14 @@
 <steps>
 1. 若 .flow/feedback.md 存在，先閱讀，並依內容修正。
 2. 撰寫讓測試通過的最小實作，符合專案既有的程式風格與架構。
-3. 執行 `{{testCmd}}` 確認全部測試通過（包含既有測試）。
+3. 先執行本任務相關的測試，確認實作方向。外部流程會再執行 `{{testCmd}}` 驗證全部測試（包含既有測試），不需要自行重跑全套測試。
 4. 測試通過後，在不改變行為的前提下整理程式碼。
 </steps>
 
 <constraints>
 - **不可修改任何測試檔**，修改會被自動還原並視為失敗。若認為測試本身有誤，請寫在回覆的 `<concerns>`。
 - 不要執行 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>

package/prompts/implement-tests.md

@@ -23,20 +23,28 @@
 ```
 </task>
 
+<acceptance>
+這個任務負責的驗收條件：
+```json
+{{acceptance}}
+```
+</acceptance>
+
 <inputs>
-完整規格與計畫請參考 .flow/spec.md、.flow/plan.md。
+先依上面的任務與驗收條件工作。只有資訊不足或互相矛盾時，再閱讀 .flow/spec.md、.flow/plan.md 的相關段落，並在交接中指出問題；不必通讀整份文件。
 </inputs>
 
 <steps>
 1. 若 .flow/feedback.md 存在，先閱讀，並依內容調整做法。
 2. 依任務描述撰寫測試，檔名必須符合正規表示式 `{{testPattern}}`。
 3. 測試必須驗證這個任務要新增的行為，並且因為功能尚未實作而**失敗**。
-4. 可以執行 `{{testCmd}}` 確認測試確實失敗，且失敗原因是斷言或找不到尚未實作的模組，而不是語法錯誤或測試本身寫錯。
+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>

package/prompts/plan-fix.md

@@ -22,10 +22,9 @@
 </requirement>
 
 <steps>
-1. 閱讀 .flow/feedback.md，裡面是其他模型的審查意見。
-2. 閱讀目前的 .flow/spec.md、.flow/acceptance.json、.flow/plan.md、.flow/tasks.json 與相關程式碼。
-3. 逐條處理審查意見，直接修改上述四個檔案。
-4. 在 .flow/plan.md 最後的「## 審查回應」一節，逐條說明每個意見怎麼處理；不同意的意見，請寫出具體理由，而不是忽略它。回應時只談內容，不要提到審查者或你自己是哪個模型、哪家公司，之後可能由第三方匿名仲裁。
+1. 先閱讀 .flow/feedback.md，依每則意見定位 .flow/spec.md、.flow/acceptance.json、.flow/plan.md、.flow/tasks.json 中相關的段落或項目；技術細節需要確認時才讀相關程式碼。
+2. 逐條處理審查意見，只修改需要修訂的檔案。新增或調整驗收條件、任務時，檢查受影響的條件與任務對應。
+3. 在 .flow/plan.md 最後的「## 審查回應」一節，逐條說明每個意見怎麼處理；不同意的意見，請寫出具體理由，而不是忽略它。回應時只談內容，不要提到審查者或你自己是哪個模型、哪家公司，之後可能由第三方匿名仲裁。
 </steps>
 
 <output_format>

package/prompts/plan-review.md

@@ -22,12 +22,8 @@
 </requirement>
 
 <inputs>
-- .flow/spec.md：規格
-- .flow/acceptance.json：驗收條件
-- .flow/plan.md：實作方式
-- .flow/tasks.json：任務拆解
-
-請同時閱讀相關的既有程式碼，確認計畫符合專案的實際架構。
+- 先核對原始需求、.flow/spec.md、.flow/acceptance.json、.flow/plan.md 與 .flow/tasks.json，確認需求、驗收條件與任務的對應。
+- 依 .flow/tasks.json 各任務 `description` 列出要動的檔案，查閱其中既有的檔案，確認計畫符合專案的架構與慣例；有疑慮時再擴大查閱範圍。
 </inputs>
 
 <review_focus>
@@ -37,6 +33,7 @@
 4. **技術方向**：是否符合專案既有的架構與慣例？有沒有更簡單的做法，或明顯的風險？
 
 措辭、格式這類不影響實作結果的小問題，不需要要求修改。
+只在證據不足時擴大查閱範圍；檔案格式、任務對驗收條件的覆蓋與任務相依已有程式關卡檢查，不必自行重跑完整檢查。仍須自行判斷原始需求是否被規格與驗收條件涵蓋。
 </review_focus>
 
 <output_format>
@@ -44,15 +41,16 @@
 
 ```json
 {
-  "verdict": "approve",
+  "verdict": "changes_requested",
   "items": [
-    { "criterion": "需求覆蓋", "status": "met", "note": "" },
     { "criterion": "AC-2", "status": "not_met", "note": "沒有涵蓋 API 逾時的情況，建議新增一條驗收條件並由 T-3 負責" }
   ]
 }
 ```
 
 - `verdict`：沒有會影響實作結果的問題時為 `approve`，否則為 `changes_requested`。
+- `items` 只列會影響實作結果的問題，每筆 `status` 為 `not_met` 或 `partial`；已通過的項目不必逐條記錄。
+- `approve` 時 `items` 為空陣列；`changes_requested` 時至少要有一筆。兩者不一致會被視為格式錯誤並重新審查。
 - 每個問題的 `note` 請寫出具體要改哪個檔案的哪個部分，以及建議怎麼改。
 </output_format>
 

package/prompts/review.md

@@ -18,9 +18,9 @@
 </handoff>
 
 <inputs>
-- 規格：.flow/spec.md
-- 驗收條件：.flow/acceptance.json
-- 本次變更：.flow/diff.patch
+- 驗收條件：.flow/acceptance.json（逐條核對）
+- 本次變更：.flow/diff.patch（先看變更，再按需讀相關程式碼與測試）
+- 規格：.flow/spec.md（驗收條件不清楚或互相矛盾時，才查相關段落）
 - 自動化檢查結果：.flow/verify.json（已全部通過）
 </inputs>
 
@@ -29,6 +29,8 @@
 2. 是否有明顯的錯誤、邊界情況遺漏、安全問題或效能問題。
 3. 是否符合專案既有的架構與慣例。
 
+先根據 diff 與驗收條件定位需要查閱的檔案；只在證據不足時讀取其他檔案。自動化檢查已由外部流程執行，不必為了審查重跑全套檢查。
+
 風格偏好與無關緊要的小問題不需要要求修改。
 </review_focus>
 
@@ -37,16 +39,16 @@
 
 ```json
 {
-  "verdict": "approve",
+  "verdict": "changes_requested",
   "items": [
-    { "criterion": "AC-1", "status": "met", "note": "" },
-    { "criterion": "錯誤處理", "status": "not_met", "note": "API 失敗時沒有顯示錯誤訊息，見 src/form.tsx" }
+    { "criterion": "AC-1", "status": "not_met", "note": "src/form.tsx 缺少 API 失敗時的錯誤訊息，請在 catch 中顯示錯誤並補測試" }
   ]
 }
 ```
 
-- `verdict`：全部驗收條件都 `met` 且沒有嚴重問題時為 `approve`，否則為 `changes_requested`。
-- 每個驗收條件都要有一筆；額外發現的問題也各自列一筆，`note` 請寫出具體位置與修正方向。
+- `verdict`：逐條核對所有驗收條件後，全部通過且沒有嚴重問題時為 `approve`，否則為 `changes_requested`。
+- `items` 只列未通過的驗收條件與額外發現的重要問題，每筆的 `status` 為 `not_met` 或 `partial`，`note` 請寫出具體位置與修正方向。
+- `approve` 時 `items` 為空陣列；`changes_requested` 時至少要有一筆。兩者不一致會被視為格式錯誤並重新審查。
 </output_format>
 
 <constraints>