docs(guidelines): 重啟閘門狀態檔規則改為一支 CLI 一份

What:`references/guidelines.md`「部署後重啟閘門」的規則表改四列——狀態檔路徑改成 `$JSC_HOME/restart-required.d/{cli}` 並標明一支 CLI 一份、清除時機標明只清自己那一份、原本的「狀態檔存在時」與「狀態檔不存在時」兩列改寫成「該 CLI 那份存在時」與「該 CLI 那份不存在時」,並寫明別支 CLI 的狀態檔不影響這一支。另外新增一段「狀態檔為什麼一支 CLI 一份」,記下 2026-08-27 部署時實測出的兩個缺陷,並把它寫成通則。

Why:準則是技能組的規則正本,`jsc-hooks` 的實作與 `jsc-cli` 的說明都對著它看。實作改成一支 CLI 一份而準則還停在單一檔案,下一次 skill-check 會判成實作違規,也可能有人照準則把實作改回去。這兩個缺陷是實測抓到的、不是推測,理由留在準則裡才擋得住下一次的簡化。

How:規則表只改該改的四列,判定位置與逃生門兩列不動。新增那段把缺陷寫清楚——並行部署互相覆蓋只留最後一支,以及任一支重啟就解除全部五支的閘門——再收成通則:跨 CLI 或跨工作階段的狀態檔,設計時先問清楚那個事實屬於誰,並指出工作包歸屬狀態檔踩過同一類錯誤。豁免清單那九支與「清單認技能名不認呼叫鏈」不動,這一輪沒有動到豁免範圍。

Who:`jsc-meta` 的技能準則,部署後重啟閘門這條規則的正本。
This commit is contained in:
2026-08-27 18:49:59 +08:00
parent a65f546911
commit baa1f1118f
+6 -4
View File
@@ -128,10 +128,10 @@
| 項目 | 規則 | | 項目 | 規則 |
| --- | --- | | --- | --- |
| 狀態檔 | `$JSC_HOME/restart-required`,由 `jsc-cli:deploy` 收尾寫入 | | 狀態檔 | `$JSC_HOME/restart-required.d/{cli}`,**一支 CLI 一份**,由 `jsc-cli:deploy` 收尾寫入 |
| 清除時機 | 重啟 CLI 之後由 `jsc-hooks` 清除,不必手動刪 | | 清除時機 | 重啟 CLI 之後由 `jsc-hooks` 清除**自己那一份**,不必手動刪 |
| 狀態檔存在時 | 擋下 jsc 技能呼叫,印出「請先重啟 CLI」與狀態檔路徑 | | 該 CLI 那份存在時 | 擋下這支 CLI 的 jsc 技能呼叫,印出要重啟哪一支與狀態檔路徑 |
| 狀態檔不存在時 | 全部放行 | | 該 CLI 那份不存在時 | 放行。別支 CLI 的狀態檔不影響這一支 |
| 判定位置 | 程式層,由 `jsc-hooks` 執行,不靠技能內文自我約束 | | 判定位置 | 程式層,由 `jsc-hooks` 執行,不靠技能內文自我約束 |
| 逃生門 | `JSC_RESTART_GATE=off` | | 逃生門 | `JSC_RESTART_GATE=off` |
@@ -151,6 +151,8 @@
豁免這幾支的理由是同一件事:`jsc-meta` 四支異動技能的收尾要求把驗證結果寫進 `SKILLSET_{HASH}`,還要結清工作日誌,而這條路徑必經 `jsc-gitea:wiki` 與 `jsc-log`。全擋的話,部署一跑完就沒有路徑寫完報告,重啟閘門與報告要求互相打死。閘門不自鎖的通則見「審核檢查清單」的流程檢查第 4 項。 豁免這幾支的理由是同一件事:`jsc-meta` 四支異動技能的收尾要求把驗證結果寫進 `SKILLSET_{HASH}`,還要結清工作日誌,而這條路徑必經 `jsc-gitea:wiki` 與 `jsc-log`。全擋的話,部署一跑完就沒有路徑寫完報告,重啟閘門與報告要求互相打死。閘門不自鎖的通則見「審核檢查清單」的流程檢查第 4 項。
**狀態檔為什麼一支 CLI 一份。** 這道閘門管的是「這支 CLI 的行程還在跑舊版」,那是每支 CLI 各自的事實。初版用全機器單一檔案,2026-08-27 部署時實測出兩個後果:並行部署互相覆蓋,`cli=` 與 `domains=` 只留最後一支;更嚴重的是清除也是全域的,**任一支 CLI 重啟就解除全部五支的閘門**,其餘四支沒重啟卻不再被擋,這道閘門在多 CLI 環境等於半失效。改成 per-CLI 之後,`require` 寫自己那份、判定只看自己那份、`clear` 只刪自己那份,`report` 才列得出「哪幾支還沒重啟」。**跨 CLI 或跨工作階段的狀態檔,設計時先問清楚那個事實屬於誰**——同一類錯誤在工作包歸屬狀態檔上也踩過(見「PR 分支階梯」相關的兩層閘門分工)。
**清單認的是技能名,不是呼叫鏈。** 豁免技能轉呼叫的下一層若不在清單上,那一層照樣會被擋。後三支(`jsc-ask:ask`、`jsc-git:pr`、`jsc-git:commit`)自己不是收尾規則的主體,是為了讓前六支走得完才補進來的。`version-guard.sh` 的豁免清單當年也是為同一個原因收進 `jsc-ask:ask`。新增豁免技能時要一併想它會呼叫誰。 **清單認的是技能名,不是呼叫鏈。** 豁免技能轉呼叫的下一層若不在清單上,那一層照樣會被擋。後三支(`jsc-ask:ask`、`jsc-git:pr`、`jsc-git:commit`)自己不是收尾規則的主體,是為了讓前六支走得完才補進來的。`version-guard.sh` 的豁免清單當年也是為同一個原因收進 `jsc-ask:ask`。新增豁免技能時要一併想它會呼叫誰。
## Wiki 頁命名總表 ## Wiki 頁命名總表