feat(hooks): 工作包閘門加上歸屬比對與領取、交回子指令 #31

2026-08-27T03:38:53Z

jiantw83 commented

2026-08-27 03:38:53 +00:00

PR 描述

摘要

需求描述：把功能主幹 feat/sdlc-flow-rules/main 累積的內容整批推上 develop。本存取庫負責使用者 15 條規則第一群「SDLC 執行流程」裡的 R4 工作包隔離：一個工作包的 PR 沒合併，擋的是相依於它的工作包，而不是整份分析；而且要擋得住「動到別人工作包的 PR」。原本的閘門只記得有沒有未結清的 PR，記不得那支 PR 屬於哪一包，所以擋不掉跨包操作。這裡把工作包歸屬寫進狀態層，讓判定跨工作階段仍然有效。
計畫名稱：無
計畫頁：無
分析頁：無

本 PR 併入 5 個 commit，來自已合併的子功能 PR plugins/hooks#30。

變更內容

檔案	為什麼改
`hooks/sdlc-gate.sh`	新增 `wp-claim`、`wp-unclaim` 兩個子指令記錄與交回工作包歸屬；`wp-lock` 多收一個工作包代號參數；`wp-check` 加上歸屬比對。歸屬是 R4 判定的依據，沒有它閘門只能擋「有沒有未結清的 PR」，擋不到「這支 PR 是不是你這一包的」
`tools/wire-cli.sh`	冒煙測試補驗工作包歸屬的四條判定路徑。新增的判定沒有測試蓋到，等於沒有
`README.md`	補上工作包歸屬狀態檔的欄位格式。這份格式是 `jsc-sdlc` 的 `wp-gate.sh` 讀取的契約，寫在文件裡兩邊才對得上
`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`	三份 manifest 版本同步升到 `0.2.3`

設計重點

歸屬一律以分析頁的工作包代號為準，不以分支名、也不以目錄名——後兩者都可能被改。決策紀錄見 wiki QUESTION_FB8DF0B5 的 2026-08-27 那一節 Q2。
查無歸屬就放行（Q5）。沒有分析頁、或查不到工作包代號時一律 exit 0 放行，只注入一句提醒。這跟 version-guard.sh「只擋確定違規」的既有裁決一致：技能組維護、臨時修 bug 這類散工本來就沒有分析頁，擋下去等於把自己鎖死。wp-lock 沒帶工作包代號時也會明講「之後一律放行」，讓使用者知道自己少給了什麼。
狀態刻意不綁工作階段 ID，寫在 $JSC_HOME/wp/ 底下的純文字檔。換工作階段、開新對話照樣擋得住，這是既有裁決的延續。
讀寫分工不重疊：hook 這半（wp-check）只注入提醒並擋掉別的階段技能，不打網路；查 Gitea 與解鎖由 jsc-sdlc 的 wp-gate.sh 單方負責。兩邊都能改狀態的話，鎖為什麼不見了就沒有人說得清。
狀態檔一律走子命令寫入，不讓呼叫端自己拼檔案。兩邊各拼各的，格式一改就對不上，而且誰寫壞了看不出來。
工作包代號 WP-03、WP-3、3 視為同一包，比對前先正規化，免得寫法差一個零就漏擋。
wp-lock、wp-unlock、wp-claim、wp-unclaim、wp-report 不讀標準輸入，避免在沒有 JSON 餵入時卡住。

測試結果

子功能 PR plugins/hooks#30 已完成該層的驗證並合併，含 wire-cli.sh smoke 新補的四條判定路徑，本 PR 不再重跑一次。
主幹整合後複驗：sh -n hooks/sdlc-gate.sh、sh -n tools/wire-cli.sh 皆通過。
主幹整合後複驗：jsc-meta/tools/ste100-lint.sh 掃整個存取庫全綠。

前置 Push Request

無

# PR 描述 ## 摘要 - 需求描述：把功能主幹 `feat/sdlc-flow-rules/main` 累積的內容整批推上 `develop`。本存取庫負責使用者 15 條規則第一群「SDLC 執行流程」裡的 R4 工作包隔離：一個工作包的 PR 沒合併，擋的是相依於它的工作包，而不是整份分析；而且要擋得住「動到別人工作包的 PR」。原本的閘門只記得有沒有未結清的 PR，記不得那支 PR 屬於哪一包，所以擋不掉跨包操作。這裡把工作包歸屬寫進狀態層，讓判定跨工作階段仍然有效。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無本 PR 併入 5 個 commit，來自已合併的子功能 PR [plugins/hooks#30](https://gitea.jsc.idv.tw/plugins/hooks/pulls/30)。 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `hooks/sdlc-gate.sh` | 新增 `wp-claim`、`wp-unclaim` 兩個子指令記錄與交回工作包歸屬；`wp-lock` 多收一個工作包代號參數；`wp-check` 加上歸屬比對。歸屬是 R4 判定的依據，沒有它閘門只能擋「有沒有未結清的 PR」，擋不到「這支 PR 是不是你這一包的」 | | `tools/wire-cli.sh` | 冒煙測試補驗工作包歸屬的四條判定路徑。新增的判定沒有測試蓋到，等於沒有 | | `README.md` | 補上工作包歸屬狀態檔的欄位格式。這份格式是 `jsc-sdlc` 的 `wp-gate.sh` 讀取的契約，寫在文件裡兩邊才對得上 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 三份 manifest 版本同步升到 `0.2.3` | ## 設計重點 - 歸屬一律以**分析頁的工作包代號**為準，不以分支名、也不以目錄名——後兩者都可能被改。決策紀錄見 wiki [QUESTION_FB8DF0B5](https://gitea.jsc.idv.tw/knowledges/QUESTION/wiki/QUESTION_FB8DF0B5) 的 2026-08-27 那一節 Q2。 - **查無歸屬就放行**（Q5）。沒有分析頁、或查不到工作包代號時一律 exit 0 放行，只注入一句提醒。這跟 `version-guard.sh`「只擋確定違規」的既有裁決一致：技能組維護、臨時修 bug 這類散工本來就沒有分析頁，擋下去等於把自己鎖死。`wp-lock` 沒帶工作包代號時也會明講「之後一律放行」，讓使用者知道自己少給了什麼。 - 狀態刻意**不綁工作階段 ID**，寫在 `$JSC_HOME/wp/` 底下的純文字檔。換工作階段、開新對話照樣擋得住，這是既有裁決的延續。 - 讀寫分工不重疊：hook 這半（`wp-check`）只注入提醒並擋掉別的階段技能，不打網路；查 Gitea 與解鎖由 `jsc-sdlc` 的 `wp-gate.sh` 單方負責。兩邊都能改狀態的話，鎖為什麼不見了就沒有人說得清。 - 狀態檔一律走子命令寫入，不讓呼叫端自己拼檔案。兩邊各拼各的，格式一改就對不上，而且誰寫壞了看不出來。 - 工作包代號 `WP-03`、`WP-3`、`3` 視為同一包，比對前先正規化，免得寫法差一個零就漏擋。 - `wp-lock`、`wp-unlock`、`wp-claim`、`wp-unclaim`、`wp-report` 不讀標準輸入，避免在沒有 JSON 餵入時卡住。 ## 測試結果 - 子功能 PR [plugins/hooks#30](https://gitea.jsc.idv.tw/plugins/hooks/pulls/30) 已完成該層的驗證並合併，含 `wire-cli.sh smoke` 新補的四條判定路徑，本 PR 不再重跑一次。 - 主幹整合後複驗：`sh -n hooks/sdlc-gate.sh`、`sh -n tools/wire-cli.sh` 皆通過。 - 主幹整合後複驗：`jsc-meta/tools/ste100-lint.sh` 掃整個存取庫全綠。 ## 前置 Push Request - 無

jiantw83 added 5 commits 2026-08-27 03:38:54 +00:00

feat(sdlc-gate): 工作包閘門加上歸屬比對與領取紀錄 870f52fbaa

What：`hooks/sdlc-gate.sh` 新增 `wp-claim {owner}/{repo} {工作包代號} [{PR 編號}] [{分析頁}]` 與 `wp-unclaim {owner}/{repo}` 兩個子命令，`wp-lock` 新增第四個參數收工作包代號，鎖檔改為純文字 `key=value`，`wp-report` 多印第四欄工作包代號。`wp-check` 逐筆判歸屬：`prompt` 多注入一行點名不屬於這裡的 PR，`skill` 擋下 `plan`、`analyze`、`maintain` 時一併點名，`implement` 仍放行但收到同一則提醒。

Why：同一份分析常有好幾包平行進行，每包各自的 worktree 與 PR。原本的鎖檔只記存取庫與 PR 編號，看不出那支 PR 是誰的，於是任何一個工作階段都可能去改別包的程式碼、回別包的留言。

How：歸屬只比一件事——鎖檔的 `wp` 與同一個存取庫領取檔的 `wp` 取數字比一次，兩邊都有值且不相等就是別包的。`WP-03`、`WP-3`、`3` 先正規化再比，不然同一包的幾種寫法會被當成不同包。任何一邊查不到（沒有分析頁、沒寫代號、領取檔不存在）一律當查無歸屬並放行，理由與 `version-guard.sh` 一致：只擋確定違規，否則會把技能組維護自己鎖死。舊版單行 TSV 鎖檔照樣讀得動，讀出來是查無歸屬，換格式不會讓既有的鎖失效。`implement` 一律放行，連別包的 PR 未結清也放行——結清 PR 正是 `implement` 的步驟，擋它會把流程鎖死。分類迴圈用 here-document 餵資料而不用管線，管線右邊是子 shell，判到的違規會在迴圈結束時全部消失。

Who：跑 SDLC 實作階段的每個工作階段，以及 `jsc-sdlc/tools/wp-gate.sh` 的 `claim`、`lock` 與 `owns`。

test(wire-cli): 冒煙測試補驗工作包歸屬的四條判定路徑 3b6dd1b901

What：`tools/wire-cli.sh` 的 `smoke` 新增一段，用一份暫時的 `$JSC_HOME` 狀態檔把「狀態檔不存在」「PR 屬於領取中的工作包」「PR 屬於別的工作包」「逃生門 `JSC_WP_GATE=off`」四種情境各跑一次，逐一比對結束碼；收尾那句 `status=ok` 的說明也跟著補上這一段。

Why：原本兩支 `wp-check` 冒煙都把技能名清空，只走得到「沒有未結清 PR」與「取不到技能名」兩條捷徑，歸屬比對整段一次都沒跑到。判定寫了卻沒驗，等於沒寫。

How：驗的是判定結果本身，不只是腳本跑得完——每一種情境都給定預期結束碼，對不上就計入失敗並印出前 200 字的輸出。狀態檔放在暫時目錄，冒煙測試不該在使用者真正的 `$JSC_HOME/wp/` 留下痕跡。每次呼叫都接 `</dev/null`：`wp-check` 會讀標準輸入，管線沒人關閉時整支會卡死。建不出暫存目錄也算失敗，不能靜悄悄跳過。

Who：`jsc-hooks:hooks-install` 接線後跑的冒煙測試，以及改動 `sdlc-gate.sh` 歸屬判定的人。

docs(hooks): README 補上工作包歸屬狀態檔格式 29facd385c

What：README 新增「工作包歸屬狀態檔」一節，用表列出鎖檔與領取檔的檔名、欄位與範例，寫明誰寫誰讀、查無歸屬一律放行、舊版 TSV 鎖檔照樣讀得動；`sdlc-gate.sh` 與 `wire-cli.sh` 兩列的說明同步補上新子命令與冒煙測試的新內容。

Why：狀態檔的格式是 `jsc-hooks` 與 `jsc-sdlc` 兩邊的介面。介面只寫在腳本註解裡，另一邊改的時候看不到，格式一走鐘歸屬就全部誤判。

How：格式壓到最簡的純文字 `key=value`，一行一欄位，順序不拘，不認得的鍵一律忽略，兩邊各自實作也對得上。表只寫欄位與範例，判定規則寫在表底下的三段短說明。

Who：讀 `jsc-hooks` 說明的人，以及 `jsc-sdlc` 那一側寫 `wp-gate.sh` 的人。

chore(manifest): 三份 manifest 版本升到 0.2.3 be75cc4bed

What：`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 的 `version` 由 0.2.2 改為 0.2.3。

Why：本次新增 `wp-claim`、`wp-unclaim` 兩個子命令並改了鎖檔格式，屬於行為變更，版本要跟著往上走，各 CLI 才知道要更新。

How：三份只改 `version` 一個欄位，其餘內容不動，三份保持同一版號。

Who：`jsc-hooks` 外掛的套件描述檔。

Merge pull request 'feat(hooks): 工作包歸屬比對與狀態檔格式' (#30 ) from feat/sdlc-flow-rules/wp-scope-gate into feat/sdlc-flow-rules/main e53dd802b8

Reviewed-on: #30

jiantw83 merged commit e714c6ade2 into develop

2026-08-27 03:39:38 +00:00

jiantw83 deleted branch feat/sdlc-flow-rules/main

2026-08-27 03:39:38 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/hooks#31