chore(ai-review 狀態): 回寫本輪已處理 findings

.gitea/ai-review/exclusions.json

@@ -1890,5 +1890,214 @@
     "endLine": 69,
     "problem": "`redactSecrets` 與 `agentFailureDetail` 是新加入的安全診斷防線，但測試只覆蓋 Authorization/token 的基本遮罩。控制字元單行化、URL 內嵌帳密、長 token/hex、輸入與輸出長度截斷、以及沒有 error code 時的 fallback 訊息都還沒被驗證。",
     "reason": "Paladin：可排除（重複）。歷史 findings 已涵蓋 redactSecrets／agentFailureDetail 對控制字元、URL 帳密、token 格式、截斷與 fallback 診斷等邊界缺少測試。"
+  },
+  {
+    "addedAt": "2026/07/21 16:00:33",
+    "prNumber": 6,
+    "reviewer": "Bard",
+    "severity": "警告",
+    "file": "src/index.js",
+    "startLine": 166,
+    "endLine": 223,
+    "problem": "`main()` 這段新添的建問題模式狀態、暫存佇列、三個閉包輔助函式，全塞在主流程開頭，讓主旋律還沒開始就先進入一大段插曲。`issueModeActive`、`trackingIssue`、`pendingIssueCommentBodies` 彼此共享可變狀態，讀者必須在腦中追蹤閉包副作用，主流程的步驟節奏因此變得沉重。",
+    "reason": "Paladin：可排除（重複）。此條指涉 main() 內 issue 模式狀態、暫存佇列與閉包職責混雜，已由既有排除事項與歷史 findings 多次涵蓋。"
+  },
+  {
+    "addedAt": "2026/07/21 16:00:33",
+    "prNumber": 6,
+    "reviewer": "Bard",
+    "severity": "建議",
+    "file": "src/index.js",
+    "startLine": 230,
+    "endLine": 239,
+    "problem": "註解標成「步驟 2：延後執行」，但實際位置夾在快速檢查與步驟 3 之前，後面又在步驟 8 後再次出現「步驟 2（延後執行）」。同一個步驟號在不同位置反覆變奏，雖然註解有解釋，閱讀節拍仍容易打結。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已指出流程步驟編號散落且實際順序變成 1、3～8、2、9～10，與本條「步驟 2 延後但仍用線性編號」相同。"
+  },
+  {
+    "addedAt": "2026/07/21 16:00:33",
+    "prNumber": 6,
+    "reviewer": "Leo",
+    "severity": "警告",
+    "file": "src/index.js",
+    "startLine": 166,
+    "endLine": 235,
+    "problem": "`main()` 現在同時負責流程編排、PR 留言、issue 模式暫存、issue 建立、fallback 狀態切換與留言 flush。這段靠 `issueModeActive`、`trackingIssue`、`pendingIssueCommentBodies`、`currentRunCommentIds` 多個閉包變數互相配合，半年後要改「留言要發去哪裡」或「建 issue 失敗怎麼降級」時，很容易漏掉某個狀態轉換，尤其後面收尾 commit、resolve 舊留言、嚴重／其他問題發布都還會讀這些狀態。",
+    "reason": "Paladin：可排除（命中已知排除事項且重複）。main() 同時承擔留言路由、issue 狀態、fallback 與 flush 的發布狀態管理，已由既有排除事項與歷史 findings 涵蓋。"
+  },
+  {
+    "addedAt": "2026/07/21 16:00:33",
+    "prNumber": 6,
+    "reviewer": "Leo",
+    "severity": "建議",
+    "file": "src/index.js",
+    "startLine": 222,
+    "endLine": 230,
+    "problem": "註解與 log 名稱把「標記舊留言過時」稱為「步驟 2」，但實際執行點被延後到流程後段。這種非時間順序的步驟編號會讓維護者追 log 或對照 README 流程圖時產生認知落差：看到「步驟 2」不再代表第二個發生的動作，而是某個被延後的歷史步驟。",
+    "reason": "Paladin：可排除（重複）。與 F003 及歷史 findings 指涉同一個延後執行的「步驟 2」仍以線性步驟編號呈現所造成的認知落差。"
+  },
+  {
+    "addedAt": "2026/07/21 16:00:33",
+    "prNumber": 6,
+    "reviewer": "Leo",
+    "severity": "警告",
+    "file": "readme.md",
+    "startLine": 76,
+    "endLine": 131,
+    "problem": "README 內大量手動維護到 `src/branch/develop/...#Lxx` 的精確行號連結。這次變更已經因程式碼位移而更新一整片連結，未來每次插入函式或註解都會造成文件 churn；更糟的是漏改時文件會指到錯誤行，讀者以為文件可信，實際上卻被帶到過期位置。",
+    "reason": "Paladin：可排除（重複）。README 大量手動維護 develop 分支與 #Lxx 行號連結，歷史 findings 已多次記錄相同維護成本與連結漂移風險。"
+  },
+  {
+    "addedAt": "2026/07/21 16:00:33",
+    "prNumber": 6,
+    "reviewer": "Mage",
+    "severity": "嚴重",
+    "file": "src/index.js",
+    "startLine": 117,
+    "endLine": 120,
+    "problem": "當 PR 審查出嚴重問題，但結果 commit/push 失敗時，`commitFindings` 只回傳 `false`。新版主流程又改成「本輪審查不因嚴重問題直接 exit 1，而是依賴下一輪讀到 `[failure]` commit 才失敗」。最小情境：`severe.length > 0`、token 權限不足或 push 競態導致 `commitAndPushFindings` 丟錯；此時沒有 `[failure]` commit、也不會有下一輪快速回報，但本輪仍可能以 0 結束，PR 檢查會在存在嚴重問題時通過。",
+    "reason": "Paladin：可排除（重複）。此條與 F001 指涉同一風險：嚴重 finding 存在時 failure 結果 commit/push 失敗，可能使本輪檢查仍以成功結束。"
+  },
+  {
+    "addedAt": "2026/07/21 16:00:33",
+    "prNumber": 6,
+    "reviewer": "Maya",
+    "severity": "警告",
+    "file": "src/index.js",
+    "startLine": 163,
+    "endLine": 437,
+    "problem": "建問題模式被大幅改寫：情境留言先暫存、只有 kept finding 才建 issue、建立失敗會 fallback 回 PR、嚴重／非嚴重 finding 會改發到 issue、最後還要回貼追蹤 issue 連結與設定相依關係。但目前新增測試只覆蓋了少數 helper，沒有驗證 `main()` 在這些分支下的實際副作用。這些行為沒經過試煉，等於還不知道留言會不會發錯地方、fallback 後會不會漏清舊留言、或無 finding 時是否真的靜默通過。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已涵蓋建問題模式的暫存留言、只在有 finding 時建 issue、fallback、嚴重／非嚴重分流、PR 回貼與靜默通過等核心分支缺少流程測試。"
+  },
+  {
+    "addedAt": "2026/07/21 16:00:33",
+    "prNumber": 6,
+    "reviewer": "Maya",
+    "severity": "警告",
+    "file": "src/lib/gitrepo.js",
+    "startLine": 298,
+    "endLine": 355,
+    "problem": "`commitAndPushFindings` 的推送行為改成一律走 `pushWithCredential`，並宣稱 token 不進 argv、會清掉 checkout 的 extraheader、只接受同一 Gitea origin 的 `.git` URL。這是安全與 CI 觸發都很關鍵的失敗路徑，但目前 `test/gitrepo.test.js` 只測了分支名稱檢查，沒有驗證推送時的 argv/env，也沒有驗證遠端 URL 不符時會停止。這段若改壞，測試不會提醒我們 token 可能出現在命令列或推送根本沒用 PAT 身分。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已記錄 commitAndPushFindings／pushWithCredential 的認證推送路徑、argv/env、遠端目標檢查與失敗訊息遮蔽缺少測試。"
+  },
+  {
+    "addedAt": "2026/07/21 16:00:33",
+    "prNumber": 6,
+    "reviewer": "Maya",
+    "severity": "警告",
+    "file": "src/lib/gitrepo.js",
+    "startLine": 130,
+    "endLine": 188,
+    "problem": "`resolveMergeBase` 新增了多階段 fetch 補歷史流程：先 fetch base、首次 merge-base、再 deepen base、deepen PR HEAD、必要時 unshallow，且每個策略成功後要立即重試並短路返回。現有測試只驗證不安全 `baseRef` 會在 fetch 前被拒絕，沒有測到淺層 checkout、首次失敗後補抓成功、策略失敗繼續下一個、全部失敗時診斷訊息等邊界。這正是容易 off-by-one 或順序錯的流程，現在還沒有測試保護。",
+    "reason": "Paladin：可排除（重複）。resolveMergeBase 多階段 fetch、淺層與非淺層路徑、策略停止條件、全部失敗診斷與 cause 缺少測試，已由歷史 findings 涵蓋。"
+  },
+  {
+    "addedAt": "2026/07/21 16:26:12",
+    "prNumber": 6,
+    "reviewer": "Assassin",
+    "severity": "嚴重",
+    "file": "src/index.js",
+    "startLine": 105,
+    "endLine": 116,
+    "problem": "這裡把審查結果 commit/push 失敗吞掉並回傳 `false`，而本次變更又把主流程改成「本輪審查不因嚴重問題直接 exit 1，靠下一輪讀到 `[failure]` commit 才失敗」。攻擊者只要讓結果 commit 推不上去，例如在 PR head 競態推送、讓 token 沒有 push 權限、或讓來源分支拒絕 bot push，就能讓嚴重安全 finding 已產生但沒有 failure commit、也沒有下一輪失敗檢查，等同把必要檢查繞過。",
+    "reason": "人工裁示排除：主流程已在 result === failure 且 commitFindings 回傳 false 時直接回傳 1；本 finding 針對舊位置的描述已由現有收尾防線涵蓋。"
+  },
+  {
+    "addedAt": "2026/07/21 16:30:12",
+    "prNumber": 6,
+    "reviewer": "Bard",
+    "severity": "建議",
+    "file": "readme.md",
+    "startLine": 48,
+    "endLine": 48,
+    "problem": "Mermaid 節點代號從 `N8` 跳回 `N2`，雖然流程語意是「步驟 2 延後」，但原始碼讀起來像旋律突然倒帶；維護者在對照圖與步驟時容易被代號順序絆住。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已指出流程步驟編號與實際順序、README 流程圖及文件對照會產生認知落差；本條 Mermaid 節點代號問題屬同一類指控。"
+  },
+  {
+    "addedAt": "2026/07/21 16:30:12",
+    "prNumber": 6,
+    "reviewer": "Bard",
+    "severity": "警告",
+    "file": "src/index.js",
+    "startLine": 167,
+    "endLine": 235,
+    "problem": "`main()` 內新增了建 issue 模式狀態、暫存佇列與三個帶長篇 JSDoc 的閉包，讓主流程的旋律被大量伴奏蓋過。這段同時管理 `issueModeActive`、`trackingIssue`、`pendingIssueCommentBodies` 與 PR 留言 id，可讀性負擔明顯升高。",
+    "reason": "Paladin：可排除（重複）。已知排除事項與歷史 findings 已涵蓋 main() 內留言路由、issue 狀態、暫存佇列與發布職責耦合造成可讀性與維護負擔。"
+  },
+  {
+    "addedAt": "2026/07/21 16:30:12",
+    "prNumber": 6,
+    "reviewer": "Bard",
+    "severity": "建議",
+    "file": "src/lib/gitrepo.js",
+    "startLine": 121,
+    "endLine": 128,
+    "problem": "`strategies` 以陣列位置承載語意，`[label, ...args]` 雖簡短，卻讓每個元素的第二欄之後全靠讀者猜是 git argv；這裡的可讀性像沒有小節線的樂譜。",
+    "reason": "Paladin：可排除（重複）。歷史 finding 已針對 resolveMergeBase 內 strategies 與補救策略編排使閱讀節奏偏密提出問題；本條 tuple 可讀性屬同一段策略結構的細項。"
+  },
+  {
+    "addedAt": "2026/07/21 16:30:12",
+    "prNumber": 6,
+    "reviewer": "Leo",
+    "severity": "警告",
+    "file": "src/index.js",
+    "startLine": 163,
+    "endLine": 231,
+    "problem": "`main()` 這次把一般模式／建問題模式／降級模式的留言去向都塞進閉包狀態：`issueModeActive`、`trackingIssue`、`pendingIssueCommentBodies`、`currentRunCommentIds` 彼此耦合。半年後要新增一種落地方式或調整「何時清舊留言」時，維護者必須同時追多個可變狀態與後續多個 `if (issueModeActive)` 分支，很容易漏掉 flush、清空、登錄留言 id 或 fallback 後的收尾行為。",
+    "reason": "Paladin：可排除（重複）。與 F003 及既有排除事項相同，均指向 main() 以可變閉包狀態承擔留言目的地、issue 生命週期與 fallback 狀態機。"
+  },
+  {
+    "addedAt": "2026/07/21 16:30:12",
+    "prNumber": 6,
+    "reviewer": "Leo",
+    "severity": "警告",
+    "file": "src/index.js",
+    "startLine": 232,
+    "endLine": 241,
+    "problem": "流程註解把「將舊留言標記為解決」稱為「步驟 2（延後執行）」，但實際執行點在審查結果產生後、接近原本步驟 9 前。這種「編號是 2、時間點是 8 後」的設計已經擴散到多個檔案的 JSDoc 與 log 描述，未來查 CI log 或維護流程圖時會產生認知落差：看到 `步驟2` 不代表它真的發生在第二步。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已明確記錄步驟編號散落於 log、JSDoc、README 且實際順序變成 1、3 到 8、2、9 到 10 的維護風險。"
+  },
+  {
+    "addedAt": "2026/07/21 16:30:12",
+    "prNumber": 6,
+    "reviewer": "Leo",
+    "severity": "建議",
+    "file": "src/lib/gitrepo.js",
+    "startLine": 103,
+    "endLine": 160,
+    "problem": "`resolveMergeBase()` 內同時負責驗證 base ref、fetch base、重試 merge-base、補抓淺層歷史、累積診斷與組錯誤訊息。這些都和「取得 merge-base」有關，但現在全部攤在同一個函式裡，策略陣列、診斷格式與 git 操作細節混在一起；未來要新增 fetch 策略或改診斷文字時，容易不小心改壞主流程判斷。",
+    "reason": "Paladin：可排除（重複）。歷史 finding 已指出 resolveMergeBase 同時負責驗證、fetch 策略編排、診斷與錯誤包裝，難以分辨主流程與補救策略。"
+  },
+  {
+    "addedAt": "2026/07/21 16:30:12",
+    "prNumber": 6,
+    "reviewer": "Maya",
+    "severity": "警告",
+    "file": "src/index.js",
+    "startLine": 164,
+    "endLine": 232,
+    "problem": "建問題模式新增了「先暫存情境留言、確定有保留 finding 才建 issue、建 issue 失敗時降級回 PR 留言」這一整段流程，但目前測試只覆蓋了部分 helper，沒有驗證主流程在 create-issue=true 下的分流行為。這代表像「無保留問題時不應建 issue／不應留言」、「建立 issue 失敗時應把 pending 留言補回 PR」、「trackingIssue 建立後後續留言應改送 issue」這些行為都還沒通過試煉。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已涵蓋建問題模式核心流程、暫存留言、issue 建立條件、發布分流、外部 API 狀態切換與降級路徑缺少測試。"
+  },
+  {
+    "addedAt": "2026/07/21 16:30:12",
+    "prNumber": 6,
+    "reviewer": "Maya",
+    "severity": "警告",
+    "file": "src/lib/gitrepo.js",
+    "startLine": 104,
+    "endLine": 150,
+    "problem": "resolveMergeBase 新增了多階段 fetch/deepen/unshallow fallback 與診斷錯誤，但測試只驗證不安全 baseRef 會被拒絕，沒有驗證任何成功或失敗 fallback 路徑。這段是 diff 基準的核心邏輯，若 shallow checkout 下 deepen PR HEAD 用錯 ref、策略順序跑錯，或全部失敗時診斷不正確，現有測試都抓不到。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已針對 resolveMergeBase 多階段 fetch、淺層與非淺層分支、策略停止條件、降級與最終診斷缺少測試提出相同問題。"
+  },
+  {
+    "addedAt": "2026/07/21 16:30:12",
+    "prNumber": 6,
+    "reviewer": "Maya",
+    "severity": "警告",
+    "file": "src/lib/gitrepo.js",
+    "startLine": 272,
+    "endLine": 322,
+    "problem": "commitAndPushFindings 改成一律透過 pushWithCredential 用 PAT extraheader 推送，且新增 headRef 安全檢查與固定錯誤遮蔽；但目前 gitrepo 測試沒有覆蓋 commitAndPushFindings/pushWithCredential 的推送行為。這讓「token 不進 argv」、「清掉 checkout 既有 extraheader」、「遠端 URL 不符時拒絕」、「push 失敗不洩漏 URL/token」這些失敗與安全邊界都沒有被驗證。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已涵蓋 commitAndPushFindings 與 pushWithCredential 的推送策略、認證遮蔽、失敗路徑與 token 不外洩等測試缺口。"
   }
 ]

.gitea/ai-review/findings/2026-07-20-17:37:54.json

@@ -47,45 +47,6 @@
       "suggestion": "補單元測試攔截 git 參數／env：斷言以 token 認證推送、推送目標 refspec 正確、呼叫次數，並確保任何拋出的錯誤、log 或快照都不含原始 token。屬測試架構決策。",
       "suggestedCode": ""
     },
-    {
-      "id": "F005",
-      "reviewer": "Bard",
-      "focus": "style",
-      "badge": "🎼",
-      "severity": "建議",
-      "file": "action.yml",
-      "startLine": 3,
-      "endLine": 3,
-      "problem": "檔頭「更新時間」為手動維護的固定字串，與實際檔案更新時間不一致；散落各檔的手動時間戳容易走調，讀者無法判斷可信度。",
-      "suggestion": "屬 jsc spec-time-log 慣例（各檔頭「更新時間」由 doc-funcs 流程統一產生／同步）。是否移除改用版控紀錄、或如何統一更新，宜由 doc-funcs 流程處理，不在 resolve 逐條硬改。",
-      "suggestedCode": ""
-    },
-    {
-      "id": "F006",
-      "reviewer": "Bard",
-      "focus": "style",
-      "badge": "🎼",
-      "severity": "建議",
-      "file": "readme.md",
-      "startLine": 3,
-      "endLine": 3,
-      "problem": "README 檔頭手動「更新時間」與實際更新時間不符，並與 action.yml、src/index.js 重複保存同類易過期資訊，形成多個不一致的真相來源。",
-      "suggestion": "同 F005：屬 jsc spec-time-log 慣例，交 doc-funcs 流程統一維護（移除或自動注入）。",
-      "suggestedCode": ""
-    },
-    {
-      "id": "F007",
-      "reviewer": "Bard",
-      "focus": "style",
-      "badge": "🎼",
-      "severity": "建議",
-      "file": "src/index.js",
-      "startLine": 7,
-      "endLine": 7,
-      "problem": "啟動橫幅硬編碼的「更新時間」與程式實際更新時間不一致，每次改程式都要人工校準，製造噪音並讓執行日誌呈現失真版本資訊。",
-      "suggestion": "同 F005：屬 jsc spec-time-log 慣例，交 doc-funcs 流程統一維護；若日誌需辨識版本，可改顯示 CI 注入的 commit SHA／版本號（屬慣例調整）。",
-      "suggestedCode": ""
-    },
     {
       "id": "F008",
       "reviewer": "Bard",

.gitea/ai-review/findings/2026-07-21-16:00:33.json

@@ -0,0 +1,184 @@
+{
+  "generatedAt": "2026/07/21 16:00:33",
+  "commitSha": "216bc39255ec176a0f66f2b257beea5929ef4eb8",
+  "prNumber": 6,
+  "tool": {
+    "name": "codex",
+    "version": "codex-cli 0.144.6",
+    "model": "gpt-5.5"
+  },
+  "findings": [],
+  "excluded": [
+    {
+      "reviewer": "Bard",
+      "focus": "style",
+      "badge": "🎼",
+      "severity": "警告",
+      "file": "src/index.js",
+      "startLine": 166,
+      "endLine": 223,
+      "problem": "`main()` 這段新添的建問題模式狀態、暫存佇列、三個閉包輔助函式，全塞在主流程開頭，讓主旋律還沒開始就先進入一大段插曲。`issueModeActive`、`trackingIssue`、`pendingIssueCommentBodies` 彼此共享可變狀態，讀者必須在腦中追蹤閉包副作用，主流程的步驟節奏因此變得沉重。",
+      "suggestion": "把留言去向抽成小型 helper（例如 `createCommentSink`），讓 `main()` 只看見 `commentSink.post()`、`commentSink.flushToIssue()`、`commentSink.fallbackToPr()` 這類語意清楚的介面。主流程保留編排，狀態管理移到專責函式，樂句會乾淨許多。",
+      "suggestedCode": "",
+      "id": "F002",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。此條指涉 main() 內 issue 模式狀態、暫存佇列與閉包職責混雜，已由既有排除事項與歷史 findings 多次涵蓋。"
+        }
+      }
+    },
+    {
+      "reviewer": "Bard",
+      "focus": "style",
+      "badge": "🎼",
+      "severity": "建議",
+      "file": "src/index.js",
+      "startLine": 230,
+      "endLine": 239,
+      "problem": "註解標成「步驟 2：延後執行」，但實際位置夾在快速檢查與步驟 3 之前，後面又在步驟 8 後再次出現「步驟 2（延後執行）」。同一個步驟號在不同位置反覆變奏，雖然註解有解釋，閱讀節拍仍容易打結。",
+      "suggestion": "將流程步驟編號與執行順序拆開命名，例如稱為「舊留言清理（延後）」或「收斂前清理舊留言」，避免用 `步驟 2` 這種線性編號描述一個實際延後執行的階段。",
+      "suggestedCode": "",
+      "id": "F003",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已指出流程步驟編號散落且實際順序變成 1、3～8、2、9～10，與本條「步驟 2 延後但仍用線性編號」相同。"
+        }
+      }
+    },
+    {
+      "reviewer": "Leo",
+      "focus": "maintainability",
+      "badge": "🧰",
+      "severity": "警告",
+      "file": "src/index.js",
+      "startLine": 166,
+      "endLine": 235,
+      "problem": "`main()` 現在同時負責流程編排、PR 留言、issue 模式暫存、issue 建立、fallback 狀態切換與留言 flush。這段靠 `issueModeActive`、`trackingIssue`、`pendingIssueCommentBodies`、`currentRunCommentIds` 多個閉包變數互相配合，半年後要改「留言要發去哪裡」或「建 issue 失敗怎麼降級」時，很容易漏掉某個狀態轉換，尤其後面收尾 commit、resolve 舊留言、嚴重／其他問題發布都還會讀這些狀態。",
+      "suggestion": "把發布目的地抽成一個小型 publisher 模組或類別，讓 `main()` 只呼叫 `publisher.comment()`、`publisher.ensureIssue()`、`publisher.fallbackToPr()`、`publisher.resolveOldComments()` 這類語意方法。狀態留在 publisher 內部，並補單元測試覆蓋「一般模式、issue 模式有 finding、issue 模式無 finding、建立 issue 失敗降級」四條路徑。",
+      "suggestedCode": "",
+      "id": "F006",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（命中已知排除事項且重複）。main() 同時承擔留言路由、issue 狀態、fallback 與 flush 的發布狀態管理，已由既有排除事項與歷史 findings 涵蓋。"
+        }
+      }
+    },
+    {
+      "reviewer": "Leo",
+      "focus": "maintainability",
+      "badge": "🧰",
+      "severity": "建議",
+      "file": "src/index.js",
+      "startLine": 222,
+      "endLine": 230,
+      "problem": "註解與 log 名稱把「標記舊留言過時」稱為「步驟 2」，但實際執行點被延後到流程後段。這種非時間順序的步驟編號會讓維護者追 log 或對照 README 流程圖時產生認知落差：看到「步驟 2」不再代表第二個發生的動作，而是某個被延後的歷史步驟。",
+      "suggestion": "改用穩定的階段名稱取代數字，例如 `清理舊留言`、`工具偵測`、`diff 摘要`，或重新編號成實際執行順序。若一定要保留舊編號，建議只放在 README 遷移說明，不要散落在程式碼註解與 log label 中。",
+      "suggestedCode": "",
+      "id": "F007",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。與 F003 及歷史 findings 指涉同一個延後執行的「步驟 2」仍以線性步驟編號呈現所造成的認知落差。"
+        }
+      }
+    },
+    {
+      "reviewer": "Leo",
+      "focus": "maintainability",
+      "badge": "🧰",
+      "severity": "警告",
+      "file": "readme.md",
+      "startLine": 76,
+      "endLine": 131,
+      "problem": "README 內大量手動維護到 `src/branch/develop/...#Lxx` 的精確行號連結。這次變更已經因程式碼位移而更新一整片連結，未來每次插入函式或註解都會造成文件 churn；更糟的是漏改時文件會指到錯誤行，讀者以為文件可信，實際上卻被帶到過期位置。",
+      "suggestion": "避免在手寫 README 維護精確行號。可改連到檔案或章節錨點，或把 API 列表改由文件產生器輸出。若需要固定定位，優先使用語意穩定的錨點或函式章節，而不是會隨程式碼行數漂移的 `#Lxx`。",
+      "suggestedCode": "",
+      "id": "F008",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。README 大量手動維護 develop 分支與 #Lxx 行號連結，歷史 findings 已多次記錄相同維護成本與連結漂移風險。"
+        }
+      }
+    },
+    {
+      "reviewer": "Mage",
+      "focus": "logic",
+      "badge": "🔮",
+      "severity": "嚴重",
+      "file": "src/index.js",
+      "startLine": 117,
+      "endLine": 120,
+      "problem": "當 PR 審查出嚴重問題，但結果 commit/push 失敗時，`commitFindings` 只回傳 `false`。新版主流程又改成「本輪審查不因嚴重問題直接 exit 1，而是依賴下一輪讀到 `[failure]` commit 才失敗」。最小情境：`severe.length > 0`、token 權限不足或 push 競態導致 `commitAndPushFindings` 丟錯；此時沒有 `[failure]` commit、也不會有下一輪快速回報，但本輪仍可能以 0 結束，PR 檢查會在存在嚴重問題時通過。",
+      "suggestion": "嚴重問題存在時，若 failure 結果 commit 沒有成功產生，必須讓本輪直接回傳 1。可保留「成功 push failure commit 時本輪回傳 0、下一輪失敗」的設計，但 push 失敗不可靜默通過。",
+      "suggestedCode": "const result = severe.length === 0 ? 'success' : 'failure';\nconst committed = commitFindings({ cwd, ctx, files: filesToCommit, result });\nif (result === 'failure' && !committed) {\n  log('收尾', 'ERR', '有嚴重問題但無法推送 failure 結果 commit，本輪直接失敗。');\n  return 1;\n}\nreturn 0;",
+      "id": "F010",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。此條與 F001 指涉同一風險：嚴重 finding 存在時 failure 結果 commit/push 失敗，可能使本輪檢查仍以成功結束。"
+        }
+      }
+    },
+    {
+      "reviewer": "Maya",
+      "focus": "testing",
+      "badge": "🧪",
+      "severity": "警告",
+      "file": "src/index.js",
+      "startLine": 163,
+      "endLine": 437,
+      "problem": "建問題模式被大幅改寫：情境留言先暫存、只有 kept finding 才建 issue、建立失敗會 fallback 回 PR、嚴重／非嚴重 finding 會改發到 issue、最後還要回貼追蹤 issue 連結與設定相依關係。但目前新增測試只覆蓋了少數 helper，沒有驗證 `main()` 在這些分支下的實際副作用。這些行為沒經過試煉，等於還不知道留言會不會發錯地方、fallback 後會不會漏清舊留言、或無 finding 時是否真的靜默通過。",
+      "suggestion": "請補 `src/index.js` 的流程層級測試，mock `gitea`、`review`、`agents`、`gitrepo` 等依賴，至少覆蓋：\n\n| 情境 | 應驗證 |\n| --- | --- |\n| `createIssue=true` 且 `kept.length===0` | 不建 issue、不發 PR 留言、暫存情境留言不外洩 |\n| `createIssue=true` 且有 finding | 先建 issue，再依序 flush 工具／diff／角色留言，finding 發到 issue，PR 只留下追蹤 issue 連結 |\n| 建 issue 或寫入 issue 失敗 | fallback 後情境留言改發 PR，後續使用一般模式留言與舊留言清理 |\n| 嚴重 finding | 結果 commit 標記為 failure，但本輪 `main()` 回傳 0，下一輪才由 bot commit 回報 1 |",
+      "suggestedCode": "",
+      "id": "F011",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已涵蓋建問題模式的暫存留言、只在有 finding 時建 issue、fallback、嚴重／非嚴重分流、PR 回貼與靜默通過等核心分支缺少流程測試。"
+        }
+      }
+    },
+    {
+      "reviewer": "Maya",
+      "focus": "testing",
+      "badge": "🧪",
+      "severity": "警告",
+      "file": "src/lib/gitrepo.js",
+      "startLine": 298,
+      "endLine": 355,
+      "problem": "`commitAndPushFindings` 的推送行為改成一律走 `pushWithCredential`，並宣稱 token 不進 argv、會清掉 checkout 的 extraheader、只接受同一 Gitea origin 的 `.git` URL。這是安全與 CI 觸發都很關鍵的失敗路徑，但目前 `test/gitrepo.test.js` 只測了分支名稱檢查，沒有驗證推送時的 argv/env，也沒有驗證遠端 URL 不符時會停止。這段若改壞，測試不會提醒我們 token 可能出現在命令列或推送根本沒用 PAT 身分。",
+      "suggestion": "請補針對 `commitAndPushFindings`／`pushWithCredential` 的測試。建議用可替換的 `execFileSync` seam 或測試專用注入方式，斷言：\n\n| 情境 | 斷言方向 |\n| --- | --- |\n| 正常推送 | `git push` argv 只含不帶帳密的 `remoteUrl` 與 refspec |\n| 正常推送 | env 含 `GIT_CONFIG_COUNT=2`，先清空 `http.<origin>/.extraheader`，再注入 `Authorization: Basic ...` |\n| `remoteUrl` origin 不符或非 `.git` | 拋出固定錯誤且不執行 push |\n| push 失敗 | 對外錯誤訊息不含 token、remote URL 或 argv |",
+      "suggestedCode": "",
+      "id": "F012",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已記錄 commitAndPushFindings／pushWithCredential 的認證推送路徑、argv/env、遠端目標檢查與失敗訊息遮蔽缺少測試。"
+        }
+      }
+    },
+    {
+      "reviewer": "Maya",
+      "focus": "testing",
+      "badge": "🧪",
+      "severity": "警告",
+      "file": "src/lib/gitrepo.js",
+      "startLine": 130,
+      "endLine": 188,
+      "problem": "`resolveMergeBase` 新增了多階段 fetch 補歷史流程：先 fetch base、首次 merge-base、再 deepen base、deepen PR HEAD、必要時 unshallow，且每個策略成功後要立即重試並短路返回。現有測試只驗證不安全 `baseRef` 會在 fetch 前被拒絕，沒有測到淺層 checkout、首次失敗後補抓成功、策略失敗繼續下一個、全部失敗時診斷訊息等邊界。這正是容易 off-by-one 或順序錯的流程，現在還沒有測試保護。",
+      "suggestion": "請補資料驅動的 `resolveMergeBase` 測試，mock git 執行結果來驗證：首次 merge-base 成功時不跑 deepen；deepen base 後成功會立刻回傳；deepen PR HEAD 使用目前 `HEAD` SHA 而不是遠端符號 `HEAD`；非 shallow repo 不呼叫 `--unshallow`；全部策略失敗時錯誤包含各策略診斷且保留 cause。",
+      "suggestedCode": "",
+      "id": "F013",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。resolveMergeBase 多階段 fetch、淺層與非淺層路徑、策略停止條件、全部失敗診斷與 cause 缺少測試，已由歷史 findings 涵蓋。"
+        }
+      }
+    }
+  ]
+}

.gitea/ai-review/findings/2026-07-21-16:30:12.json

@@ -0,0 +1,184 @@
+{
+  "generatedAt": "2026/07/21 16:30:12",
+  "commitSha": "43ad2b56d27429aa3c812522dc1d4fedce4a9b76",
+  "prNumber": 6,
+  "tool": {
+    "name": "codex",
+    "version": "codex-cli 0.144.6",
+    "model": "gpt-5.5"
+  },
+  "findings": [],
+  "excluded": [
+    {
+      "reviewer": "Bard",
+      "focus": "style",
+      "badge": "🎼",
+      "severity": "建議",
+      "file": "readme.md",
+      "startLine": 48,
+      "endLine": 48,
+      "problem": "Mermaid 節點代號從 `N8` 跳回 `N2`，雖然流程語意是「步驟 2 延後」，但原始碼讀起來像旋律突然倒帶；維護者在對照圖與步驟時容易被代號順序絆住。",
+      "suggestion": "節點 id 建議改用語意名稱，而把顯示文字保留步驟編號。例如 `ResolveOldComments[2 延後將舊留言標記解決...]`，讓圖的原始碼與顯示內容各自清楚。",
+      "suggestedCode": "",
+      "id": "F002",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已指出流程步驟編號與實際順序、README 流程圖及文件對照會產生認知落差；本條 Mermaid 節點代號問題屬同一類指控。"
+        }
+      }
+    },
+    {
+      "reviewer": "Bard",
+      "focus": "style",
+      "badge": "🎼",
+      "severity": "警告",
+      "file": "src/index.js",
+      "startLine": 167,
+      "endLine": 235,
+      "problem": "`main()` 內新增了建 issue 模式狀態、暫存佇列與三個帶長篇 JSDoc 的閉包，讓主流程的旋律被大量伴奏蓋過。這段同時管理 `issueModeActive`、`trackingIssue`、`pendingIssueCommentBodies` 與 PR 留言 id，可讀性負擔明顯升高。",
+      "suggestion": "把留言路由與建 issue 暫存邏輯抽成小型 helper（例如 `createCommentRouter`），`main()` 只保留流程編排；JSDoc 也移到 helper 旁，讓主流程步驟重新一眼可讀。",
+      "suggestedCode": "",
+      "id": "F003",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。已知排除事項與歷史 findings 已涵蓋 main() 內留言路由、issue 狀態、暫存佇列與發布職責耦合造成可讀性與維護負擔。"
+        }
+      }
+    },
+    {
+      "reviewer": "Bard",
+      "focus": "style",
+      "badge": "🎼",
+      "severity": "建議",
+      "file": "src/lib/gitrepo.js",
+      "startLine": 121,
+      "endLine": 128,
+      "problem": "`strategies` 以陣列位置承載語意，`[label, ...args]` 雖簡短，卻讓每個元素的第二欄之後全靠讀者猜是 git argv；這裡的可讀性像沒有小節線的樂譜。",
+      "suggestion": "改成物件陣列，明確標出 `label` 與 `args`，可降低後續新增 fetch 策略時的閱讀成本。",
+      "suggestedCode": "const strategies = [\n  { label: 'deepen base', args: ['fetch', '--no-tags', '--deepen=1000', 'origin', `+refs/heads/${baseRef}:refs/remotes/${remoteBase}`] },\n  { label: 'deepen PR HEAD', args: ['fetch', '--no-tags', '--deepen=1000', 'origin', headSha] },\n];",
+      "id": "F005",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 finding 已針對 resolveMergeBase 內 strategies 與補救策略編排使閱讀節奏偏密提出問題；本條 tuple 可讀性屬同一段策略結構的細項。"
+        }
+      }
+    },
+    {
+      "reviewer": "Leo",
+      "focus": "maintainability",
+      "badge": "🧰",
+      "severity": "警告",
+      "file": "src/index.js",
+      "startLine": 163,
+      "endLine": 231,
+      "problem": "`main()` 這次把一般模式／建問題模式／降級模式的留言去向都塞進閉包狀態：`issueModeActive`、`trackingIssue`、`pendingIssueCommentBodies`、`currentRunCommentIds` 彼此耦合。半年後要新增一種落地方式或調整「何時清舊留言」時，維護者必須同時追多個可變狀態與後續多個 `if (issueModeActive)` 分支，很容易漏掉 flush、清空、登錄留言 id 或 fallback 後的收尾行為。",
+      "suggestion": "把留言目的地抽成小型物件，讓主流程只呼叫 `commentSink.postContext()`、`commentSink.finalizeAfterFindings()`、`commentSink.postFinding()` 這類語意方法。一般 PR、issue buffering、fallback 的狀態轉換集中在同一個模組或工廠函式內，`main()` 保持審查流程編排，不承擔留言狀態機。",
+      "suggestedCode": "",
+      "id": "F006",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。與 F003 及既有排除事項相同，均指向 main() 以可變閉包狀態承擔留言目的地、issue 生命週期與 fallback 狀態機。"
+        }
+      }
+    },
+    {
+      "reviewer": "Leo",
+      "focus": "maintainability",
+      "badge": "🧰",
+      "severity": "警告",
+      "file": "src/index.js",
+      "startLine": 232,
+      "endLine": 241,
+      "problem": "流程註解把「將舊留言標記為解決」稱為「步驟 2（延後執行）」，但實際執行點在審查結果產生後、接近原本步驟 9 前。這種「編號是 2、時間點是 8 後」的設計已經擴散到多個檔案的 JSDoc 與 log 描述，未來查 CI log 或維護流程圖時會產生認知落差：看到 `步驟2` 不代表它真的發生在第二步。",
+      "suggestion": "不要用固定序號承載流程語意。建議改成穩定階段名稱，例如 `清理舊留言`、`工具偵測`、`diff整理`，或重新編號為實際執行順序並在文件說明「清理舊留言延後到結果產生後」。這樣 log、JSDoc、README 流程圖才不會互相背離。",
+      "suggestedCode": "",
+      "id": "F007",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已明確記錄步驟編號散落於 log、JSDoc、README 且實際順序變成 1、3 到 8、2、9 到 10 的維護風險。"
+        }
+      }
+    },
+    {
+      "reviewer": "Leo",
+      "focus": "maintainability",
+      "badge": "🧰",
+      "severity": "建議",
+      "file": "src/lib/gitrepo.js",
+      "startLine": 103,
+      "endLine": 160,
+      "problem": "`resolveMergeBase()` 內同時負責驗證 base ref、fetch base、重試 merge-base、補抓淺層歷史、累積診斷與組錯誤訊息。這些都和「取得 merge-base」有關，但現在全部攤在同一個函式裡，策略陣列、診斷格式與 git 操作細節混在一起；未來要新增 fetch 策略或改診斷文字時，容易不小心改壞主流程判斷。",
+      "suggestion": "把補抓策略與重試邏輯拆成私有 helper，例如 `fetchBaseRef()`、`mergeBaseOrNull()`、`shallowFetchStrategies()`。主函式保留高階流程：驗證 ref → 更新 base → 嘗試 merge-base → 逐一套用策略 → 丟出診斷錯誤。",
+      "suggestedCode": "",
+      "id": "F008",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 finding 已指出 resolveMergeBase 同時負責驗證、fetch 策略編排、診斷與錯誤包裝，難以分辨主流程與補救策略。"
+        }
+      }
+    },
+    {
+      "reviewer": "Maya",
+      "focus": "testing",
+      "badge": "🧪",
+      "severity": "警告",
+      "file": "src/index.js",
+      "startLine": 164,
+      "endLine": 232,
+      "problem": "建問題模式新增了「先暫存情境留言、確定有保留 finding 才建 issue、建 issue 失敗時降級回 PR 留言」這一整段流程，但目前測試只覆蓋了部分 helper，沒有驗證主流程在 create-issue=true 下的分流行為。這代表像「無保留問題時不應建 issue／不應留言」、「建立 issue 失敗時應把 pending 留言補回 PR」、「trackingIssue 建立後後續留言應改送 issue」這些行為都還沒通過試煉。",
+      "suggestion": "建議把 main 流程拆出可注入 gitea/review/agents/gitrepo 的 orchestrator，或至少匯出可測的流程函式，補上 create-issue=true 的案例：1. kept=[] 時不呼叫 createIssue/createIssueComment；2. kept>0 時先 flush pending issue comments 再發 finding；3. createIssue 拋錯時 fallbackToPrComments 會發回 PR 並記錄 currentRunCommentIds；4. issueModeActive 降級後會走一般 PR 留言與 resolveOldComments。",
+      "suggestedCode": "",
+      "id": "F011",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已涵蓋建問題模式核心流程、暫存留言、issue 建立條件、發布分流、外部 API 狀態切換與降級路徑缺少測試。"
+        }
+      }
+    },
+    {
+      "reviewer": "Maya",
+      "focus": "testing",
+      "badge": "🧪",
+      "severity": "警告",
+      "file": "src/lib/gitrepo.js",
+      "startLine": 104,
+      "endLine": 150,
+      "problem": "resolveMergeBase 新增了多階段 fetch/deepen/unshallow fallback 與診斷錯誤，但測試只驗證不安全 baseRef 會被拒絕，沒有驗證任何成功或失敗 fallback 路徑。這段是 diff 基準的核心邏輯，若 shallow checkout 下 deepen PR HEAD 用錯 ref、策略順序跑錯，或全部失敗時診斷不正確，現有測試都抓不到。",
+      "suggestion": "建議用假的 git 執行層或臨時 git repo 補測：首次 merge-base 成功時不跑後續策略；首次失敗但 deepen base 後成功；deepen base 失敗會繼續 deepen PR HEAD；shallow repo 才嘗試 --unshallow；全部失敗時錯誤訊息包含各策略診斷且保留 cause。",
+      "suggestedCode": "",
+      "id": "F012",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已針對 resolveMergeBase 多階段 fetch、淺層與非淺層分支、策略停止條件、降級與最終診斷缺少測試提出相同問題。"
+        }
+      }
+    },
+    {
+      "reviewer": "Maya",
+      "focus": "testing",
+      "badge": "🧪",
+      "severity": "警告",
+      "file": "src/lib/gitrepo.js",
+      "startLine": 272,
+      "endLine": 322,
+      "problem": "commitAndPushFindings 改成一律透過 pushWithCredential 用 PAT extraheader 推送，且新增 headRef 安全檢查與固定錯誤遮蔽；但目前 gitrepo 測試沒有覆蓋 commitAndPushFindings/pushWithCredential 的推送行為。這讓「token 不進 argv」、「清掉 checkout 既有 extraheader」、「遠端 URL 不符時拒絕」、「push 失敗不洩漏 URL/token」這些失敗與安全邊界都沒有被驗證。",
+      "suggestion": "建議以 stub child_process.execFileSync 或可注入 git runner 的方式補測：commit 後呼叫 git push 的 argv 不含 token；env 內含 GIT_CONFIG_COUNT 與 Authorization extraheader；headRef 不安全時在 git add/commit/push 前拋錯；remote origin 不符與 push 失敗時錯誤訊息不包含 token、repo URL 或 Basic header。",
+      "suggestedCode": "",
+      "id": "F013",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已涵蓋 commitAndPushFindings 與 pushWithCredential 的推送策略、認證遮蔽、失敗路徑與 token 不外洩等測試缺口。"
+        }
+      }
+    }
+  ]
+}

action.yml

@@ -1,6 +1,6 @@
 # ============================================================================
 # 用途：定義 AI Code Review Node action 的名稱、輸入參數與 Node.js 24 進入點，供 Gitea / GitHub workflow 以 uses 引用。
-# 更新時間：2026/07/17 18:49:58
+# 更新時間：2026/07/21 17:19:15
 # ============================================================================
 # Gitea / GitHub node action 的 manifest（action.yml）：
 # 定義本 action 的名稱、說明、輸入參數（inputs）與執行方式（runs），
@@ -16,11 +16,11 @@ author: 'Jeffery'
 # 輸入參數區塊：呼叫端 workflow 以 `with:` 傳入，
 # runner 會自動注入為 INPUT_* 環境變數（例如 INPUT_TOKEN、INPUT_MODEL、INPUT_CREATE-ISSUE）供主程式讀取。
 inputs:
-  # Gitea API token：用於對 PR／issue 留言審查結果，以及 push 審查結果檔（findings/exclusions）回 repo。
+  # Gitea API token：用於對 PR／issue 留言審查結果，以及 push 審查結果檔（findings／exclusions）回 repo。
   token:
     # 參數用途說明：secrets/vars context 在 action 內不可用，故由呼叫端 workflow 以 secrets 傳入。
     # 建議傳入能觸發 CI 的 PAT；自動 token 推送結果 commit 時可能不會再觸發 workflow。
-    description: 'Gitea API token（PR/issue 留言與 push findings 用；建議以能觸發 CI 的 PAT 由 secrets 傳入）'
+    description: 'Gitea API token（PR／issue 留言與 push findings 用；建議以能觸發 CI 的 PAT 由 secrets 傳入）'
     # 必填：缺少 token 無法呼叫 Gitea API，action 無法運作。
     required: true
   # 指定 AI 工具使用的模型名稱。

readme.md

@@ -1,6 +1,6 @@
 # AI Code Review
 
-> 更新時間：2026/07/17 18:49:58
+> 更新時間：2026/07/21 17:19:15
 
 AI 多角色 code review 的 Gitea **node action**（`node24`、零外部相依）：以攻擊方六角色（🔮 Mage 邏輯、🗡️ Assassin 安全、⚡ Rogue 效率、🎼 Bard 風格、🧪 Maya 測試、🧰 Leo 可維護性）並行找問題、防守方（🛡️ Paladin）裁決誤報，結果留言到 PR、保存 findings，並以 bot commit 標記審查結果（`[success]`／`[failure]`）供下次觸發快速回報。
 

src/index.js

@@ -4,7 +4,7 @@
 console.log('================================================');
 console.log('Action  : AI Code Review');
 console.log('用途    : AI 多角色 code review：攻擊方找問題、防守方裁決誤報，結果留言到 PR 並保存 findings');
-console.log('更新時間: 2026/07/17 18:49:58');
+console.log('更新時間: 2026/07/21 17:19:15');
 console.log('================================================');
 
 const fs = require('fs');
@@ -126,15 +126,14 @@ function commitFindings({ cwd, ctx, files, result }) {
  * 建問題模式會把審查情境與每條 finding 發到追蹤 issue；沒有保留 finding 時不建立 issue、PR 也不留言。
  * 嚴重 finding 會寫入 failure 結果 commit，警告與建議只建立追蹤資訊，不直接阻擋合併。
  *
- * @returns {Promise<number>} process exit code：本輪「審查」一律回傳 0（不因嚴重問題直接讓檢查失敗——
+ * @returns {Promise<number>} process exit code：沒有嚴重問題且結果 commit 已成功推送時回傳 0；
- *   失敗改由推出的 `[ai-review-bot][failure]` 結果 commit，於下一輪在步驟 1 讀 commit 訊息時回報）；
+ *   若步驟 1 偵測到 `[ai-review-bot][failure]`、前置條件不足，或需要推送結果檔卻未成功推送，
- *   回傳 1 僅發生於：步驟 1 偵測到 `[ai-review-bot][failure]` 結果 commit，或前置條件不足
+ *   則回傳 1，避免 token 權限不足或遠端競態讓 workflow 靜默通過。
- *   （缺 PR 編號／token、找不到 AI 工具）等無法進行審查的情況。
  * @remarks
  * 使用情境：由本檔尾端的頂層呼叫端執行 —— `main().then((code) => process.exit(code))`；
  * 非預期例外由頂層 `catch` 記 ERR log 後以 exit code 1 收場，且刻意不 commit 結果標記，
  * 讓下一次 workflow 觸發時重新完整審查。警告＋建議等級不影響結果標記，只有「嚴重」會使結果 commit
- * 標記為 failure；而「失敗檢查（exit 1）」只由步驟 1 讀到該 failure 結果 commit 時產生，審查本輪不直接 exit 1。
+ * 標記為 failure；若結果檔需要 push 卻失敗，本輪直接 exit 1，避免缺權限時無聲放行。
  * 建問題模式只改變問題明細的落地方式（issue 留言取代 findings 進版控），不改變上述結果標記判定。
  */
 async function main() {
@@ -193,7 +192,7 @@ async function main() {
     return created;
   };
   /**
-   * 建問題模式：建立追蹤 issue（標題＝PR 標題、本文＝PR 描述＋回溯 PR 的引言，連同挑好的標籤一次建立），
+   * 建問題模式：開啟追蹤 issue（標題＝PR 標題、本文＝PR 描述＋回溯 PR 的引言，連同挑好的標籤一次建立），
    * 並把 `pendingIssueCommentBodies` 內暫存的情境留言依流程順序寫入 issue；
    * 設定閉包變數 `trackingIssue` 供後續留言直接發到 issue。
    * 僅於「確定有保留問題」時呼叫一次。標籤於建立時一次帶入，省去「先建空標籤 issue 再補掛」的多餘 API 往返。
@@ -202,17 +201,18 @@ async function main() {
    *   空陣列或省略時不掛任何標籤（`gitea.createIssue` 對空陣列不帶 labels 欄位）。
    * @returns {Promise<void>} 無回傳值；結果反映在閉包變數 `trackingIssue` 與 issue 留言。
    */
-  const createIssueAndFlushBufferedComments = async (labelIds = []) => {
+  const openTrackingIssue = async (labelIds = []) => {
     trackingIssue = await gitea.createIssue(ctx, {
       title: ctx.prTitle || `AI Code Review：PR #${ctx.prNumber}`,
       body: templates.issueBody({ prNumber: ctx.prNumber, prBody: ctx.prBody }),
       labels: labelIds,
     });
     log('建問題', 'INF', `已建立追蹤 issue #${trackingIssue.number}，寫入 ${pendingIssueCommentBodies.length} 則情境留言。`);
-    for (const body of pendingIssueCommentBodies) {
+    while (pendingIssueCommentBodies.length > 0) {
+      const body = pendingIssueCommentBodies[0];
       await gitea.createCommentOnIssue(ctx, trackingIssue.number, body);
+      pendingIssueCommentBodies.shift();
     }
-    pendingIssueCommentBodies.length = 0;
   };
   /**
    * 建問題模式降級：追蹤 issue 無法建立或寫入時，改把已暫存的情境留言發回 PR，後續沿用一般模式。
@@ -337,7 +337,7 @@ async function main() {
         log('建問題', 'WRN', `標籤挑選失敗（${err.message}），issue 不掛標籤。`);
       }
       try {
-        await createIssueAndFlushBufferedComments(labelIds);
+        await openTrackingIssue(labelIds);
       } catch (err) {
         log('建問題', 'WRN', `建立或寫入追蹤 issue 失敗（${err.message}），改用 PR 留言與 findings 檔流程。`);
         await fallbackToPrComments();
@@ -377,7 +377,7 @@ async function main() {
   }
 
   // ── 建問題模式收束：在 PR 回貼 issue 連結（雙向關聯）；僅在有嚴重問題時才讓 PR 相依於該 issue ─
-  //    標籤已於建立 issue 時一次帶入（見上方 selectLabels → createIssueAndFlushBufferedComments），此處不再補掛。
+  //    標籤已於建立 issue 時一次帶入（見上方 selectLabels → openTrackingIssue），此處不再補掛。
   if (issueModeActive && trackingIssue) {
     await review.resolveOldIssueLinkComments({ ctx, gitea });
     await gitea.createIssueComment(
@@ -420,14 +420,13 @@ async function main() {
   } else {
     log('收尾', 'INF', '建問題模式且 exclusions.json 無變更，略過 commit/push。');
   }
-  // 本輪「審查」一律以成功收場、不直接讓檢查失敗；有嚴重問題時已推出 [failure] 結果 commit，
+  // 需要推送結果檔卻沒成功時直接失敗；這通常代表 token 權限不足、非快轉或分支保護阻擋。
-  // 由它再觸發的下一輪在步驟 1 讀 commit 訊息時才回報失敗（exit 1）。如此失敗檢查落在帶有結果
+  if (review.shouldFailMissingResultCommit({ filesToCommit, resultCommitted })) {
-  // 標記的最新 head 上，與合併判定一致。（result 僅用於上方 commit 訊息的結果標記。）
+    log('收尾', 'ERR', '審查結果檔需要 push 但未成功產生結果 commit；直接回報失敗避免缺權限時靜默通過。');
-  if (result === 'failure') {
-    if (!resultCommitted) {
-      log('收尾', 'ERR', '本輪有嚴重問題，但未成功產生 [failure] 結果 commit；直接回報失敗避免 fail-open。');
     return 1;
   }
+  // 嚴重問題已推出 [failure] 結果 commit 時，由它再觸發的下一輪在步驟 1 讀 commit 訊息回報失敗。
+  if (result === 'failure') {
     log('收尾', 'INF', '本輪有嚴重問題：已標記結果 commit 為 [failure]，失敗檢查由下一輪步驟 1 讀 commit 訊息回報。');
   }
   return 0;

src/lib/gitref.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { execFileSync } = require('child_process');
+
+/**
+ * 驗證遠端分支名稱可安全用於 refspec 與 refs/remotes/origin/*。
+ *
+ * @param {string} refName - 使用者或事件 payload 提供的分支名稱。
+ * @param {string} fieldName - 錯誤訊息中的欄位名稱。
+ * @returns {string} 原樣回傳通過驗證的分支名稱。
+ * @throws {Error} 分支名稱空白、含路徑穿越，或不符合 git 分支 ref 規則時拋出。
+ */
+function assertSafeBranchRef(refName, fieldName) {
+  const value = String(refName || '').trim();
+  if (!value) throw new Error(`${fieldName} 不可為空。`);
+  if (value.includes('..') || value.startsWith('/') || value.endsWith('/') || value.includes('\\')) {
+    throw new Error(`${fieldName} 不是安全的分支名稱：${value}`);
+  }
+  try {
+    execFileSync('git', ['check-ref-format', '--branch', value], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch {
+    throw new Error(`${fieldName} 不是合法的 git 分支名稱：${value}`);
+  }
+  return value;
+}
+
+module.exports = {
+  assertSafeBranchRef,
+};

src/lib/gitrepo.js

@@ -1,37 +1,10 @@
 'use strict';
 
 const { execFileSync } = require('child_process');
+const { assertSafeBranchRef } = require('./gitref');
 
 // git 操作工具：一律以 execFileSync 呼叫 git（不經 shell，避免注入），輸出以 UTF-8 回傳。
 
-/**
- * 驗證遠端分支名稱可安全用於 refspec 與 refs/remotes/origin/*。
- *
- * @param {string} refName - 使用者或事件 payload 提供的分支名稱。
- * @param {string} fieldName - 錯誤訊息中的欄位名稱。
- * @returns {string} 原樣回傳通過驗證的分支名稱。
- * @throws {Error} 分支名稱空白、含路徑穿越，或不符合 git 分支 ref 規則時拋出。
- * @remarks
- * 使用情境：`resolveMergeBase` 的 `baseRef` 與 `commitAndPushFindings` 的
- * `headRef` 會被組進 refspec；先驗證可避免惡意 payload 影響本地 refs 路徑。
- */
-function assertSafeBranchRef(refName, fieldName) {
-  const value = String(refName || '').trim();
-  if (!value) throw new Error(`${fieldName} 不可為空。`);
-  if (value.includes('..') || value.startsWith('/') || value.endsWith('/') || value.includes('\\')) {
-    throw new Error(`${fieldName} 不是安全的分支名稱：${value}`);
-  }
-  try {
-    execFileSync('git', ['check-ref-format', '--branch', value], {
-      encoding: 'utf8',
-      stdio: ['ignore', 'pipe', 'pipe'],
-    });
-  } catch {
-    throw new Error(`${fieldName} 不是合法的 git 分支名稱：${value}`);
-  }
-  return value;
-}
-
 /**
  * 同步執行 git 指令並回傳原始 stdout 輸出。
  *
@@ -308,18 +281,9 @@ function commitAndPushFindings(cwd, { headRef, headSha, message, files, token, s
 /**
  * 以帶認證的方式推送到指定遠端，認證資訊只經環境變數傳入、不進命令列 argv。
  *
- * 認證方式：等同 `https://ai-review-bot:<secret>@host/...` 的 HTTP Basic（git 會把
+ * 以 `GIT_CONFIG_*` 注入本次 HTTP Basic extraheader，避免憑證出現在 argv；
- * URL 帳密轉成相同的 `Authorization: Basic` 標頭送出），但改以 git 的
+ * 同時先清空 checkout 持久化的自動 token extraheader，確保本次 push 使用呼叫端 token。
- * `GIT_CONFIG_*` 環境變數注入 `http.<serverUrl>/.extraheader`，使 base64 憑證**不出現在 argv**
+ * 推送失敗時改拋固定訊息，避免原始例外帶出遠端 URL 或認證資訊。
- * （避免程序清單／例外回顯洩漏）；推送目標 URL 亦不含帳密。
- *
- * 觸發 CI 關鍵：`actions/checkout` 會把「自動 Actions token」持久化在同一個
- * `http.<serverUrl>/.extraheader` scope；若沿用它推送，Gitea 會視為「自動 token 觸發」而
- * **不再觸發 workflow**（防遞迴）。故本函式對這次 push 於該 scope**先以空值重置**（清掉自動
- * token——git 對 extraHeader 給空值即清空既有清單），**再注入 PAT 的 Authorization**，讓推送以
- * PAT 身分進行、觸發 PR 的 synchronize；作用範圍僅限本次 push 的環境變數，不影響 action 其他
- * 仰賴 checkout 持久化憑證的 fetch（如 {@link resolveMergeBase}）。
- * 推送失敗時**不重拋原始例外**（其 message 會含命令列與遠端 URL），改拋固定訊息。
  *
  * @param {string} cwd - git 工作目錄（repo 的 checkout 路徑）。
  * @param {string} remoteUrl - 不含帳密的遠端 URL（形如 `https://host/owner/repo.git`）。
@@ -367,7 +331,4 @@ module.exports = {
   fileDiff,
   fileLastUpdatedIso,
   commitAndPushFindings,
-  __test: {
-    assertSafeBranchRef,
-  },
 };

src/lib/review.js

@@ -579,6 +579,18 @@ function resultFilesToCommit({ createIssue, severeCount, relativePath, exclusion
   return files;
 }
 
+/**
+ * 判斷本輪是否因結果 commit 未成功推送而必須失敗。
+ *
+ * @param {Object} params - 解構參數。
+ * @param {string[]} params.filesToCommit - 本輪預期寫回遠端分支的結果檔清單。
+ * @param {boolean} params.resultCommitted - 結果檔是否已成功 commit 並 push。
+ * @returns {boolean} 需要寫回結果檔卻沒有成功推送時回傳 true。
+ */
+function shouldFailMissingResultCommit({ filesToCommit, resultCommitted }) {
+  return filesToCommit.length > 0 && !resultCommitted;
+}
+
 /**
  * 就地排序 findings：依 嚴重→警告→建議、再依檔案路徑、再依起始行遞增。
  *
@@ -914,6 +926,7 @@ module.exports = {
   sortFindings,
   appendExclusions,
   resultFilesToCommit,
+  shouldFailMissingResultCommit,
   selectLabels,
   postSevereToIssue,
   postOthersToIssue,

test/gitrepo.test.js

@@ -4,18 +4,46 @@ const assert = require('node:assert/strict');
 const test = require('node:test');
 
 const gitrepo = require('../src/lib/gitrepo');
+const gitref = require('../src/lib/gitref');
 
 test('assertSafeBranchRef 接受一般分支名稱', () => {
-  assert.equal(gitrepo.__test.assertSafeBranchRef('feature/review-123', 'baseRef'), 'feature/review-123');
+  assert.equal(gitref.assertSafeBranchRef('feature/review-123', 'baseRef'), 'feature/review-123');
 });
 
 test('assertSafeBranchRef 拒絕路徑穿越分支名稱', () => {
   assert.throws(
-    () => gitrepo.__test.assertSafeBranchRef('../../hooks/pre-push', 'baseRef'),
+    () => gitref.assertSafeBranchRef('../../hooks/pre-push', 'baseRef'),
     /不是安全的分支名稱/,
   );
 });
 
+test('assertSafeBranchRef 拒絕空白分支名稱', () => {
+  for (const value of ['', '   ', null, undefined]) {
+    assert.throws(
+      () => gitref.assertSafeBranchRef(value, 'baseRef'),
+      /baseRef 不可為空/,
+    );
+  }
+});
+
+test('assertSafeBranchRef 拒絕不安全的 refspec 分支名稱', () => {
+  for (const value of ['/feature', 'feature/', 'feature\\x', 'feature..x']) {
+    assert.throws(
+      () => gitref.assertSafeBranchRef(value, 'baseRef'),
+      /不是安全的分支名稱/,
+    );
+  }
+});
+
+test('assertSafeBranchRef 拒絕 git 不合法的分支名稱', () => {
+  for (const value of ['feature.lock', 'feature@{x}', 'feature~x', 'feature^x']) {
+    assert.throws(
+      () => gitref.assertSafeBranchRef(value, 'baseRef'),
+      /不是合法的 git 分支名稱/,
+    );
+  }
+});
+
 test('resolveMergeBase 會在 git fetch 前拒絕不安全 baseRef', () => {
   assert.throws(
     () => gitrepo.resolveMergeBase(process.cwd(), '../../hooks/pre-push'),

test/review.test.js

@@ -98,6 +98,30 @@ test('resultFilesToCommit 在建問題模式無嚴重問題時只提交 exclusio
   );
 });
 
+test('shouldFailMissingResultCommit 在結果檔需要 push 但未成功時回報失敗', () => {
+  assert.equal(
+    review.shouldFailMissingResultCommit({
+      filesToCommit: ['.gitea/ai-review/findings/run.json'],
+      resultCommitted: false,
+    }),
+    true,
+  );
+  assert.equal(
+    review.shouldFailMissingResultCommit({
+      filesToCommit: ['.gitea/ai-review/findings/run.json'],
+      resultCommitted: true,
+    }),
+    false,
+  );
+  assert.equal(
+    review.shouldFailMissingResultCommit({
+      filesToCommit: [],
+      resultCommitted: false,
+    }),
+    false,
+  );
+});
+
 test('resolveOldIssueLinkComments 只標註舊追蹤 issue 連結', async () => {
   const edited = [];
   const fakeGitea = {