fix/skill-check-compliance-and-flow #44

2026-08-31T03:14:58Z

jiantw83 commented

2026-08-31 03:14:58 +00:00

摘要

需求描述：技能組例行稽核在開發生命週期外掛上開出的合規與流程效率修正。合規面把技能內文寫得跟腳本實際行為一致，補齊閘門非零退出的分支，並替目錄頁補上寫入語意。效率面把停止條件與相依閘門移到流程最前面，並把彼此不相依的工作改成併行。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`skills/plan/SKILL.md`	開場補上「wiki 讀寫失敗就停」的規則，避免對讀不到的頁面繼續動作。計畫目錄改成先讀回整頁再更新自己那一列，並新增附加語意小節與讀取退出碼對照表。硬性限制補上寫入閘門只在一支 CLI 生效的事實。另外寫明工作包閘門在這個階段降成提醒後，放棄的是哪一道保護
`skills/analyze/SKILL.md`	步驟原本混用中文，改回英文與其他技能一致。把「有沒有計畫可分析」移到最前面，沒有可選就直接停，不再先問分支。盤點目錄改成先讀回再更新一列，並補上附加語意小節與退出碼對照表。開場同樣補上 wiki 失敗即停
`skills/implement/SKILL.md`	閘門與停止條件移到最前面：先讀分析頁、批次預取已開 PR 狀態，再列候選、逐一過相依閘門，沒有可挑的工作包就停。領包登錄不成功不得開工。來源分支改成單鍵確認，兩種例外仍走完整決策樹。交付目錄與維護目錄改成先讀回再更新一列，並新增附加語意小節與退出碼對照表。多個存取庫的 worktree 與兩關收尾稽核改成併行
`skills/maintain/SKILL.md`	存取庫的抓取與分支對齊改成整批併行，之後才逐專案循序跑。維護目錄改成先讀回再更新那一列，其餘專案的列不得變動，並新增附加語意小節與退出碼對照表。開場補上 wiki 失敗即停，註解把關交給既有的兩道掃描，不再多做一輪人工自查
`references/branch.md`	hook 閘門的說明與實際行為不符：規劃階段其實只印提醒就放行。改成照實描述，並寫出放棄在製品上限的代價，以及實作階段一律放行的理由。指向實作技能的步驟編號跟著搬移後的順序更新
`references/model-gate.md`	這份規則寫「非零退出該回合不做別的事」，階段回報那份卻要求提前停下來也要回報，兩邊互相矛盾。改成明確保留階段回報這一項
`tools/wp-gate.sh`	檔頭的用法說明漏了上鎖時可帶的工作包參數，讀腳本的人看不出 PR 要怎麼掛到工作包名下。補上該參數與不帶它的後果
`templates/plan-contents.md`	範本沒寫寫入語意，套用時容易整頁覆蓋。補上先讀回整頁、有列就更新、沒有才附加的規則
`templates/analyze-contents.md`	同上，補上一列代表一份分析頁的寫入語意
`templates/deliver-contents.md`	同上，補上一列代表一個工作包交付的寫入語意
`templates/maintain-contents.md`	同上，補上一列代表一個受維護存取庫的寫入語意
`templates/repo-contents.md`	同上，補上一列代表一個存取庫盤點的寫入語意
`README.md`	技能摘要與腳本說明要跟改後的流程一致：閘門用法數量、各階段的併行點、規劃階段的閘門降級，以及分析階段先選計畫再確認分支的順序
`plugin.json`	補上維護階段實際會呼叫的套件外掛相依，並提高 hook 外掛的相依下限，讓寫入閘門與註解掃描的行為有依據
`.claude-plugin/plugin.json`	同上，三份外掛宣告要一致，否則不同 CLI 裝到的相依不同
`.codex-plugin/plugin.json`	同上，三份外掛宣告要一致，否則不同 CLI 裝到的相依不同

設計重點

來源分支改成單鍵確認。放棄的是每一輪都要使用者親口說出「來源分支同時也是 PR 目標」的雙向確認。分析頁上若記著過期或錯誤的目標，這一輪不會再被問出來，會直接進到 PR。保留兩種強制例外：分析頁沒有記錄，以及該分支在遠端找不到，這兩種情況仍走完整決策樹。
規劃階段的工作包閘門降為提醒。放棄的是在製品上限：手上還有沒結清的工作包時，照樣可以開新計畫，計畫會比實作累積得更快。提醒仍會指名沒結清的工作包，分析與維護兩個階段的閘門仍然擋人，上限只是晚一個階段才生效。
閘門的失敗分支要寫全，不能只寫成功路徑。腳本的用法錯誤與查不到的情況各有明確處置，領包登錄與上鎖也補上查不到就停的分支。領包沒登錄成功就不得開工：沒有歸屬紀錄，歸屬比對對任何一支 PR 都會回報查無歸屬，之後每個工作階段都會被放行到別人的 PR 上。
目錄頁只能附加，不能整頁覆蓋。目錄頁上的每一列都屬於別人的計畫、工作包或存取庫，這一輪不會從別處讀到那些列。整頁套範本寫回去，別人的列就會消失，而且寫入沒有合併也沒有備份。所以五份目錄範本都寫明先讀回整頁、有列就更新、沒有才附加，四支技能各補一節附加語意與讀取退出碼對照表：只有「頁面確實不存在」這個碼可以走建立路徑，權限錯誤與其他 API 失敗一律停下來回報。
停止條件與閘門移到最前面，白工才不會發生。實作階段先列候選、先過相依閘門，只有通過的才進選項；分析階段先確認有沒有計畫可分析。原本的順序會先跑完決策樹、寫過 wiki、抓過遠端、改過工作階段名稱，才發現沒得做。
彼此不相依的工作改成併行：兩關收尾稽核同時啟動、多個存取庫的 worktree 同時建立、候選工作包的相依查驗與已開 PR 的狀態預取都整批發出。互動仍維持一次一則，併行只用在查詢與建立。
說明與行為對齊。閘門在規劃階段的實際行為、模型閘門非零退出時仍要跑階段回報、上鎖可帶的工作包參數，這三處原本的文字都跟實作對不上。

測試結果

這個存取庫沒有測試套件。改動集中在技能內文、參考文件、目錄範本與外掛宣告，只有一支腳本的檔頭註解有變動，沒有可執行的邏輯改變。
對 tools/ 底下的每一支腳本跑 bash -n：tools/stage-report.sh 結束碼 0，tools/wp-gate.sh 結束碼 0，兩支語法都沒有問題。
不帶參數跑 bash tools/wp-gate.sh：結束碼 2，第一行印出 status=usage，接著印出五個子命令的用法與結束碼說明，與檔頭註解一致。
以上就是實際跑過的全部，沒有跑其他測試。

前置 Push Request

無

## 摘要 - 需求描述：技能組例行稽核在開發生命週期外掛上開出的合規與流程效率修正。合規面把技能內文寫得跟腳本實際行為一致，補齊閘門非零退出的分支，並替目錄頁補上寫入語意。效率面把停止條件與相依閘門移到流程最前面，並把彼此不相依的工作改成併行。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `skills/plan/SKILL.md` | 開場補上「wiki 讀寫失敗就停」的規則，避免對讀不到的頁面繼續動作。計畫目錄改成先讀回整頁再更新自己那一列，並新增附加語意小節與讀取退出碼對照表。硬性限制補上寫入閘門只在一支 CLI 生效的事實。另外寫明工作包閘門在這個階段降成提醒後，放棄的是哪一道保護 | | `skills/analyze/SKILL.md` | 步驟原本混用中文，改回英文與其他技能一致。把「有沒有計畫可分析」移到最前面，沒有可選就直接停，不再先問分支。盤點目錄改成先讀回再更新一列，並補上附加語意小節與退出碼對照表。開場同樣補上 wiki 失敗即停 | | `skills/implement/SKILL.md` | 閘門與停止條件移到最前面：先讀分析頁、批次預取已開 PR 狀態，再列候選、逐一過相依閘門，沒有可挑的工作包就停。領包登錄不成功不得開工。來源分支改成單鍵確認，兩種例外仍走完整決策樹。交付目錄與維護目錄改成先讀回再更新一列，並新增附加語意小節與退出碼對照表。多個存取庫的 worktree 與兩關收尾稽核改成併行 | | `skills/maintain/SKILL.md` | 存取庫的抓取與分支對齊改成整批併行，之後才逐專案循序跑。維護目錄改成先讀回再更新那一列，其餘專案的列不得變動，並新增附加語意小節與退出碼對照表。開場補上 wiki 失敗即停，註解把關交給既有的兩道掃描，不再多做一輪人工自查 | | `references/branch.md` | hook 閘門的說明與實際行為不符：規劃階段其實只印提醒就放行。改成照實描述，並寫出放棄在製品上限的代價，以及實作階段一律放行的理由。指向實作技能的步驟編號跟著搬移後的順序更新 | | `references/model-gate.md` | 這份規則寫「非零退出該回合不做別的事」，階段回報那份卻要求提前停下來也要回報，兩邊互相矛盾。改成明確保留階段回報這一項 | | `tools/wp-gate.sh` | 檔頭的用法說明漏了上鎖時可帶的工作包參數，讀腳本的人看不出 PR 要怎麼掛到工作包名下。補上該參數與不帶它的後果 | | `templates/plan-contents.md` | 範本沒寫寫入語意，套用時容易整頁覆蓋。補上先讀回整頁、有列就更新、沒有才附加的規則 | | `templates/analyze-contents.md` | 同上，補上一列代表一份分析頁的寫入語意 | | `templates/deliver-contents.md` | 同上，補上一列代表一個工作包交付的寫入語意 | | `templates/maintain-contents.md` | 同上，補上一列代表一個受維護存取庫的寫入語意 | | `templates/repo-contents.md` | 同上，補上一列代表一個存取庫盤點的寫入語意 | | `README.md` | 技能摘要與腳本說明要跟改後的流程一致：閘門用法數量、各階段的併行點、規劃階段的閘門降級，以及分析階段先選計畫再確認分支的順序 | | `plugin.json` | 補上維護階段實際會呼叫的套件外掛相依，並提高 hook 外掛的相依下限，讓寫入閘門與註解掃描的行為有依據 | | `.claude-plugin/plugin.json` | 同上，三份外掛宣告要一致，否則不同 CLI 裝到的相依不同 | | `.codex-plugin/plugin.json` | 同上，三份外掛宣告要一致，否則不同 CLI 裝到的相依不同 | ## 設計重點 - 來源分支改成單鍵確認。放棄的是每一輪都要使用者親口說出「來源分支同時也是 PR 目標」的雙向確認。分析頁上若記著過期或錯誤的目標，這一輪不會再被問出來，會直接進到 PR。保留兩種強制例外：分析頁沒有記錄，以及該分支在遠端找不到，這兩種情況仍走完整決策樹。 - 規劃階段的工作包閘門降為提醒。放棄的是在製品上限：手上還有沒結清的工作包時，照樣可以開新計畫，計畫會比實作累積得更快。提醒仍會指名沒結清的工作包，分析與維護兩個階段的閘門仍然擋人，上限只是晚一個階段才生效。 - 閘門的失敗分支要寫全，不能只寫成功路徑。腳本的用法錯誤與查不到的情況各有明確處置，領包登錄與上鎖也補上查不到就停的分支。領包沒登錄成功就不得開工：沒有歸屬紀錄，歸屬比對對任何一支 PR 都會回報查無歸屬，之後每個工作階段都會被放行到別人的 PR 上。 - 目錄頁只能附加，不能整頁覆蓋。目錄頁上的每一列都屬於別人的計畫、工作包或存取庫，這一輪不會從別處讀到那些列。整頁套範本寫回去，別人的列就會消失，而且寫入沒有合併也沒有備份。所以五份目錄範本都寫明先讀回整頁、有列就更新、沒有才附加，四支技能各補一節附加語意與讀取退出碼對照表：只有「頁面確實不存在」這個碼可以走建立路徑，權限錯誤與其他 API 失敗一律停下來回報。 - 停止條件與閘門移到最前面，白工才不會發生。實作階段先列候選、先過相依閘門，只有通過的才進選項；分析階段先確認有沒有計畫可分析。原本的順序會先跑完決策樹、寫過 wiki、抓過遠端、改過工作階段名稱，才發現沒得做。 - 彼此不相依的工作改成併行：兩關收尾稽核同時啟動、多個存取庫的 worktree 同時建立、候選工作包的相依查驗與已開 PR 的狀態預取都整批發出。互動仍維持一次一則，併行只用在查詢與建立。 - 說明與行為對齊。閘門在規劃階段的實際行為、模型閘門非零退出時仍要跑階段回報、上鎖可帶的工作包參數，這三處原本的文字都跟實作對不上。 ## 測試結果 - 這個存取庫沒有測試套件。改動集中在技能內文、參考文件、目錄範本與外掛宣告，只有一支腳本的檔頭註解有變動，沒有可執行的邏輯改變。 - 對 `tools/` 底下的每一支腳本跑 `bash -n`：`tools/stage-report.sh` 結束碼 0，`tools/wp-gate.sh` 結束碼 0，兩支語法都沒有問題。 - 不帶參數跑 `bash tools/wp-gate.sh`：結束碼 2，第一行印出 `status=usage`，接著印出五個子命令的用法與結束碼說明，與檔頭註解一致。 - 以上就是實際跑過的全部，沒有跑其他測試。 ## 前置 Push Request - 無

jiantw83 added 5 commits 2026-08-31 03:14:58 +00:00

fix(gate): 閘門說明與實際行為對齊 de7962a8c1

兩份參考文件跟實際判定互相矛盾。照著做會漏掉收尾，或是擋錯階段。

- 模型閘門非零退出時，該回合仍要跑階段回報。提前停下來也要留紀錄，不然使用者看不到停在哪裡。
- 工作包閘門只擋分析與維護：規劃只印提醒就放行，實作一律放行。實作是結清那支 PR 的唯一路徑，擋了閘門就自己鎖死。
- 順帶把指向實作技能的步驟引用改成新的順序。

feat(contents): 目錄頁改為先讀回再附加 39a7e17b85

目錄頁的每一列都屬於別人的計畫、工作包或存取庫。過去照範本整頁覆寫，別人的列會直接消失，而且寫入不做合併，也沒有備份。

- 五份目錄範本都寫明寫入語意：先讀回整頁，已有的列就更新，沒有才附加。
- 規劃與維護技能加上讀取結束碼分支表。只有「頁面真的不存在」才准照範本建頁；金鑰失效或 API 失敗一律停下來回報，不得當成沒有頁面。
- wiki 讀或寫失敗就停止該階段，並指出是哪一頁、哪一個動作失敗，避免把沒存成功的頁面報成已存。
- 補上寫入閘門只有 claude 擋得住的事實，其餘四支 CLI 只能靠內文約束。
- 記下工作包閘門對規劃階段降為提醒後放棄的在製品上限。
- 維護階段先整批對齊各專案再逐一交給 sub agent，專案之間互不相依。

perf(sdlc): 停止條件與閘門移到最前面 015ceb66d2

過去先問來源分支、先產生工作證、先建 worktree，等跑到閘門才發現沒有可挑的項目。前面的決策樹、wiki 寫入、抓取遠端與改名全部白做。

- 實作先讀分析頁、先結清已開 PR 的留言，再逐一過相依閘門，只有通過的候選才進選項。來源分支與工作證都移到領到工作包之後。
- 分析先併行讀計畫與分析目錄，沒有可分析的計畫就直接停。分支隨計畫而變，所以等目標定了才問。
- 互不相依的呼叫改成併發：已開 PR 的狀態批次預取、每個候選的相依查詢同時發、多個存取庫的 worktree 一起建、兩道收尾稽核並列跑。
- 領取登錄不成功就不得開工。沒有登錄，存取庫就沒有歸屬紀錄，之後每一支 PR 都會被當成無人認領而放行。上鎖失敗同樣要停，否則下一個工作階段會在 PR 還沒合併時就被放行。
- 來源分支改成單鍵確認。放棄的是每輪都要使用者明講「來源分支同時是 PR 目標」這道確認；分析頁沒記錄、遠端找不到分支這兩種例外仍走完整決策樹。
- 把仍寫成中文的驗收計畫步驟改回英文，與其他步驟一致。

docs(sdlc): 說明同步實際流程 0bb00d2fb9

說明跟腳本、技能的實際行為對不上，讀的人會照舊做法走。

- 工作包閘門腳本的檔頭補上上鎖的工作包參數。不帶就沒有歸屬，歸屬比對對誰都放行。
- 腳本用法數量改成正確的五個。
- 四段技能摘要改寫成現在的流程：閘門與停止條件先跑、互不相依的動作併發、寫入閘門只有 claude 擋得住、認可前的留言掃描是其餘四支 CLI 唯一來得及的一道。

chore(deps): 補上維護階段實際用到的相依外掛 dfe4ed03ca

維護階段的候選方法直接呼叫 jsc-pkg 更新套件，相依清單卻沒有列它。裝了本外掛不一定裝得到，跑到那一步才失敗。

- 三份外掛描述檔都補上 jsc-pkg。
- 提高 jsc-hooks 的版本下限。本次流程倚賴的寫入閘門與留言掃描要新版才有。
- 同步調高本外掛版本。

admin merged commit 3713fde61e into develop

2026-08-31 03:33:43 +00:00

admin deleted branch fix/skill-check-compliance-and-flow

2026-08-31 03:33:43 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/sdlc#44