docs(ai-code-review): 補齊各模組 JSDoc、指令檔逐行註解並重建 README

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/main.js

@@ -13,6 +13,44 @@ import { section, step, line, input, output, result, warn, error } from './log.j
 
 const WORKSPACE = process.env.GITHUB_WORKSPACE || '/workspace';
 
+/**
+ * AI Code Review Pipeline 的總指揮（orchestrator）。
+ *
+ * 依序串接 Step1~Step11：啟動參數讀取、前置驗證、自動提交檢查、PR 對話收斂、
+ * 角色平行分析產生 findings、新舊 findings 合併與語意去重、排除規則與誤報過濾、
+ * 寫入 findings 並發布 Gitea Review、findings/exclusions JSON 格式驗證、
+ * 記憶區 commit/push，以及嚴重問題把關。
+ *
+ * 結果主要透過 `process.exit()` 決定 workflow 成敗，而非以回傳值傳遞。
+ *
+ * @async
+ * @returns {Promise<void>} 流程正常走完（無嚴重問題）時 resolve；多數結束路徑會直接
+ *   呼叫 `process.exit()` 結束程序，函式不會以回傳值回報審查結果。
+ * @throws {Error} 內部未被個別 try/catch 攔截的未預期例外會向上拋出，
+ *   由頂層 `main().catch(...)` 接住並以 `process.exit(1)` 結束。
+ *
+ * @remarks
+ * 流程階段（Step1~Step11）：
+ * - Step1 啟動：讀取 repo / PR / 分支等基本參數。
+ * - Step2 前置驗證：`runPreflight`，未通過則 exit 1。
+ * - Step3 自動提交檢查：偵測上輪 bot `[failure]`（exit 1）或本次為 bot 自動提交（exit 0 跳過）。
+ * - Step4 PR 對話收斂：關閉未解決 comment 並將 finding 分流為已修復 / 誤報 / 仍成立（失敗則降級繼續）。
+ * - Step5 角色分析：載入角色、取 PR diff，平行產生 findings 並補齊缺漏行號；
+ *   未設定 API Key 或取 diff 失敗 exit 1，diff 為空 exit 0。
+ * - Step6 合併去重：舊 findings + 對話收斂結果 + 新 findings → 語意去重並排序。
+ * - Step7 過濾：套用排除規則 + 防守方 AI 誤報裁決。
+ * - Step8 發布：寫入 findings、組裝使用量，發布 Gitea Review（失敗則降級繼續）。
+ * - Step9 JSON 驗證：驗證 findings/exclusions 檔，格式錯誤 exit 1，缺檔則建立空陣列檔。
+ * - Step10 記憶區 commit/push：依是否有 critical 計算 reviewOutcome 後推回來源分支。
+ * - Step11 嚴重問題把關：有 critical 則 exit 1，否則正常結束。
+ *
+ * 退出行為：
+ * - exit 1：前置驗證未過、上輪 bot failure、未設定 LLM Key、取 diff 失敗、JSON 格式錯誤、發現嚴重問題、頂層未預期例外。
+ * - exit 0：本次為 bot 自動提交、diff 為空、正常走完無嚴重問題。
+ *
+ * 降級處理：Step4 對話收斂、Step5 角色介紹 comment 與個別角色分析、Step6 clone repo、
+ * Step8 Review 發布等非致命步驟失敗時，僅 `warn` 後繼續執行。
+ */
 async function main() {
   section('AI Code Review Pipeline');