review/references/behaviors.md

jsc-review 技能行為清單

本頁記錄 jsc-review 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。

api-doc

項目	內容
觸發時機	控制器改完之後叫用，或工作包實作完成之後叫用。jsc-sdlc:implement 在收尾時與 jsc-review:code-review 並排叫用它。專案沒有啟用 Swagger 就不跑，這一點由步驟 1 的腳本判定，不由人判斷。原始碼註解合約歸 jsc-review:code-review 第 5 組，這支技能只看 Swagger 文件屬性。資安、邏輯錯誤、測試涵蓋率歸 CLI 內建審查。
關鍵步驟	跑 tools/swagger-detect.sh 偵測 Swagger 套件與掛載，讀退出碼 0、1、2 分流、退出碼 1 回報「本專案未啟用 Swagger 文件，略過 API 文件稽核」並停止、退出碼 2 照三種原因回報並停止、列出稽核範圍（全專案控制器，或 git diff 指定的變更控制器）、git diff 失敗就原文回報 git 的 stderr 並停止、開兩個 sub agent 平行稽核兩個面向（面向 1 狀態碼與回應型別宣告、面向 2 描述與範例並遞迴走訪資料模型）、每個面向回傳六欄 TSV 或「無發現」、把兩個面向的 TSV 依序餵給 tools/merge-findings.sh 合併、依退出碼 0、1、2、3 分流、繁體中文逐列回報、跑 jsc-hooks/hooks/write-guard.sh release 解鎖。
外部呼叫	tools/swagger-detect.sh、tools/merge-findings.sh、jsc-hooks/hooks/write-guard.sh（review 模式擋寫入工具、release 模式解鎖）、git diff、references/smells.md 的嚴重度分級、2 個稽核 sub agent。沒有 Gitea API 呼叫。
完成條件	偵測結果、範圍清單、兩個面向的回傳、合併結果四段都有結論。合併清單每個位置只出現一次，或整輪以「無發現」收尾，或以腳本錯誤收尾。報告交給呼叫方，release 指令已經執行，報告內說明 JSC_WRITE_GUARD_TTL 逾時解鎖與 JSC_WRITE_GUARD=off 兩條退路，修不修由呼叫方決定。
可驗證跡象	不改任何程式碼。唯一的環境寫入是解鎖：$JSC_HOME/sessions/{sid}.lastskill 被清掉，可以直接檢查該檔是否還在。舊版 jsc-hooks 不認得 release，該檔會留到逾時，這也是可檢查的狀態。除此之外沒有寫入跡象，只有回報內容。

code-review

項目	內容
觸發時機	一個檔案或一組相關檔案改完之後叫用，或工作包的所有待辦做完之後叫用。jsc-sdlc:implement 在工作包最後一項待辦之後、提交與開 PR 之前叫用它。資安、邏輯錯誤、測試涵蓋率不在範圍內，那些歸 CLI 內建審查。Swagger 文件稽核歸 jsc-review:api-doc，兩支技能不重複回報同一個缺口。
關鍵步驟	用一道指令把 git diff（未提交變更）或 git diff {base}...HEAD（比對基底分支）導進 ${TMPDIR:-/tmp}/jsc-code-review.$$.diff 快照檔並印出展開後的路徑、git 非零退出碼就原文回報 stderr 並停止、快照檔空的就刪檔並回報「無發現」、開六個 sub agent 平行審查六組氣味（1 膨脹、2 晦澀、3 耦合、4 冗贅與其他、5 註解合約、6 淺模組）、六組都只讀步驟 1 的同一份快照、每組回傳六欄 TSV 或「無發現」、六組全數回傳後才把 TSV 依組序餵給 tools/merge-findings.sh、依退出碼 0、1、2、3 分流、繁體中文逐列回報、刪掉快照檔、跑 jsc-hooks/hooks/write-guard.sh release 解鎖。
外部呼叫	git diff、tools/merge-findings.sh、jsc-hooks/hooks/write-guard.sh（review 模式擋寫入工具、release 模式解鎖）、references/smells.md、references/comment-scope.md（第 2 組的禁列與允列來源）、6 個審查 sub agent。沒有 Gitea API 呼叫。
完成條件	六組全部回傳，合併清單每個位置只出現一次，或整輪以「無發現」收尾，或以 git 或腳本的錯誤收尾。報告交給呼叫方，快照檔已刪除，release 指令已經執行，報告內說明 JSC_WRITE_GUARD_TTL 逾時解鎖與 JSC_WRITE_GUARD=off 兩條退路。修不修由呼叫方決定，實作流程內高與中通常必修，低看情況。
可驗證跡象	不改任何程式碼。過程中產生 ${TMPDIR:-/tmp}/jsc-code-review.$$.diff 快照檔，收尾時刪除，跑完該檔不應該還在，殘留就代表沒收尾。解鎖後 $JSC_HOME/sessions/{sid}.lastskill 被清掉，可直接檢查。除這兩個檔案狀態外沒有寫入跡象，只有回報內容。

comment-cleanup

項目	內容
觸發時機	使用者要求清註解、移除審查痕跡、不要留審查產物時叫用。提交前 jsc-hooks 回報註解範圍警告時叫用，或變更的註解明顯帶著流程細節時叫用。預設只處理這次變更碰到的註解，使用者明講要清舊註解才擴大範圍。
關鍵步驟	在待清的儲存庫內跑 tools/changed-comments.sh 取得範圍（不帶參數看未提交變更，帶 {base} 比對基底分支）、依退出碼 0、1、2 分流、退出碼 1 回報「無發現」並停止、退出碼 2 原文回報 stderr 並停止且不手讀 diff 代替、一個檔案開一個 sub agent 平行改寫、每個 sub agent 拿到自己的檔案路徑與該檔的註解列並比對 references/comment-scope.md、移除流程細節並保留程式碼存在的理由、只剩流程細節的註解整段刪除、每個 sub agent 回傳前重讀自己改過的區域確認句子完整且沒有殘句、只改註解與文件字串不動行為、全部 sub agent 回傳後跑一次最小的建置或測試指令、失敗就判斷是否本輪造成並依規則重跑一次或還原、依類別回報清理結果。
外部呼叫	tools/changed-comments.sh、references/comment-scope.md、專案自己的建置或測試指令（沒有就改跑受影響腳本的語法檢查）、git diff、每個檔案一個改寫 sub agent。這支技能不呼叫 jsc-hooks/hooks/write-guard.sh，也不在它的 review 模式擋下範圍內：那支腳本的檔頭寫明 comment-cleanup 一律放行，因為精確判定註解列要解析整份新內容再逐語言判斷，判錯會擋掉合法清理。寫入範圍改由步驟 4 與後續審查把關。沒有 Gitea API 呼叫。
完成條件	範圍內每一列註解都有結果：維持原樣並說明理由、改寫、或刪除。每個 sub agent 都確認過自己的檔案且沒有未解決的殘句。git diff 只顯示註解與文件字串的變更。驗證指令退出碼 0，或報告寫明指令、退出碼與失敗歸屬，或寫明缺哪一個指令。報告說明移除了哪些類別、動了哪些檔案、驗證有沒有過。
可驗證跡象	這是三支技能裡唯一會改檔的。跑完在工作區留下實際的檔案修改，git diff 看得到被清理的註解列，且變更只涵蓋註解與文件字串，不涉及識別字、控制流程、資料結構。還原情境下 git diff 會看到該檔的本輪修改被撤回。不寫 wiki 頁、不開 PR、不改狀態檔。