Merge pull request '釋出：收尾寫一筆執行狀態事件' (#32) from develop into master

Reviewed-on: #32
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>

.agents/plugins/marketplace.json

@@ -13,6 +13,14 @@
       },
       "description": "決策樹問詢與問詢紀錄（QUESTION_* wiki 頁）"
     },
+    {
+      "name": "jsc-assist",
+      "source": {
+        "source": "url",
+        "url": "https://gitea.jsc.idv.tw/plugins/assist.git"
+      },
+      "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_* wiki 頁）"
+    },
     {
       "name": "jsc-cli",
       "source": {

.claude-plugin/marketplace.json

@@ -13,6 +13,14 @@
       },
       "description": "決策樹問詢與問詢紀錄（QUESTION_* wiki 頁）"
     },
+    {
+      "name": "jsc-assist",
+      "source": {
+        "source": "url",
+        "url": "https://gitea.jsc.idv.tw/plugins/assist.git"
+      },
+      "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_* wiki 頁）"
+    },
     {
       "name": "jsc-cli",
       "source": {

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-review",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組",
   "skills": "./skills",
   "author": {

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-review",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組",
   "skills": "./skills",
   "jsc": {

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-review",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組",
   "skills": "./skills/",
   "jsc": {

references/behaviors.md

@@ -7,27 +7,27 @@
 | 項目 | 內容 |
 | --- | --- |
 | 觸發時機 | 控制器改完之後叫用，或工作包實作完成之後叫用。`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` 偵測 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` 解鎖、最後跑 `jsc-hooks/tools/report-status.sh skill-end jsc-review:api-doc {status} {結束碼} {detail}` 記下本輪結果，腳本不在這台機器上就安靜跳過。 |
-| 外部呼叫 | `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 呼叫。 |
+| 外部呼叫 | `tools/swagger-detect.sh`、`tools/merge-findings.sh`、`jsc-hooks/hooks/write-guard.sh`（`review` 模式擋寫入工具、`release` 模式解鎖）、`jsc-hooks/tools/report-status.sh skill-end`（收尾狀態事件）、`git diff`、`references/smells.md` 的嚴重度分級、2 個稽核 sub agent。沒有 Gitea API 呼叫。 |
-| 完成條件 | 偵測結果、範圍清單、兩個面向的回傳、合併結果四段都有結論。合併清單每個位置只出現一次，或整輪以「無發現」收尾，或以腳本錯誤收尾。報告交給呼叫方，`release` 指令已經執行，報告內說明 `JSC_WRITE_GUARD_TTL` 逾時解鎖與 `JSC_WRITE_GUARD=off` 兩條退路，修不修由呼叫方決定。 |
+| 完成條件 | 偵測結果、範圍清單、兩個面向的回傳、合併結果四段都有結論。合併清單每個位置只出現一次，或整輪以「無發現」收尾，或以腳本錯誤收尾。報告交給呼叫方，`release` 指令已經執行，報告內說明 `JSC_WRITE_GUARD_TTL` 逾時解鎖與 `JSC_WRITE_GUARD=off` 兩條退路，修不修由呼叫方決定。收尾一定要寫一筆 `skill-end` 狀態事件：兩個面向都回來且合併清單交出去是 `ok`（`merge-findings.sh` 回 1 的「無發現」也是 `ok`，那是稽核過而沒東西可報），偵測不到 Swagger 而跳過是 `blocked`（偵測腳本回 2、`git diff` 被拒也歸這裡），解鎖沒清掉 `lastskill` 是 `degraded`，`merge-findings.sh` 回 2 或連兩次回 3 是 `failed`，控制器清單是空的、根本沒有可審的變更是 `aborted`。 |
-| 可驗證跡象 | 不改任何程式碼。唯一的環境寫入是解鎖：`$JSC_HOME/sessions/{sid}.lastskill` 被清掉，可以直接檢查該檔是否還在。舊版 `jsc-hooks` 不認得 `release`，該檔會留到逾時，這也是可檢查的狀態。除此之外沒有寫入跡象，只有回報內容。 |
+| 可驗證跡象 | 不改任何程式碼。唯一的環境寫入是解鎖：`$JSC_HOME/sessions/{sid}.lastskill` 被清掉，可以直接檢查該檔是否還在。舊版 `jsc-hooks` 不認得 `release`，該檔會留到逾時，這也是可檢查的狀態。另一個寫入跡象是狀態事件：跑完 `$JSC_HOME/usage/events.jsonl` 會多一筆 `{kind:skill,phase:end}` 事件，`name` 欄是 `jsc-review:api-doc`，`status` 與 `exit` 兩欄對得上上一列講的判準；沒有 Swagger 那一輪看得到 `blocked`，沒有可審變更那一輪看得到 `aborted`，兩者和稽核過而無發現的 `ok` 一眼分得開；`jsc-hooks` 不在這台機器上時沒有這一筆，技能本身照樣跑完。除這兩處外沒有寫入跡象，只有回報內容。 |
 
 ## 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`（未提交變更）或 `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` 解鎖、最後跑 `jsc-hooks/tools/report-status.sh skill-end jsc-review:code-review {status} {結束碼} {detail}` 記下本輪結果，腳本不在這台機器上就安靜跳過。 |
-| 外部呼叫 | `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 diff`、`tools/merge-findings.sh`、`jsc-hooks/hooks/write-guard.sh`（`review` 模式擋寫入工具、`release` 模式解鎖）、`references/smells.md`、`references/comment-scope.md`（第 2 組的禁列與允列來源）、`jsc-hooks/tools/report-status.sh skill-end`（收尾狀態事件）、6 個審查 sub agent。沒有 Gitea API 呼叫。 |
-| 完成條件 | 六組全部回傳，合併清單每個位置只出現一次，或整輪以「無發現」收尾，或以 git 或腳本的錯誤收尾。報告交給呼叫方，快照檔已刪除，`release` 指令已經執行，報告內說明 `JSC_WRITE_GUARD_TTL` 逾時解鎖與 `JSC_WRITE_GUARD=off` 兩條退路。修不修由呼叫方決定，實作流程內高與中通常必修，低看情況。 |
+| 完成條件 | 六組全部回傳，合併清單每個位置只出現一次，或整輪以「無發現」收尾，或以 git 或腳本的錯誤收尾。報告交給呼叫方，快照檔已刪除，`release` 指令已經執行，報告內說明 `JSC_WRITE_GUARD_TTL` 逾時解鎖與 `JSC_WRITE_GUARD=off` 兩條退路。修不修由呼叫方決定，實作流程內高與中通常必修，低看情況。收尾一定要寫一筆 `skill-end` 狀態事件：六組都回來且合併清單交出去是 `ok`（`merge-findings.sh` 回 1 的「無發現」也是 `ok`），`git diff` 被拒、審查範圍根本建不出來是 `blocked`，快照檔沒刪掉或解鎖沒清掉 `lastskill` 是 `degraded`，`merge-findings.sh` 回 2 或連兩次回 3 是 `failed`，快照檔是空的、沒有可審的變更是 `aborted`。 |
-| 可驗證跡象 | 不改任何程式碼。過程中產生 `${TMPDIR:-/tmp}/jsc-code-review.$$.diff` 快照檔，收尾時刪除，跑完該檔不應該還在，殘留就代表沒收尾。解鎖後 `$JSC_HOME/sessions/{sid}.lastskill` 被清掉，可直接檢查。除這兩個檔案狀態外沒有寫入跡象，只有回報內容。 |
+| 可驗證跡象 | 不改任何程式碼。過程中產生 `${TMPDIR:-/tmp}/jsc-code-review.$$.diff` 快照檔，收尾時刪除，跑完該檔不應該還在，殘留就代表沒收尾。解鎖後 `$JSC_HOME/sessions/{sid}.lastskill` 被清掉，可直接檢查。第三個檔案跡象是狀態事件：跑完 `$JSC_HOME/usage/events.jsonl` 會多一筆 `{kind:skill,phase:end}` 事件，`name` 欄是 `jsc-review:code-review`，`status` 與 `exit` 兩欄對得上上一列講的判準；空 diff 那一輪看得到 `aborted`，和六組審完而無發現的 `ok` 一眼分得開；`jsc-hooks` 不在這台機器上時沒有這一筆，技能本身照樣跑完。除這三個檔案狀態外沒有寫入跡象，只有回報內容。 |
 
 ## 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` 取得範圍（不帶參數看未提交變更，帶 `{base}` 比對基底分支）、依退出碼 0、1、2 分流、退出碼 1 回報「無發現」並停止、退出碼 2 原文回報 stderr 並停止且不手讀 diff 代替、一個檔案開一個 sub agent 平行改寫、每個 sub agent 拿到自己的檔案路徑與該檔的註解列並比對 `references/comment-scope.md`、移除流程細節並保留程式碼存在的理由、只剩流程細節的註解整段刪除、每個 sub agent 回傳前重讀自己改過的區域確認句子完整且沒有殘句、只改註解與文件字串不動行為、全部 sub agent 回傳後跑一次最小的建置或測試指令、失敗就判斷是否本輪造成並依規則重跑一次或還原、依類別回報清理結果、最後跑 `jsc-hooks/tools/report-status.sh skill-end jsc-review:comment-cleanup {status} {結束碼} {detail}` 記下本輪結果，腳本不在這台機器上就安靜跳過。 |
-| 外部呼叫 | `tools/changed-comments.sh`、`references/comment-scope.md`、專案自己的建置或測試指令（沒有就改跑受影響腳本的語法檢查）、`git diff`、每個檔案一個改寫 sub agent。這支技能不呼叫 `jsc-hooks/hooks/write-guard.sh`，也不在它的 `review` 模式擋下範圍內：那支腳本的檔頭寫明 comment-cleanup 一律放行，因為精確判定註解列要解析整份新內容再逐語言判斷，判錯會擋掉合法清理。寫入範圍改由步驟 4 與後續審查把關。沒有 Gitea API 呼叫。 |
+| 外部呼叫 | `tools/changed-comments.sh`、`references/comment-scope.md`、專案自己的建置或測試指令（沒有就改跑受影響腳本的語法檢查）、`git diff`、每個檔案一個改寫 sub agent。這支技能不呼叫 `jsc-hooks/hooks/write-guard.sh`，也不在它的 `review` 模式擋下範圍內：那支腳本的檔頭寫明 comment-cleanup 一律放行，因為精確判定註解列要解析整份新內容再逐語言判斷，判錯會擋掉合法清理。寫入範圍改由步驟 4 與後續審查把關。收尾另外呼叫 `jsc-hooks/tools/report-status.sh skill-end` 寫狀態事件。沒有 Gitea API 呼叫。 |
-| 完成條件 | 範圍內每一列註解都有結果：維持原樣並說明理由、改寫、或刪除。每個 sub agent 都確認過自己的檔案且沒有未解決的殘句。`git diff` 只顯示註解與文件字串的變更。驗證指令退出碼 0，或報告寫明指令、退出碼與失敗歸屬，或寫明缺哪一個指令。報告說明移除了哪些類別、動了哪些檔案、驗證有沒有過。 |
+| 完成條件 | 範圍內每一列註解都有結果：維持原樣並說明理由、改寫、或刪除。每個 sub agent 都確認過自己的檔案且沒有未解決的殘句。`git diff` 只顯示註解與文件字串的變更。驗證指令退出碼 0，或報告寫明指令、退出碼與失敗歸屬，或寫明缺哪一個指令。報告說明移除了哪些類別、動了哪些檔案、驗證有沒有過。收尾一定要寫一筆 `skill-end` 狀態事件：範圍內每一列都有結果且驗證退出碼 0 是 `ok`，`changed-comments.sh` 回 2 讓範圍算不出來、什麼都沒改是 `blocked`，改完了但沒有驗證指令可跑、失敗判給既有問題、或有殘句沒解決是 `degraded`，驗證失敗歸本輪且重跑一次仍失敗而還原了該檔是 `failed`，`changed-comments.sh` 回 1 代表這次變更沒動到任何註解、沒有可清的東西，是 `aborted`。 |
-| 可驗證跡象 | 這是三支技能裡唯一會改檔的。跑完在工作區留下實際的檔案修改，`git diff` 看得到被清理的註解列，且變更只涵蓋註解與文件字串，不涉及識別字、控制流程、資料結構。還原情境下 `git diff` 會看到該檔的本輪修改被撤回。不寫 wiki 頁、不開 PR、不改狀態檔。 |
+| 可驗證跡象 | 這是三支技能裡唯一會改檔的。跑完在工作區留下實際的檔案修改，`git diff` 看得到被清理的註解列，且變更只涵蓋註解與文件字串，不涉及識別字、控制流程、資料結構。還原情境下 `git diff` 會看到該檔的本輪修改被撤回。跑完 `$JSC_HOME/usage/events.jsonl` 會多一筆 `{kind:skill,phase:end}` 事件，`name` 欄是 `jsc-review:comment-cleanup`，`status` 與 `exit` 兩欄對得上上一列講的判準；沒有註解可清那一輪看得到 `aborted`，還原那一輪看得到 `failed`，兩者和清乾淨的 `ok` 一眼分得開；`jsc-hooks` 不在這台機器上時沒有這一筆，技能本身照樣跑完。除這一筆事件外，不寫 wiki 頁、不開 PR、不改其他狀態檔。 |

skills/api-doc/SKILL.md

@@ -55,6 +55,23 @@ Audit whether an API project's Swagger (OpenAPI) documentation is complete enoug
    Then release the review lock: run `jsc-hooks/hooks/write-guard.sh release`, which clears `$JSC_HOME/sessions/{sid}.lastskill`. That file is how the guard recognizes the running skill, and no event tells the guard a skill ended: leave it in place and the caller's first fix — the fix this very report asked for — is blocked by the audit that just finished. State the fallback in the report either way, because an older `jsc-hooks` treats `release` as an unknown mode and exits `0` without clearing anything: the lock then lifts by itself once the file is older than `JSC_WRITE_GUARD_TTL` (900 seconds by default), and `JSC_WRITE_GUARD=off` opens it immediately.
 
    Completion condition: the report is handed to the caller, the release command has been run and the wait plus the `JSC_WRITE_GUARD=off` escape hatch are stated, and the fix decision is left to them.
+7. Record how this run ended, as the very last thing this skill does — after the release, so a lock that would not clear is still visible to it:
+
+   `jsc-hooks/tools/report-status.sh skill-end jsc-review:api-doc {status} {exit} "{detail}"`
+
+   Resolve that path the way step 6 already resolves `jsc-hooks/hooks/write-guard.sh` — the sibling plugin directory, no separate lookup rule for this one call. **A missing script is not a failure here: skip this step in silence and let the run end as it stands.** The script swallows its own write errors and exits 0 even then, so nothing branches on its code either. This skill writes no code; it must not start failing over a line it could not write about itself.
+
+   | status | This skill's case |
+   | --- | --- |
+   | `ok` | Both aspects returned and the merged list reached the caller. A `merge-findings.sh` exit 1 is `ok` too: the audit ran and found nothing, which is a real answer and a different thing from never auditing |
+   | `blocked` | A precondition refused before any aspect ran: `swagger-detect.sh` exit 1 — the project has no Swagger package or no wiring, so the audit is skipped, which is exactly what step 2 reports and never a failure of this run. Exit 2 (project path missing, or no `grep` in the environment) and a `git diff` that refused belong here too |
+   | `degraded` | The finding list is reported but the close-out is short: `write-guard.sh release` did not clear `$JSC_HOME/sessions/{sid}.lastskill`, so the lock lingers until `JSC_WRITE_GUARD_TTL` and the caller's first fix is blocked by the audit that just finished |
+   | `failed` | The aspects ran and their findings never reached a report: `merge-findings.sh` exit 2, or a second exit 3 with malformed rows still on the table |
+   | `aborted` | There was nothing to audit — step 3's controller list came back empty, so a scoped run found no changed controller and no sub agent was spawned. Keep this apart from the `ok` above: both end in 「無發現」, and only the event tells a clean audit from an audit that never had a subject |
+
+   `{exit}` is the exit code of whatever decided the status, `0` for `ok`. `{detail}` is one short line well under 200 characters: controller and finding counts plus exit codes, never file paths, endpoint names, example payloads, or personal data.
+
+   Completion condition: the command has run, or the script was absent and this step was skipped.
 
 ## Severity
 

skills/code-review/SKILL.md

@@ -54,6 +54,23 @@ Review changed code against `references/smells.md` (from the book *Refactoring*)
    Then close the run down in two moves. Delete the step 1 snapshot file; nothing else ever reads it, and left behind it accumulates one stale diff per review. Release the review lock by running `jsc-hooks/hooks/write-guard.sh release`, which clears `$JSC_HOME/sessions/{sid}.lastskill`. That file is how the guard recognizes the running skill, and no event tells the guard a skill ended: leave it in place and the caller's first fix — the fix this very report asked for — is blocked by the audit that just finished. State the fallback in the report either way, because an older `jsc-hooks` treats `release` as an unknown mode and exits `0` without clearing anything: the lock then lifts by itself once the file is older than `JSC_WRITE_GUARD_TTL` (900 seconds by default), and `JSC_WRITE_GUARD=off` opens it immediately.
 
    Completion condition: the report is handed to the caller, the snapshot is deleted, the release command has been run and the wait plus the `JSC_WRITE_GUARD=off` escape hatch are stated, and the fix decision is left to them.
+5. Record how this run ended, as the very last thing this skill does — after the snapshot deletion and the release, so a cleanup that did not complete is still visible to it:
+
+   `jsc-hooks/tools/report-status.sh skill-end jsc-review:code-review {status} {exit} "{detail}"`
+
+   Resolve that path the way step 4 already resolves `jsc-hooks/hooks/write-guard.sh` — the sibling plugin directory, no separate lookup rule for this one call. **A missing script is not a failure here: skip this step in silence and let the run end as it stands.** The script swallows its own write errors and exits 0 even then, so nothing branches on its code either. This skill writes no code; it must not start failing over a line it could not write about itself.
+
+   | status | This skill's case |
+   | --- | --- |
+   | `ok` | All six groups returned and the merged list reached the caller, the snapshot is deleted and the lock is clear. A `merge-findings.sh` exit 1 is `ok` too: six groups read the diff and none had anything to report, which is a real answer |
+   | `blocked` | The review scope never existed, so no sub agent ran: step 1's `git diff` refused — not a repository, an unknown base revision, or an unreadable object. Nothing was reviewed and nothing could be |
+   | `degraded` | The report is handed over but the close-out is short: the step 1 snapshot is still on disk, or `write-guard.sh release` did not clear `$JSC_HOME/sessions/{sid}.lastskill` and the lock lingers until `JSC_WRITE_GUARD_TTL` |
+   | `failed` | The six groups ran and their findings never reached a report: `merge-findings.sh` exit 2, or a second exit 3 with malformed rows still on the table |
+   | `aborted` | There was nothing to review — the step 1 snapshot came back empty, so the diff holds no changed line, the file was deleted and no sub agent was spawned. Keep this apart from the `ok` above: both end in 「無發現」, and only the event tells a clean review from a review that never had a subject |
+
+   `{exit}` is the exit code of whatever decided the status, `0` for `ok`. `{detail}` is one short line well under 200 characters: changed-file and finding counts plus exit codes, never file paths, code excerpts, branch names, or personal data.
+
+   Completion condition: the command has run, or the script was absent and this step was skipped.
 
 ## Notes
 

skills/comment-cleanup/SKILL.md

@@ -31,3 +31,20 @@ Use `references/comment-scope.md` for the banned list, allowed list, and rewrite
 4. Change comments and documentation strings only. Do not change executable behavior, identifiers, control flow, data shape, or tests except when a test fixture literally asserts the old comment text. `jsc-hooks/hooks/write-guard.sh` in `review` mode is the code-level backstop, but it covers this skill only as far as jsc-hooks can decide a comment line precisely: where that decision is not precise, the guard is limited to `jsc-review:code-review` and `jsc-review:api-doc`, which write nothing at all, and this skill runs unguarded. Only claude has a `PreToolUse` hook in the first place, so on codex, copilot, antigravity, and kiro this step's prose is the only constraint. Completion condition: `git diff` shows comment-only or documentation-string-only edits.
 5. Run the smallest relevant build or test command once for the whole changed project, after every sub agent in step 2 has returned. Read the exit code. `0` — verification passed. Non-zero — the command ran and failed, so name the command, its exit code, and the failing output, then decide whether this run caused it: a failure that names a file this run touched is treated as caused here, so restore that file's comment syntax and re-run the command once; if it fails the same way again, revert this run's edits in that file and report the revert. A failure that names no file this run touched is reported as pre-existing, and the cleanup edits stay. If no project command is available, run syntax checks for the touched scripts and report the gap. Completion condition: the command exited `0`, or the report states the command, its exit code and whether the failure belongs to this run, or the exact missing command is reported.
 6. Report the cleanup by category, not by full diff. Completion condition: the report names which categories were removed, which files were touched, and whether verification passed.
+7. Record how this run ended, as the very last thing this skill does — after the verification of step 5, whose result decides most of the status below:
+
+   `jsc-hooks/tools/report-status.sh skill-end jsc-review:comment-cleanup {status} {exit} "{detail}"`
+
+   Resolve that path the way this file already names `jsc-hooks/hooks/comment-scope.sh` — the sibling plugin directory, no separate lookup rule for this one call. **A missing script is not a failure here: skip this step in silence and let the run end as it stands.** The script swallows its own write errors and exits 0 even then, so nothing branches on its code either. This is the one skill of the three that edits files, so the rule matters more here: rewritten comments are already on disk, and a recorder that is not installed must not turn that into a failed run.
+
+   | status | This skill's case |
+   | --- | --- |
+   | `ok` | Every scoped comment is unchanged with a stated reason, rewritten, or deleted, no sub agent reported an unresolved fragment, and step 5's verification command exited 0 |
+   | `blocked` | `changed-comments.sh` exit 2 — a parameter or environment error left the scope uncomputed, so no file was read and none was rewritten. A scope that could not be computed is not an empty scope, and this status is what keeps the two apart |
+   | `degraded` | The comments are cleaned but nothing confirmed them: no project build or test command exists so only syntax checks ran, or step 5 failed on a file this run never touched and the failure was recorded as pre-existing while the edits stayed. A sub agent that returned an unresolved fragment lands here too |
+   | `failed` | Step 5 failed on a file this run touched, the one retry failed the same way, and this run's edits in that file were reverted. The cleanup did not stand, and the revert is the fact the caller has to see |
+   | `aborted` | `changed-comments.sh` exit 1 — this change added or modified no comment line, so there is nothing to clean and no sub agent was spawned. The user asking to stop before step 2 lands here as well |
+
+   `{exit}` is the exit code of whatever decided the status, `0` for `ok`. `{detail}` is one short line well under 200 characters: file and comment-line counts plus exit codes, never comment text, file paths, branch names, or personal data — the text this skill removes is exactly the text that must not be copied into an event line.
+
+   Completion condition: the command has run, or the script was absent and this step was skipped.