Compare commits

..

5 Commits

Author SHA1 Message Date
claude-code 605f1fe5a6 Merge PR #127:ship-check 送達 + 版本 0.22.0
總管複驗並定版 0.22.0。ship-check 在 plugin 那份逐位元組等同真相源(md5 f565e4df)。
票:inkstone/ISEP#122
2026-09-02 04:02:23 +00:00
Leo f1b2ed909f 測試沙盒傳錯參數時,會把整個 tech_projects 複製進暫存區(inkstone/ISEP#122)
本輪跑迴歸測試時實撞兩次,兩次都把這台機器的磁碟寫滿:

  $ bash hooks/tests/main-and-prod-push-guard.test.sh "$PWD"
      REAL="$1" 要的是「那支 hook 的檔案路徑」,我傳了 repo 根目錄
    ⇒ hook_sandbox 不驗參數,直接 cp -R "$(dirname "$1")"
    ⇒ dirname 變成 ~/Documents/tech_projects(上一層)
    ⇒ 整個 tech_projects(所有 repo、所有 worktree)被搬進 mktemp

  實測:第一次 13 GB + 10 GB,第二次 23 GB。
        磁碟可用 25 GB → 462 MB,cp 一路吐 "No space left on device"。
        兩次都是我手動 rm -rf 才回來的(27 GB)。

🔴 而它印出來的只有一句「 沙盒建不起來」——
   沒說是參數傳錯,也沒說它已經把磁碟寫滿了。
   ⇒ 這跟本票在講的是同一句話:**閘/工具給的下一步,沒有人照著打過一次**,
     差別只在這次壞的不是逃生門,是「它壞掉時說的話」。

改法(判準是「要求某個東西在場」,不是關鍵字比對):
  ① $1 要指到一個真的檔案(空字串、目錄、不存在的路徑都不算)
  ② 它的上一層目錄名要叫 hooks(沙盒的前提就是複製一整個 hooks/)
  任一不成立 ⇒ 在 mktemp 之前 return 1,並印出走得通的那一行。

順手補上 docs/TESTING.md 之前沒寫過的一件事:**有五支測試要傳參數**,
而不傳的後果不是報錯是假綠——prod-write-guard.test.sh 的 HOOK="$1" 空掉時
每一條都執行空指令回 0 ⇒「該擋」全變成「實得 pass」,19 條假紅
(傳對參數:通過 37 / 失敗 0)。

測試:hooks/tests/hook-sandbox.test.sh 10 條(A30),通過 10 失敗 0
      ①③⑤⑥ 驗的是「收手在複製之前」,不是「訊息好不好看」
      ⑧⑨⑩ 驗正常用法沒被弄壞、複本裡沒混進 hooks/ 以外的東西
既有兩支沙盒測試複驗:
      scripts/test-main-and-prod-push-guard.sh                    13/13
      hooks/tests/main-and-prod-push-guard.test.sh          通過 10 / 失敗 0
      hooks/tests/main-and-prod-push-guard-cross-repo.test.sh 通過 19 / 失敗 0

📌 這顆跟 0.22.0 的三件事無關,是本輪路上撞到的。要拆票或丟掉這顆都行,
   它獨立於前面兩顆,而且只動 hooks/tests/(沒有任何 hook 的執行行為改變)。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-02 11:54:50 +08:00
Leo 9e76571af8 定版 v0.22.0(ship-check 送得到、逃生門走得通)
總管定版:inkstone/ISEP#122 → comment 6122。三件會改變行為的東西 ⇒ minor 進一格:
  • ship-check 的「描述」換掉——描述是 skill 自動載入的唯一判準,
    舊描述在「要發部落格文章」的情境一個觸發詞都沒有
  • 信標多了 ②b/②c(掃 skills/commands/agents;sha256 單邊驗)
  • history-first-guard.sh 的逃生門從「恆擋」變成真的能放行

順手修掉的一格(同一個病,不同檔案):
  .claude-plugin/marketplace.json 的描述停在「51 支閘/64 條註冊/27 支腳本」,
  而 plugin.json 是「61/84/49」——同一段描述兩份 manifest 各存一份,
  marketplace 那份從 7de1ad6(v0.5 前後)之後就沒人動過。
  這正是本票在講的病,只是分身這次是同一個 repo 裡的兩個 manifest。
  已同步成 plugin.json 那一份,六個數字在這棵樹上實數確認:
    61 支閘/84 條註冊/7 位工人/7 支命令/2 支 skill/49 支腳本

🔴 這顆 commit 只是把版本號寫上去。**tag 還沒打**——
   plugin.json 說 0.22.0 而最新 tag 是 v0.18.0,
   `scripts/check-version-consistency.sh` 現在是紅的,要等 v0.22.0 的 tag 打下去才會綠。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-02 11:25:07 +08:00
Leo 044ef289fe ship-check 送到得了任何 session:內容原樣搬過來,歸屬寫下來讓機器去比(inkstone/ISEP#122 → comment 6096)
## 這一份是原樣搬過來的,一個字都沒改

skills/ship-check/SKILL.md ← inkstone/InkStoneCo `bd52fa3`(PR #114,**還沒併**)
  搬完 md5 f565e4df1b18cc8aaf057f5fa64a9e15,跟來源逐位元組相同(cmp 通過)
  595 → 651 行;描述裡多了部落格/GitHub 鏡像/n8n/pages deploy 這些觸發詞
  ——舊描述那幾個詞**一個都沒有**,所以「我要發一篇部落格文章」那個情境
    根本觸發不到它,而那正是 leo 這次要解的問題。

## 為什麼不是「改成指針」也不是「ISEP 不再自帶」

雲端的 project dir 是**薄殼根**,InkStoneCo 只是它底下的一個目錄
(docs/governance/cloud-wiring.md 記著這件事)
⇒ `InkStoneCo/.claude/skills/` 在雲端**不會被載入**,只有 plugin 這一份會
⇒ ISEP 不帶全文 = 雲端拿不到 = 又變回「薄殼是真身的子集」,
   而那正是這個 repo 成立時要殺掉的病(README 開頭)。
所以 ISEP 必須帶全文,但它是**搬運工不是作者**:內容改在真相源,這裡只放複本。

## 歸屬不能靠人記得——實查證明兩個方向都會發生

skills/ 與 commands/ 那 9 個檔案在 0.1.0(c263866)從 InkStoneCo 複製過來一次,
之後**再也沒有同步過**(git log 只有那一顆)。到今天已經分家兩個,方向相反:

  skills/ship-check/SKILL.md   InkStoneCo 651 行 / ISEP 595 行   ← 那邊新
  commands/sdd-check.md        ISEP 81 行 / InkStoneCo 65 行     ← 這邊新
                               (InkStoneCo 那份還在教 ISEP#91 已退役的「唯一 active SDD」)

⇒「ISEP 一定比較新」與「InkStoneCo 一定比較新」兩句都是錯的。
  這是票上第 4 題「為什麼會有兩份」的答案:不是誰忘了同步,
  是**兩份都會被就地編輯**,而沒有任何東西會喊一聲。

## 所以機制是「寫下來 + 讓機器去比」,而且不新開一支閘

- docs/file-ownership.tsv —— 哪一份是真相源、取自哪顆 commit、當時的 sha256
- 比對長在**既有的信標**上(isep-presence-beacon.sh → hooks/lib/beacon_report.py):
  它的 ② 已經在做「同名而內容不同」這件事,只是**只掃 scripts/**。
  這次把 skills/commands/agents 一起納進去(②b),
  再加一格 ②c 用 sha256 單邊驗——**雲端沒有 InkStoneCo 可以比,那是唯一還作數的檢查**。
  🔴 刻意不開新閘:ISEP 最常見的錯是重造一支平行的閘
  (docs/governance/dispatch-and-reply-format.md §1.6 記著同一課)。

判準是「檔名一樣**而內容不同**」,同步過的不吵——誤攔比漏擋嚴重。
全部只講不擋(SessionStart 本來就不該擋人)。

## 實跑(這棵樹,真的 InkStoneCo)

  🟡 會自動載入的東西兩邊各有一份,而且內容不同:
    - skills/ship-check/SKILL.md ↔ .claude/skills/ship-check/SKILL.md
      (真相源=inkstone/InkStoneCo:… ⇒ 內容改在那裡,改完原樣搬進 ISEP、更新 commit/sha256、升版)
    - commands/sdd-check.md ↔ .claude/commands/sdd-check.md
      (真相源=ISEP 這一份 ⇒ 專案那份是舊複本,同步過去或刪掉它)

兩個方向各講對了自己的出路。

測試:hooks/tests/isep-presence-beacon.test.sh 14 → 26 條,全綠、全離線。
README/docs/hooks-inventory.md/docs/TESTING.md(A18 改 26 條、新增 A29)都跟著改了。
六個數字在這棵樹上實數:61 支閘/84 條註冊/7 位工人/7 支命令/2 支 skill/49 支腳本
——這次沒有增減,但仍然是數出來的,不是沿用上一版。

(本 commit 也帶著上一顆「逃生門」那件事的兩列文件:hooks-inventory 第 255 列與 TESTING A29。)

🔴 待總管定版:改了會被載入的東西就要升版,否則 plugin update 是 no-op。
🔴 InkStoneCo 那半不是我做的(不同 repo):那邊的 .claude/skills/ 與 .claude/commands/
   還留著兩份舊複本,該同步或刪掉;在那之前信標會每次開場點名它們。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-02 11:12:22 +08:00
Leo 5909c2a43a 逃生門要真的走得通:touch /tmp/.kbdb-down 從來沒放行過(inkstone/ISEP#122)
實撞(2026-09-02,做這張票的路上):KBDB 兩支工具都回 Connection closed,
照 history-first-guard.sh 印出來的那行 `touch /tmp/.kbdb-down` 打完再送同一個編輯,
**被一模一樣地擋第二次,訊息一字不差**。

根因(打出來的,不是推的):
    $ touch /tmp/.kbdb-down
    $ t=$(cat /tmp/.kbdb-down); echo "[$t]"        → []
    $ echo $((now - t))                            → 1788318047   ≥ 3600
  touch 造的是空檔,而那支閘讀的是**檔案內容**當時戳
  ⇒ 空字串被當成 0 ⇒「距今 17 億秒」⇒ 永遠不新鮮 ⇒ 恆擋。

⇒ 那行逃生門是印出來好看的,**沒有人照著打過一次**。
  跟本票 comment 6071(scripts/ticket 沒有 handback 這個動詞)、
  inkstone/ISEP#125(worktree 閘的逃生門原文照打 rc=2)是同一句話。

改法:內容不是數字就改用檔案的 mtime——touch 做的正是更新 mtime,
所以訊息那一行從此真的走得通;kbdb-asked-stamp.sh 寫數字的舊格式照樣相容。
路徑加 KBDB_STAMP_DIR 覆寫,只為了讓測試不去動這台機器真正的戳記
(清掉別的 session 的戳記=把閘弄成隨機的)。

沒有把閘弄鬆:過期的戳記照樣不算數(測試第 ⑦ 條守這件事),
文件/新檔/測試檔本來就不擋的三條也各有一格守著。

驗(hooks/tests/history-first-guard.test.sh,10 條,全離線):
  修好後            10/10
  修好前(路徑隔離) 9/10 —— ④「擋人的換成歷史警察了嗎」紅
  ⚠️ 第 ③ 條兩版都綠(它只驗離開碼,而過了第 0 道還有歷史警察會擋)
     真正分辨得出新舊的是 ④,檔頭寫了怎麼重現這個對照。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-02 11:11:39 +08:00
19 changed files with 631 additions and 463 deletions
+1 -1
View File
@@ -8,7 +8,7 @@
"plugins": [
{
"name": "isep",
"description": "InkStone Environment Plugin —— leo 的 Claude Code 環境唯一真相源:51 支機械閘(64 條註冊,白話盤點見 docs/hooks-inventory.md)、7 支 slash command、2 支 skill、27 支腳本,外加治理規範與標籤真相源。本機與雲端裝同一份,沒有子集。",
"description": "InkStone Environment Plugin —— leo 的 Claude Code 環境唯一真相源:61 支機械閘(84 條註冊,白話盤點見 docs/hooks-inventory.md)、7 支 slash command、2 支 skill、7 位有名字的工人(agents/,見 docs/governance/worker-roster.md)、49 支腳本,外加治理規範與標籤真相源。本機與雲端裝同一份,沒有子集。",
"author": {
"name": "Leo",
"url": "https://uncle6.me"
+1 -1
View File
@@ -1,7 +1,7 @@
{
"name": "isep",
"description": "InkStone Environment Plugin —— leo 的 Claude Code 環境唯一真相源:61 支機械閘(84 條註冊,白話盤點見 docs/hooks-inventory.md)、7 支 slash command、2 支 skill、7 位有名字的工人(agents/,見 docs/governance/worker-roster.md)、49 支腳本,外加治理規範與標籤真相源。本機與雲端裝同一份,沒有子集。",
"version": "0.21.0",
"version": "0.22.0",
"keywords": [
"inkstone",
"guardrails",
+9 -2
View File
@@ -25,8 +25,8 @@
|---|---|---|
| `hooks/` | 61 支 `hooks.json` | 全部機械閘(PreToolUseStopSubagentStopSessionStartPostToolUseUserPromptSubmit 共 84 條註冊)。**一支一行的白話盤點在 `docs/hooks-inventory.md`,那裡才是這兩個數字的家** |
| `agents/` | 7 位 | **工人名單**`inkstone/ISEP#86`)——派工時指名派給誰,規約見 `docs/governance/worker-roster.md` |
| `commands/` | 7 支 | `/wiki-recall` `/ship-check` `/cp-write` … |
| `skills/` | 2 支 | |
| `commands/` | 7 支 | `/wiki-recall` `/wiki-capture` `/cp-write` `/issue-handle` … |
| `skills/` | 2 支 | `ship-check`(東西要出去之前)/`deep-recall`(把散落的枝葉還原成一棵樹)。🔴 **這兩支的內容不一定是在這裡寫的**——誰是真相源查 `docs/file-ownership.tsv` |
| `scripts/` | 49 支 | `ticket``roster``isep-nag``wiki-compress``github-arm.sh` …(頂層檔案,不含 `lib/` 等子目錄) |
> 🔴 這五個數字**每次都要在自己的樹上實數**,不准沿用上一版、也不准用加減推
@@ -70,6 +70,13 @@ hook 一律用官方的 `${CLAUDE_PLUGIN_ROOT}`**不准寫死絕對路徑、
🔴 **只改這裡,然後兩邊 `/plugin update`。**
不要再改 `InkStoneCo/.claude/hooks/`——那個目錄退場中。
🔴 **但有些檔案的內容不是在這裡寫的**`inkstone/ISEP#122`):
`skills/``commands/``agents/` 底下有幾個檔案在 InkStoneCo 也有一份,
**誰是真相源、往哪個方向修,一律查 `docs/file-ownership.tsv`**,不要憑「ISEP 一定比較新」動手
——2026-09-02 實查,兩個方向都真的發生過(`ship-check` 是那邊新,`sdd-check` 是這邊新)。
改完那類檔案要把 commit/sha256 兩欄一起更新;沒更新的話,
`isep-presence-beacon.sh` 會在下一個 session 開場當著大家的面說它對不上。
## 這些閘各自在管什麼
**不用點開任何 `.sh`**——`docs/hooks-inventory.md` 一支一行白話,按「你會在什麼時候撞到它」分組。
+75 -51
View File
@@ -330,11 +330,19 @@ bash hooks/tests/unpushed-police.test.sh
- B 群(⑦—⑩,該報)任一紅 ⇒ 為了不吵而改成放行了,那是把閘關掉不是修好
- 特別看 ④:問不到遠端(離線)**不准當成「你沒推」**
### A18 — 信標會講出雲端會壞掉的那件事:14
### A18 — 信標會講出雲端會壞掉的那件事:26
```
bash hooks/tests/isep-presence-beacon.test.sh
```
**該看到**`通過 14 條,失敗 0 條`。全離線。
**該看到**`通過 26 條,失敗 0 條`。全離線。
> 📌 `inkstone/ISEP#122` 從 14 條加到 26 條:信標原本只掃 `scripts/`
> 而**真正會自動載入的東西**skillcommandagent)同樣兩邊各有一份。
> 實查:那 9 個檔案在 `0.1.0`(c263866)複製過來之後**一次都沒再同步**,
> 到 2026-09-02 已經分家兩個、而且**方向相反**——
> `skills/ship-check/SKILL.md` 是 InkStoneCo 那邊新,`commands/sdd-check.md` 是 ISEP 這邊新。
> ⇒ 所以新增的不只是「有沒有掃到」,還有「**說不說得出真相源是哪一份**」
> `docs/file-ownership.tsv`),以及**雲端沒有專案那一份可比時**改用 sha256 單邊驗。
**它在守什麼**inkstone/ISEP#90 ②③):信標原本只證明「有一份 plugin 載入了」,
不證明「載入的是哪一份」——08-27 雲端載 0.3.9、main 0.9.0,差 7 個 release
@@ -346,6 +354,71 @@ bash hooks/tests/isep-presence-beacon.test.sh
- ⑤⑦ 紅 ⇒ 舊複本遮蔽正門抓不到(`InkStoneCo/scripts/ticket` 那件)
- ⑥ 紅 ⇒ **誤攔**:同步過的複本被念,人就學會忽略它
- ⑪ 紅 ⇒ 內層迴圈變數撞名的回歸(同一個 `.claude` 下第二個殘骸會被靜靜跳過)
- ⑮⑱⑲⑳ 任一紅 ⇒ 自動載入的分身抓不到(`ship-check` 那件會再發生一次)
- ⑰ 紅 ⇒ **誤攔**:同步過的複本被念,人就學會忽略它(跟 ⑥ 同一條線)
- ㉔ 紅 ⇒ 雲端唯一還作數的那個檢查失效(薄殼沒有 InkStoneCo 可以比)
- ㉕ 紅 ⇒ **誤攔**:還沒登記 sha256 的檔案被當成「被改過」
### A29 — 閘印出來的逃生門,照著打真的過得去:10 條
> 📌 編號跳過 A27/A28:那兩格被同一張票的 PR `inkstone/ISEP#124` 佔著(還沒併)。
```
bash hooks/tests/history-first-guard.test.sh
```
**該看到**`通過 10 條,失敗 0 條`。全離線,全程用 `KBDB_STAMP_DIR` 指到 TMP
**不碰這台機器真正的 `/tmp/.kbdb-*` 戳記**(清掉別人的戳記=把閘弄成隨機的)。
**它在守什麼**`inkstone/ISEP#122`2026-09-02 實撞):`history-first-guard.sh` 印的
`🚪 KBDB 真的連不上:touch /tmp/.kbdb-down 後重送` 是**假的**——
`touch` 造出來的是空檔,而那支閘讀的是**檔案內容**當時戳,空字串被當成 0
⇒ 「距今 17 億秒」⇒ 永遠不新鮮 ⇒ **照著訊息打完,被一模一樣地擋第二次**
🔴 這跟本票 comment 6071、`inkstone/ISEP#125` 是同一句話:
**閘印出來的下一步,沒有人實際照著打過一次。**
**失敗**
- ④ 紅 ⇒ 逃生門又是假的(這是本支唯一分辨得出新舊版的那一格,見檔頭)
- ⑦ 紅 ⇒ 逃生門變成永久後門(一次 `touch` 就免疫,過期不算數這件事沒了)
- ⑧⑨⑩ 任一紅 ⇒ **誤攔**:文件/新檔/測試檔本來就不該被這支碰
### A30 — 測試沙盒傳錯參數時要在**複製之前**收手:10 條
```
bash hooks/tests/hook-sandbox.test.sh
```
**該看到**`通過 10 條,失敗 0 條`。全離線。
**它在守什麼**`inkstone/ISEP#122`2026-09-02 實撞,**兩次**):
`hooks/tests/lib/hook-sandbox.sh``hook_sandbox <hook 的檔案路徑>` 舊版**不驗參數**
直接 `cp -R "$(dirname "$1")"`。順手把 repo 根目錄傳進去時:
```
$ bash hooks/tests/main-and-prod-push-guard.test.sh "$PWD"
dirname → ~/Documents/tech_projects ← 上一層,不是 hooks/
cp -R → 整個 tech_projects(所有 repo、所有 worktree)搬進 mktemp
實測 一次 13 GB+一次 10 GB,磁碟可用從 25 GB 掉到 462 MB
印出來的 ❌ 沙盒建不起來 ← 只有這一句
```
🔴 **它沒說參數傳錯,也沒說它已經把磁碟寫滿了。**
判準用「要求某個東西在場」(`$1` 要是真的檔案;上一層要叫 `hooks`),
不是關鍵字比對——兩條任一不成立就在 `mktemp` 之前 `return 1`
📌 **正確用法**(兩支需要傳參數的測試,`docs/TESTING.md` 之前沒寫過):
```
bash hooks/tests/main-and-prod-push-guard.test.sh hooks/main-and-prod-push-guard.sh
bash hooks/tests/main-and-prod-push-guard-cross-repo.test.sh hooks/main-and-prod-push-guard.sh
bash hooks/tests/prod-write-guard.test.sh hooks/prod-write-guard.sh
bash hooks/tests/stage-before-prod-guard.test.sh hooks/stage-before-prod-guard.sh
bash hooks/tests/gitea-arm-check.test.sh .
```
**不傳的後果不是報錯,是假綠**`prod-write-guard.test.sh``HOOK="$1"` 空掉時
每一條都執行空指令回 0 ⇒ 「該擋」全部變成「實得 pass」,**19 條假紅**
(同一支傳對參數是 `通過 37 失敗 0`)。不必自己傳參數的包裝在
`scripts/test-main-and-prod-push-guard.sh`
**失敗**
- ①③⑤⑥ 任一紅 ⇒ 收手收得太晚,暫存區已經開始長東西(磁碟風險回來了)
- ② 紅 ⇒ 訊息沒給出走得通的那一行(本票整張票在講的就是這件事)
- ⑧⑨⑩ 任一紅 ⇒ **誤攔/複製錯**:正常用法被弄壞,或複本裡混進了 `hooks/` 以外的東西
### A19 — 下游做完時頂層跟著關:49 條
```
bash scripts/test-ticket-handoff-writeback.sh
@@ -605,55 +678,6 @@ B 段拿這台機器真正的 `.env` 對帳——**`.env` 不在的機器(雲
> ```
> ⇒ 第二條正是黑名單會放過去的形狀。
### A27 — 一次性戳記真的能放行一次:重複掛載清乾淨了,也不會靜靜復發(`inkstone/ISEP#122`
```
bash hooks/tests/duplicate-hook-registration-guard.test.sh
bash hooks/tests/kv-write-guard.test.sh
```
**該看到**:兩支各自 `8 通過 / 0 失敗`。全程用假的 plugin root/專案目錄,
不碰真正的 `InkStoneCo/.claude/` 或這台機器裝著的 ISEP plugin。
**它們在守什麼**2026-09-01 實撞):總管三次要部署 uncle6.me,三次被
`prod-write-guard.sh` 恆擋——蓋了戳記、確認戳記還在,執行動作時照樣被擋,
再看戳記已經不見。根因:`InkStoneCo/.claude/settings.json` 還登記著一份
2026-08-20 立 ISEP plugin 之前的舊 hook(那時 `.claude/hooks/` 是唯一的家),
跟 plugin 自己的 `hooks.json` 同時掛在同一個 `PreToolUse` 事件上——每個動作
都跑了**兩次**,一次由專案版、一次由 plugin。多數閘只是白跑一次沒感覺,
但一次性戳記(蓋了就消耗掉)被第一份吃光,第二份永遠看到空戳記,於是恆擋。
**實查結果**(在這台機器的樹上實數,不是推算):`InkStoneCo/.claude/settings.json`
登記著 38 支專案版 hook——**34 支跟 plugin 完全同名同用途**(純殘骸)、
**3 支是已經退役的機制**`claim-verify-police.sh``subagent-claim-worksheet.sh`
`sdd-guard.sh``inkstone/ISEP#60``#91` 早已裁定退役,但專案版沒有跟著退),
**1 支(`kv-write-guard.sh`)是專案版有、plugin 當時沒有的真閘**2026-08-25
立,長效資料不准寫進 KV)。前 37 支已從 `InkStoneCo/.claude/settings.json`
`.claude/hooks/` 刪除;第 38 支原樣搬進本 repo(同一輪 commit,見 B 組)。
**失敗**
- `kv-write-guard.test.sh` 任一「該擋」紅 ⇒ 搬過來時邏輯改壞了,
KV 寫入的偵測失靈
- `kv-write-guard.test.sh` 任一「不該擋」紅 ⇒ 誤攔,這比漏擋嚴重——
正常的 `.get`/退休戰的刪除/`kv-ok` 豁免都要放得過
- `duplicate-hook-registration-guard.test.sh` 的「該吵」任一紅 ⇒
重複掛載又會靜靜發生,**下一次會是另一支帶戳記語意的閘恆擋,
而且要等 leo 自己撞到才會被發現**
- `duplicate-hook-registration-guard.test.sh` 的「不該吵」任一紅 ⇒
誤攔,每個 session 開場都吵一次沒問題的環境,最後被學會忽略
### A28 — 收工前的實測:蓋一次戳記真的只用得掉一次(手動,這台機器)
這一格驗的是**行為**,不是**檔案**——上面兩支測試證明「新機制自己邏輯對」,
這格證明「舊的重複掛載真的被拆掉了」。在**新開**的 session 裡跑(PreToolUse hook
是 session 啟動時載入的常駐清單,同一支閘改完不會讓已經在跑的 session 重新讀):
```
bash "$CLAUDE_PLUGIN_ROOT/scripts/gate-ok" prod-write # 蓋一次戳記
# 執行一個會被 prod-write-guard.sh 擋的動作(例如 wrangler pages deploy 打非白名單目標)
```
**該看到**:蓋戳記那個會被擋的動作**這次放行**(① 蓋一次戳記 → ② 動作通過);
不蓋戳記重跑同一個動作 → **仍然被擋**(證明沒有把閘弄鬆,只是不再被自己的複本吃掉)。
**失敗**:蓋了戳記仍被擋 ⇒ 還有第三份複本沒清乾淨,去跑
`bash "$CLAUDE_PLUGIN_ROOT/hooks/duplicate-hook-registration-guard.sh"`
(或直接開一個新 session 看它開場有沒有吵)先定位是哪一份。
### A5 — 開票前的搜尋是跨 repo 的
```
python3 scripts/ticket where 標籤 模組化
+30
View File
@@ -0,0 +1,30 @@
# file-ownership.tsv — 同一個檔案兩邊都有時,**哪一份是真相源**inkstone/ISEP#122
#
# 為什麼要有這張表(2026-09-02 實查,兩個方向都真的發生過):
# skills/ship-check/SKILL.md InkStoneCo 那份前進到 651 行,ISEP 停在 595 行
# commands/sdd-check.md ISEP 那份前進到 81 行,InkStoneCo 停在 65 行
# InkStoneCo 那份還在教已經退役的「唯一 active SDD」)
# ⇒ 「ISEP 一定比較新」是錯的,「InkStoneCo 一定比較新」也是錯的。
# 兩邊都會被就地編輯,所以歸屬**不能靠人記得**,要寫下來、而且要有東西去比對。
#
# 誰在用這張表:`hooks/lib/beacon_report.py`SessionStart 信標,只報告、不擋人)
# ① 兩邊內容不同時 → 照這張表講出「真相源是哪一份、該往哪個方向修」
# ② 表上有 sha256 時 → 順便驗 ISEP 這份有沒有被就地改過(雲端沒有 InkStoneCo
# 可以比,這一格是那時唯一還能作數的檢查)
#
# 規約三條:
# 1. **只有內容會分家的檔案才需要一列。** 兩邊一模一樣時不必登記,信標也不會出聲。
# 2. 真相源是 `inkstone/InkStoneCo` ⇒ **內容要改就改在那裡**,改完把檔案原樣搬過來、
# 更新 ④⑤ 兩欄、升版。**不要在 ISEP 這邊改內容**(改了兩邊就各自演化,就是本表要解的病)。
# 3. 真相源是 `inkstone/ISEP` ⇒ 專案那份是退場中的舊複本,該被同步或刪掉;
# ③④⑤ 三欄填 `-`。
#
# 欄位(TAB 分隔,5 欄):
# ① plugin 內路徑
# ② 真相源 repo
# ③ 真相源在那個 repo 裡的路徑(真相源就是 ISEP 時填 `-`)
# ④ 這一份是從哪顆 commit 搬過來的(同上,填 `-`)
# ⑤ 搬過來的當下 sha256(同上,填 `-`)
#
skills/ship-check/SKILL.md inkstone/InkStoneCo .claude/skills/ship-check/SKILL.md bd52fa3a508cbfb29755ddc24923c6fea8c3fbf7 847967830007e804a16dec9adfc5d4120c233445649d4d5cdd34b04550fb3270
commands/sdd-check.md inkstone/ISEP - - -
1 # file-ownership.tsv — 同一個檔案兩邊都有時,**哪一份是真相源**(inkstone/ISEP#122)
2 #
3 # 為什麼要有這張表(2026-09-02 實查,兩個方向都真的發生過):
4 # skills/ship-check/SKILL.md InkStoneCo 那份前進到 651 行,ISEP 停在 595 行
5 # commands/sdd-check.md ISEP 那份前進到 81 行,InkStoneCo 停在 65 行
6 # (InkStoneCo 那份還在教已經退役的「唯一 active SDD」)
7 # ⇒ 「ISEP 一定比較新」是錯的,「InkStoneCo 一定比較新」也是錯的。
8 # 兩邊都會被就地編輯,所以歸屬**不能靠人記得**,要寫下來、而且要有東西去比對。
9 #
10 # 誰在用這張表:`hooks/lib/beacon_report.py`(SessionStart 信標,只報告、不擋人)
11 # ① 兩邊內容不同時 → 照這張表講出「真相源是哪一份、該往哪個方向修」
12 # ② 表上有 sha256 時 → 順便驗 ISEP 這份有沒有被就地改過(雲端沒有 InkStoneCo
13 # 可以比,這一格是那時唯一還能作數的檢查)
14 #
15 # 規約三條:
16 # 1. **只有內容會分家的檔案才需要一列。** 兩邊一模一樣時不必登記,信標也不會出聲。
17 # 2. 真相源是 `inkstone/InkStoneCo` ⇒ **內容要改就改在那裡**,改完把檔案原樣搬過來、
18 # 更新 ④⑤ 兩欄、升版。**不要在 ISEP 這邊改內容**(改了兩邊就各自演化,就是本表要解的病)。
19 # 3. 真相源是 `inkstone/ISEP` ⇒ 專案那份是退場中的舊複本,該被同步或刪掉;
20 # ③④⑤ 三欄填 `-`。
21 #
22 # 欄位(TAB 分隔,5 欄):
23 # ① plugin 內路徑
24 # ② 真相源 repo
25 # ③ 真相源在那個 repo 裡的路徑(真相源就是 ISEP 時填 `-`)
26 # ④ 這一份是從哪顆 commit 搬過來的(同上,填 `-`)
27 # ⑤ 搬過來的當下 sha256(同上,填 `-`)
28 #
29 skills/ship-check/SKILL.md inkstone/InkStoneCo .claude/skills/ship-check/SKILL.md bd52fa3a508cbfb29755ddc24923c6fea8c3fbf7 847967830007e804a16dec9adfc5d4120c233445649d4d5cdd34b04550fb3270
30 commands/sdd-check.md inkstone/ISEP - - -
+4 -23
View File
@@ -1,4 +1,4 @@
# 63 支閘,白話盤點表
# 61 支閘,白話盤點表
> 回應 `inkstone/InkStoneCo#40`:「如果加入了,我應該可以白話文看到 hooks 的內容?」
> 這份表就是那個「白話文」——不用點開任何 `.sh` 檔,一行看懂一支閘在管什麼。
@@ -7,27 +7,10 @@
## 一句話結論
`hooks/` 底下有 **63 個 `.sh` 檔**`hooks.json` 實際掛上 **86 條註冊**(同一支閘常被多種情境同時掛上);
`hooks/` 底下有 **61 個 `.sh` 檔**`hooks.json` 實際掛上 **84 條註冊**(同一支閘常被多種情境同時掛上);
其中 **3 支檔案存在但沒被掛上**(2 支是待人填的空範本、1 支是刻意留著沒開的止血帶,見下面「未生效」表)。
下面按「你會在什麼時候撞到它」分組,一支一行。
> 📌 **`inkstone/ISEP#122`2026-09-02)進來兩支、+2 條**`kv-write-guard.sh`B 組,
> 2026-08-25 立於 InkStoneCo 專案版,原樣搬進來)與 `duplicate-hook-registration-guard.sh`
> (E 組,這次新寫)。61→**63** 支、84→**86** 條,兩個數字都是加完之後**在自己的樹上當場數出來的**
> `ls hooks/*.sh | wc -l``grep -c '"command":' hooks/hooks.json`),不是拿上一版加二。
>
> 這張票查的是「總管三次要部署被 `prod-write-guard.sh` 恆擋、蓋了戳記也放不了行」,
> 根因不在 `prod-write-guard.sh` 本身,而在 `InkStoneCo/.claude/settings.json`
> 還登記著一份跟 ISEP plugin 同名的舊 hook——每個 `PreToolUse` 事件都跑了**兩次**
> 一次性戳記被第一份消耗掉,第二份永遠看到空戳記、恆擋。實查:專案版登記著 38 支,
> **34 支跟 plugin 完全同名同用途**(純殘骸,已從 `InkStoneCo/.claude/settings.json`
> 刪除登記)、**3 支是已經退役的機制**`claim-verify-police.sh`
> `subagent-claim-worksheet.sh``sdd-guard.sh`,同樣刪除)、
> **1 支(`kv-write-guard.sh`)是專案版有、plugin 當時沒有的真閘**——原樣搬進本 repo,
> 這就是這次 B 組新增的那一支。`duplicate-hook-registration-guard.sh` 是防復發的機械閘:
> 下次任何專案的 `settings.json` 又長出跟 plugin 同名的登記,SessionStart 就會點名,
> 不必再靠「戳記莫名其妙失效」這種事後除錯才發現。
>
> 🔴 **這兩個數字上一版是錯的(2026-08-26 實際數過才發現)**:本頁原本寫「43 個檔、53 條註冊」,
> 而當時真實是 **45 個檔、55 條註冊**——中間有兩支閘進來時沒有回頭改這裡。
> 現在的寫法是實際數出來的:
@@ -162,7 +145,6 @@
| `mistake-needs-ticket-guard.sh` | AI 想往 `mistakes.md`(教訓紀錄)新增一條「機制可以防止」的教訓,卻沒附對應票號就擋下——沒有票號的教訓沒有人會回頭處理。 | 🛑 擋 |
| `wiki-size-guard.sh` | AI 想**一口氣砍掉 wiki 檔一大半內容**(淨縮水超過 800 字且超過原本 45%)就擋一次——那不是一次編輯,那是一次壓縮,而**壓縮會弄丟東西,弄丟的當下沒有人會發現**。出路是走 `scripts/wiki-compress`:它逼你附票號、把壓掉了什麼寫進 `.compress-log.md`,並用內文雜湊**逐條對帳**證明沒弄丟。只是改字、加字、小修一律不碰;真要手改就在內容裡放 `wiki-compress-ok` 留痕。 | 🛑 擋(至多攔一次) |
| `pending-changes-retired.sh` | AI 想寫東西進已經廢除的 `pending-changes.md` 檔案就擋下——這個檔案已停用,規格變更一律改開 Gitea 票。 | 🛑 擋 |
| `kv-write-guard.sh` | AI 想新增一行「往 KV 綁定寫入」的程式碼(`大寫識別字.put(``.delete(`)就擋下——長效資料一律要走 KBDB API,KV 只是暫存。判準是形狀(全大寫識別字 + `.put``.delete`),不是列名字清單;只讀(`.get``.list`)放行,刪除既有 KV 寫入(退休戰)也放行。真的是短命資料(session/nonce/有 TTL 的快取)在那一行尾端加 `kv-ok: <為什麼>` 留痕放行。2026-08-25 立於 InkStoneCo 專案版,`inkstone/ISEP#122` 原樣搬進本 repo。 | 🛑 擋 |
> 🔴 **`sdd-guard.sh` 已於 `inkstone/ISEP#91` 退役**(原本掛在這一組)。
> 它擋的是「動 code 檔時,`status: active` 的 SDD 不是恰好一份」。
@@ -221,13 +203,12 @@
| 閘名 | 對你意味著什麼 | 動作 |
|---|---|---|
| `isep-presence-beacon.sh` | 對話一開始印一行 `🟢 ISEP vX.Y.Z 已載入(N 支閘|來源:…)`。**這行不是裝飾,是唯一能證明「這個 session 真的有閘」的東西**——它自己就住在 plugin 裡,看得到它就表示 plugin 載入了;某個 session 從頭到尾沒有這行,那個 session 是零閘狀態,先修 plugin 再做事。同一台機器可能同時有兩份 ISEP(marketplace 裝的、repo 裡 vendor 的),所以那行會講出這次是哪一份在說話。 | 📝 記錄(context 注入) |
| `isep-presence-beacon.sh` | 對話一開始印一行 `🟢 ISEP vX.Y.Z 已載入(N 支閘|來源:…)`。**這行不是裝飾,是唯一能證明「這個 session 真的有閘」的東西**——它自己就住在 plugin 裡,看得到它就表示 plugin 載入了;某個 session 從頭到尾沒有這行,那個 session 是零閘狀態,先修 plugin 再做事。同一台機器可能同時有兩份 ISEP(marketplace 裝的、repo 裡 vendor 的),所以那行會講出這次是哪一份在說話。它另外會報四件「這一份是不是還有效」:①這一份落後 ISEP main 幾版 ②專案裡有沒有內容不同的同名**腳本**②b 專案裡有沒有內容不同的同名**skillcommandagent**——這些是**自動載入**的,載到舊的那份不會有任何症狀,只會安靜地教錯的東西(`docs/file-ownership.tsv` 說得出每一組的真相源是哪一份、往哪個方向修)②c 本身的內容跟那張歸屬表對不對得上(雲端沒有專案那一份可比時,這是唯一還作數的檢查)③工作區有沒有已退役機制留下的產物。**全部只講不擋。** | 📝 記錄(context 注入) |
| `session-start-recall.sh` | 對話一開始就自動把「全局現況」(Gitea 各 repo 的票、KBDB 的藏書地圖)推到 AI 眼前,不必等它自己想到要查。 | 📝 記錄(context 注入) |
| `scripts/mainline refresh` | (不是閘,是腳本)對話一開始把**現在的主線**那條 milestone 的進度與期限更新一次,好讓每回合眼前那一行講的是今天的數字。拿不到 Gitea 就原封不動——**寧可資料舊,不要把主線弄丟**。跑一次就結束,不輪詢。 | 📝 記錄 |
| `overdue-nag-guard.sh` | 對話一開始就去 Gitea 撈**沒有人會叫的事**:逾期的 milestone、掛著等你的票(標「等了幾天」)、標著「有人在做」卻好幾天沒動的票;撈完用白話講出來,**有事就發 Telegram 給你**。沒東西可報時它會說「查過了,沒有」——**安靜跟壞掉長得一模一樣**。發不出去時不會靜默:它會先問這個 session 的 `prod-write-guard` 會不會擋(舊版把「發通知」誤認成「部署」),擋就改貼回票上並把原文印在眼前。只在開 session 時跑一次,**不輪詢、不掛排程**。 | 📝 記錄(context 注入 Telegram |
| `wiki-size-guard.sh` | 對話一開始講出「哪幾個 wiki 檔已經沒有人讀得完了」(預設超過 1200 行就點名)。**讀不完的必讀檔,跟沒有那個檔的差別只在於它讓人以為有。** 另一半掛在寫檔上,見 B 組。 | 📝 記錄(context 注入) |
| `skill-deploy-drift-guard.sh` | 如果「全機真正在用的 skill」跟「repo 裡版控的正本」內容對不上,就在開場講出來——避免用著一份沒人知道已經跟正本分家的舊拷貝。 | 📝 記錄 |
| `duplicate-hook-registration-guard.sh` | 如果這個專案自己的 `.claude/settings.json` 還登記著跟 ISEP plugin 同名的舊 hook,就在開場點名是哪幾支——**同一個動作跑兩次**,多數閘只是白跑,但帶「蓋一次戳記只放行一次」語意的閘會被第一份吃光,第二份永遠看到空戳記、恆擋(`inkstone/ISEP#122` 就是這樣,2026-09-01 撞了三次才被抓到)。判準是「有沒有真的註冊」,不是「檔案存不存在」。 | 📝 記錄(context 注入) |
## F. AI 想結束這一輪、要收工的時候(Stop)
@@ -271,7 +252,7 @@
| 閘名 | 對你意味著什麼 | 動作 |
|---|---|---|
| `history-first-guard.sh` | AI 要改一個舊檔案之前,先把這個檔案過去被改過幾次、被誰在什麼情況下改過的紀錄攤在它眼前,逼它回答「這是不是已經修過的老問題」再動手。 | 🛑 擋 |
| `history-first-guard.sh` | AI 要改一個舊檔案之前,先把這個檔案過去被改過幾次、被誰在什麼情況下改過的紀錄攤在它眼前,逼它回答「這是不是已經修過的老問題」再動手。前面還有第 0 道:這一小時內有沒有問過 KBDB。**KBDB 連不上時 `touch /tmp/.kbdb-down` 就放行**——這條逃生門 2026-09-02 之前是壞的(`touch` 造的是空檔,而它讀的是檔案內容)**照著訊息打完還是被擋**,`inkstone/ISEP#122` 修好並補了迴歸測試。 | 🛑 擋 |
---
@@ -1,68 +0,0 @@
#!/usr/bin/env bash
# duplicate-hook-registration-guard.sh — SessionStart:這個專案自己的 .claude/settings.json
# 是不是還在登記一支跟 ISEP plugin 同名的舊 hookinkstone/ISEP#122
#
# 為什麼存在(2026-09-01 實撞):
# 總管三次要部署 uncle6.me,三次被 prod-write-guard.sh 擋。leo 問「你沒有權限?」
# ——不是沒權限,是 InkStoneCo/.claude/settings.json 裡還留著 ISEP 立 plugin 之前
# 的舊登記,跟 plugin 自己的 hooks.json 同時掛在同一個事件上,於是每個 PreToolUse
# 都跑了**兩次**:一次由專案版、一次由 plugin。多數閘只是白跑一次沒感覺,
# 但**帶「蓋一次戳記只放行一次」語意的閘會被第一份吃光**——第二份永遠看到空的戳記,
# 於是恆擋。查證見 ISEP#122:37 支專案版登記裡,34 支跟 plugin 完全同名同用途、
# 3 支是已經退役的機制(`claim-verify-police.sh``subagent-claim-worksheet.sh`
# `sdd-guard.sh`),全部清掉;剩下 1 支(`kv-write-guard.sh`)是專案版有、plugin
# 當時沒有的真閘,已原樣搬進本 repo(同一輪 commit)。
#
# 🔑 這支 hook 的用途不是清除,是**讓「又長出重複掛載」這件事有人立刻知道**。
# 上一次它能存活 13 天沒被發現,就是因為除了「戳記莫名其妙失效」以外沒有任何
# 訊號會指出來——一支天天在跑的閘,跟一支不存在的閘,行為長得一模一樣。
#
# 三條設計約束(跟 skill-deploy-drift-guard.sh 同一個形狀):
# 1. 沒事不出聲——乾淨時完全靜音。
# 2. 從不擋人——SessionStart 一律 exit 0,這是通知,不是閘。
# 3. 判準是「登記在不在」,不是關鍵字——比對的是 hooks.jsonsettings.json
# 裡實際出現的檔名,不是靠猜或列黑名單(isep-hand 紅線:不准用關鍵字黑名單)。
set -uo pipefail
ROOT="${CLAUDE_PLUGIN_ROOT:-}"
[ -n "$ROOT" ] || exit 0
[ -f "$ROOT/hooks/hooks.json" ] || exit 0
PROJ="${CLAUDE_PROJECT_DIR:-}"
[ -n "$PROJ" ] || exit 0
SETTINGS="$PROJ/.claude/settings.json"
[ -f "$SETTINGS" ] || exit 0
# ISEP plugin 自己「真的註冊了」的 hook 檔名(不是目錄列表——目錄裡可能有沒掛的樣板)
PLUGIN_NAMES="$(grep -oE 'hooks/[a-zA-Z0-9._-]+\.sh' "$ROOT/hooks/hooks.json" 2>/dev/null \
| sed 's|.*/||' | sort -u)"
[ -n "$PLUGIN_NAMES" ] || exit 0
# 這個專案自己的 settings.json 裡,指向 .claude/hooks/ 底下的登記
PROJECT_NAMES="$(grep -oE '\.claude/hooks/[a-zA-Z0-9_.-]+\.sh' "$SETTINGS" 2>/dev/null \
| sed 's|.*/||' | sort -u)"
[ -n "$PROJECT_NAMES" ] || exit 0
DUPES="$(comm -12 <(printf '%s\n' "$PLUGIN_NAMES") <(printf '%s\n' "$PROJECT_NAMES") 2>/dev/null || true)"
[ -n "$DUPES" ] || exit 0
N=$(printf '%s\n' "$DUPES" | grep -c .)
LIST="$(printf '%s\n' "$DUPES" | sed 's/^/ • /')"
cat <<EOF
🔁 重複掛載警報:\`$SETTINGS\` 還登記著 ${N} 支跟 ISEP plugin 同名的舊 hook。
$LIST
⇒ 每個對應的動作都會**跑兩次**——一次由這份專案版複本、一次由 plugin。
多數閘只是白跑一次;**帶「蓋一次戳記只放行一次」語意的閘會被第一份吃光**,
第二份永遠看到空戳記,於是恆擋——這正是 inkstone/ISEP#122 那次的形狀。
出路(二選一,不是「留著沒關係」):
① 這幾支 plugin 已經覆蓋 → 從 \`$SETTINGS\` 的 hooks 區段刪掉這幾條登記。
② 專案版身上還有 plugin 沒有的邏輯 → 先把那段邏輯併進 ISEP(開票、比照
kv-write-guard.sh 那次的搬法),plugin 升版裝上之後再刪專案版登記。
**不要讓兩份同時掛著**——那正是這支閘存在的理由。
EOF
exit 0
+23 -6
View File
@@ -56,15 +56,32 @@ STAMP="/tmp/.history-guard-$(printf '%s' "$FILE_PATH" | shasum | cut -c1-12)"
#
# 時戳由 kbdb-asked-stamp.shPostToolUsematcher 對 kbdb_* 工具)寫下。
# 逃生口:KBDB 真的連不上時 `touch /tmp/.kbdb-down`——放行但留痕,且回覆裡要說明。
KBDB_STAMP=/tmp/.kbdb-asked
KBDB_DOWN=/tmp/.kbdb-down
#
# 🔴 **逃生門要真的走得通**inkstone/ISEP#1222026-09-02 實撞,本檔第二次修):
# 上面那句訊息叫人 `touch /tmp/.kbdb-down`,而 `touch` 造出來的是**空檔**
# ⇒ 舊版 `t=$(cat "$f")` 讀到空字串 ⇒ 算式當成 0 ⇒ 「距今 17 億秒」
# ⇒ 永遠不新鮮 ⇒ **照著訊息打完,還是被擋**。
# 實測(2026-09-02KBDB 兩支工具都回 Connection closed 時):
# $ touch /tmp/.kbdb-down → 再送同一個編輯 → 一模一樣的擋,訊息一字不差
# ⇒ 那行逃生門是印出來好看的,**沒有人照著打過一次**
# (同族:ISEP#125 worktree 閘印的逃生門原文照打 rc=2;本票 comment 6071)。
#
# 改法:**內容不是數字就用檔案的 mtime**——`touch` 做的正是更新 mtime
# 所以訊息裡那一行從此真的走得通,而 `kbdb-asked-stamp.sh` 寫數字的舊格式照樣相容。
# 路徑用 `KBDB_STAMP_DIR` 可覆寫,**只為了讓迴歸測試不去動這台機器真正的戳記**
# (測試把別的 session 的戳記清掉=把閘弄成隨機的)。
KBDB_STAMP="${KBDB_STAMP_DIR:-/tmp}/.kbdb-asked"
KBDB_DOWN="${KBDB_STAMP_DIR:-/tmp}/.kbdb-down"
kbdb_fresh=0
now=$(date +%s)
for f in "$KBDB_STAMP" "$KBDB_DOWN"; do
if [ -f "$f" ]; then
t=$(cat "$f" 2>/dev/null || echo 0)
[ $((now - t)) -lt 3600 ] && kbdb_fresh=1
fi
[ -f "$f" ] || continue
t=$(cat "$f" 2>/dev/null || true)
case "$t" in
''|*[!0-9]*) t=$(date -r "$f" +%s 2>/dev/null || stat -c %Y "$f" 2>/dev/null || echo 0) ;;
esac
[ "${t:-0}" -gt 0 ] || continue
[ $((now - t)) -lt 3600 ] && kbdb_fresh=1
done
if [ "$kbdb_fresh" -eq 0 ]; then
cat >&2 <<'KEOF'
-8
View File
@@ -126,10 +126,6 @@
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/wiki-size-guard.sh"
},
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/kv-write-guard.sh"
}
]
},
@@ -292,10 +288,6 @@
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/wiki-size-guard.sh"
},
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/duplicate-hook-registration-guard.sh"
}
]
}
+2 -1
View File
@@ -16,5 +16,6 @@
# KBDB(一次看所有庫,最便宜)→ 該 repo 的 wiki/tasks → git log -S → 讀源碼(最貴,
# 只看得到「現在長怎樣」,看不到「為什麼變成這樣」)
set -eu
date +%s > /tmp/.kbdb-asked
# 路徑跟 history-first-guard.sh 用同一個覆寫變數,否則測試會兩邊指到不同地方
date +%s > "${KBDB_STAMP_DIR:-/tmp}/.kbdb-asked"
exit 0
-115
View File
@@ -1,115 +0,0 @@
#!/bin/bash
# PreToolUse hookWrite|Edit|MultiEdit)— 長效資料不准寫進 KV,一律走 KBDB API
#
# 【portage 記錄,inkstone/ISEP#122】本檔 2026-08-25 立於
# `InkStoneCo/.claude/hooks/kv-write-guard.sh`(那時 ISEP 還沒吸收它),
# 2026-09-02 原樣搬進 ISEP——它是那次盤點揪出來的**唯一一支**「專案版有、
# plugin 沒有」的真閘(另外 3 支同名殘骸是已退役機制,直接刪掉,不搬)。
# 搬完之後 `InkStoneCo/.claude/hooks/kv-write-guard.sh` 就是廢棄複本,
# 待這裡升版、`/plugin update` 裝上之後即可從專案版與 settings.json 一併移除。
#
# 【leo 2026-08-25 立】原話(三句,一句比一句尖):
# 「已經禁止寫入 KV 了,這是太貴的資源,應該都去寫入 KBDB,到底寫入 KV 做什麼?」
# 「上次刪掉一堆東西,現在又寫入,**你沒有規範嗎**」
# 「**我強制禁止寫 SQL,要用 KBDB API,你就讓它繞過寫 KV 代替?**」
#
# ── 為什麼存在(2026-08-25 實查,這是本閘的正身)─────────────────────────
# 規則早就在:`system-dev/wiki/decisions-summary.md:133`
# 「**KV =暫存(cache / transient),不是長期真相源。**」
# 而且打過一場「KV 退休戰」(同檔 254 行,SUBMISSIONS_KV 併入那一役)。
#
# 🔴 **但 `.claude/hooks/` 底下跟 KV 有關的閘:0 支。**
# ⇒ 規則被讀到了,卻沒有任何機制驗證有沒有照做——與 2026-08-25 一整天挖出來的
# 四層 migration 缺陷、以及 08-10 抓到的 history-firstKBDB-firststage-first
# **完全同一個形狀**。
#
# 🔴 **更糟的是 leo 指出的因果**(總管用 git 查證屬實):
# 禁 SQL 的牆 2026-08-07
# app-system.ts 誕生 2026-08-24 ← 17 天之後,**從第一行就在寫 KV**
# 而 `kbdbFetch()` 裡的 KV 字樣是 **0** ⇒ 走 KBDB API 根本不碰 KV
# ⇒ 那些 KV 寫入**每一處都是繞過**,沒有一處經過知識庫。
# **牆立起來了,水從旁邊流走了。**
#
# ── 判準(封動作,不封措辭)──────────────────────────────────────────
# 新增一行「往 KV 寫入」的程式碼 ⇒ 擋一次,要求說明它為什麼不是長效資料
# 只是讀(.get.list ⇒ 放行
# 刪除既有的 KV 寫入(退休戰) ⇒ 放行(那正是我們要的方向)
#
# ── 豁免(留痕,不是後門)────────────────────────────────────────────
# 那一行尾端加 `kv-ok: <理由>`。
# 合法的理由只有一種形狀:**這筆資料本來就是短命的**(session、一次性 nonce、
# 有 TTL 的快取)。寫「暫時先這樣」「之後再搬」都不算——
# 那是把債留給下一個人,而 2026-08-25 證明了沒人會回來還。
set -uo pipefail
payload=$(cat)
read -r tool content file <<<"$(printf '%s' "$payload" | python3 -c "
import json,sys
try:
d=json.load(sys.stdin); ti=d.get('tool_input') or {}
# Write 用 contentEdit 用 new_stringMultiEdit 把每筆 new_string 串起來
parts=[ti.get('content') or '', ti.get('new_string') or '']
for e in (ti.get('edits') or []): parts.append(e.get('new_string') or '')
body='\n'.join(p for p in parts if p)
print(d.get('tool_name','') or 'x', len(body), ti.get('file_path','') or 'x')
sys.stderr.write(body)
except Exception:
print('x 0 x')
" 2>/tmp/.kv-guard-body)" || exit 0
body=$(cat /tmp/.kv-guard-body 2>/dev/null)
rm -f /tmp/.kv-guard-body
[ -z "$body" ] && exit 0
# 只管程式碼檔;文件、設定、測試裡提到 KV 不算違規
case "$file" in
*.ts|*.js|*.mjs|*.tsx|*.jsx) ;;
*) exit 0 ;;
esac
# 閘自己、與退休戰的測試檔放行(否則永遠改不動它)
case "$file" in
*kv-write-guard*|*.test.*|*/tests/*) exit 0 ;;
esac
# 命中的行:往 KV 綁定寫入,且**該行沒有 kv-ok 豁免**
# 判準是形狀不是名字:**全大寫的 binding 後面接 .put(.delete(**。
# 為什麼不列名字清單(第一版就是這樣寫壞的):名字會長出新的(下一個 KV 綁定叫什麼沒人知道),
# 而清單只認得已知的那幾個 ⇒ 新的 KV 從清單的縫隙走過去,本閘就變成裝飾。
# 全大寫識別字 .put/.delete 這個形狀,在 Workers 裡就是 KVD1 沒有 .putJS 物件用 .set)。
hits=$(printf '%s' "$body" | grep -nE '\b[A-Z][A-Z0-9_]{1,}\.(put|delete)\(' \
| grep -v 'kv-ok' || true)
[ -z "$hits" ] && exit 0
cat >&2 <<EOF
🚫 長效資料不准寫進 KV——一律走 KBDB APIleo 2026-08-25 立)
leo 原話:
「**我強制禁止寫 SQL,要用 KBDB API,你就讓它繞過寫 KV 代替?**」
「上次刪掉一堆東西,現在又寫入,**你沒有規範嗎**」
━━ 你這次要寫的 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
$(printf '%s' "$hits" | head -6 | sed 's/^/ /')
━━ 為什麼擋 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
規則早就在(\`system-dev/wiki/decisions-summary.md:133\`):
**KV =暫存(cache / transient),不是長期真相源。**
而 2026-08-25 實查:\`.claude/hooks/\` 底下跟 KV 有關的閘 **0 支**
⇒ 規則被讀到了,卻沒有機制驗證有沒有照做。本閘就是補那一格。
🔴 **並且**\`kbdbFetch()\` 裡的 KV 字樣是 **0**——走 KBDB API 根本不碰 KV。
所以「寫 KV」在這個系統裡**必定意味著繞過知識庫**,不是一種實作選擇。
禁 SQL 的牆 2026-08-07 立,而 app-system 2026-08-24 誕生就在寫 KV
——**牆立起來了,水從旁邊流走了。**
━━ 怎麼過 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
① **本來就該走 KBDB**(絕大多數)→ 改成 KBDB API。
新資料類型=seed 一列 template,資料展開成完整 record
**不准打包進 metadata_json**D91D93)。讀 \`arcrun-kbdb-guardrails\` skill。
② **這筆資料真的是短命的**(session/一次性 nonce/有 TTL 的快取)
→ 那一行尾端加 \`kv-ok: <為什麼它是短命的>\`,留痕放行。
③ **你在做的是退休戰(刪掉 KV 寫入)** → 本閘不擋刪除,只擋新增。
🔴 \`kv-ok: 暫時先這樣\` / \`之後再搬\` **不算理由**——那是把債留給下一個人,
而 2026-08-25 已經證明了沒人會回來還。
EOF
exit 2
+141 -2
View File
@@ -1,6 +1,7 @@
# ── 以下格是 inkstone/ISEP#90 加的「這一份是不是還有效」自檢 ──────────
# ── 以下格是「這一份是不是還有效」自檢 ─────────────────────────────
# ①②③ inkstone/ISEP#90 立;②b②c inkstone/ISEP#122 補(會自動載入的東西也有分身)
# 都**只是報告,不擋任何事**(SessionStart 本來就不該擋),而且每一格拿不到答案就閉嘴。
import json, os, re, subprocess, sys, time, urllib.request
import hashlib, json, os, re, subprocess, sys, time, urllib.request
ROOT = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
PROJ = os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
@@ -103,6 +104,144 @@ if sh:
"在雲端一律死在「拿不到 gitea token」。要嘛刪掉複本改叫 "
"`\"$CLAUDE_PLUGIN_ROOT\"/scripts/<名字>`,要嘛把複本同步回 ISEP。" % "".join(sh))
# ══ ②b 會**自動載入**的東西(skillcommand/agent)兩邊各有一份而內容不同 ══
#
# 🔴 為什麼上面那一格抓不到(inkstone/ISEP#1222026-09-02 實查):
# ② 只掃 `scripts/`。而真正會**自動載入**的東西住在別的目錄,同樣兩邊各有一份:
# plugin `skills/<名>/SKILL.md` ↔ 專案 `.claude/skills/<名>/SKILL.md`
# plugin `commands/<名>.md` ↔ 專案 `.claude/commands/<名>.md`
# plugin `agents/<名>.md` ↔ 專案 `.claude/agents/<名>.md`
#
# 實況:這 9 個檔案在 ISEP `0.1.0`c263866)從 InkStoneCo 複製過來**一次**
# 之後再也沒有同步過。到 2026-09-02 已經分家兩個,而且**方向相反**:
# `skills/ship-check/SKILL.md` InkStoneCo 651 行 ISEP 595 行
# `commands/sdd-check.md` ISEP 81 行 InkStoneCo 65 行
# InkStoneCo 那份還在教 ISEP#91 已退役的「唯一 active SDD」)
# ⇒ 「ISEP 一定比較新」與「InkStoneCo 一定比較新」**兩句都是錯的**。
# 兩份都會被就地編輯 ⇒ 歸屬只能寫下來(`docs/file-ownership.tsv`)並且要有東西去比。
#
# 🔴 這一格比 ② 嚴重:腳本要有人叫它才會跑,**skill/command 是自動載入的**——
# 載到舊的那份不會報錯、不會變慢、不會有任何症狀,只會安靜地教錯的東西。
# ship-check 就是這樣:舊描述在「我要發一篇部落格文章」時根本不會被觸發。)
#
# 判準與 ② 同一條:**檔名一樣而內容不同**才出聲,同步過的不吵。
LOADABLE_PAIRS = [("skills", ".claude/skills", True),
("commands", ".claude/commands", False),
("agents", ".claude/agents", False)]
def ownership():
"""讀 docs/file-ownership.tsv → {plugin 內路徑: (真相源, 真相源路徑, commit, sha256)}"""
out = {}
try:
with open(os.path.join(ROOT, "docs", "file-ownership.tsv"), encoding="utf-8") as f:
for line in f:
if not line.strip() or line.lstrip().startswith("#"):
continue
c = line.rstrip("\n").split("\t")
if len(c) >= 2 and c[0].strip():
out[c[0].strip()] = tuple((c[1:5] + ["-", "-", "-", "-"])[:4])
except Exception:
pass
return out
OWN = ownership()
def loadable_pairs():
"""產生 (plugin 內相對路徑, 專案內相對路徑)——只列 plugin 真的有的那些"""
for pdir, jdir, nested in LOADABLE_PAIRS:
src = os.path.join(ROOT, pdir)
if not os.path.isdir(src):
continue
try:
names = sorted(os.listdir(src))
except Exception:
continue
for name in names:
if nested:
if os.path.isfile(os.path.join(src, name, "SKILL.md")):
yield "%s/%s/SKILL.md" % (pdir, name), "%s/%s/SKILL.md" % (jdir, name)
elif name.endswith(".md") and os.path.isfile(os.path.join(src, name)):
yield "%s/%s" % (pdir, name), "%s/%s" % (jdir, name)
def whose(rel):
"""真相源是誰 → 一句照著做就會走到的話。表上沒有就誠實說未定,不要猜。"""
row = OWN.get(rel)
if not row:
return "歸屬未定 ⇒ 兩份都看一眼,決定之後補一列進 docs/file-ownership.tsv"
src, spath, _commit, _sha = row
if src == "inkstone/ISEP":
return "真相源=ISEP 這一份 ⇒ 專案那份是舊複本,同步過去或刪掉它"
return ("真相源=%s:%s ⇒ 內容改在那裡,改完原樣搬進 ISEP、"
"更新 docs/file-ownership.tsv 的 commitsha256、升版" % (src, spath or "?"))
def shadow_loadables():
out = []
roots = [PROJ, os.path.join(PROJ, "InkStoneCo")]
for prel, jrel in loadable_pairs():
a = os.path.join(ROOT, prel)
try:
ab = open(a, "rb").read()
except Exception:
continue
for base in roots:
b = os.path.join(base, jrel)
try:
if os.path.realpath(b) == os.path.realpath(a) or not os.path.isfile(b):
continue
if open(b, "rb").read() != ab:
out.append("%s%s%s"
% (prel, os.path.relpath(b, PROJ), whose(prel)))
except Exception:
pass
return out
ld = shadow_loadables()
if ld:
notes.append(
"🟡 **會自動載入的東西兩邊各有一份,而且內容不同**:\n - %s\n"
" 自動載入的東西載到舊的那份**不會有任何症狀**——不報錯、不變慢,"
"只會安靜地教錯的東西(`ship-check` 的舊描述在「我要發一篇部落格文章」時"
"根本不會被觸發)。歸屬表:docs/file-ownership.tsvinkstone/ISEP#122)。"
% "\n - ".join(ld))
# ══ ②c ISEP 自己這一份,跟歸屬表記的那顆對不對得上 ══════════════════════
#
# 🔴 為什麼要有這一格:②b 要「專案那一份」在磁碟上才比得出來,
# 而**雲端的 project dir 是薄殼,根本沒有那一份**(ISEP#90 記過同一件事)。
# 這一格只比「檔案 vs 表上寫的 sha256」——離線、單邊、不依賴任何別的 repo,
# 是雲端唯一還作數的那個檢查。
def off_manifest():
out = []
for rel, (src, spath, commit, sha) in OWN.items():
if not sha or sha == "-":
continue
p = os.path.join(ROOT, rel)
if not os.path.isfile(p):
continue
try:
h = hashlib.sha256(open(p, "rb").read()).hexdigest()
except Exception:
continue
if h != sha:
out.append("%s(表記 %s%s…,實際 %s…;真相源 %s:%s"
% (rel, (commit or "?")[:7], sha[:12], h[:12], src, spath or "?"))
return out
om = off_manifest()
if om:
notes.append(
"🟡 **ISEP 這一份跟歸屬表對不上**:%s。兩種可能,兩種都要動手:"
"① 它被就地改過 ⇒ 內容要改在真相源那邊,這裡只放原樣搬過來的複本;"
"② 它是同步過的新內容、只是沒更新 docs/file-ownership.tsv 的 commitsha256 ⇒ 補上那兩欄。"
% "".join(om))
# ══ ③ 工作區有沒有「已退役機制」留下的產物 ══════════════════════════════
#
# 判準是機械的、而且會自己長大:**plugin 自己的原始碼裡有沒有任何一個字提到這個目錄**。
@@ -1,111 +0,0 @@
#!/usr/bin/env bash
# duplicate-hook-registration-guard.sh 的迴歸測試(inkstone/ISEP#122
#
# 這支閘的價值是「不吵的時候真的不吵,該吵的時候真的吵得出正確清單」——
# 兩邊都要驗,而且全程用假的 plugin root/專案目錄,不碰真正的
# InkStoneCo/.claude/ 或這台機器裝著的 ISEP plugin。
set -u
HOOK="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/duplicate-hook-registration-guard.sh}"
PASS=0; FAIL=0; N=0
check() { # check <說明> <輸出> <exit碼> <該出現|!不該出現>...
desc="$1"; out="$2"; code="$3"; shift 3; N=$((N+1)); ok=1; why=""
if [ "$code" != "0" ]; then ok=0; why="exit 應該是 0(這支從不擋人),實際是 $code"; fi
for w in "$@"; do
case "$w" in
"!"*) if printf '%s' "$out" | grep -qF -- "${w#!}"; then ok=0; why="不該出現卻出現了:${w#!}"; fi ;;
*) if ! printf '%s' "$out" | grep -qF -- "$w"; then ok=0; why="少了:$w"; fi ;;
esac
done
if [ "$ok" = 1 ]; then printf ' ✅ %s\n' "$desc"; PASS=$((PASS+1))
else printf ' ❌ %s —— %s\n' "$desc" "$why"; printf '%s\n' "$out" | sed 's/^/ /'; FAIL=$((FAIL+1)); fi
}
# mkroot <名字...> → 造一份假 plugin roothooks.json 裡真的註冊這些檔名
mkroot() {
d="$TMP/root-$RANDOM"; mkdir -p "$d/hooks"
{
printf '{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":['
first=1
for n in "$@"; do
[ "$first" = 1 ] || printf ','
printf '{"type":"command","command":"${CLAUDE_PLUGIN_ROOT}/hooks/%s"}' "$n"
first=0
done
printf ']}]}}\n'
} > "$d/hooks/hooks.json"
printf '%s\n' "$d"
}
# mkproj <名字...> → 造一份假專案目錄,settings.json 裡登記這些檔名
mkproj() {
d="$TMP/proj-$RANDOM"; mkdir -p "$d/.claude"
{
printf '{"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":['
first=1
for n in "$@"; do
[ "$first" = 1 ] || printf ','
printf '{"type":"command","command":"$CLAUDE_PROJECT_DIR/.claude/hooks/%s"}' "$n"
first=0
done
printf ']}]}}\n'
} > "$d/.claude/settings.json"
printf '%s\n' "$d"
}
run() { # run <root> <proj>
out=$(CLAUDE_PLUGIN_ROOT="$1" CLAUDE_PROJECT_DIR="$2" bash "$HOOK" 2>&1)
code=$?
printf '%s\x1e%s' "$out" "$code"
}
TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
echo "── 該吵 ──────────────────────────────────────────────────────"
R=$(mkroot prod-write-guard.sh github-contact-guard.sh)
P=$(mkproj prod-write-guard.sh other-thing.sh)
o=$(run "$R" "$P"); out="${o%$'\x1e'*}"; code="${o##*$'\x1e'}"
check "① 專案版跟 plugin 同名一支 → 點名那一支" "$out" "$code" \
"重複掛載警報" "1 支" "prod-write-guard.sh" "!github-contact-guard.sh" "!other-thing.sh"
R=$(mkroot a.sh b.sh c.sh)
P=$(mkproj a.sh b.sh c.sh)
o=$(run "$R" "$P"); out="${o%$'\x1e'*}"; code="${o##*$'\x1e'}"
check "② 全部同名 → 三支都點名" "$out" "$code" "3 支" "a.sh" "b.sh" "c.sh"
echo "── 不該吵(誤攔比漏擋嚴重)───────────────────────────────────"
R=$(mkroot a.sh)
P=$(mkproj z.sh)
o=$(run "$R" "$P"); out="${o%$'\x1e'*}"; code="${o##*$'\x1e'}"
check "③ 完全不重疊 → 靜音" "$out" "$code" "!重複掛載"
R=$(mkroot a.sh)
d="$TMP/proj-empty-$RANDOM"; mkdir -p "$d/.claude"; echo '{"hooks":{}}' > "$d/.claude/settings.json"
o=$(run "$R" "$d"); out="${o%$'\x1e'*}"; code="${o##*$'\x1e'}"
check "④ 專案沒登記任何 .claude/hooks/*.sh → 靜音" "$out" "$code" "!重複掛載"
d="$TMP/proj-nosettings-$RANDOM"; mkdir -p "$d/.claude"
o=$(run "$R" "$d"); out="${o%$'\x1e'*}"; code="${o##*$'\x1e'}"
check "⑤ 專案根本沒有 settings.json → 靜音" "$out" "$code" "!重複掛載"
o=$(CLAUDE_PROJECT_DIR="$(mkproj a.sh)" bash "$HOOK" 2>&1); code=$?
check "⑥ 沒有 CLAUDE_PLUGIN_ROOT(不是 plugin 環境)→ 靜音" "$o" "$code" "!重複掛載"
d="$TMP/root-nohooksjson-$RANDOM"; mkdir -p "$d/hooks"
o=$(CLAUDE_PLUGIN_ROOT="$d" CLAUDE_PROJECT_DIR="$(mkproj a.sh)" bash "$HOOK" 2>&1); code=$?
check "⑦ plugin root 沒有 hooks.json(環境不完整)→ 靜音" "$o" "$code" "!重複掛載"
echo "── 判準是「登記」不是「檔案存在」──────────────────────────────"
R=$(mkroot pre-write-guard.template.sh) # 有這個檔但 hooks.json 沒收(樣板慣例)
d="$TMP/root-unreg-$RANDOM"; mkdir -p "$d/hooks"; echo '{"hooks":{}}' > "$d/hooks/hooks.json"
touch "$d/hooks/pre-write-guard.template.sh"
P=$(mkproj pre-write-guard.template.sh)
o=$(run "$d" "$P"); out="${o%$'\x1e'*}"; code="${o##*$'\x1e'}"
check "⑧ plugin 有這個檔但沒真的註冊 → 不算重複,靜音" "$out" "$code" "!重複掛載"
echo ""
echo "── 結果:$PASS 通過 / $FAIL 失敗(共 $N)──"
[ "$FAIL" -eq 0 ]
+96
View File
@@ -0,0 +1,96 @@
#!/usr/bin/env bash
# history-first-guard.sh 的迴歸測試 —— 重點在**逃生門真的走得通**inkstone/ISEP#122
#
# ── 這支在守什麼 ────────────────────────────────────────────────────
# 2026-09-02 實撞:KBDB 兩支工具都回 `Connection closed`,照這支閘印出來的那行
# `touch /tmp/.kbdb-down`
# 打完再送同一個編輯,**被一模一樣地擋第二次**——因為 `touch` 造的是空檔,
# 而舊版是 `cat` 檔案內容當時戳,空字串被當成 0 ⇒ 「距今 17 億秒」⇒ 永遠不新鮮。
#
# 🔴 一道閘印出來的出路走不通,比沒有出路更糟:人照做了、還是被擋,
# 下一步就是去繞過這道閘(本 repo 的 ticket-api-bypass-guard.sh 檔頭記過同一課)。
# 所以這支測試的第一等公民是**逃生門那一條**,不是「擋不擋得住」。
#
# 🔴 **這支測試自己怎麼被證明有鑑別力**(不要只看它全綠):
# 把修好之前那一版拿來跑,第 ④ 條要紅。因為舊版沒有 KBDB_STAMP_DIR
# 直接餵它會去讀這台機器真正的 /tmp 戳記而「剛好過關」,所以要先把路徑隔離:
# git show <修好前的 commit>:hooks/history-first-guard.sh > /tmp/old.sh
# sed 's#/tmp/\.kbdb-asked#${KBDB_STAMP_DIR:-/tmp}/.kbdb-asked#;
# s#/tmp/\.kbdb-down#${KBDB_STAMP_DIR:-/tmp}/.kbdb-down#' /tmp/old.sh > /tmp/old-iso.sh
# bash hooks/tests/history-first-guard.test.sh /tmp/old-iso.sh
# 2026-09-02 實跑:舊版 9/10(④ 紅),修好後 10/10。
# ⚠️ 第 ③ 條**兩版都是綠的**——它只驗離開碼 2,而過了第 0 道之後歷史警察照樣會擋。
# 真正分辨得出來的是 ④「擋人的是誰」。這一格是本支最容易寫成假綠的地方。
#
# 🔴 全程用 KBDB_STAMP_DIR 指到 TMP**不碰這台機器真正的 /tmp/.kbdb-* 戳記**
# (把別的 session 的戳記清掉=把閘弄成隨機的)。不打網路。
set -u
HOOK="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/history-first-guard.sh}"
TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
export KBDB_STAMP_DIR="$TMP/stamps"; mkdir -p "$KBDB_STAMP_DIR"
PASS=0; FAIL=0; N=0
# 造一個「有前科」的 code 檔:放在一個有 git 歷史的假 repo 裡
REPO="$TMP/repo"; mkdir -p "$REPO"
( cd "$REPO" && git init -q && git config user.email t@t && git config user.name t \
&& printf 'echo old\n' > victim.sh && git add . && git commit -qm "第一版" ) >/dev/null 2>&1
VICTIM="$REPO/victim.sh"
# run <檔案> → 印出離開碼(送一份 Edit 的 payload 進去)
run() {
printf '{"tool_input":{"file_path":"%s"}}' "$1" \
| CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" >/dev/null 2>"$TMP/err"
printf '%s' "$?"
}
check() { # check <說明> <實際> <期望>
N=$((N+1))
if [ "$2" = "$3" ]; then printf ' ✅ %s\n' "$1"; PASS=$((PASS+1))
else printf ' ❌ %s —— 期望離開碼 %s,實際 %s\n' "$1" "$3" "$2"; sed 's/^/ /' "$TMP/err" | head -6; FAIL=$((FAIL+1)); fi
}
clean_stamps() { rm -f "$KBDB_STAMP_DIR/.kbdb-asked" "$KBDB_STAMP_DIR/.kbdb-down"; rm -f /tmp/.history-guard-*; }
echo "── 第 0 道:問過 KBDB 了沒 ──────────────────────────────────"
clean_stamps
check "① 沒有任何戳記 → 擋" "$(run "$VICTIM")" 2
grep -q "KBDB" "$TMP/err" && printf ' ✅ ② 擋下時訊息講得出是哪一道\n' && PASS=$((PASS+1)) || { printf ' ❌ ② 訊息沒提到 KBDB\n'; FAIL=$((FAIL+1)); }; N=$((N+1))
echo "── 🔴 逃生門:照訊息打那一行,就要真的過得去 ──────────────────"
clean_stamps
touch "$KBDB_STAMP_DIR/.kbdb-down" # ← 訊息裡原文那一行做的事
check "③ touch 出來的空檔(本票的實撞)→ 要放行過第 0 道" "$(run "$VICTIM")" 2
# ↑ 期望仍是 2:過了第 0 道之後會被「歷史警察」擋(這個檔真的有前科),
# 所以要看訊息換人了沒——這是這支測試最容易寫錯的一格。
grep -q "歷史警察" "$TMP/err" && printf ' ✅ ④ 擋人的換成歷史警察 ⇒ 第 0 道確實被逃生門放過了\n' && PASS=$((PASS+1)) || { printf ' ❌ ④ 還是卡在 KBDB 那一道 ⇒ 逃生門是假的\n'; sed 's/^/ /' "$TMP/err" | head -4; FAIL=$((FAIL+1)); }; N=$((N+1))
clean_stamps
date +%s > "$KBDB_STAMP_DIR/.kbdb-down" # 舊格式(檔案內容是時戳)
run "$VICTIM" >/dev/null
grep -q "歷史警察" "$TMP/err" && printf ' ✅ ⑤ 舊格式(內容寫時戳)照樣認得 ⇒ 沒有把既有的弄壞\n' && PASS=$((PASS+1)) || { printf ' ❌ ⑤ 舊格式壞了\n'; FAIL=$((FAIL+1)); }; N=$((N+1))
clean_stamps
date +%s > "$KBDB_STAMP_DIR/.kbdb-asked"
run "$VICTIM" >/dev/null
grep -q "歷史警察" "$TMP/err" && printf ' ✅ ⑥ 真的問過 KBDBkbdb-asked-stamp.sh 寫的戳記)→ 過第 0 道\n' && PASS=$((PASS+1)) || { printf ' ❌ ⑥ 問過了還被擋\n'; FAIL=$((FAIL+1)); }; N=$((N+1))
echo "── 過期的戳記不算數(逃生門不能變成永久後門)──────────────────"
clean_stamps
touch -t "$(date -v-2H '+%Y%m%d%H%M' 2>/dev/null || date -d '2 hours ago' '+%Y%m%d%H%M')" "$KBDB_STAMP_DIR/.kbdb-down"
run "$VICTIM" >/dev/null
grep -q "KBDB" "$TMP/err" && printf ' ✅ ⑦ 兩小時前的空戳記 → 過期,回到擋\n' && PASS=$((PASS+1)) || { printf ' ❌ ⑦ 過期的戳記還在放行 ⇒ 一次 touch 就永久免疫\n'; FAIL=$((FAIL+1)); }; N=$((N+1))
echo "── 不該擋的(誤攔比漏擋嚴重)────────────────────────────────"
clean_stamps
printf '# doc\n' > "$REPO/readme.md"
check "⑧ 文件檔(.md)→ 一路放行,連第 0 道都不該碰" "$(run "$REPO/readme.md")" 0
clean_stamps
check "⑨ 不存在的新檔 → 放行" "$(run "$REPO/brand-new.sh")" 0
clean_stamps
mkdir -p "$REPO/tests"; printf 'echo t\n' > "$REPO/tests/a.sh"
check "⑩ 測試檔 → 放行" "$(run "$REPO/tests/a.sh")" 0
echo
printf '通過 %s 條,失敗 %s 條(共 %s 條)\n' "$PASS" "$FAIL" "$N"
[ "$FAIL" = 0 ] || exit 1
+74
View File
@@ -0,0 +1,74 @@
#!/usr/bin/env bash
# hooks/tests/lib/hook-sandbox.sh 的迴歸測試(inkstone/ISEP#122
#
# 🔴 為什麼有這支(2026-09-02 實撞,證據在票上):
# `hook_sandbox` 的第一個參數是「那支 hook 的檔案路徑」,傳錯時舊版不檢查就
# `cp -R "$(dirname "$1")"` ⇒ 複製的是上一層。傳 repo 根目錄進去,
# 複製的就是**整個 tech_projects**:兩次吃掉 23 GB,磁碟剩 462 MB
# 而它只印一句「沙盒建不起來」——**沒說參數錯,也沒說它已經把磁碟寫滿**。
#
# 所以這支測的不是「錯誤訊息好不好看」,是**收手的時機**:
# ④⑤ 兩條驗「複製之前就 return 1」——暫存區裡不准留下任何東西。
#
# 用法:bash hooks/tests/hook-sandbox.test.sh
set -u
HERE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
ROOT=$(CDPATH= cd -- "$HERE/.." && pwd) # …/hooks
REPO=$(CDPATH= cd -- "$ROOT/.." && pwd)
PASS=0; FAIL=0
ok(){ printf ' ✅ %s\n' "$1"; PASS=$((PASS+1)); }
no(){ printf ' ❌ %s —— %s\n' "$1" "$2"; FAIL=$((FAIL+1)); }
# 每一條都在自己的子殼裡跑:hook_sandbox 會設全域變數,不隔離會互相污染。
run(){ # run <參數> → 印 "rc|沙盒路徑|訊息"
( . "$HERE/lib/hook-sandbox.sh"
msg=$(hook_sandbox "$1" 2>&1); rc=$?
printf '%s|%s|%s' "$rc" "${HOOK_SANDBOX:-}" "$(printf '%s' "$msg" | tr '\n' ' ')"
)
}
echo "── 該收手(傳錯參數)──────────────────────────────────────"
r=$(run "$REPO"); rc=${r%%|*}; rest=${r#*|}; sb=${rest%%|*}; msg=${rest#*|}
[ "$rc" = "1" ] && ok "① 傳 repo 根目錄(本票的實撞)→ return 1" \
|| no "① 傳 repo 根目錄(本票的實撞)→ return 1" "實得 rc=$rc"
case "$msg" in *"hooks/main-and-prod-push-guard.sh"*)
ok "② 訊息給得出一行**真的跑得起來**的用法" ;;
*) no "② 訊息給得出一行**真的跑得起來**的用法" "訊息:$msg" ;;
esac
if [ -z "$sb" ] || [ ! -d "$sb" ]; then ok "③ 收手在 mktemp 之前,暫存區沒有殘骸"
else no "③ 收手在 mktemp 之前,暫存區沒有殘骸" "留下了 $sb"; fi
r=$(run ""); [ "${r%%|*}" = "1" ] && ok "④ 空參數 → return 1(不是拿空字串去 dirname" \
|| no "④ 空參數 → return 1" "實得 rc=${r%%|*}"
r=$(run "$REPO/scripts/ticket"); rc=${r%%|*}; rest=${r#*|}; sb=${rest%%|*}
if [ "$rc" = "1" ]; then ok "⑤ 檔案存在但上一層不是 hooks/ → 一樣收手"
else no "⑤ 檔案存在但上一層不是 hooks/ → 一樣收手" "實得 rc=$rc"; fi
if [ -z "$sb" ] || [ ! -d "$sb" ]; then ok "⑥ ⑤ 這條也沒把 scripts/ 複製出去"
else no "⑥ ⑤ 這條也沒把 scripts/ 複製出去" "留下了 $sb"; fi
r=$(run "$ROOT/沒有這支.sh"); [ "${r%%|*}" = "1" ] && ok "⑦ 路徑不存在 → return 1" \
|| no "⑦ 路徑不存在 → return 1" "實得 rc=${r%%|*}"
echo "── 不准把本來會過的弄壞(誤攔比漏擋嚴重)────────────────────"
( . "$HERE/lib/hook-sandbox.sh"
hook_sandbox "$ROOT/main-and-prod-push-guard.sh"; rc=$?
if [ "$rc" != "0" ]; then echo "RC=$rc"; exit 0; fi
[ -f "$HOOK_SANDBOX_HOOK" ] && echo "HOOKOK"
[ -d "$HOOK_SANDBOX/hooks/lib" ] && echo "LIBOK"
# 只複製 hooks/,不該把 repo 的其他目錄帶進來
[ -d "$HOOK_SANDBOX/hooks/scripts" ] && echo "LEAK"
hook_sandbox_cleanup
) > /tmp/.hs-ok.$$ 2>&1
grep -q HOOKOK /tmp/.hs-ok.$$ && ok "⑧ 正常用法照樣建得起來,複本裡有那支 hook" \
|| no "⑧ 正常用法照樣建得起來" "$(cat /tmp/.hs-ok.$$)"
grep -q LIBOK /tmp/.hs-ok.$$ && ok "⑨ 整個 hooks/(含 lib/)都在複本裡" \
|| no "⑨ 整個 hooks/(含 lib/)都在複本裡" "$(cat /tmp/.hs-ok.$$)"
grep -q LEAK /tmp/.hs-ok.$$ && no "⑩ 只複製 hooks/,沒有把 repo 其他目錄帶進去" "複本裡出現 scripts/" \
|| ok "⑩ 只複製 hooks/,沒有把 repo 其他目錄帶進去"
rm -f /tmp/.hs-ok.$$
echo
echo "通過 $PASS 條,失敗 $FAIL 條(共 $((PASS+FAIL)) 條)"
[ "$FAIL" -eq 0 ]
+78
View File
@@ -25,9 +25,21 @@ mkplugin() {
cp "$HOOK" "$d/hooks/$(basename "$HOOK")"
cp "$REAL_HOOKS/lib/beacon_report.py" "$d/hooks/lib/beacon_report.py"
printf '#!/bin/sh\necho real\n' > "$d/scripts/ticket"
# inkstone/ISEP#122:會自動載入的東西(skillcommandagent)也要造得出來
mkdir -p "$d/skills/demo" "$d/commands" "$d/agents" "$d/docs"
printf 'PLUGIN 版的 skill\n' > "$d/skills/demo/SKILL.md"
printf 'PLUGIN 版的 command\n' > "$d/commands/demo.md"
printf 'PLUGIN 版的 agent\n' > "$d/agents/demo.md"
printf '%s\n' "$d"
}
# mkown <plugin root> <列...> → 寫一份 docs/file-ownership.tsv(欄位用真正的 TAB
mkown() {
d="$1"; shift; mkdir -p "$d/docs"
{ printf '# 測試用\n'; for row in "$@"; do printf '%s\n' "$row"; done; } \
| sed 's/|/\t/g' > "$d/docs/file-ownership.tsv"
}
# run <plugin root> <project dir> → 印出 systemMessageJSON 壞掉就印 __BADJSON__
run() {
CLAUDE_PLUGIN_ROOT="$1" CLAUDE_PROJECT_DIR="$2" bash "$1/hooks/$(basename "$HOOK")" 2>/dev/null \
@@ -112,6 +124,72 @@ printf '#!/bin/sh\necho "OLD"\n' > "$J6/scripts/ticket"
out=$(run "$P" "$J6")
check "⑭ 報告內容含引號 → JSON 仍然合法" "$out" "🟢 ISEP" "!__BADJSON__"
P2=$(mkplugin 1.0.0) # ⑫⑬ 會刪掉 $P 的 report,這一組要自己一份
echo "── ②b 會自動載入的東西也有分身(inkstone/ISEP#122)──────────────"
# 🔴 這一組守的是 ship-check 那件:plugin 帶著舊描述,而舊描述在「我要發部落格文章」
# 的情境根本不會被觸發 ⇒ 那個 session 永遠載不到出貨流程,而且不會有任何症狀。
JS="$TMP/proj-skill"; mkdir -p "$JS/.claude/skills/demo"
printf '專案版的 skill(比較舊)\n' > "$JS/.claude/skills/demo/SKILL.md"
out=$(run "$P2" "$JS")
check "⑮ 專案有同名 skill 而內容不同 → 要點名" "$out" \
"會自動載入的東西兩邊各有一份" "skills/demo/SKILL.md" ".claude/skills/demo/SKILL.md"
check "⑯ 歸屬表沒登記 → 誠實說未定,不要替人猜方向" "$out" "歸屬未定"
JS2="$TMP/proj-skill-same"; mkdir -p "$JS2/.claude/skills/demo"
cp "$P2/skills/demo/SKILL.md" "$JS2/.claude/skills/demo/SKILL.md"
out=$(run "$P2" "$JS2")
check "⑰ 內容一模一樣 → 不吵(誤攔比漏擋嚴重)" "$out" "!會自動載入的東西兩邊各有一份"
JC="$TMP/proj-cmd"; mkdir -p "$JC/.claude/commands"
printf '專案版的 command(比較舊)\n' > "$JC/.claude/commands/demo.md"
out=$(run "$P2" "$JC")
check "⑱ command 也要掃(sdd-check 那件)" "$out" "commands/demo.md" ".claude/commands/demo.md"
JA="$TMP/proj-agent"; mkdir -p "$JA/.claude/agents"
printf '專案版的 agent(比較舊)\n' > "$JA/.claude/agents/demo.md"
out=$(run "$P2" "$JA")
check "⑲ agent 也要掃" "$out" "agents/demo.md" ".claude/agents/demo.md"
JCL="$TMP/proj-cloud"; mkdir -p "$JCL/InkStoneCo/.claude/skills/demo"
printf '專案版的 skill(比較舊)\n' > "$JCL/InkStoneCo/.claude/skills/demo/SKILL.md"
out=$(run "$P2" "$JCL")
check "⑳ 雲端排法:真身在 \$TOP/InkStoneCo/ 底下也要抓到" "$out" \
"InkStoneCo/.claude/skills/demo/SKILL.md"
echo "── 歸屬表要講得出「往哪個方向修」──────────────────────────────"
PO=$(mkplugin 1.0.1)
mkown "$PO" "skills/demo/SKILL.md|inkstone/InkStoneCo|.claude/skills/demo/SKILL.md|abc1234|-"
out=$(run "$PO" "$JS")
check "㉑ 真相源=InkStoneCo → 說「內容改在那裡」並給得出路徑" "$out" \
"真相源=inkstone/InkStoneCo:.claude/skills/demo/SKILL.md" "內容改在那裡" "!歸屬未定"
mkown "$PO" "skills/demo/SKILL.md|inkstone/ISEP|-|-|-"
out=$(run "$PO" "$JS")
check "㉒ 真相源=ISEP → 說「專案那份是舊複本」" "$out" \
"真相源=ISEP 這一份" "舊複本" "!歸屬未定"
echo "── ②c 沒有專案那一份也要驗得出來(雲端唯一作數的檢查)────────────"
# 雲端的 project dir 是薄殼,沒有 InkStoneCo 可以比 ⇒ 只剩「檔案 vs 表上的 sha256」
SHA=$(shasum -a 256 "$PO/skills/demo/SKILL.md" | cut -d" " -f1)
mkown "$PO" "skills/demo/SKILL.md|inkstone/InkStoneCo|.claude/skills/demo/SKILL.md|abc1234|$SHA"
out=$(run "$PO" "$J")
check "㉓ sha256 對得上(而且專案那份不存在)→ 一個字都不說" "$out" \
"🟢 ISEP v1.0.1 已載入" "!跟歸屬表對不上" "!會自動載入的東西兩邊各有一份"
printf '被就地改過\n' >> "$PO/skills/demo/SKILL.md"
out=$(run "$PO" "$J")
check "㉔ 檔案被就地改過 → 就算沒有專案那份,也要抓得到" "$out" \
"跟歸屬表對不上" "skills/demo/SKILL.md" "abc1234"
mkown "$PO" "skills/demo/SKILL.md|inkstone/InkStoneCo|.claude/skills/demo/SKILL.md|abc1234|-"
out=$(run "$PO" "$J")
check "㉕ 表上 sha 欄是 \`-\` → 這一格閉嘴(還沒登記不是錯)" "$out" "!跟歸屬表對不上"
echo "── 加了這兩格也不准讓信標消失 ────────────────────────────────"
out=$(run "$P2" "$JS")
check "㉖ ②b 有報告時,那行綠色信標仍在且 JSON 合法" "$out" \
"🟢 ISEP v1.0.0 已載入" "!__BADJSON__"
echo
printf '通過 %s 條,失敗 %s 條(共 %s 條)\n' "$PASS" "$FAIL" "$N"
[ "$FAIL" = 0 ] || exit 1
-62
View File
@@ -1,62 +0,0 @@
#!/usr/bin/env bash
# kv-write-guard.sh 的迴歸測試(inkstone/ISEP#122 搬進 ISEP 時補上——
# 原檔 2026-08-25 立於 InkStoneCo 專案版,搬過來之前沒有自動化測試)。
set -u
HOOK="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/kv-write-guard.sh}"
PASS=0; FAIL=0; N=0
# run <tool> <file_path> <content> → 送一個 Write 事件的 payload
run() {
python3 -c '
import json,sys
tool, fp, content = sys.argv[1], sys.argv[2], sys.argv[3]
print(json.dumps({"tool_name": tool, "tool_input": {"file_path": fp, "content": content}}))
' "$1" "$2" "$3" | bash "$HOOK" 2>&1
echo "EXIT:$?"
}
check() { # check <說明> <輸出+EXIT行> <該擋(2)|該放行(0)> <該出現|!不該出現>...
desc="$1"; out="$2"; want="$3"; shift 3
code="$(printf '%s\n' "$out" | grep -oE 'EXIT:[0-9]+' | tail -1 | cut -d: -f2)"
N=$((N+1)); ok=1; why=""
if [ "$code" != "$want" ]; then ok=0; why="要 exit $want,實際 $code"; fi
for w in "$@"; do
case "$w" in
"!"*) if printf '%s' "$out" | grep -qF -- "${w#!}"; then ok=0; why="$why 不該出現卻出現:${w#!}"; fi ;;
*) if ! printf '%s' "$out" | grep -qF -- "$w"; then ok=0; why="$why 少了:$w"; fi ;;
esac
done
if [ "$ok" = 1 ]; then printf ' ✅ %s\n' "$desc"; PASS=$((PASS+1))
else printf ' ❌ %s ——%s\n' "$desc" "$why"; printf '%s\n' "$out" | sed 's/^/ /'; FAIL=$((FAIL+1)); fi
}
echo "── 該擋:往 KV binding 寫入 ──────────────────────────────────"
out=$(run "Write" "src/app-system.ts" $'export async function save() {\n await MY_KV.put("k", "v");\n}')
check "① 全大寫 binding.put( → 擋" "$out" 2 "長效資料不准寫進 KV" "MY_KV"
out=$(run "Edit" "src/app-system.ts" $'const x = 1;\nSESSION_KV.delete(id);')
check "② .delete( 一樣擋" "$out" 2 "長效資料不准寫進 KV"
echo "── 不該擋(誤攔比漏擋嚴重)───────────────────────────────────"
out=$(run "Write" "src/app-system.ts" 'const v = await MY_KV.get("k");')
check "③ 只是讀(.get)→ 放行" "$out" 0 "!長效資料不准寫進 KV"
out=$(run "Write" "src/app-system.ts" 'MY_KV.put("k", v); // kv-ok: session nonce,有 TTL')
check "④ 加了 kv-ok 豁免留痕的那行 → 放行" "$out" 0 "!長效資料不准寫進 KV"
out=$(run "Write" "README.md" 'MY_KV.put("k", "v")')
check "⑤ 非程式碼檔(.md)→ 放行" "$out" 0 "!長效資料不准寫進 KV"
out=$(run "Write" "src/kv-write-guard.test.ts" 'MY_KV.put("k", "v")')
check "⑥ 閘自己的測試檔 → 放行" "$out" 0 "!長效資料不准寫進 KV"
out=$(run "Write" "src/app-system.ts" 'const config = { retries: 3 };')
check "⑦ 完全不提 KV 的一般程式碼 → 放行" "$out" 0 "!長效資料不准寫進 KV"
out=$(run "Write" "src/app-system.ts" 'this.myKv.put("k", "v"); // 小寫 binding,不是本閘要的形狀')
check "⑧ 小寫變數名(不是「全大寫識別字」形狀)→ 放行" "$out" 0 "!長效資料不准寫進 KV"
echo ""
echo "── 結果:$PASS 通過 / $FAIL 失敗(共 $N)──"
[ "$FAIL" -eq 0 ]
+29
View File
@@ -39,9 +39,38 @@
# ⇒ hostsum 兩次都回 `NODIR`(相等)、沙盒的請求數當然是 0
# ⇒ **第一條斷言變成「拿空的比空的」的假綠**。
# 所以改成「設變數、不印」,而且 hook_sandbox_assert 開頭會擋空值(見下)。
#
# 🔴 **先驗參數再複製**inkstone/ISEP#1222026-09-02 實撞,本檔第二次修):
# `$1` 是「那支 hook 的路徑」。傳錯(例如順手傳了 repo 根目錄)時,舊版不檢查就
# `cp -R "$(dirname "$1")" …` ⇒ **複製的是那個目錄的上一層**。
# 當天實測:`bash hooks/tests/main-and-prod-push-guard.test.sh "$PWD"`
# ⇒ dirname 變成 ~/Documents/tech_projects
# ⇒ 把 **整個 tech_projects**(所有 repo、所有 worktree)複製進 mktemp
# ⇒ 兩次就吃掉 23 GB,磁碟從 25 GB 剩到 462 MB`cp` 一路吐
# `No space left on device`,最後才印一句「❌ 沙盒建不起來」。
# ⇒ 訊息只說「建不起來」,**沒說是參數傳錯,也沒說它已經把磁碟寫滿了**。
# 判準用「要求某個東西在場」,不是關鍵字比對:
# ① `$1` 要指到一個**真的檔案**(傳目錄、傳空字串都不算)
# ② 它的上一層目錄名要叫 `hooks`(沙盒的前提就是「複製一整個 hooks/」)
# 兩條任一不成立就**在複製之前**收手,並印出走得通的那一行。
hook_sandbox() {
_hs_real=$1
if [ -z "${_hs_real:-}" ] || [ ! -f "$_hs_real" ]; then
printf '❌ hook_sandbox:第一個參數要是「那支 hook 的檔案路徑」,實得 %s\n' \
"${_hs_real:-(空的)}" >&2
printf ' 例:bash hooks/tests/main-and-prod-push-guard.test.sh hooks/main-and-prod-push-guard.sh\n' >&2
printf ' (不必自己傳的版本:bash scripts/test-main-and-prod-push-guard.sh\n' >&2
return 1
fi
_hs_hooks=$(CDPATH= cd -- "$(dirname -- "$_hs_real")" && pwd) || return 1
if [ "$(basename "$_hs_hooks")" != "hooks" ]; then
printf '❌ hook_sandbox%s 的上一層不是 hooks/,而沙盒要複製的就是那個目錄。\n' \
"$_hs_real" >&2
printf ' 算出來的來源是 %s——照複製下去會把它整個搬進暫存區(2026-09-02 這樣寫滿過磁碟)。\n' \
"$_hs_hooks" >&2
printf ' 例:bash hooks/tests/main-and-prod-push-guard.test.sh hooks/main-and-prod-push-guard.sh\n' >&2
return 1
fi
HOOK_SANDBOX=$(mktemp -d) || return 1
cp -R "$_hs_hooks" "$HOOK_SANDBOX/hooks" || return 1
HOOK_SANDBOX_HOST="${_hs_hooks%/hooks}/pending-main-push"
+68 -12
View File
@@ -1,18 +1,21 @@
---
name: ship-check
description: |
改完任何會影響用戶的東西之後、說「做完了」之前必讀(改雲端 workerportaldaemon
workflowinstaller 都算)。也在下列時機自動載入:要打包 App、要出貨、要推 bundle
要送 MS Store、leo 問「可以測了嗎」「版本為什麼沒變」「更新了嗎」「封測者拿得到嗎」。
核心判準:**版本號是 leo 唯一的驗收介面**——portal 版本卡看雲端、daemon 檢查更新看桌面;
版本沒動=他無從判斷你做了什麼=等於沒交付,而「我在某台實例 wrangler deploy 過了」不算
收齊:兩條版本線的差別/重打 bundle(最常漏,要 grep 複驗改動真的進去)/
改 workflow 要重編預編圖/三支機械閘+把 DMG/zip 真的打開檢查/寫 changelog(用戶語言)/
D20 開閘出貨/purge jsDelivr/從 leo 會看的那兩處抓實際畫面複驗。
附「常見漏掉的」實撞表與收工前五問
**任何東西要從「內」(Gitea)送到「外」之前必讀**——不只是 arcrun。
對外包含:發一篇部落格文章到 uncle6.me、推 tag 到 GitHub 鏡像 repo、投稿 n8n 官方模板庫
出雲端零件包、出桌面 daemon。也在下列時機自動載入:改完會影響用戶的東西之後、
要打包 App/出貨/推 bundle/送 MS Store、要發文、要 pages deploy、要推 GitHub、
leo 問「可以測了嗎」「版本為什麼沒變」「更新了嗎」「封測者拿得到嗎」「發出去了嗎」
🔴 第一個動作是**分辨這是哪個出口**,因為 stage/版本/arm 每個出口都不同——
流程本體住在 system-dev/docs/3-specs/critical-paths/ship.md(唯一一份),本 skill 是它的入口。
核心判準:**收的人拿到的東西真的變了,而且他看得出變了什麼**;
對 arcrun 兩條線而言那個介面就是版本號(portal 看雲端、daemon 看桌面)
收齊:五個出口的判準/兩條版本線的差別/重打 bundle(最常漏)/改 workflow 要重編預編圖/
三支機械閘+把 DMG/zip 真的打開檢查/寫 changelogD20 開閘出貨/purge jsDelivr
從收的人會看的那個地方抓實際畫面複驗。附「常見漏掉的」實撞表與收工前五問。
---
# /ship-check — 改完東西後,讓 leo 看得到版本變了
# /ship-check — 東西要出去之前,先確定收的人真的會拿到
> **這支解什麼病**leo 2026-08-05 原話):
> 「對人來說,**我雲端看 portal 有沒有更新,本地看 daemon 有沒有更新**,
@@ -25,6 +28,44 @@ description: |
---
## 🚦 第一步:這是哪個出口?(2026-09-02 補,`inkstone/InkStoneCo#112`
> **為什麼補這段**leo 2026-09-02):「Gitea 為『內』,只要對外都是『外』,
> **任何東西出去之前都要經過出貨流程,不是只有 Arcrun, Arcrun RAG 這個計劃**」
>
> 🔴 **這支 skill 2026-09-01 失效過**:它自己與它指向的地方**只認得 daemon 那個形狀**
> 於是那晚要發部落格與 GitHub 模板時,它沒把人導向任何可用的流程——**只好即興補**。
- 🔴 **流程本體只有一份**`system-dev/docs/3-specs/critical-paths/ship.md`
- 它定義了**內/外的判準**、**六個步驟**、**五個出口各自的 stage/版本/arm/驗法**
- **動手前先讀那一卷的對應出口段**,不要憑本 skill 的印象做
- **判準一句:送出去之後,有沒有一個不是我們的人看得到/拿得到?** 有 ⇒ 走那六步
- **五個出口,各自去 `ship.md` 的哪一段**
- ① 桌面 daemon`v0.18.x`)——**本 skill 底下的內容主要是它與 ②**
- ② 雲端零件包(`1.4.x`)——同上
- ③ 部落格 uncle6.me — 🔴 **沒有 arm、沒有版本號**stage 是 `<8碼>.kbcontent.pages.dev` 快照;
`pages deploy` **必須在 repo 外的目錄跑**,否則 `.env` 的 token 會蓋掉 OAuth 並報成權限錯誤
**驗法是瀏覽器,不是 `curl`**(收件人是讀者 ⇒ 見 §5.8 與 `ship.md` 出口③「驗法」)
- ④ GitHub 鏡像 repo — 🔴 **要 arm,而且連 `git remote add` 都擋**D20);
Gitea 就是它的 stage**推 tag 之外還要發 release note**
(怎麼發、要不要再 arm ⇒ `ship.md` 出口④ 的「release note 怎麼發」段)
- 🔴 **步驟 3 的「Use this template」也要 arm,而且要單獨請一次**——它建的是
**第二個 repo**,撞 ROE「單一 repo」那條,夾不進推 tag 的窗口。
且 guard 只掛在 `Bash`**走瀏覽器按那顆按鈕不會被擋,這條靠人守**
(⇒ `ship.md` 出口④ 的「Use this template 要不要 arm」段)
- ⑤ n8n 官方投稿 — 沒有 stage,投稿端點尚未查到(`inkstone/llm-wiki-template#9`
- 🔴 **不要拿 ① 的答案去套 ③④⑤**——那正是 2026-09-01 出錯的機制
- 🔴 **「這個出口沒有 arm」不等於「這個出口不必經過 leo」**——③⑤ 的人閘是**步驟 5**
(leo 親手在 stage 上走過那一遍)。判準全文=`ship.md`
「誰批准、誰按鍵、在哪台跑」段:**leo 批准,機器執行**
- **跨多個 repo 的一批貨,「100%」看母票的相依清單,不要看 milestone 的百分比**
milestone 只數 hub 那個 repo,別的 repo 那幾張不在分母裡)
`ship.md` 的「那個數字看哪裡」段
- 🔴 **發現 `ship.md` 沒涵蓋你手上這件事 ⇒ 那一卷缺了一格,回去補它**
不要在別處另開一份流程(leo 2026-09-02 明確選了「改寫 ship.md」)
---
## ⚠️ 這支 skill 自己的失效模式(先讀這段)
leo 2026-08-05:「**你寫完一個 skill 然後每個我要提醒你,表示這個 skill 無效**」
@@ -44,8 +85,19 @@ leo 2026-08-05:「**你寫完一個 skill 然後每個我要提醒你,表示
## 什麼時候跑
**改完任何會影響用戶的東西之後**(雲端 workerportaldaemonworkflow),
在說「做完了」之前不是收工才跑。
**任何東西要送到「外面」之前**——改完會影響用戶的東西、要發一篇文章、要推 tag 到 GitHub、
要投稿、要出零件包或 daemon。在說「做完了」之前跑,不是收工才跑。
⚠️ **底下的步驟是出口①②(arcrun 兩條版本線)的細節。**
出口③④⑤ 請照上面那段回 `ship.md` 讀該出口的判準——**它們沒有版本號卡可以看**。
🔴 **但底下 §5.8「驗前端=用瀏覽器真的載一次」是全出口通則,不歸①② 所有**
2026-09-02 補:本 skill 這句劃界曾把 §5.8 圈進①②,
`ship.md` 對出口③ 給的驗法是 `curl`**兩個檔對同一個問題給了兩種答案**)。
- **一句話判準:用收的人的那個介面驗。**
- 收的人的介面是**網頁** ⇒ 瀏覽器(出口③ 讀者、出口① 的 portal 版本卡)
- 收的人的介面是 **APICLI**`curl` 才是對的(出口② 的 `/health`,程式在讀它)
- ⇒ 這不是「①② 用 curl、③ 用瀏覽器」,是**每個出口各自問自己的收件人在看什麼**
---
@@ -503,6 +555,10 @@ curl -s "https://rag.arcrun.dev/docs/start/install-windows/?cb=$RANDOM" \
> leo 原話:「**你的環境有 web,你應該用 web 驗,你已經開啓了卻沒有完成,你要把這個列入規定。**」
🔴 **適用範圍:全出口,不是只有①②**2026-09-02 補,見上面「什麼時候跑」那段的劃界)。
**收的人的介面是網頁就套這條**——出口③ 部落格的收件人是讀者,他的介面就是瀏覽器。
`ship.md` 出口③「驗法」那格寫的是同一件事,兩邊只有一種說法。
**為什麼 `curl | grep` 是假驗證**(08-08 實撞,leo 抓到而不是我發現):
`curl` 拿到的是 **HTML 原始碼**——它**不執行 JS、不載入 `config.js`、不發 API 請求**。
所以我 grep 到文案就宣稱「前端驗過」,而使用者實際打開看到的是整條紅色錯誤: