feat(狀態回報): 收尾寫一筆 skill-end 事件

現行紀錄只記「被叫用」，沒有成敗也沒有結束碼。跑完整輪的技能與開場就
中止的技能，在紀錄裡長得一模一樣。

start 由技能用量 hook 順手發，不必改技能文件。end 只能由技能自己在收尾
步驟寫——hook 接在技能工具呼叫上，而實際工作發生在之後的模型輪次，它在
原理上看不到成敗。有 start 沒有配對的 end，就是那一輪中止了。

status 五選一，每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜
跳過，回報失敗一律不改變技能自己的結論。

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.