Merge pull request 'feat/change-requests/comment-cleanup-skill' (#13) from feat/change-requests/comment-cleanup-skill into feat/change-requests/main

Reviewed-on: #13

.claude-plugin/plugin.json

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

.codex-plugin/plugin.json

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

README.md

@@ -26,12 +26,16 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 
 ### `code-review`
 
-對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號`、嚴重度、建議重構手法，修正與否由呼叫端決定。第 2 組同時擋「文件編號夾帶」：註解只寫「為什麼這樣寫」，議題編號、wiki 頁編號、工作包編號、commit hash、`@` 提及、外部文件連結一律不進註解，清單看 `references/comment-scope.md`。diff 是空的就直接回報「無發現」，不開任何 sub agent；六組全部回覆才進入彙整，沒東西可報的那組也要回「無發現」。安全性與 bug 審查交給 CLI 內建 review，不重複。
+對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號`、嚴重度、建議重構手法，修正與否由呼叫端決定。第 2 組同時擋「文件編號與審查流程痕跡夾帶」：註解只寫「為什麼這樣寫」，議題編號、wiki 頁編號、工作包編號、commit hash、`@` 提及、外部文件連結、審查輪次、發現編號與審查狀態一律不進註解，清單看 `references/comment-scope.md`。diff 是空的就直接回報「無發現」，不開任何 sub agent；六組全部回覆才進入彙整，沒東西可報的那組也要回「無發現」。安全性與 bug 審查交給 CLI 內建 review，不重複。
 
 ### `api-doc`
 
 稽核 API 專案的 Swagger 文件：每個可能回傳的 HTTP 狀態碼都要宣告回覆類型，每個輸入與輸出都要有說明與真實資料範例，並沿著巢狀資料模型逐層遞迴。控制器改完或實作完成時執行，例如由 `jsc-sdlc:implement` 呼叫，與 `jsc-review:code-review` 並列為兩關收尾稽核。先跑 `tools/swagger-detect.sh` 偵測，套件與掛接設定要雙重命中才算支援；只裝套件沒掛接就回報未啟用並停手，不開任何 sub agent。原始碼的註解契約歸 `jsc-review:code-review` 第 5 組，這支只管 Swagger 文件屬性與範例，兩支不重複回報。回報 `檔案:行號`、嚴重度與建議修法，本技能不改程式碼。
 
+### `comment-cleanup`
+
+清理本次變更新增或修改的註解，把文件追蹤資訊與審查流程痕跡移除，只留下程式邏輯的實質理由。使用者要求「清一下註解」、「不要留 review 痕跡」，或 commit 前發現註解夾帶流程資訊時執行。判斷準則只看 `references/comment-scope.md`，本技能負責清理，`comment-scope.sh` 負責擋，`code-review` 第 2 組負責指出人工判讀案例。未明確要求時不動未變更的舊註解。
+
 <!-- JSC-SKILLS:END -->
 
 ## 參考
@@ -39,7 +43,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
 | 檔案 | 用途 |
 | --- | --- |
 | `references/smells.md` | 六組壞味道完整清單：定義、偵測訊號、建議重構手法、嚴重度分級；範例資料必須去識別化 |
-| `references/comment-scope.md` | 程式碼註解內容界線：禁止寫進註解的文件編號清單、允許項目與白名單、命中時的改法 |
+| `references/comment-scope.md` | 程式碼註解內容界線：禁止寫進註解的文件編號、審查流程痕跡、允許項目與白名單、命中時的改法 |
 
 ## 工具
 

plugin.json

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

references/comment-scope.md

@@ -65,6 +65,18 @@
 | 產生來源署名、AI 署名 | `// 本檔由 jsc-sdlc:implement 產生` |
 | 外部文件連結 | `// 見 Confluence、Notion、Google Docs 連結` |
 
+### 審查流程痕跡
+
+這些資訊是討論當下的座標。沒有參與那場討論的人看不懂，討論結束後也會失效。註解要留下程式邏輯的原因，不留下審查流程的路徑。
+
+| 項目 | 命中例 |
+| --- | --- |
+| `review`、`code review` 字樣用來描述審查流程 | `// code review 要求改成共用函式` |
+| 輪次描述 | `// 第二輪追加檢查這個分支` |
+| 問題與發現編號 | `// Finding1：避免空指標`、`// 問題3 已修` |
+| 審查者代稱或工具名 | `// hermes 建議保留這個判斷`、`// CodeReview bot 標出這裡` |
+| 審查狀態標籤 | `// 真缺陷，已解決`、`// BLOCKING` |
+
 ## 允許寫進註解
 
 | 項目 | 允許的理由 | 例 |
@@ -87,5 +99,7 @@
 | `// 見 #123` | 把 `#123` 裡的原因寫進註解本身 |
 | `// @someone 2026-08-26 修` | `// 2026-08-26 改用新費率` |
 | `// PLAN_A1B2C3D4 第 2 頁的規則` | 把該頁的規則正文濃縮成一句寫進來 |
+| `// Finding1：避免空指標` | `// 輸入來自外部系統，空值要直接略過` |
+| `// 第二輪追加這個判斷` | `// 舊資料可能缺欄位，先補預設值再解析` |
 
 原則一句話：把編號指向的內容**搬進註解**，再刪掉編號。搬不動就代表那件事不該用註解表達，改寫進文件。

skills/code-review/SKILL.md

@@ -26,7 +26,7 @@ Review changed code against `references/smells.md` (from the book *Refactoring*)
    | Group | Scope |
    | --- | --- |
    | 1 Bloaters | smells.md group 1 |
-   | 2 Obscurity | smells.md group 2, including 2.5 document reference leak — comments carrying issue ids, wiki page ids, work package ids, commit hashes, @ mentions, or external document links; the full banned and allowed lists live in `references/comment-scope.md` |
+   | 2 Obscurity | smells.md group 2, including 2.5 comment scope leaks — comments carrying issue ids, wiki page ids, work package ids, commit hashes, @ mentions, external document links, review rounds, finding ids, reviewer aliases, or review status labels; the full banned and allowed lists live in `references/comment-scope.md` |
    | 3 Couplers | smells.md group 3 |
    | 4 Dispensables & Others | smells.md group 4 |
    | 5 Comment contract | smells.md group 5, 5.1 to 5.8 — including 5.6 navigation links to the functions a method calls, 5.7 XML comment tag layout (opening and closing tag each on its own line), and 5.8 code-element markup by language convention (`<paramref>`, `<see cref>`, `<c>` in XML; backticks in JSDoc and docstrings) |
@@ -40,6 +40,6 @@ Review changed code against `references/smells.md` (from the book *Refactoring*)
 
 ## Notes
 
-- `jsc-hooks`' `comment-scope.sh` already matches the pattern-detectable items after every file write. Group 2 here covers what patterns cannot decide — project code names and customer names — plus the overall judgment; the two never report the same finding twice.
+- `jsc-hooks`' `comment-scope.sh` already matches the pattern-detectable items after every file write. Group 2 here covers what patterns cannot decide — project code names, customer names, and context-dependent review traces — plus the overall judgment; the two never report the same finding twice.
 - If group 5 examples are fetched from a database, they must be de-identified; never include personal data.
 - When there are no findings, report the literal 「無發現」 explicitly; never leave the report empty.

skills/comment-cleanup/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: comment-cleanup
+description: Clean review traces and document-tracking noise from comments touched by the current change. Use when the user asks to clean comments, remove review traces, or when a pre-commit check finds process details in changed comments. It rewrites comments only, keeps code behavior unchanged, and uses references/comment-scope.md as the single source of banned and allowed content. Do not use for untouched legacy comments unless the user explicitly asks for that wider scope.
+---
+
+# comment-cleanup
+
+Clean comments changed in the current diff so they explain why the code exists, without carrying review traces, issue coordinates, wiki page ids, or other process-only details.
+
+## When to run
+
+1. **User asks to clean comments**: examples include "clean the comments", "remove review traces", or "do not leave review artifacts".
+2. **Before commit**: `jsc-hooks` reports comment scope warnings, or a changed comment clearly carries process-only details.
+3. **Not for untouched legacy comments**: only widen the scope when the user explicitly asks for legacy cleanup.
+
+## Single Source
+
+Use `references/comment-scope.md` for the banned list, allowed list, and rewrite rules. Do not copy those lists into this skill.
+
+## Division of Labor
+
+- `jsc-hooks/comment-scope.sh` blocks pattern-detectable violations after writes.
+- `jsc-review:code-review` group 2 reports judgment-based cases that patterns cannot decide.
+- This skill cleans the changed comments. Do not report the same finding again when a hook or code review already reported it; either clean it or explain why it is outside this skill's scope.
+
+## Steps
+
+1. Define the scope: inspect the current diff and list only added or modified comment lines. Include untouched legacy comments only when the user explicitly requested that. Completion condition: the cleanup scope is listed by file, or the run ends with the literal 「無發現」.
+2. Compare each scoped comment with `references/comment-scope.md`. Remove process-only details and keep the real reason for the code. If a whole comment is only process detail and no real reason remains, delete the whole comment. Completion condition: every scoped comment is either unchanged with a reason, rewritten, or deleted.
+3. Re-read the changed area after every rewrite. Confirm the sentence is complete, the logic still reads naturally, and no dangling fragment remains after deletion. Completion condition: every touched comment reads as a complete explanation or is gone.
+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. Completion condition: `git diff` shows comment-only or documentation-string-only edits.
+5. Run the smallest relevant build or test command for the changed project. If no project command is available, run syntax checks for touched scripts and report the gap. Completion condition: verification passed, 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.