feat(skillset-report): 四支異動技能收尾套用到工作階段、驗證並寫異動報告

What：`skill-new`、`skill-update`、`skill-delete`、`skillset-update` 四支各新增一個收尾步驟，內含三個子步驟：把改動套用到目前工作階段、逐項驗證功能真的動得起來、把驗證結果附加到 wiki 的 `SKILLSET_{HASH}`。四支的 `description` 同步補上這段收尾。 Why：原本四支都以「開了 PR」作為收尾。PR 開完技能還沒進到任何 CLI，改動到底動不動得起來沒人驗過，壞了要等下一次有人踩到才知道。技能組的異動紀錄也一樣沒有落腳處：同一支技能改過幾次、每次改了什麼，只能翻 git 紀錄。 How：套用那一步分兩條路徑，依改動走到哪裡決定。PR 已經合併到 `master` 才走 `jsc-cli:deploy` 更新模式，並依提示重新啟動；PR 還停在 `develop` 或還在等審核，就改用工作樹驗證，報告標成「工作樹驗證、尚未部署」，並點名還沒合併的發佈 PR。分兩條路徑的理由是完成條件達不到：marketplace 與 `version-guard.sh` 都讀存取庫的預設分支，停在 `develop` 的改動 `deploy` 一定看不到，硬跑就卡在永遠達不到的完成條件上。驗證那一步要求逐項比對結束碼與實際輸出，不接受「跑完沒報錯」；對不上就回到套用那一步重跑，不往下走。報告一律附加一節、不覆蓋舊節，要看一支技能改過幾次就在同一頁上翻；寫不進去就把頁名與未寫入的內容交回使用者，這一步留著不結案。 Who：`jsc-meta` 的四支技能組異動技能，以及日後查技能組異動紀錄的人。
2026-08-27 16:34:16 +08:00
parent 9a0ea8e248
commit 478f670d53
4 changed files with 28 additions and 4 deletions
@@ -1,6 +1,6 @@
 ---
 name: skill-delete
-description: Remove a skill from the jsc skill set safely. Pick the skill from the Gitea canonical marketplace skill list, inventory every file referencing it, fix each affected file through decision-tree questions until guideline checks pass, delete the skill and verify no on-disk leftover in any CLI, then open a PR via jsc-git pr. Use only for removal; not for renaming (use skill-update).
+description: Remove a skill from the jsc skill set safely. Pick the skill from the Gitea canonical marketplace skill list, inventory every file referencing it, fix each affected file through decision-tree questions until guideline checks pass, delete the skill and verify no on-disk leftover in any CLI, open a PR via jsc-git pr, then deploy the deletion into the current session and append the change report to wiki SKILLSET_{HASH}. Use only for removal; not for renaming (use skill-update).
 ---
 # skill-delete — delete a skill
@@ -28,3 +28,9 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
   Completion condition: the script exits 0, or exit 3 is reported to the user and recorded in the PR.
 8. Call `jsc-git:pr` to open a Push Request. Completion condition: a PR URL comes back.
 9. Apply the deletion to the current working session, verify it took, then report:
   1. Force the change into the session — which of the two routes applies depends on where the change has reached, because the marketplace and `version-guard.sh` both read the repository's **default branch** (`master`), so `jsc-cli:deploy` cannot see anything that stopped at `develop`:
      - The PR is merged all the way to `master`: call `jsc-cli:deploy` in update mode so every installed CLI loads the version without the skill, and restart the CLI when it asks (the deploy writes `$JSC_HOME/restart-required`; see guidelines.md「部署後重啟閘門」). When the deploy cannot update a CLI, record which CLIs did load the new version and carry on with one of those; when none did, stop and report the deletion as unverified. Completion condition: `claude plugin list` (or the equivalent command of another installed CLI) prints `jsc-{domain}` at the version the three manifests now carry.
      - The PR is still short of `master` (waiting on review, or merged only into `develop`): deploying is pointless and its completion condition is unreachable, so verify against the **worktree** instead — run the next sub-step against `/root/plugins/{domain}` rather than the installed copy, mark the report as 「工作樹驗證、尚未部署」, and say plainly which release PR still has to merge before the deletion reaches any CLI. Until it merges the skill is still installed and still callable, so say that too. Completion condition: the verification sub-step passed against the worktree and the outstanding release PR is named in the report.
   2. Verify the function concretely: run `tools/list-skills.sh` and confirm no row carries the deleted `{domain}/{name}`, rerun `tools/verify-skill-removed.sh {domain} {name}` for exit 0, then run every tool and skill that step 5 fixed and confirm each still finishes with its documented exit code — a fix that broke a caller shows up here, not earlier. On any mismatch — the deleted skill still listed, a leftover from exit 1, a fixed caller that now fails — fix the cause and rerun this step from 9.1. Completion condition: the skill is absent from the list, the verification script exits 0 (or its exit 3 stays reported as「無處可查」), and every fixed caller ran.
   3. Write the change report to wiki page `SKILLSET_{HASH}` — this part MUST run as a sub agent. Call `jsc-gitea:wiki`; `{HASH}` comes from the `{owner}/{repo}` of the domain repo that lost the skill, and the wiki repo resolves through `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. **Append** a section for this change — date, 「刪除」, skill name, changed files (the step 5 inventory verdicts included), PR URL, the step 9.2 verification result per item — and keep every earlier section. Add the page to `SKILLSET_CONTENTS` when it is new. When the write fails — no `{owner}/{repo}` resolves, or `jsc-gitea:wiki` reports an API error — hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: the page holds the new section plus all earlier sections, and `SKILLSET_CONTENTS` links it.
@@ -1,6 +1,6 @@
 ---
 name: skill-new
-description: Create a new skill in the jsc skill set. Ask skill details via decision tree, generate the skill under the right jsc-{domain} per guidelines.md (create the domain from the template repo if missing), then open a PR via jsc-git pr. Use when the user wants to add a skill; not for editing an existing one (use skill-update).
+description: Create a new skill in the jsc skill set. Ask skill details via decision tree, generate the skill under the right jsc-{domain} per guidelines.md (create the domain from the template repo if missing), open a PR via jsc-git pr, then deploy the skill into the current session, verify it runs, and append the change report to wiki SKILLSET_{HASH}. Use when the user wants to add a skill; not for editing an existing one (use skill-update).
 ---
 # skill-new — create a skill
@@ -34,3 +34,9 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
   Then run `tools/sync-skill-manifest.sh {domain-path}` directly (no sub agent needed) to sync the domain README's 「Skills 目錄」 section and bump the version in all three manifests. Completion condition: `skills/{name}/SKILL.md` exists, the README lists the skill, and all three manifests show the same new version.
 4. Self-check every item of the guidelines.md audit checklist; fix anything that fails. Completion condition: every checklist item passes.
 5. Call `jsc-git:pr` to open a Push Request. Completion condition: a PR URL comes back.
 6. Apply the new skill to the current working session, verify it works, then report:
   1. Force the change into the session — which of the two routes applies depends on where the change has reached, because the marketplace and `version-guard.sh` both read the repository's **default branch** (`master`), so `jsc-cli:deploy` cannot see anything that stopped at `develop`:
      - The PR is merged all the way to `master`: call `jsc-cli:deploy` in update mode so every installed CLI loads the new version, and restart the CLI when it asks (the deploy writes `$JSC_HOME/restart-required`; see guidelines.md「部署後重啟閘門」). When the deploy cannot update a CLI, record which CLIs did load the new version and carry on with one of those; when none did, stop and report the change as unverified. Completion condition: `claude plugin list` (or the equivalent command of another installed CLI) prints `jsc-{domain}` at the version the three manifests now carry.
      - The PR is still short of `master` (waiting on review, or merged only into `develop`): deploying is pointless and its completion condition is unreachable, so verify against the **worktree** instead — run step 6.2 against `/root/plugins/{domain}` rather than the installed copy, mark the report in 6.3 as 「工作樹驗證、尚未部署」, and say plainly which release PR still has to merge before the change reaches any CLI. Completion condition: step 6.2 passed against the worktree and the outstanding release PR is named in the report.
   2. Verify the function concretely: run `tools/list-skills.sh` and see the `{domain}<TAB>{name}` row for the new skill, then run every tool the skill added with real arguments and compare each exit code against its documented meaning. Invoke `/jsc-{domain}:{name}` once and confirm the CLI loads the SKILL.md body instead of reporting an unknown command. On any mismatch — a missing row, an exit code the tool's own documentation does not describe, an unknown command — fix the cause and rerun this step from 6.1. Completion condition: the row is printed, every added tool ran with an expected exit code, and the command loaded.
   3. Write the change report to wiki page `SKILLSET_{HASH}` — this part MUST run as a sub agent. Call `jsc-gitea:wiki`; `{HASH}` comes from the `{owner}/{repo}` of the domain repo that gained the skill, and the wiki repo resolves through `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. **Append** a section for this change — date, 「新增」, skill name, changed files, PR URL, the step 6.2 verification result per item — and keep every earlier section. Add the page to `SKILLSET_CONTENTS` when it is new. When the write fails — no `{owner}/{repo}` resolves, or `jsc-gitea:wiki` reports an API error — hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: the page holds the new section plus all earlier sections, and `SKILLSET_CONTENTS` links it.
@@ -1,6 +1,6 @@
 ---
 name: skill-update
-description: Update one existing skill in the jsc skill set. List all skills from the Gitea canonical marketplace (cloning any missing domain repo) and let the user pick one, ask update details via decision tree, apply the change, then re-check against the guidelines checklist until it passes and open a PR via jsc-git pr. Use for modifying a single skill; not for creating (skill-new), not for removing (skill-delete), and not for a change spanning several skills or domains (skillset-update).
+description: Update one existing skill in the jsc skill set. List all skills from the Gitea canonical marketplace (cloning any missing domain repo) and let the user pick one, ask update details via decision tree, apply the change, re-check against the guidelines checklist until it passes, open a PR via jsc-git pr, then deploy the change into the current session, verify it runs, and append the change report to wiki SKILLSET_{HASH}. Use for modifying a single skill; not for creating (skill-new), not for removing (skill-delete), and not for a change spanning several skills or domains (skillset-update).
 ---
 # skill-update — update a skill
@@ -16,3 +16,9 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
 5. Update the skill — the modification part MUST run as a sub agent: modify SKILL.md and related files. Then run `tools/sync-skill-manifest.sh {domain-path}` directly (no sub agent needed) to sync the domain README's 「Skills 目錄」 section and bump the version in all three manifests. Completion condition: the skill files carry the change and all three manifests show the same new version.
 6. Check every item of the guidelines.md audit checklist. On any failure, **return to step 4**: ask again and fix, until all items pass. Completion condition: every checklist item passes.
 7. Call `jsc-git:pr` to open a Push Request. Completion condition: a PR URL comes back.
 8. Apply the update to the current working session, verify it works, then report:
   1. Force the change into the session — which of the two routes applies depends on where the change has reached, because the marketplace and `version-guard.sh` both read the repository's **default branch** (`master`), so `jsc-cli:deploy` cannot see anything that stopped at `develop`:
      - The PR is merged all the way to `master`: call `jsc-cli:deploy` in update mode so every installed CLI loads the new version, and restart the CLI when it asks (the deploy writes `$JSC_HOME/restart-required`; see guidelines.md「部署後重啟閘門」). When the deploy cannot update a CLI, record which CLIs did load the new version and carry on with one of those; when none did, stop and report the change as unverified. Completion condition: `claude plugin list` (or the equivalent command of another installed CLI) prints `jsc-{domain}` at the version the three manifests now carry.
      - The PR is still short of `master` (waiting on review, or merged only into `develop`): deploying is pointless and its completion condition is unreachable, so verify against the **worktree** instead — run the next sub-step against `/root/plugins/{domain}` rather than the installed copy, mark the report as 「工作樹驗證、尚未部署」, and say plainly which release PR still has to merge before the change reaches any CLI. Completion condition: the verification sub-step passed against the worktree and the outstanding release PR is named in the report.
   2. Verify the function concretely: run `tools/list-skills.sh` and see the updated `description` in the skill's row, then run every tool this change touched with real arguments and compare each exit code against its documented meaning. Invoke `/jsc-{domain}:{name}` once and confirm the CLI loads the changed SKILL.md body. On any mismatch — a stale row, an exit code the tool's own documentation does not describe, an unchanged body — fix the cause and rerun this step from 8.1. Completion condition: the row shows the new description, every touched tool ran with an expected exit code, and the command loaded.
   3. Write the change report to wiki page `SKILLSET_{HASH}` — this part MUST run as a sub agent. Call `jsc-gitea:wiki`; `{HASH}` comes from the `{owner}/{repo}` of the changed domain repo, and the wiki repo resolves through `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. **Append** a section for this change — date, 「更新」, skill name, changed files, PR URL, the step 8.2 verification result per item — and keep every earlier section. Add the page to `SKILLSET_CONTENTS` when it is new. When the write fails — no `{owner}/{repo}` resolves, or `jsc-gitea:wiki` reports an API error — hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: the page holds the new section plus all earlier sections, and `SKILLSET_CONTENTS` links it.
@@ -1,6 +1,6 @@
 ---
 name: skillset-update
-description: Apply one change request across the whole jsc skill set — multiple skills in multiple domains in one pass. Ask the change details via decision tree, sync every domain repo from the Gitea canonical marketplace, apply the change per affected domain via sub agents, re-check against the guidelines checklist until it passes, then open a PR per affected repo via jsc-git pr. Use when a change spans multiple skills or domains; not for a single skill (use skill-update).
+description: Apply one change request across the whole jsc skill set — multiple skills in multiple domains in one pass. Ask the change details via decision tree, sync every domain repo from the Gitea canonical marketplace, apply the change per affected domain via sub agents, re-check against the guidelines checklist until it passes, open a PR per affected repo via jsc-git pr, then deploy the change into the current session, verify it runs, and append the change report to wiki SKILLSET_{HASH}. Use when a change spans multiple skills or domains; not for a single skill (use skill-update).
 ---
 # skillset-update — apply one change across the skill set
@@ -14,3 +14,9 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
 3. Apply the change to every affected skill — the modification part MUST run as a sub agent, one sub agent per affected domain repo: modify SKILL.md and related files and tools. Then run `tools/sync-skill-manifest.sh {domain-path}` directly (no sub agent needed) for each affected domain repo to sync that domain README's 「Skills 目錄」 section and bump the version in all three manifests. Completion condition: every affected domain repo carries the change, the README sync, and the manifest bump.
 4. Check every item of the guidelines.md audit checklist for each touched skill. On any failure, **return to step 1**: ask again and fix, until all items pass. Completion condition: every checklist item passes for every touched skill.
 5. Call `jsc-git:pr` once per affected domain repo to open a Push Request. Completion condition: every affected repo has a PR URL.
 6. Apply the batch change to the current working session, verify it works, then report:
   1. Force the change into the session — which of the two routes applies depends on where the change has reached, because the marketplace and `version-guard.sh` both read each repository's **default branch** (`master`), so `jsc-cli:deploy` cannot see anything that stopped at `develop`:
      - Every affected repo's PR is merged all the way to `master`: call `jsc-cli:deploy` in update mode so every installed CLI loads the new version of **every** affected plugin, and restart the CLI when it asks (the deploy writes `$JSC_HOME/restart-required`; see guidelines.md「部署後重啟閘門」). When the deploy cannot update a CLI, record which CLIs did load the new versions and carry on with one of those; when none did, stop and report the change as unverified. Completion condition: `claude plugin list` (or the equivalent command of another installed CLI) prints every affected `jsc-{domain}` at the version its three manifests now carry.
      - Any affected repo is still short of `master` (waiting on review, or merged only into `develop`): deploying is pointless and its completion condition is unreachable, so verify against the **worktree** instead — run the next sub-step against each `/root/plugins/{domain}` rather than the installed copies, mark the report as 「工作樹驗證、尚未部署」, and list every release PR that still has to merge before the change reaches any CLI. A change spanning several repos reaches the CLIs only when the last of them merges, so name them all. Completion condition: the verification sub-step passed against every affected worktree and every outstanding release PR is named in the report.
   2. Verify the function concretely: run `tools/list-skills.sh` and check the row of every touched skill against the change, then run every tool this change touched with real arguments and compare each exit code against its documented meaning. Invoke one touched skill per affected domain as `/jsc-{domain}:{name}` and confirm the CLI loads the changed SKILL.md body. On any mismatch — a stale row, an exit code the tool's own documentation does not describe, an unchanged body — fix the cause and rerun this step from 6.1. Completion condition: every touched skill's row matches the change, every touched tool ran with an expected exit code, and one command per affected domain loaded.
   3. Write the change report to wiki page `SKILLSET_{HASH}` — this part MUST run as a sub agent, one sub agent per affected domain repo. Call `jsc-gitea:wiki`; `{HASH}` comes from that repo's `{owner}/{repo}`, and the wiki repo resolves through `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. **Append** a section for this change — date, 「批次更新」, the change request in one line, touched skills, changed files, PR URL, the step 6.2 verification result per item — and keep every earlier section. Add each page to `SKILLSET_CONTENTS` when it is new. When a write fails — no `{owner}/{repo}` resolves, or `jsc-gitea:wiki` reports an API error — hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: every affected repo's page holds the new section plus all earlier sections, and `SKILLSET_CONTENTS` links them all.