chore(ai-review 狀態): 回寫本輪 findings 與排除事項

style(action manifest): 統一中文斜線標點
refactor(gitref): 將分支名稱驗證改為正式模組
2026-07-21 16:26:30 +08:00 · 2026-07-21 16:26:30 +08:00 · 2026-07-21 16:26:30 +08:00 · 2026-07-21 08:00:35 +00:00 · 2026-07-21 15:57:53 +08:00 · 2026-07-21 15:57:53 +08:00
11 changed files with 771 additions and 69 deletions
@@ -1791,5 +1791,214 @@
    "endLine": 32,
    "problem": "`redactSecrets` 新增多個遮罩規則與控制字元單行化，但測試只透過 `agentFailureDetail` 間接覆蓋 Authorization 與 token 兩種格式。URL 內嵌帳密、長 token、GitHub token 樣式、控制字元注入與 null/undefined 邊界都還沒被直接驗證。",
    "reason": "Paladin：可排除（重複）。歷史 findings 已記錄失敗診斷與 redactSecrets 對 Authorization、URL 帳密、token 格式、控制字元、截斷與空值邊界缺少測試；本條為同一測試缺口。"
+  },
+  {
+    "addedAt": "2026/07/21 14:42:39",
+    "prNumber": 6,
+    "reviewer": "Bard",
+    "severity": "建議",
+    "file": "src/index.js",
+    "startLine": 179,
+    "endLine": 212,
+    "problem": "`queueOrPostComment` 與 `createIssueAndFlushBufferedComments` 這兩個閉包名稱像兩段不同旋律：一個強調「排隊或發布」，另一個卻把「建立 issue、flush 暫存留言、設定狀態」全塞進名稱與實作。讀者要來回追 `trackingIssue`、`pendingIssueCommentBodies`，節奏偏長且語意負擔重。",
+    "reason": "Paladin：可排除（重複）。歷史 finding 已指出 main() 內新增閉包與 issue/comment 路由細節讓主流程閱讀負擔加重；本條只是改以目前函式名稱描述同一維護性問題。"
+  },
+  {
+    "addedAt": "2026/07/21 14:42:39",
+    "prNumber": 6,
+    "reviewer": "Leo",
+    "severity": "警告",
+    "file": "src/index.js",
+    "startLine": 165,
+    "endLine": 213,
+    "problem": "`main()` 這次把「留言目的地切換、issue 建立、暫存留言 flush、標籤挑選前置狀態」都塞進閉包與可變狀態（`pendingIssueCommentBodies`、`trackingIssue`、`currentRunCommentIds`）。半年後要改建問題模式時，維護者得同時追蹤主流程步驟、閉包副作用與留言落點，任何新增留言點都可能忘記處理 queue/flush 或 PR 排除清單，長期會讓流程編排變得很脆弱。",
+    "reason": "Paladin：可排除（命中已知排除事項且重複）。已知與歷史 findings 已涵蓋 main() 內留言目的地、issue 狀態、緩衝佇列與可變閉包耦合，及應抽出發布器／sink 的方向。"
+  },
+  {
+    "addedAt": "2026/07/21 14:42:39",
+    "prNumber": 6,
+    "reviewer": "Leo",
+    "severity": "警告",
+    "file": "src/index.js",
+    "startLine": 302,
+    "endLine": 353,
+    "problem": "建問題模式的收束邏輯把「挑標籤、建立 issue、發 finding、回貼 PR、設定 issue dependency、決定是否阻擋合併」全部展開在 `main()`。這段和前面的 `createIssueAndFlushBufferedComments` 共同組成一條隱性的 issue workflow，但邊界沒有被封裝；未來要新增 issue 模板、改排序、改阻擋條件或重試策略時，會在主流程裡到處補條件，維護成本會快速上升。",
+    "reason": "Paladin：可排除（重複）。此條與 F006 及歷史 findings 同樣指向建問題模式在 main() 中承擔 issue workflow、發布分流與狀態管理，屬同一維護性問題的延伸描述。"
+  },
+  {
+    "addedAt": "2026/07/21 14:42:39",
+    "prNumber": 6,
+    "reviewer": "Leo",
+    "severity": "建議",
+    "file": "readme.md",
+    "startLine": 56,
+    "endLine": 132,
+    "problem": "README 內大量維護到原始碼行號的連結，這次 diff 只是分支與行號位移就需要同步改一整片表格。這種文件和程式碼行號的硬耦合很容易在後續修改時過期，讀者點到錯誤位置，維護者也要花時間做機械式同步。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已多次指出 README 功能表硬編分支與行號連結，導致文件與原始碼高度耦合且容易失準。"
+  },
+  {
+    "addedAt": "2026/07/21 14:42:39",
+    "prNumber": 6,
+    "reviewer": "Mage",
+    "severity": "警告",
+    "file": "src/index.js",
+    "startLine": 251,
+    "endLine": 253,
+    "problem": "無可審查變更的分支在一般模式下會先把舊留言標為過時，之後才保存 findings 與 commit/push 結果。最小重現：`files.length === 0`、`nothingToReviewComment` 成功、`resolveOldComments` 成功，但接著 `saveFindings` 因檔案系統錯誤或 `commitFindings` 因 push 失敗拋例外。此時舊審查結果已被標過時，但沒有成功落地本回合的 success 結果 commit，狀態會停在半更新。",
+    "reason": "Paladin：可排除（命中已知排除事項）。維護者已裁示舊留言應刻意在本回合結果發布前標為過時；本條要求延後清理，落在同一已排除範圍。"
+  },
+  {
+    "addedAt": "2026/07/21 14:42:39",
+    "prNumber": 6,
+    "reviewer": "Maya",
+    "severity": "警告",
+    "file": "src/index.js",
+    "startLine": 160,
+    "endLine": 353,
+    "problem": "建問題模式的主流程被大幅改寫，但目前測試只驗證了少數 helper，沒有驗證「留言先暫存、確定有 kept finding 才建 issue、無保留問題時靜默通過、嚴重問題才加 issue dependency、最後回貼 PR 連結」這些新增流程。這些行為一旦順序或條件寫錯，測試不會擋下來。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已涵蓋建問題模式 main() 層級流程缺測試，包括暫存留言、有 finding 才建 issue、無 finding 靜默、PR 回貼、嚴重與非嚴重分流及 dependency 失敗降級。"
+  },
+  {
+    "addedAt": "2026/07/21 14:42:39",
+    "prNumber": 6,
+    "reviewer": "Maya",
+    "severity": "警告",
+    "file": "src/lib/gitrepo.js",
+    "startLine": 307,
+    "endLine": 361,
+    "problem": "`pushWithCredential` 新增了關鍵認證行為，但沒有測試驗證它真的用 `GIT_CONFIG_*` 清掉 checkout 的 extraheader、再注入 PAT Authorization，也沒有測試遠端 URL 不符與 push 失敗時不洩漏 URL/token 的失敗路徑。這段是結果 commit 能否觸發下一輪 CI 的核心，沒有測試等於這個新契約還沒通過試煉。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已記錄 pushWithCredential／pushToken 認證推送路徑缺少測試，包含 token 不進 argv、認證遮蔽、推送目標與失敗訊息不洩漏敏感資訊。"
+  },
+  {
+    "addedAt": "2026/07/21 14:42:39",
+    "prNumber": 6,
+    "reviewer": "Maya",
+    "severity": "警告",
+    "file": "src/lib/gitrepo.js",
+    "startLine": 130,
+    "endLine": 192,
+    "problem": "`resolveMergeBase` 新增多段 fetch fallback：先抓 base、再 deepen base、deepen PR HEAD、最後 shallow repo 才 unshallow，但現有測試只驗證不安全 baseRef 會被拒絕，沒有驗證淺層歷史補抓順序、每次 fetch 後會重試 merge-base、成功後會短路，也沒有覆蓋所有策略失敗時的診斷錯誤。",
+    "reason": "Paladin：可排除（重複）。歷史 findings 已針對 resolveMergeBase 多階段 fetch、淺層與非淺層分支、成功短路、降級順序與最終失敗診斷缺測試提出相同問題。"
+  },
+  {
+    "addedAt": "2026/07/21 14:42:39",
+    "prNumber": 6,
+    "reviewer": "Maya",
+    "severity": "建議",
+    "file": "src/lib/diagnostics.js",
+    "startLine": 18,
+    "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 針對舊位置的描述已由現有收尾防線涵蓋。"
  }
 ]
@@ -0,0 +1,204 @@
+{
+  "generatedAt": "2026/07/21 14:42:39",
+  "commitSha": "d424447d1502f49538fcb3093d23b5ac7bfa16c5",
+  "prNumber": 6,
+  "tool": {
+    "name": "codex",
+    "version": "codex-cli 0.144.6",
+    "model": "gpt-5.5"
+  },
+  "findings": [
+    {
+      "reviewer": "Bard",
+      "focus": "style",
+      "badge": "🎼",
+      "severity": "建議",
+      "file": "src/lib/gitrepo.js",
+      "startLine": 139,
+      "endLine": 160,
+      "problem": "`runFetch`、`tryMergeBase`、`firstError`、`strategies` 夾在 `resolveMergeBase` 主旋律中，使這個函式同時負責驗證、fetch 策略編排、診斷文字組裝與錯誤包裝。即使邏輯可行，閱讀節奏已偏密，維護者很難一眼分辨「主要流程」與「補救策略」。",
+      "suggestion": "建議將 fetch 策略與診斷收集抽成小函式，例如 `fetchAndRecord`、`resolveMergeBaseWithStrategies`，讓 `resolveMergeBase` 保留高階流程：驗證 baseRef → fetch base → 嘗試 merge-base → 補抓歷史。",
+      "suggestedCode": "",
+      "id": "F003",
+      "verdicts": {
+        "Paladin": {
+          "exclude": false,
+          "reason": "保留。歷史 findings 主要涵蓋 resolveMergeBase 缺測試與診斷不足，本條指向函式內策略編排、診斷組裝與錯誤包裝混雜的可維護性問題，未被既有排除事項完整涵蓋。"
+        }
+      }
+    }
+  ],
+  "excluded": [
+    {
+      "reviewer": "Bard",
+      "focus": "style",
+      "badge": "🎼",
+      "severity": "建議",
+      "file": "src/index.js",
+      "startLine": 179,
+      "endLine": 212,
+      "problem": "`queueOrPostComment` 與 `createIssueAndFlushBufferedComments` 這兩個閉包名稱像兩段不同旋律：一個強調「排隊或發布」，另一個卻把「建立 issue、flush 暫存留言、設定狀態」全塞進名稱與實作。讀者要來回追 `trackingIssue`、`pendingIssueCommentBodies`，節奏偏長且語意負擔重。",
+      "suggestion": "建議統一命名語彙，例如把「暫存／發布」集中成 `postReviewComment`、`flushPendingIssueComments`，讓函式名稱只描述一件事；建立 issue 與 flush 留言也可拆成兩段，讀起來會更像樂句而不是長句。",
+      "suggestedCode": "",
+      "id": "F002",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 finding 已指出 main() 內新增閉包與 issue/comment 路由細節讓主流程閱讀負擔加重；本條只是改以目前函式名稱描述同一維護性問題。"
+        }
+      }
+    },
+    {
+      "reviewer": "Leo",
+      "focus": "maintainability",
+      "badge": "🧰",
+      "severity": "警告",
+      "file": "src/index.js",
+      "startLine": 165,
+      "endLine": 213,
+      "problem": "`main()` 這次把「留言目的地切換、issue 建立、暫存留言 flush、標籤挑選前置狀態」都塞進閉包與可變狀態（`pendingIssueCommentBodies`、`trackingIssue`、`currentRunCommentIds`）。半年後要改建問題模式時，維護者得同時追蹤主流程步驟、閉包副作用與留言落點，任何新增留言點都可能忘記處理 queue/flush 或 PR 排除清單，長期會讓流程編排變得很脆弱。",
+      "suggestion": "把留言目的地抽成明確的小型物件或模組，例如 `ReviewCommentSink` / `IssueCommentSink`，由它負責 `post()`、`flush()`、`currentRunCommentIds`。`main()` 只保留流程順序，不直接管理留言暫存與 issue 狀態。",
+      "suggestedCode": "",
+      "id": "F006",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（命中已知排除事項且重複）。已知與歷史 findings 已涵蓋 main() 內留言目的地、issue 狀態、緩衝佇列與可變閉包耦合，及應抽出發布器／sink 的方向。"
+        }
+      }
+    },
+    {
+      "reviewer": "Leo",
+      "focus": "maintainability",
+      "badge": "🧰",
+      "severity": "警告",
+      "file": "src/index.js",
+      "startLine": 302,
+      "endLine": 353,
+      "problem": "建問題模式的收束邏輯把「挑標籤、建立 issue、發 finding、回貼 PR、設定 issue dependency、決定是否阻擋合併」全部展開在 `main()`。這段和前面的 `createIssueAndFlushBufferedComments` 共同組成一條隱性的 issue workflow，但邊界沒有被封裝；未來要新增 issue 模板、改排序、改阻擋條件或重試策略時，會在主流程裡到處補條件，維護成本會快速上升。",
+      "suggestion": "把建問題模式整理成單一高階函式，例如 `review.publishIssueModeResults({ ctx, gitea, tool, model, cwd, kept, severe, others, bufferedComments })`，主流程只接收 `trackingIssue` / `filesToCommit` 等結果。這樣 PR 模式與 issue 模式的責任邊界會清楚很多。",
+      "suggestedCode": "",
+      "id": "F007",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。此條與 F006 及歷史 findings 同樣指向建問題模式在 main() 中承擔 issue workflow、發布分流與狀態管理，屬同一維護性問題的延伸描述。"
+        }
+      }
+    },
+    {
+      "reviewer": "Leo",
+      "focus": "maintainability",
+      "badge": "🧰",
+      "severity": "建議",
+      "file": "readme.md",
+      "startLine": 56,
+      "endLine": 132,
+      "problem": "README 內大量維護到原始碼行號的連結，這次 diff 只是分支與行號位移就需要同步改一整片表格。這種文件和程式碼行號的硬耦合很容易在後續修改時過期，讀者點到錯誤位置，維護者也要花時間做機械式同步。",
+      "suggestion": "若這份表格是 API 索引，建議改成自動產生，或至少移除 `#Lxx` 行號錨點，改連到檔案或穩定章節錨點。讓文件描述 API，而不是跟著每次程式碼行號漂移。",
+      "suggestedCode": "",
+      "id": "F008",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已多次指出 README 功能表硬編分支與行號連結，導致文件與原始碼高度耦合且容易失準。"
+        }
+      }
+    },
+    {
+      "reviewer": "Mage",
+      "focus": "logic",
+      "badge": "🔮",
+      "severity": "警告",
+      "file": "src/index.js",
+      "startLine": 251,
+      "endLine": 253,
+      "problem": "無可審查變更的分支在一般模式下會先把舊留言標為過時，之後才保存 findings 與 commit/push 結果。最小重現：`files.length === 0`、`nothingToReviewComment` 成功、`resolveOldComments` 成功，但接著 `saveFindings` 因檔案系統錯誤或 `commitFindings` 因 push 失敗拋例外。此時舊審查結果已被標過時，但沒有成功落地本回合的 success 結果 commit，狀態會停在半更新。",
+      "suggestion": "把 `review.resolveOldComments` 延後到 `saveFindings` 與必要的 `commitFindings` 成功之後；或至少在空變更路徑也遵守同一個交易順序：先產生並提交本回合結果，再清理舊留言。",
+      "suggestedCode": "",
+      "id": "F010",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（命中已知排除事項）。維護者已裁示舊留言應刻意在本回合結果發布前標為過時；本條要求延後清理，落在同一已排除範圍。"
+        }
+      }
+    },
+    {
+      "reviewer": "Maya",
+      "focus": "testing",
+      "badge": "🧪",
+      "severity": "警告",
+      "file": "src/index.js",
+      "startLine": 160,
+      "endLine": 353,
+      "problem": "建問題模式的主流程被大幅改寫，但目前測試只驗證了少數 helper，沒有驗證「留言先暫存、確定有 kept finding 才建 issue、無保留問題時靜默通過、嚴重問題才加 issue dependency、最後回貼 PR 連結」這些新增流程。這些行為一旦順序或條件寫錯，測試不會擋下來。",
+      "suggestion": "請補 `main()` 層級的流程測試，stub `agents`、`review`、`gitea`、`gitrepo`，至少覆蓋：`createIssue=true && kept=[]` 不建立 issue/不貼 PR 留言；`kept` 只有警告/建議時建立 issue、flush 暫存留言、回貼 PR 連結但不呼叫 `addIssueDependency`；`kept` 含嚴重時呼叫 `addIssueDependency`，且 dependency 失敗時流程仍完成並 commit failure findings。",
+      "suggestedCode": "",
+      "id": "F011",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已涵蓋建問題模式 main() 層級流程缺測試，包括暫存留言、有 finding 才建 issue、無 finding 靜默、PR 回貼、嚴重與非嚴重分流及 dependency 失敗降級。"
+        }
+      }
+    },
+    {
+      "reviewer": "Maya",
+      "focus": "testing",
+      "badge": "🧪",
+      "severity": "警告",
+      "file": "src/lib/gitrepo.js",
+      "startLine": 307,
+      "endLine": 361,
+      "problem": "`pushWithCredential` 新增了關鍵認證行為，但沒有測試驗證它真的用 `GIT_CONFIG_*` 清掉 checkout 的 extraheader、再注入 PAT Authorization，也沒有測試遠端 URL 不符與 push 失敗時不洩漏 URL/token 的失敗路徑。這段是結果 commit 能否觸發下一輪 CI 的核心，沒有測試等於這個新契約還沒通過試煉。",
+      "suggestion": "請補推送行為測試。可用可注入的 exec wrapper 或子程序測試方式驗證：`git push` argv 不含 token、env 包含兩筆同 scope extraheader、`GIT_CONFIG_VALUE_0` 為空值、`GIT_CONFIG_VALUE_1` 為 Basic header；再補 `remote.origin !== server.origin` 與 exec 失敗時錯誤訊息不含 token/remoteUrl 的案例。",
+      "suggestedCode": "",
+      "id": "F012",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已記錄 pushWithCredential／pushToken 認證推送路徑缺少測試，包含 token 不進 argv、認證遮蔽、推送目標與失敗訊息不洩漏敏感資訊。"
+        }
+      }
+    },
+    {
+      "reviewer": "Maya",
+      "focus": "testing",
+      "badge": "🧪",
+      "severity": "警告",
+      "file": "src/lib/gitrepo.js",
+      "startLine": 130,
+      "endLine": 192,
+      "problem": "`resolveMergeBase` 新增多段 fetch fallback：先抓 base、再 deepen base、deepen PR HEAD、最後 shallow repo 才 unshallow，但現有測試只驗證不安全 baseRef 會被拒絕，沒有驗證淺層歷史補抓順序、每次 fetch 後會重試 merge-base、成功後會短路，也沒有覆蓋所有策略失敗時的診斷錯誤。",
+      "suggestion": "請補針對 `resolveMergeBase` 的失敗與邊界測試。建議把 git 執行函式抽成可替換依賴，或用臨時 git repo 模擬 shallow 狀態，斷言：首次 merge-base 成功不走 fallback；deepen base 成功後立即回傳；deepen PR HEAD 使用目前 HEAD SHA 而不是遠端 `HEAD`；非 shallow repo 不呼叫 `--unshallow`；全部失敗時錯誤包含策略診斷。",
+      "suggestedCode": "",
+      "id": "F013",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已針對 resolveMergeBase 多階段 fetch、淺層與非淺層分支、成功短路、降級順序與最終失敗診斷缺測試提出相同問題。"
+        }
+      }
+    },
+    {
+      "reviewer": "Maya",
+      "focus": "testing",
+      "badge": "🧪",
+      "severity": "建議",
+      "file": "src/lib/diagnostics.js",
+      "startLine": 18,
+      "endLine": 69,
+      "problem": "`redactSecrets` 與 `agentFailureDetail` 是新加入的安全診斷防線，但測試只覆蓋 Authorization/token 的基本遮罩。控制字元單行化、URL 內嵌帳密、長 token/hex、輸入與輸出長度截斷、以及沒有 error code 時的 fallback 訊息都還沒被驗證。",
+      "suggestion": "請補診斷邊界測試，至少包含：含換行與 tab 的輸出不會產生多行 log；`https://user:pass@host` 會被遮罩；40 字元以上 token 會被遮罩；debug 模式下 stderr/stdout 只輸出到限制長度；沒有 `error.code`、`signal`、`stderr/stdout` 時仍回傳安全的 fallback 訊息。",
+      "suggestedCode": "",
+      "id": "F014",
+      "verdicts": {
+        "Paladin": {
+          "exclude": true,
+          "reason": "可排除（重複）。歷史 findings 已涵蓋 redactSecrets／agentFailureDetail 對控制字元、URL 帳密、token 格式、截斷與 fallback 診斷等邊界缺少測試。"
+        }
+      }
+    }
+  ]
+}
@@ -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 涵蓋。"
+        }
+      }
+    }
+  ]
+}
@@ -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 工具使用的模型名稱。
@@ -72,7 +72,7 @@ function saveFindings({ cwd, ctx, tool, kept, excluded }) {
 * 供下一回合 `main()` 步驟 1 比對辨識、直接回報結果而不重複審查。
 * 依 `commitAndPushFindings` 的回傳值記錄不同日誌：true＝已 commit/push；
 * false＝檔案無實際變更（空 commit 防護），記「略過 commit/push」。
- * commit/push 失敗（例如與開發者新 commit 競態）時僅記 WRN log，不拋出例外、不改變審查結果。
+ * commit/push 失敗（例如與開發者新 commit 競態）時僅記 WRN log，不拋出例外；呼叫端可依回傳值決定是否阻擋。
 *
 * @param {Object} params - 解構參數。
 * @param {string} params.cwd - repo 根目錄（workspace）絕對路徑，git 操作在此目錄執行。
@@ -84,7 +84,7 @@ function saveFindings({ cwd, ctx, tool, kept, excluded }) {
 * @param {string} params.ctx.repository - `owner/repo` 形式的 repo 名稱。
 * @param {string[]} params.files - 要 commit 的檔案 repo 相對路徑陣列（如 findings 檔、`.gitea/ai-review/exclusions.json`）；全數無變更時只記 INF 略過。
 * @param {'success'|'failure'} params.result - 本回合審查結果：success＝無嚴重問題、failure＝有嚴重問題；會拼進 commit 訊息尾端。
- * @returns {void} 無回傳值；成敗僅反映在 log 上。
+ * @returns {boolean} true＝已 commit/push；false＝無變更或 commit/push 失敗。
 * @remarks
 * 使用情境：`main()` 於流程尾端依 `severe.length === 0 ? 'success' : 'failure'` 決定 result、
 * 依模式組出 filesToCommit（一般模式：findings 檔＋有變更時的 exclusions.json；
@@ -107,12 +107,15 @@ function commitFindings({ cwd, ctx, files, result }) {
    });
    if (committed) {
      log('收尾', 'INF', `審查結果檔已 commit 並 push 回 ${ctx.headRef}（結果：${result}）。`);
+      return true;
    } else {
      log('收尾', 'INF', '審查結果檔無實際變更，略過 commit/push。');
+      return false;
    }
  } catch (err) {
-    // push 失敗（例如與開發者新 commit 競態）時只記錄，不改變審查結果。
+    // push 失敗（例如與開發者新 commit 競態）時只記錄，交由呼叫端依嚴重度決定是否阻擋。
    log('收尾', 'WRN', `commit/push 審查結果檔失敗：${err.message}。`);
+    return false;
  }
 }

@@ -165,6 +168,7 @@ async function main() {
  // 建問題模式：追蹤 issue 於「確定有保留問題」後才建立；在那之前的情境留言（工具／diff／角色）
  // 先暫存於 pendingIssueCommentBodies，建立 issue 後一次寫入。
  const pendingIssueCommentBodies = [];
+  let issueModeActive = ctx.createIssue;
  let trackingIssue = null;
  /**
   * 發布一則審查留言。依模式決定去向：
@@ -179,7 +183,7 @@ async function main() {
   * 警告／建議彙整等留言。若 Gitea API 失敗，例外會往上拋出並由主流程頂層 catch 收斂。
   */
  const queueOrPostComment = async (body) => {
-    if (ctx.createIssue) {
+    if (issueModeActive) {
      if (trackingIssue) return gitea.createCommentOnIssue(ctx, trackingIssue.number, body);
      pendingIssueCommentBodies.push(body);
      return null;
@@ -210,13 +214,27 @@ async function main() {
    }
    pendingIssueCommentBodies.length = 0;
  };
+  /**
+   * 建問題模式降級：追蹤 issue 無法建立或寫入時，改把已暫存的情境留言發回 PR，後續沿用一般模式。
+   *
+   * @returns {Promise<void>} 無回傳值；會關閉建問題模式並把 PR 留言 id 登錄到 `currentRunCommentIds`。
+   */
+  const fallbackToPrComments = async () => {
+    issueModeActive = false;
+    trackingIssue = null;
+    for (const body of pendingIssueCommentBodies) {
+      const created = await gitea.createIssueComment(ctx, body);
+      currentRunCommentIds.add(created.id);
+    }
+    pendingIssueCommentBodies.length = 0;
+  };

  // ── 步驟 2：延後執行 ───────────────────────────────────────────────────
  // 「將 PR 既有留言標記為解決」原本在此執行，但若工具偵測／diff／攻防裁決任一失敗，
  // 舊結果會先被清掉卻沒有新結果。故延後到「本回合審查已成功產生結果、發布問題留言前」
  // 才呼叫 review.resolveOldComments（見下方步驟 4 空變更路徑與步驟 9 前）；
  // 屆時本回合的工具／diff／角色留言已登錄於 currentRunCommentIds，不會被誤標為過時。
-  // 建問題模式全程不觸碰 PR 既有留言（審查內容改發到 issue）。
+  // 建問題模式不清理 PR 既有審查內容，只在收束時標記舊追蹤 issue 連結。

  // ── 步驟 3：偵測 AI agent 工具並留言 ──────────────────────────────────
  const tool = agents.detectTool();
@@ -248,7 +266,7 @@ async function main() {
  if (files.length === 0) {
    // 沒有可審查的變更：保存空 findings、以 success 收場。
    // 一般模式在 PR 留言告知；建問題模式靜默通過（不建 issue、PR 也不留言，暫存的情境留言捨棄）。
-    if (ctx.createIssue) {
+    if (issueModeActive) {
      log('步驟4', 'INF', '建問題模式且無可審查變更：靜默通過（不建 issue、PR 不留言）。');
    } else {
      await queueOrPostComment(templates.nothingToReviewComment(ignoredCount));
@@ -256,7 +274,7 @@ async function main() {
      await review.resolveOldComments({ ctx, gitea, currentRunCommentIds });
    }
    const relativePath = saveFindings({ cwd, ctx, tool, kept: [], excluded: [] });
-    if (ctx.createIssue) {
+    if (issueModeActive) {
      // 建問題模式下 findings 不進版控，且 exclusions.json 無變更 → 沒東西可提交。
      log('收尾', 'INF', '建問題模式且無可審查變更，略過 commit/push。');
    } else {
@@ -299,7 +317,7 @@ async function main() {

  // ── 建問題模式：確定有保留問題才建立 issue，並把暫存的情境留言一次寫入；
  //    無保留問題則不建 issue、PR 也完全不留言（靜默通過，暫存的情境留言捨棄）。 ──────
-  if (ctx.createIssue) {
+  if (issueModeActive) {
    if (kept.length > 0) {
      // 先依保留問題挑好標籤，於建立 issue 時一次帶入（省去「先建空標籤 issue 再補掛」的多餘 API 往返）；
      // 標籤挑選失敗一律降級為不掛標籤，不阻斷建 issue 流程。
@@ -318,7 +336,12 @@ async function main() {
      } catch (err) {
        log('建問題', 'WRN', `標籤挑選失敗（${err.message}），issue 不掛標籤。`);
      }
+      try {
        await createIssueAndFlushBufferedComments(labelIds);
+      } catch (err) {
+        log('建問題', 'WRN', `建立或寫入追蹤 issue 失敗（${err.message}），改用 PR 留言與 findings 檔流程。`);
+        await fallbackToPrComments();
+      }
    } else {
      // 無保留問題 → 不建 issue、PR 也不留言（靜默通過，暫存的情境留言捨棄）。
      log('建問題', 'INF', '沒有保留的問題：靜默通過（不建 issue、PR 不留言）。');
@@ -329,13 +352,13 @@ async function main() {
  //    延後到此可避免工具偵測／diff／攻防裁決任一失敗時舊結果先被清掉卻無新結果；
  //    本回合的工具／diff／角色留言已登錄於 currentRunCommentIds，不會被誤標為過時；
  //    嚴重／其他問題留言於本步驟之後才發布，同樣不受影響。
-  if (!ctx.createIssue) {
+  if (!issueModeActive) {
    await review.resolveOldComments({ ctx, gitea, currentRunCommentIds });
  }

  // ── 步驟 9：嚴重問題留言（一般模式掛在 PR 程式碼行上；建問題模式逐條發到 issue）─
  if (severe.length > 0) {
-    if (ctx.createIssue) {
+    if (issueModeActive && trackingIssue) {
      await review.postSevereToIssue({ ctx, gitea, issueNumber: trackingIssue.number, severe });
    } else {
      await review.postSevereComments({ ctx, gitea, severe, cwd });
@@ -345,7 +368,7 @@ async function main() {
  // ── 步驟 10：警告＋建議——一般模式彙整為單一表格留言到 PR；
  //    建問題模式逐條發到 issue，讓每條問題都能被個別回覆。 ──
  if (others.length > 0) {
-    if (ctx.createIssue) {
+    if (issueModeActive && trackingIssue) {
      await review.postOthersToIssue({ ctx, gitea, issueNumber: trackingIssue.number, others });
    } else {
      await queueOrPostComment(templates.othersComment(others));
@@ -355,7 +378,8 @@ async function main() {

  // ── 建問題模式收束：在 PR 回貼 issue 連結（雙向關聯）；僅在有嚴重問題時才讓 PR 相依於該 issue ─
  //    標籤已於建立 issue 時一次帶入（見上方 selectLabels → createIssueAndFlushBufferedComments），此處不再補掛。
-  if (ctx.createIssue && trackingIssue) {
+  if (issueModeActive && trackingIssue) {
+    await review.resolveOldIssueLinkComments({ ctx, gitea });
    await gitea.createIssueComment(
      ctx,
      templates.prIssueLinkComment({
@@ -385,13 +409,14 @@ async function main() {
  // 若有嚴重問題，仍 commit findings 檔產生 [failure] 結果 commit，避免相依 API 不支援時 fail-open。
  const result = severe.length === 0 ? 'success' : 'failure';
  const filesToCommit = review.resultFilesToCommit({
-    createIssue: ctx.createIssue,
+    createIssue: issueModeActive,
    severeCount: severe.length,
    relativePath,
    exclusionsChanged,
  });
+  let resultCommitted = false;
  if (filesToCommit.length > 0) {
-    commitFindings({ cwd, ctx, files: filesToCommit, result });
+    resultCommitted = commitFindings({ cwd, ctx, files: filesToCommit, result });
  } else {
    log('收尾', 'INF', '建問題模式且 exclusions.json 無變更，略過 commit/push。');
  }
@@ -399,6 +424,10 @@ async function main() {
  // 由它再觸發的下一輪在步驟 1 讀 commit 訊息時才回報失敗（exit 1）。如此失敗檢查落在帶有結果
  // 標記的最新 head 上，與合併判定一致。（result 僅用於上方 commit 訊息的結果標記。）
  if (result === 'failure') {
+    if (!resultCommitted) {
+      log('收尾', 'ERR', '本輪有嚴重問題，但未成功產生 [failure] 結果 commit；直接回報失敗避免 fail-open。');
+      return 1;
+    }
    log('收尾', 'INF', '本輪有嚴重問題：已標記結果 commit 為 [failure]，失敗檢查由下一輪步驟 1 讀 commit 訊息回報。');
  }
  return 0;
@@ -29,6 +29,19 @@ function redactSecrets(text) {
    .trim();
 }

+/**
+ * 將 AI CLI 失敗輸出整理成單行、遮罩且限長的診斷片段。
+ *
+ * @param {string[]} parts - 要附加診斷片段的陣列。
+ * @param {string} label - 診斷欄位名稱（如 stderr／stdout）。
+ * @param {*} value - 原始診斷輸出。
+ * @returns {void}
+ */
+function appendRedactedOutput(parts, label, value) {
+  const redacted = redactSecrets(String(value || '').slice(0, AGENT_DIAGNOSTIC_INPUT_LIMIT));
+  if (redacted) parts.push(`${label}：${redacted.slice(0, AGENT_DIAGNOSTIC_OUTPUT_LIMIT)}`);
+}
+
 /**
 * 從 `runAgent` 的失敗結果組出可診斷的一行摘要：退出碼／訊號為主，原始輸出預設隱藏。
 *
@@ -52,10 +65,8 @@ function agentFailureDetail(agentResult) {
  }
  // 失敗輸出可能含 token 或 PII，預設不寫入長期 CI log；debug 模式才輸出遮罩後片段。
  if (process.env.ACTIONS_STEP_DEBUG === 'true') {
-    const stderr = redactSecrets(String((agentResult && agentResult.stderr) || '').slice(0, AGENT_DIAGNOSTIC_INPUT_LIMIT));
-    if (stderr) parts.push(`stderr：${stderr.slice(0, AGENT_DIAGNOSTIC_OUTPUT_LIMIT)}`);
-    const stdout = redactSecrets(String((agentResult && agentResult.output) || '').slice(0, AGENT_DIAGNOSTIC_INPUT_LIMIT));
-    if (stdout) parts.push(`stdout：${stdout.slice(0, AGENT_DIAGNOSTIC_OUTPUT_LIMIT)}`);
+    appendRedactedOutput(parts, 'stderr', agentResult && agentResult.stderr);
+    appendRedactedOutput(parts, 'stdout', agentResult && agentResult.output);
  }
  if (parts.length === 0) {
    parts.push((err && err.message && redactSecrets(err.message)) || 'AI CLI 執行失敗（無診斷輸出）');
@@ -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,
+};
@@ -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 輸出。
 *
@@ -300,8 +273,7 @@ function commitAndPushFindings(cwd, { headRef, headSha, message, files, token, s
  );
  const refspec = `HEAD:refs/heads/${headRef}`;
  const remoteUrl = `${serverUrl}/${repository}.git`;
-  // 一律以 token 的身分明確認證推送（不走 origin 的自動 token）——只要 token 是能觸發 CI 的 PAT，
-  // 結果 commit 就會讓 PR 的 synchronize 事件再觸發 CI，由步驟 1 快速回報把結果蓋到新 head。
+  // 一律以 token 的身分明確認證推送，不沿用 origin 的自動 token。
  pushWithCredential(cwd, remoteUrl, token, refspec, serverUrl);
  return true;
 }
@@ -309,18 +281,9 @@ function commitAndPushFindings(cwd, { headRef, headSha, message, files, token, s
 /**
 * 以帶認證的方式推送到指定遠端，認證資訊只經環境變數傳入、不進命令列 argv。
 *
- * 認證方式：等同 `https://ai-review-bot:<secret>@host/...` 的 HTTP Basic（git 會把
- * URL 帳密轉成相同的 `Authorization: Basic` 標頭送出），但改以 git 的
- * `GIT_CONFIG_*` 環境變數注入 `http.<serverUrl>/.extraheader`，使 base64 憑證**不出現在 argv**
- * （避免程序清單／例外回顯洩漏）；推送目標 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），改拋固定訊息。
+ * 以 `GIT_CONFIG_*` 注入本次 HTTP Basic extraheader，避免憑證出現在 argv；
+ * 同時先清空 checkout 持久化的自動 token extraheader，確保本次 push 使用呼叫端 token。
+ * 推送失敗時改拋固定訊息，避免原始例外帶出遠端 URL 或認證資訊。
 *
 * @param {string} cwd - git 工作目錄（repo 的 checkout 路徑）。
 * @param {string} remoteUrl - 不含帳密的遠端 URL（形如 `https://host/owner/repo.git`）。
@@ -348,7 +311,7 @@ function pushWithCredential(cwd, remoteUrl, token, refspec, serverUrl) {
      env: {
        ...process.env,
        GIT_TERMINAL_PROMPT: '0',
-        // 兩筆同 scope 設定：先空值清掉 checkout 的自動 token，再注入 PAT 的 Authorization。
+        // 先清空 checkout extraheader，再注入本次 PAT header。
        GIT_CONFIG_COUNT: '2',
        GIT_CONFIG_KEY_0: headerScope,
        GIT_CONFIG_VALUE_0: '',
@@ -368,7 +331,4 @@ module.exports = {
  fileDiff,
  fileLastUpdatedIso,
  commitAndPushFindings,
-  __test: {
-    assertSafeBranchRef,
-  },
 };
@@ -832,6 +832,40 @@ async function resolveOldComments({ ctx, gitea, currentRunCommentIds }) {
  }
 }

+/**
+ * 建問題模式：只將 PR 上舊的「追蹤問題連結」留言標註為過時，不觸碰 issue 內審查內容。
+ *
+ * @param {Object} params - 解構參數。
+ * @param {Object} params.ctx - 執行環境 context（`loadContext()` 產出）。
+ * @param {Object} params.gitea - Gitea API 模組，需提供 `whoAmI`、`listIssueComments`、`editIssueComment`。
+ * @returns {Promise<void>} 無回傳值；失敗時只記 WRN，不阻斷主流程。
+ */
+async function resolveOldIssueLinkComments({ ctx, gitea }) {
+  let botLogin = '';
+  try {
+    botLogin = (await gitea.whoAmI(ctx)).login || '';
+  } catch (err) {
+    log('建問題', 'WRN', `無法取得 bot 身分（${err.message}），略過舊追蹤連結標註。`);
+    return;
+  }
+
+  try {
+    const comments = await gitea.listIssueComments(ctx);
+    let outdatedCount = 0;
+    for (const comment of comments) {
+      const isBot = comment.user && comment.user.login === botLogin;
+      const body = typeof comment.body === 'string' ? comment.body : '';
+      const isIssueLink = body.includes(templates.MARK) && body.includes('## 🔍 AI Code Review｜已建立追蹤問題');
+      if (!isBot || !isIssueLink || body.startsWith(templates.OUTDATED_PREFIX)) continue;
+      await gitea.editIssueComment(ctx, comment.id, `${templates.OUTDATED_PREFIX}${body}`);
+      outdatedCount += 1;
+    }
+    log('建問題', 'INF', `舊追蹤 issue 連結已標註〔已過時〕：${outdatedCount} 則。`);
+  } catch (err) {
+    log('建問題', 'WRN', `標註舊追蹤 issue 連結失敗：${err.message}。`);
+  }
+}
+
 /**
 * 步驟 9：嚴重問題逐條掛在 PR 程式碼行上留言（建立 code review）；
 * 建立 review 失敗時降級為一般留言逐條發布（留言內補上檔案與行號位置）。
@@ -884,5 +918,6 @@ module.exports = {
  postSevereToIssue,
  postOthersToIssue,
  resolveOldComments,
+  resolveOldIssueLinkComments,
  postSevereComments,
 };
@@ -4,14 +4,15 @@ 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'),
    /不是安全的分支名稱/,
  );
 });
@@ -97,3 +97,40 @@ test('resultFilesToCommit 在建問題模式無嚴重問題時只提交 exclusio
    ['.gitea/ai-review/exclusions.json'],
  );
 });
+
+test('resolveOldIssueLinkComments 只標註舊追蹤 issue 連結', async () => {
+  const edited = [];
+  const fakeGitea = {
+    async whoAmI() {
+      return { login: 'bot' };
+    },
+    async listIssueComments() {
+      return [
+        {
+          id: 1,
+          user: { login: 'bot' },
+          body: '<!-- ai-code-review -->\n## 🔍 AI Code Review｜已建立追蹤問題\nold',
+        },
+        {
+          id: 2,
+          user: { login: 'bot' },
+          body: '<!-- ai-code-review -->\n## 📋 變更摘要（送審 git diff）\nkeep',
+        },
+        {
+          id: 3,
+          user: { login: 'someone' },
+          body: '<!-- ai-code-review -->\n## 🔍 AI Code Review｜已建立追蹤問題\nkeep',
+        },
+      ];
+    },
+    async editIssueComment(ctx, commentId, body) {
+      edited.push({ ctx, commentId, body });
+    },
+  };
+
+  await review.resolveOldIssueLinkComments({ ctx: { token: 'hidden' }, gitea: fakeGitea });
+
+  assert.equal(edited.length, 1);
+  assert.equal(edited[0].commentId, 1);
+  assert.match(edited[0].body, /^> 〔已過時〕/);
+});
Author	SHA1	Message	Date
Jeffery	43ad2b56d2	chore(ai-review 狀態): 回寫本輪 findings 與排除事項 node-actions/template: CI / BUILD (pull_request) Successful in 4s Details CI / TEST (Claude) (pull_request) Successful in 33s Details CI / TEST (Antigravity) (pull_request) Successful in 49s Details CI / TEST (Codex) (pull_request) Successful in 3m38s Details	2026-07-21 16:26:30 +08:00
Jeffery	8e18bbacc2	style(action manifest): 統一中文斜線標點	2026-07-21 16:26:30 +08:00
Jeffery	1f012c6cfb	refactor(gitref): 將分支名稱驗證改為正式模組	2026-07-21 16:26:30 +08:00
ai-review-bot	76617dd9dc	chore: update ai-review findings [ai-review-bot][failure] node-actions/template: CI / BUILD (pull_request) Successful in 5s Details CI / TEST (Codex) (pull_request) Failing after 25s Details CI / TEST (Claude) (pull_request) Failing after 27s Details CI / TEST (Antigravity) (pull_request) Failing after 35s Details	2026-07-21 08:00:35 +00:00
Jeffery	216bc39255	chore(ai-review 狀態): 回寫本輪已處理 findings node-actions/template: CI / BUILD (pull_request) Successful in 4s Details CI / TEST (Claude) (pull_request) Successful in 26s Details CI / TEST (Antigravity) (pull_request) Successful in 49s Details CI / TEST (Codex) (pull_request) Successful in 2m34s Details	2026-07-21 15:57:53 +08:00
Jeffery	75ca8cdb83	refactor(ai-review 診斷): 收斂失敗輸出處理與推送註解	2026-07-21 15:57:53 +08:00
Jeffery	aaf2e484d5	fix(ai-review): 避免建問題模式阻擋失效與連結累積	2026-07-21 15:57:53 +08:00
ai-review-bot	55da29a86f	chore: update ai-review findings [ai-review-bot][failure] CI / TEST (Claude) (pull_request) Failing after 22s Details CI / TEST (Codex) (pull_request) Failing after 26s Details CI / TEST (Antigravity) (pull_request) Failing after 33s Details node-actions/template: CI / BUILD (pull_request) Successful in 4s Details	2026-07-21 06:42:40 +00:00