From 3f622ba6463e64fdec2df29650b1e712cc367947 Mon Sep 17 00:00:00 2001 From: claude-code Date: Fri, 28 Aug 2026 00:54:21 +0000 Subject: [PATCH] =?UTF-8?q?=E4=B8=80=E6=AC=A1=E4=BA=A4=E8=B2=A8=20?= =?UTF-8?q?=EF=BC=9D=20=E4=B8=80=E4=BB=BD=E8=B7=A8=20repo=20=E7=89=88?= =?UTF-8?q?=E6=9C=AC=E6=B8=85=E5=96=AE=EF=BC=88inkstone/ISEP#84=EF=BC=89?= =?UTF-8?q?=20=20=20=20=20=20=20=EF=BC=8B=20=E6=AF=8F=E6=AC=A1=E7=B5=90?= =?UTF-8?q?=E6=A1=88=E9=83=BD=E7=95=99=E4=B8=8B=E4=BC=B0=E5=A4=9A=E4=B9=85?= =?UTF-8?q?=EF=BC=8F=E8=8A=B1=E5=A4=9A=E4=B9=85=EF=BC=8F=E5=B7=AE=E5=A4=9A?= =?UTF-8?q?=E5=B0=91=EF=BC=88inkstone/ISEP#85=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #84：scripts/release-manifest freeze 前每一格都真的去 Gitea 抓過（抓不到不給凍結）；凍結後不准再加東西； rollback 一定吐出整份清單的每一格，--only 指名單一 repo 會被擋下 ——那正是票上那個病：剩下的還停在新版 ⇒ 一組從來沒測過的組合。 清單與 INDEX.md 寫在專案根的 releases/（不是 plugin 目錄，plugin update 會清掉）。 #85：scripts/milestone-account ＋ hooks/milestone-account-guard.sh 三個數字自己算（取自 Gitea 的 created_at／due_on／closed_at，不用手填）； 差超過 ±25%（超時或提早都算）就要從七個固定代號裡挑一個，挑不出來不准結案； 代號要有 Gitea 時間軸撐得住——訊號不成立的代號直接拒收（不採信自述）。 閘擋的是「直接 curl PATCH state=closed 但還沒記帳」，正門走 milestone-account close。 盤點數字在本樹實數（ls hooks/*.sh｜grep -c '"command":'）： hooks 53→54 支、註冊 68→69 條、scripts 39 支（描述欄舊的 38 把三個目錄也數進去了）。 順手修掉 docs/hooks-inventory.md「一句話結論」被貼兩次、且標頭 52／內文 53 互相矛盾。 測試（全部離線，不打 Gitea、不留測試票／不關真的 milestone）： scripts/test-release-manifest.sh 21/21 scripts/test-milestone-account.sh 23/23 hooks/tests/milestone-account-guard.test.sh 22/22 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_016ZBu4Sa1cGntKFRBYNZ6xs --- .claude-plugin/plugin.json | 2 +- README.md | 2 +- docs/TESTING.md | 65 ++ docs/hooks-inventory.md | 15 +- hooks/hooks.json | 4 + hooks/milestone-account-guard.sh | 107 ++++ hooks/tests/milestone-account-guard.test.sh | 85 +++ scripts/milestone-account | 634 ++++++++++++++++++++ scripts/release-manifest | 410 +++++++++++++ scripts/test-milestone-account.sh | 155 +++++ scripts/test-release-manifest.sh | 98 +++ 11 files changed, 1572 insertions(+), 5 deletions(-) create mode 100755 hooks/milestone-account-guard.sh create mode 100755 hooks/tests/milestone-account-guard.test.sh create mode 100755 scripts/milestone-account create mode 100755 scripts/release-manifest create mode 100755 scripts/test-milestone-account.sh create mode 100755 scripts/test-release-manifest.sh diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 9fadbbc..4f04017 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "isep", - "description": "InkStone Environment Plugin —— leo 的 Claude Code 環境唯一真相源：53 支機械閘（68 條註冊，白話盤點見 docs/hooks-inventory.md）、7 支 slash command、2 支 skill、38 支腳本，外加治理規範與標籤真相源。本機與雲端裝同一份，沒有子集。", + "description": "InkStone Environment Plugin —— leo 的 Claude Code 環境唯一真相源：54 支機械閘（69 條註冊，白話盤點見 docs/hooks-inventory.md）、7 支 slash command、2 支 skill、39 支腳本，外加治理規範與標籤真相源。本機與雲端裝同一份，沒有子集。", "version": "0.11.0", "keywords": [ "inkstone", diff --git a/README.md b/README.md index 38c7fb0..b653fe8 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ | | 數量 | 是什麼 | |---|---|---| -| `hooks/` | 48 支 ＋ `hooks.json` | 全部機械閘（PreToolUse／Stop／SubagentStop／SessionStart／PostToolUse 共 59 條註冊；`ISEP#60` 移除 `claim-verify-police.sh`／`subagent-claim-worksheet.sh` 這對自造機制，改由 Gitea 原生三格承接見 `ISEP#59`） | +| `hooks/` | 54 支 ＋ `hooks.json` | 全部機械閘（PreToolUse／Stop／SubagentStop／SessionStart／PostToolUse 共 69 條註冊，2026-08-28 在樹上實數；`ISEP#60` 移除 `claim-verify-police.sh`／`subagent-claim-worksheet.sh` 這對自造機制，改由 Gitea 原生三格承接見 `ISEP#59`） | | `commands/` | 7 支 | `/wiki-recall` `/ship-check` `/cp-write` … | | `skills/` | 2 支 | | | `scripts/` | 23 支 | `ticket`／`github-arm.sh`／`gitea-bootstrap.sh` … | diff --git a/docs/TESTING.md b/docs/TESTING.md index 3b7763b..eec87b5 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -165,6 +165,68 @@ bash hooks/tests/prod-write-guard.test.sh hooks/prod-write-guard.sh - 「卡點二」2 條任一紅 ⇒ 「談論它」又被當成「執行它」（同款第八次）， 或是剝了內文之後連真的部署都放行了 +### A16 — 一次交貨 ＝ 一份清單（跨 repo 版本組合）：21 條 +``` +bash scripts/test-release-manifest.sh +``` +**該看到**：`通過 21 條，失敗 0 條`。全程離線（`RELEASE_MANIFEST_FIXTURE`）， +**不打 Gitea、不建任何真的 release**；清單寫在 `mktemp` 的目錄，不碰 repo 裡的 `releases/`。 + +**它在守什麼**（`inkstone/ISEP#84`）：一次交貨常常同時動到好幾個 repo， +而「這一版 ＝ 哪幾個 repo 的哪幾版」**沒有任何地方記著** ⇒ 退版只退了其中一個， +剩下的還停在新版 ⇒ **變成一組從來沒測過的組合**。 + +**失敗**： +- ⑨⑩ 紅 ⇒ 驗收 1 沒過：**版本號寫上去就算數**，沒有真的去 Gitea 抓過 + （「寫上去」跟「存在」是兩件事，而清單的用處完全建立在後者） +- ⑱ 紅 ⇒ 驗收 3 沒過：**只退其中一個 repo 沒有被擋下來**，那正是票上那個病 +- ⑯⑰⑲ 任一紅 ⇒ 驗收 2 沒過：退版沒有吐出整份清單的每一格 + （包含「已經在目標版本、不必動」那幾格——列出來才證明沒有一格被漏掉） +- ⑫ 紅 ⇒ 凍結過的清單還能再加東西，「凍結」兩個字就沒有意義了 +- ⑳㉑ 紅 ⇒ 驗收 4 沒過：leo 打開 `INDEX.md` 看不出「我現在手上是哪一版」 + +### A17 — 每次結案都留下估多久／花多久／差多少：23 條 +``` +bash scripts/test-milestone-account.sh +``` +**該看到**：`通過 23 條，失敗 0 條`。全程離線（`MILESTONE_ACCOUNT_FIXTURE` ＝一份假的 +Gitea 回應表），時鐘用 `MILESTONE_ACCOUNT_NOW` 定住，帳本寫在 `mktemp` 目錄， +**不打 Gitea、不關任何真的 milestone**。 + +**它在守什麼**（`inkstone/ISEP#85`，leo 2026-08-27 說那天「**拖時間**」）： +拖了多久、比預計多拖多少、為什麼拖——**沒有任何數字**。偵測器早就有了 +（`mainline-idle-guard.sh`／`factory-idle-guard.sh`），**但沒有人把它算成帳**。 + +**失敗**： +- ①②③④ 任一紅 ⇒ 驗收 1 沒過：三個數字不是自己算出來的 +- ⑤⑥ 紅 ⇒ 驗收 2 沒過：差超過 ±25% 卻能不挑代號就結案 +- ⑧ 紅 ⇒ 代號不再是封閉集合。**能統計的前提是分類有限**，這一格垮了統計就垮了 +- ⑨ 紅 ⇒ **挑一個時間軸撐不住的代號也能過**，等於「採信我自己說的」， + 而票上寫死證據一律從 Gitea 的時間軸取 +- ⑦ 紅 ⇒ **誤攔**：只差 -6% 也逼人挑代號。這比漏擋嚴重——每次結案都被念， + 人就學會繞過去 +- ⑭⑮⑯⑰ 任一紅 ⇒ 驗收 3 沒過：累積之後看不出哪一種原因最常發生 +- ⑱⑲ 紅 ⇒ 驗收 4 沒過：拿已經逾期的里程碑進去算不出數字 + +### A18 — 結案要記帳的那道閘：22 條 +``` +bash hooks/tests/milestone-account-guard.test.sh +``` +**該看到**：`通過 22 條，失敗 0 條`。離線（帳本走 `MILESTONE_ACCOUNT_LEDGER`）， +純結構判斷、沒有語意判官，所以每次結果都一樣。 + +**失敗**： +- **A 群任何一條紅 ⇒ 誤攔，這比漏擋嚴重。** ⑥⑦⑧⑪ 特別重要： + `echo` 一段指令、`cat` 這支閘自己、commit 訊息裡提到、把指令寫進文件的 heredoc 內文 + ——**四種都只是「談論它」，不是「執行它」**。這四格是本 repo 撞過很多次的同一個病 + （`strip_heredoc.py` 的檔頭記著兩次真跡） +- ⑨⑩ 紅 ⇒ 走正門 `scripts/milestone-account close` 反而被自己的閘擋下， + 那道閘就等於封死了唯一的出路 +- ⑭⑮⑯⑰⑱ 任一紅 ⇒ 漏擋：換個寫法（`python urllib`、前面串一個無害指令、 + `--request` 長寫法、換一個 repo）就繞過去了 +- ⑲ 紅 ⇒ 訊息沒有點名目標，人看完不知道要對哪一個里程碑動手 +- ⑳㉑ 紅 ⇒ 「記過帳就放行」這個出路是假的，或者一記帳就把所有里程碑全開了 + ### A5 — 開票前的搜尋是跨 repo 的 ``` python3 scripts/ticket where 標籤 模組化 @@ -362,6 +424,9 @@ B2（信標那行）／B3（setup 輸出）／B4（閘的訊息）三個畫面 | **A15 pr-verdict --dry-run** | 總管 | ✅（2026-08-28） | | **A14 回覆自己說出拖了多久** | 總管 | ✅ 20/20（2026-08-28，inkstone/ISEP#63） | | **A15 發通知不等於部署** | 總管 | ✅ 37/37（2026-08-28，inkstone/ISEP#63） | +| **A16 跨 repo 版本清單** | 總管 | ✅ 21/21（2026-08-28，inkstone/ISEP#84） | +| **A17 估多久／花多久／差多少** | 總管 | ✅ 23/23（2026-08-28，inkstone/ISEP#85） | +| **A18 結案要記帳的閘** | 總管 | ✅ 22/22（2026-08-28，inkstone/ISEP#85） | | A5 搜尋跨 repo | 總管 | ✅ | | A6 標籤對齊＋冪等 | 總管 | ✅ 14 repo，第二次 0/0 | | **A9 人閘警察管路** | 總管 | ✅ 14/14（2026-08-26） | diff --git a/docs/hooks-inventory.md b/docs/hooks-inventory.md index d7f7a86..8a9b7a7 100644 --- a/docs/hooks-inventory.md +++ b/docs/hooks-inventory.md @@ -1,4 +1,4 @@ -# 52 支閘，白話盤點表 +# 54 支閘，白話盤點表 > 回應 `inkstone/InkStoneCo#40`：「如果加入了，我應該可以白話文看到 hooks 的內容？」 > 這份表就是那個「白話文」——不用點開任何 `.sh` 檔，一行看懂一支閘在管什麼。 @@ -7,8 +7,7 @@ ## 一句話結論 -`hooks/` 底下有 **53 個 `.sh` 檔**，`hooks.json` 實際掛上 **68 條註冊**（同一支閘常被多種情境同時掛上）； -`hooks/` 底下有 **53 個 `.sh` 檔**，`hooks.json` 實際掛上 **68 條註冊**（同一支閘常被多種情境同時掛上）； +`hooks/` 底下有 **54 個 `.sh` 檔**，`hooks.json` 實際掛上 **69 條註冊**（同一支閘常被多種情境同時掛上）； 其中 **3 支檔案存在但沒被掛上**（2 支是待人填的空範本、1 支是刻意留著沒開的止血帶，見下面「未生效」表）。 下面按「你會在什麼時候撞到它」分組，一支一行。 @@ -46,6 +45,15 @@ > 順手改掉一個過期的數字：描述欄長期寫「27 支腳本」，實數是 **34** > （`ls -p scripts | grep -v / | wc -l`）——**同一個病，只是換一欄。** +> 📌 **`inkstone/ISEP#85`（2026-08-28）進來一支**：`milestone-account-guard.sh`（A 組，PreToolUse／Bash）。 +> 53→**54** 支、68→**69** 條，兩個數字都是加完之後**在自己的樹上當場數出來的** +> （指令同上），**不是拿上一版加一**——`system-dev/wiki/mistakes.md` 記著這條： +> 那個數字是 leo 的驗收介面，多報就是假綠。 +> 順手修掉一個真的漂移：上一版「一句話結論」那一句**被貼了兩次**（同一行連續出現兩遍）， +> 而標頭寫 52、內文寫 53——**同一頁裡三個數字互相矛盾**，正是本頁自己警告過的那種病。 +> 另外描述欄的「38 支腳本」是把 `kbdb-live-exam/`／`lib/`／`patches/` 三個**目錄**也數進去了； +> 用本頁寫死的那道指令（只數檔案）實數是 **39**。 + --- ## 怎麼讀這張表 @@ -74,6 +82,7 @@ | `release-tag-guard.sh` | AI 想打版本 tag，但 `plugin.json` 裡寫的版本號跟 tag 對不上就擋下——避免「這裡說 0.2.0、那裡說 0.1.0」各說各話。 | 🛑 擋 | | `ticket-api-bypass-guard.sh` | AI 想繞過 `scripts/ticket` 工具、直接打 API 新增 Gitea 東西（開新票／milestone／label／PR，會漏掉「新增前先搜過」這道檢查）就擋下——不管是隱式 POST（urllib 傳 data= 沒寫 method）還是小寫 `requests.post(...)`。 | 🛑 擋 | | `milestone-due-guard.sh` | AI 想開一個新的里程碑（milestone）卻沒填期限就擋下，**填 `9999-01-01` 一樣擋**——那是「沒有期限」穿了一件期限的衣服，盤點時每一格看起來都有值，其實一格都沒有。只管「建里程碑」這個動作，查詢／改別的欄位都放行。 | 🛑 擋 | +| `milestone-account-guard.sh` | AI 想直接打 API 把某個里程碑改成「已關閉」，卻**還沒留下「估多久／花多久／差多少／為什麼差」**就擋下。跟上一列是同一條線的兩端：那支管**開**里程碑要有真的期限，這支管**關**的時候要留下帳。走正門 `scripts/milestone-account close` 就會自己算（數字取自 Gitea 的 `created_at`／`due_on`／`closed_at`，不用手填），差超過 ±25% 才要你從**七個固定代號**裡挑一個，而且那個代號要有 Gitea 時間軸撐得住——**不採信自述**。純讀取／建里程碑／改期限／只是談論它／走正門，全部放行；真要手動關就在指令裡加 `milestone-account-ok`（留痕）。 | 🛑 擋 | | `reply-identity-guard.sh` | 直接打 Gitea API 貼留言到票上時，內文第一行沒有 `【身份】`（`總管`／`subagent`／`leo`）就擋下——票上多條線並行時，看不出哪一則是誰寫的。純讀取、走 `scripts/ticket` 正門、指令裡加 `reply-identity-ok` 都放行。 | 🛑 擋 | | `comment-carries-task-guard.sh` | AI 要在票裡留一則「等某某上線才驗得了」這種**還沒做完的事**，卻沒有把它開成一張子票時，擋一次。留言沒人會回頭讀，票的 open／closed 撈一次就看得到。 | 🛑 擋（同一輪只擋一次） | | `search-is-not-proof-guard.sh` | AI 用知識庫的**搜尋**找到一筆東西，然後把那筆東西的原始編號直接貼進票裡或派工單裡，當成「某個功能壞了」的證據——而它從沒用正規的檢索路徑去查過那筆——擋一次。你關心的是：不會再有人拿錯的方法量出一個錯的結論，然後退回一張其實已經做完的票。 | 🛑 擋（同一輪只擋一次） | diff --git a/hooks/hooks.json b/hooks/hooks.json index 4896338..9984cbf 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -49,6 +49,10 @@ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/milestone-due-guard.sh" }, + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/hooks/milestone-account-guard.sh" + }, { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/reply-identity-guard.sh" diff --git a/hooks/milestone-account-guard.sh b/hooks/milestone-account-guard.sh new file mode 100755 index 0000000..d50e22e --- /dev/null +++ b/hooks/milestone-account-guard.sh @@ -0,0 +1,107 @@ +#!/usr/bin/env bash +# 管什麼: 直接打 Gitea API 把一個里程碑改成 closed，卻沒有先記帳（估多久／花多久／ +# 差多少／為什麼差），就擋下來。 +# 為什麼: leo 2026-08-27 說那天「拖時間」，但拖了多久、比預計多拖多少、為什麼拖—— +# 一個數字都沒有。偵測器早就有了（mainline-idle-guard／factory-idle-guard）， +# **但沒有人把它算成帳**，所以事後只能說「這次比較慢」，下次還是一樣。 +# 誤觸時怎麼關: 走正門 `scripts/milestone-account close ` +# （它會自己算三個數字、自己去 Gitea 的時間軸取證據、然後幫你關）。 +# 真的有理由要繞過去 ⇒ 指令裡加 `milestone-account-ok`（留痕，commit 說明理由）。 +# +# milestone-account-guard.sh — 結案要記帳（PreToolUse／Bash；inkstone/ISEP#85） +# +# ── 這支跟 milestone-due-guard.sh 是同一條線的兩端 ──────────────────── +# 那支管**開**里程碑要有真的期限（沒有期限就沒有「估多久」可言）。 +# 這支管**關**里程碑要留下那三個數字。少了任何一端，帳都算不出來。 +# +# ── 判準：三件同時成立才擋，缺一放行 ────────────────────────────── +# ① 指令位置真的有人在發網路請求（curl／wget／python／node／gh） +# ——「講到它」跟「執行它」是兩件事，這是本 repo 已經證明過的判準 +# （release-tag-guard.sh 的 `git tag` 位置比對、strip_heredoc.py 的來由）。 +# ② URL 指名了**某一個**里程碑：`/repos///milestones/<數字>` +# ——沒有數字的（建里程碑、列清單）不是本閘管的形狀。 +# ③ 有寫入動詞（PATCH／POST／.patch(／.post(）**而且**內容把 state 設成 closed。 +# +# ⇒ 純 GET、建里程碑、改標題改期限、`cat` 這支腳本、把指令寫進文件（heredoc 內文 +# 先被 strip_heredoc.py 剝掉）、走正門 `scripts/milestone-account close` +# ——全部放行，一條都不擋。 +# +# ── 抽不出 owner/repo/編號就不擋 ──────────────────────────────────── +# fail-open on 解析失敗（不是 fail-open on 檢查結果）。理由同 release-tag-guard.sh： +# 誤攔比漏擋更該修——**誤攔會懲罰謹慎**，而被誤攔幾次之後人就學會繞過這支閘。 +# +# ── 已知的漏擋（寫出來，不假裝沒有）──────────────────────────────── +# `bash -c 'curl -X PATCH …'` 這種把真正的指令包進引號裡的寫法，本閘看不到。 +# 這是刻意的取捨：要接住它就得去猜引號裡的內容，而那條路的盡頭是關鍵字黑名單 +# （leo 2026-08-17 已證偽：當日 8 次誤攔、0 次正確攔截）。 +# +# 迴歸測試：hooks/tests/milestone-account-guard.test.sh（離線，不打 Gitea） +set -uo pipefail + +HOOKDIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +INPUT=$(cat 2>/dev/null || echo '{}') +CMD=$(printf '%s' "$INPUT" | python3 -c ' +import json, sys +try: print(json.load(sys.stdin).get("tool_input", {}).get("command", "") or "") +except Exception: print("") +' 2>/dev/null || printf '') +[ -n "$CMD" ] || exit 0 + +# 明講的豁免（留痕） +case "$CMD" in *milestone-account-ok*) exit 0 ;; esac + +# heredoc 的內文是資料不是指令——先剝掉，理由見 hooks/lib/strip_heredoc.py 檔頭 +if [ -f "$HOOKDIR/lib/strip_heredoc.py" ]; then + CMD=$(printf '%s' "$CMD" | python3 "$HOOKDIR/lib/strip_heredoc.py" 2>/dev/null || printf '%s' "$CMD") +fi + +# ① 指令位置真的有人在發請求 +printf '%s' "$CMD" | grep -qE '(^|[;&|(`]|&&|\|\|)[[:space:]]*(sudo[[:space:]]+)?(curl|wget|http|python3?|node|gh)[[:space:]]' || exit 0 + +# ② 指名某一個里程碑 +REF=$(printf '%s' "$CMD" | grep -oE '/repos/[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+/milestones/[0-9]+' | head -1 || printf '') +[ -n "$REF" ] || exit 0 + +# ③ 寫入動詞 ＋ 把 state 設成 closed +printf '%s' "$CMD" | grep -qiE -- '-X[[:space:]]*[^A-Za-z]{0,3}(PATCH|POST)|--request[[:space:]]*[^A-Za-z]{0,3}(PATCH|POST)|\.(patch|post)\(|method[[:space:]]*=[[:space:]]*[^A-Za-z]{0,3}(PATCH|POST)' || exit 0 +printf '%s' "$CMD" | grep -qiE 'state[^A-Za-z0-9]{1,8}closed' || exit 0 + +OWNER=$(printf '%s' "$REF" | cut -d/ -f3) +REPO=$(printf '%s' "$REF" | cut -d/ -f4) +NUM=$(printf '%s' "$REF" | cut -d/ -f6) +TARGET="$OWNER/$REPO#$NUM" + +# 已經記過帳的就放行——正門 `milestone-account close` 是**先記帳、再關**， +# 所以「帳本裡有這一筆」就代表三個數字已經留下來了。 +LEDGER="${MILESTONE_ACCOUNT_LEDGER:-}" +if [ -z "$LEDGER" ] && [ -x "$HOOKDIR/../scripts/milestone-account" ]; then + LEDGER=$(python3 "$HOOKDIR/../scripts/milestone-account" ledger-path 2>/dev/null || printf '') +fi +if [ -n "$LEDGER" ] && [ -f "$LEDGER" ] && grep -qF "\"ref\": \"$TARGET\"" "$LEDGER" 2>/dev/null; then + exit 0 +fi + +cat >&2 <] + + 三個數字**它自己算**（取自 Gitea 的 created_at／due_on／closed_at），不用你手填。 + 差超過 ±25%（超時或提早都算）才需要 --reason，而且代號只能從那七個裡面挑： + scripts/milestone-account codes + 代號要有**時間軸撐得住**——證據取自 Gitea，不採信任何人的自述。 + +━━ 為什麼不是「你自己 curl 一下就好」 ━━━━━━━━━━━━━━━━━━━━ + 這一關掉，那個里程碑就再也算不出帳了（closed_at 之後沒有人會回頭補）。 + ⇒ 這是**不可逆**的一步，所以閘長在這裡，不長在誰的記性上。 + + 真的有理由要手動關 ⇒ 指令裡加 `milestone-account-ok`（留痕，commit 說明理由）。 +MSG +exit 2 diff --git a/hooks/tests/milestone-account-guard.test.sh b/hooks/tests/milestone-account-guard.test.sh new file mode 100755 index 0000000..21e7c9d --- /dev/null +++ b/hooks/tests/milestone-account-guard.test.sh @@ -0,0 +1,85 @@ +#!/usr/bin/env bash +# milestone-account-guard.sh 的迴歸測試（inkstone/ISEP#85） +# +# A 群「不該擋」——純讀取／建里程碑／改別的欄位／只是談論它／heredoc 內文／ +# 走正門 `milestone-account close`／已經記過帳／解析不出來 +# B 群「該擋」 ——真的用 curl／python 把某一個里程碑 PATCH 成 closed，而帳本裡沒有它 +# C 群「訊息承諾的出路真的走得通」——記過帳之後立刻不再擋；加了豁免字樣就放行 +# +# 🔴 全程離線：帳本走 MILESTONE_ACCOUNT_LEDGER 指到 mktemp 的檔，不打 Gitea。 +# **誤攔比漏擋更該修**——A 群任何一條紅，就是這支閘在懲罰謹慎。 +set -u +HOOK="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/milestone-account-guard.sh}" +TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT +LED="$TMP/ledger.jsonl"; : > "$LED" +PASS=0; FAIL=0; N=0 + +fire() { + want="$1"; desc="$2"; cmd="$3" + N=$((N+1)) + payload=$(python3 -c 'import json,sys; print(json.dumps({"tool_input":{"command":sys.argv[1]}}))' "$cmd") + out=$(printf '%s' "$payload" | MILESTONE_ACCOUNT_LEDGER="$LED" bash "$HOOK" 2>&1 >/dev/null); rc=$? + if [ "$rc" -eq "$want" ]; then printf ' ✅ %s\n' "$desc"; PASS=$((PASS+1)) + else + printf ' ❌ %s —— 期望 exit=%s，實得 exit=%s\n' "$desc" "$want" "$rc" + printf '%s\n' "$out" | sed -n '1,6p' | sed 's/^/ /'; FAIL=$((FAIL+1)) + fi +} + +CLOSE='curl -s -X PATCH -H "Authorization: token X" -d {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/12' + +echo "── A 群：不該擋（誤攔比漏擋更該修）─────────────────────────" +fire 0 "① 空指令" "" +fire 0 "② 純 GET 撈里程碑" \ + 'curl -s https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/12' +fire 0 "③ 列出所有里程碑" \ + 'curl -s "https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones?state=open"' +fire 0 "④ 建一個新里程碑（那是 milestone-due-guard 管的，不是這支）" \ + 'curl -X POST -d {"title":"x","due_on":"2026-09-05T23:59:59Z"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones' +fire 0 "⑤ PATCH 但只是改期限，沒有要關它" \ + 'curl -X PATCH -d {"due_on":"2026-09-05T23:59:59Z"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/12' +fire 0 "⑥ 只是談論它（echo 在指令位置，curl 在字串裡）" \ + "echo '$CLOSE'" +fire 0 "⑦ 讀這支閘自己的原始碼" 'cat hooks/milestone-account-guard.sh' +fire 0 "⑧ commit 訊息裡出現「關掉 milestone」" \ + 'git commit -m "關掉 milestone 12，state closed"' +fire 0 "⑨ 走正門：scripts/milestone-account close" \ + 'python3 scripts/milestone-account close inkstone/ISEP#12 --reason idle' +fire 0 "⑩ 正門的 --dry-run" \ + 'python3 scripts/milestone-account close inkstone/ISEP#12 --reason idle --dry-run' +fire 0 "⑪ 把那段指令寫進文件（heredoc 內文是資料不是指令）" \ + "$(printf 'cat > docs/x.md <<%s\n%s\nEOD\n' "'EOD'" "$CLOSE")" +fire 0 "⑫ 網址沒有里程碑編號（抽不出目標 ⇒ 不擋）" \ + 'curl -X PATCH -d {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones' +fire 0 "⑬ 關的是一張票不是里程碑" \ + 'curl -X PATCH -d {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/issues/12' + +echo "── B 群：該擋 ──────────────────────────────────────────────" +fire 2 "⑭ curl PATCH state=closed，帳本裡沒有它" "$CLOSE" +fire 2 "⑮ 換成 python urllib（method=\"PATCH\"）一樣擋" \ + 'python3 -c "import urllib.request,json; urllib.request.urlopen(urllib.request.Request(\"https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/12\", data=json.dumps({\"state\":\"closed\"}).encode(), method=\"PATCH\"))"' +fire 2 "⑯ 前面串一個無害指令也擋（不是靠前綴判斷）" "ls && $CLOSE" +fire 2 "⑰ --request PATCH 的長寫法" \ + 'curl --request PATCH --data {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/12' +fire 2 "⑱ 別的 repo 的里程碑一樣管" \ + 'curl -X PATCH -d {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/arcrun-rag/milestones/47' + +echo "── C 群：訊息承諾的出路真的走得通 ──────────────────────────" +N=$((N+1)) +out=$(python3 -c 'import json,sys; print(json.dumps({"tool_input":{"command":sys.argv[1]}}))' "$CLOSE" \ + | MILESTONE_ACCOUNT_LEDGER="$LED" bash "$HOOK" 2>&1 >/dev/null) +if printf '%s' "$out" | grep -q "scripts/milestone-account audit inkstone/ISEP#12"; then + printf ' ✅ ⑲ 訊息直接給出可以照打的那一行（含正確的 owner/repo#編號）\n'; PASS=$((PASS+1)) +else + printf ' ❌ ⑲ 訊息沒有點名目標\n'; FAIL=$((FAIL+1)) +fi + +echo '{"ref": "inkstone/ISEP#12", "reason": "idle"}' >> "$LED" +fire 0 "⑳ 記過帳之後立刻放行（正門是先記帳再關）" "$CLOSE" +fire 2 "㉑ 但別的里程碑還是照擋（不是一記帳就全開）" \ + 'curl -X PATCH -d {"state":"closed"} https://git.uncle6.me/api/v1/repos/inkstone/ISEP/milestones/13' +fire 0 "㉒ 明講的豁免字樣（留痕）" "$CLOSE # milestone-account-ok" + +echo +echo "通過 $PASS 條，失敗 $FAIL 條（共 $N 條）" +[ "$FAIL" -eq 0 ] diff --git a/scripts/milestone-account b/scripts/milestone-account new file mode 100755 index 0000000..27cdc4c --- /dev/null +++ b/scripts/milestone-account @@ -0,0 +1,634 @@ +#!/usr/bin/env python3 +"""milestone-account — 每次結案都留下「估多久／花多久／差多少／為什麼」（inkstone/ISEP#85）。 + +leo 的問題（票上原文）：「leo 2026-08-27 說今天『**拖時間**』。但拖了多久、 +比預計多拖多少、為什麼拖——**沒有任何數字**⋯⋯每次事後只能用『這次比較慢』 +這種話帶過，下次還是一樣。」 + + milestone-account codes 七個代號是哪七個（封閉集合） + milestone-account list --org inkstone [--overdue] 現在每個里程碑的三個數字 + milestone-account audit inkstone/ISEP#12 從 Gitea 時間軸算證據 + milestone-account close inkstone/ISEP#12 --reason idle [--dry-run] + milestone-account report 累計：哪一種原因最常發生 + milestone-account ledger-path 帳本檔在哪（給閘問的） + +🔴 這支工具的三條，全部長在機器上（不是寫在規範裡靠人記得）： + + ① **三個數字自己算，不用手填**：期限與實際都取自 Gitea 的 `created_at`／ + `due_on`／`closed_at`。手填的數字沒有人會去對，等於沒有。 + ② **差超過 25%（超時或提早都算）就一定要挑一個代號**，挑不出來不准結案。 + 提早太多不是好消息，是**當初估太鬆**——所以兩個方向同一條線。 + ③ **代號要有時間軸撐得住**：`audit` 先從 Gitea 的時間軸算出哪幾個訊號成立， + `close` 只接受**訊號成立的那幾個代號**；一個都沒成立時，唯一合法的代號 + 就是 `misestimate`（＝票上那句「以上都沒有，但還是差很多」）。 + ⇒ **不採信我自己說的**，這是票上寫死的。 + +🔴 代號是**封閉集合**，這一點是刻意的——票上原文：「**能統計的前提是分類有限**」。 + 真的歸不進去才提案加一個，而那要走 leo 核准（開票，不是自己加）。 + +離線測試：`scripts/test-milestone-account.sh`（走 `MILESTONE_ACCOUNT_FIXTURE`，不打網路）。 +""" +import json +import os +import re +import subprocess +import sys +import time +import urllib.error +import urllib.parse +import urllib.request + +HOST = os.environ.get("MILESTONE_ACCOUNT_HOST", "https://git.uncle6.me") +HERE = os.path.dirname(os.path.abspath(__file__)) +ROOT = os.path.dirname(HERE) +def _resolve_dir(): + """帳本住哪裡。 + + 🔴 **不能住在 plugin 目錄裡**：ISEP 是用 marketplace 裝的， + `claude plugin update` 會把那個目錄整個換掉 ⇒ 累積幾個月的帳一次歸零， + 而這張票的全部價值就在「累積」。 + 順序：環境變數 → 這個 session 的專案根底下的 `system-dev/`（總管的跨專案知識庫， + 帳本本來就屬於那一層）→ 這份原始碼所在 repo 的 `system-dev/` → `~/.claude/`。 + """ + v = os.environ.get("MILESTONE_ACCOUNT_DIR") + if v: + return v + for base in (os.environ.get("CLAUDE_PROJECT_DIR") or "", ROOT): + if base and os.path.isdir(os.path.join(base, "system-dev")): + return os.path.join(base, "system-dev", "estimates") + return os.path.join(os.path.expanduser("~"), ".claude", "isep-estimates") + + +DIR = _resolve_dir() +LEDGER = os.path.join(DIR, "ledger.jsonl") +FIXTURE = os.environ.get("MILESTONE_ACCOUNT_FIXTURE", "") +DRY = False +THRESHOLD = 25.0 # 差超過幾 % 就一定要挑代號（票上寫死「四分之一」） + +# ── 封閉集合：七個代號，一個都不准多、不准少 ────────────────────────────── +CODES = [ + ("idle", "磨洋工", "小事拖成大事", "時間軸上有長長的空白"), + ("sidetrack", "分心跳線", "講到別的就跑去做", "期間出現不屬於這條線的動作"), + ("undispatched", "忘了派工", "該派沒派，票停著", "票很久沒有人被指派"), + ("cherry-pick", "偏科", "挑喜歡的做，難的擱著", "完成順序跟優先順序倒過來"), + ("waiting", "等答案", "問了就原地等，沒去做別的", "等待期間其他票零進度"), + ("scope-creep", "範圍變大", "一直塞新東西進來", "補收的次數、票數成長曲線"), + ("misestimate", "純粹估錯", "過程沒異常，就是估錯", "以上都沒有，但還是差很多"), +] +CODE_IDS = [c[0] for c in CODES] +LABEL = {c[0]: c[1] for c in CODES} + + +def die(msg, code=2): + print(msg, file=sys.stderr) + sys.exit(code) + + +def token(): + root = os.environ.get("CLAUDE_PROJECT_DIR") or HERE + host = HOST.split("//")[-1].rstrip("/") + try: + out = subprocess.run(["git", "-C", root, "remote", "-v"], + capture_output=True, text=True, timeout=20).stdout + except Exception: + out = "" + for line in out.splitlines(): + if host in line: + m = re.search(r"//[^:/]+:([^@]+)@", line) + if m: + return m.group(1) + for env in ("GITEA_TOKEN_CLAUDE_CODE", "GITEA_TOKEN"): + if os.environ.get(env): + return os.environ[env] + return "" + + +_FX = None + + +def fx(): + global _FX + if _FX is None: + try: + with open(FIXTURE) as f: + _FX = json.load(f) + except Exception: + die("🔴 讀不到 MILESTONE_ACCOUNT_FIXTURE：%s" % FIXTURE) + return _FX + + +def api(path, payload=None, method=None): + verb = method or ("POST" if payload is not None else "GET") + if FIXTURE: + if verb == "GET": + return (fx().get("api") or {}).get(path) + print(" [fixture] %s %s %s" % (verb, path, json.dumps(payload or {}))) + return {} + if DRY and verb != "GET": + print(" [dry-run] %s %s %s" % (verb, path, json.dumps(payload or {}))) + return {} + tk = token() + if not tk: + die("🔴 拿不到 %s 的 token（remote 沒帶憑證，也沒有 GITEA_TOKEN_CLAUDE_CODE）" % HOST) + data = json.dumps(payload).encode() if payload is not None else None + req = urllib.request.Request( + HOST + "/api/v1" + path, data=data, method=verb, + headers={"Authorization": "token " + tk, "Content-Type": "application/json"}) + try: + raw = urllib.request.urlopen(req, timeout=30).read() + return json.loads(raw) if raw.strip() else {} + except urllib.error.HTTPError as e: + if e.code == 404: + return None + die("🔴 Gitea %d on %s %s：%s" % (e.code, verb, path, e.read().decode()[:200])) + except Exception as e: + die("🔴 連不上 %s：%s" % (HOST, e)) + + +# ── 時間 ───────────────────────────────────────────────────────────────── +_TS = re.compile(r"^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2}):(\d{2})" + r"(?:\.\d+)?(Z|[+-]\d{2}:?\d{2})?$") + + +def ts(s): + """Gitea 的時間字串 → epoch 秒。認得 Z 與 +08:00 兩種尾巴；認不得回 None。""" + if not s: + return None + m = _TS.match(str(s).strip()) + if not m: + return None + y, mo, d, h, mi, se, off = m.groups() + t = time.mktime((int(y), int(mo), int(d), int(h), int(mi), int(se), 0, 1, 0)) \ + - time.timezone + if off and off not in ("Z", "z"): + sign = 1 if off[0] == "+" else -1 + off = off[1:].replace(":", "") + t -= sign * (int(off[:2]) * 3600 + int(off[2:]) * 60) + return t + + +def now(): + v = os.environ.get("MILESTONE_ACCOUNT_NOW") + return ts(v) if v else time.time() + + +def days(sec): + return sec / 86400.0 + + +def parse_ref(s): + m = re.match(r"^([\w.-]+)/([\w.-]+)#(\d+)$", s.strip()) + if not m: + die("🔴 寫法是 owner/repo#里程碑編號，你給的是：%s" % s) + return m.group(1), m.group(2), int(m.group(3)) + + +# ── 三個數字 ───────────────────────────────────────────────────────────── +def numbers(ms): + """回 (planned_days, actual_days, deviation_pct)。算不出來的格子回 None。""" + c, due = ts(ms.get("created_at")), ts(ms.get("due_on")) + end = ts(ms.get("closed_at")) or now() + if c is None: + return None, None, None + actual = days(end - c) + if due is None or due <= c: + return None, actual, None + planned = days(due - c) + return planned, actual, (actual - planned) / planned * 100.0 + + +def fmt(v, unit=""): + return "—" if v is None else ("%.1f%s" % (v, unit)) + + +def three_lines(ms, planned, actual, dev): + return (" 當初訂的期限　%s天　（%s → %s）\n" + " 實際花掉的　　%s天　（到 %s）\n" + " 差了　　　　　%s" + % (fmt(planned), (ms.get("created_at") or "?")[:10], + (ms.get("due_on") or "沒填期限")[:10], + fmt(actual), (ms.get("closed_at") or "現在")[:10], + "算不出來（期限沒填，或期限不晚於建立日）" if dev is None + else "%+.0f%%%s" % (dev, "　🔴 超過 ±25%，要挑代號" + if abs(dev) > THRESHOLD else ""))) + + +# ── 從 Gitea 時間軸取證據 ──────────────────────────────────────────────── +def fetch_issues(owner, repo): + rows, page = [], 1 + while page <= 5: + r = api("/repos/%s/%s/issues?state=all&type=issues&limit=50&page=%d" + % (owner, repo, page)) + if not isinstance(r, list) or not r: + break + rows.extend(r) + if len(r) < 50: + break + page += 1 + return rows + + +def fetch_comments(owner, repo, since): + q = "?limit=100" + if since: + q += "&since=" + urllib.parse.quote(since) + r = api("/repos/%s/%s/issues/comments%s" % (owner, repo, q)) + return r if isinstance(r, list) else [] + + +def prio(issue): + """優先度：p/high=3、p/med=2、p/low=1、沒標=0。""" + v = 0 + for l in issue.get("labels") or []: + n = (l.get("name") or "").lower() + if n in ("p/high", "p/urgent", "p0", "p1"): + v = max(v, 3) + elif n in ("p/med", "p/medium", "p2"): + v = max(v, 2) + elif n in ("p/low", "p3"): + v = max(v, 1) + return v + + +def evidence(owner, repo, ms): + """把 Gitea 時間軸算成七個訊號。回 (signals, detail)。 + + 🔴 這裡**一句話都不讀**：全部只看時間戳、指派欄位、標籤、票的歸屬。 + 票上寫死「不採信我自己說的」，所以判準不能碰任何自然語言。 + """ + start = ts(ms.get("created_at")) + end = ts(ms.get("closed_at")) or now() + span = max(end - start, 1.0) + mid = ms.get("id") + + issues = fetch_issues(owner, repo) + if issues is None: + issues = [] + mine = [i for i in issues if (i.get("milestone") or {}).get("id") == mid] + others = [i for i in issues if (i.get("milestone") or {}).get("id") != mid] + comments = fetch_comments(owner, repo, ms.get("created_at")) + + mine_ids = set(i.get("number") for i in mine) + + def cnum(c): + u = c.get("issue_url") or c.get("html_url") or "" + m = re.search(r"/(?:issues|pulls)/(\d+)", u) + return int(m.group(1)) if m else c.get("issue_number") + + ev_mine, ev_other = [], [] + for i in mine: + for k in ("created_at", "closed_at"): + t = ts(i.get(k)) + if t and start <= t <= end: + ev_mine.append(t) + for c in comments: + t = ts(c.get("created_at")) + if not t or not (start <= t <= end): + continue + (ev_mine if cnum(c) in mine_ids else ev_other).append(t) + for i in others: + t = ts(i.get("created_at")) + if t and start <= t <= end: + ev_other.append(t) + + marks = sorted([start] + ev_mine + [end]) + gap, gap_at = 0.0, None + for a, b in zip(marks, marks[1:]): + if b - a > gap: + gap, gap_at = b - a, a + sig, det = {}, {} + + # ① 磨洋工：時間軸上有長長的空白 + sig["idle"] = days(gap) >= 2.0 and gap / span >= 0.35 + det["idle"] = ("最長空白 %.1f 天（佔整段 %.0f%%），起點 %s" + % (days(gap), gap / span * 100, + time.strftime("%Y-%m-%d", time.gmtime(gap_at)) if gap_at else "?")) + + # ② 分心跳線：期間出現不屬於這條線的動作 + tot = len(ev_mine) + len(ev_other) + ratio = (len(ev_other) / tot) if tot else 0.0 + sig["sidetrack"] = len(ev_other) >= 5 and ratio >= 0.30 + det["sidetrack"] = ("這段期間 %d 個動作在這條線上、%d 個在別的票上（%.0f%%）" + % (len(ev_mine), len(ev_other), ratio * 100)) + + # ③ 忘了派工：票很久沒有人被指派 + naked = [i for i in mine if not (i.get("assignees") or i.get("assignee")) + and days(end - (ts(i.get("created_at")) or end)) >= days(span) * 0.5] + sig["undispatched"] = len(naked) > 0 + det["undispatched"] = ("%d 張票整段期間沒有人被指派：%s" + % (len(naked), ", ".join("#%s" % i.get("number") + for i in naked[:6])) if naked + else "每一張票都有人被指派過") + + # ④ 偏科：完成順序跟優先順序倒過來 + inv = 0 + closed = [i for i in mine if ts(i.get("closed_at"))] + openv = [i for i in mine if not ts(i.get("closed_at"))] + for a in closed: + for b in closed: + if prio(a) < prio(b) and ts(a["closed_at"]) < ts(b["closed_at"]): + inv += 1 + for a in closed: + for b in openv: + if prio(a) < prio(b): + inv += 1 + sig["cherry-pick"] = inv >= 2 + det["cherry-pick"] = ("低優先先收掉、高優先還晾著的配對 %d 組" % inv) + + # ⑤ 等答案：等待期間其他票零進度 + waitset = [i for i in mine + if any((l.get("name") or "").lower() == "human" + for l in (i.get("labels") or []))] + wait_days = 0.0 + for i in waitset: + s = ts(i.get("created_at")) or start + e = ts(i.get("closed_at")) or end + wait_days = max(wait_days, days(e - s)) + moved = sum(1 for i in mine + if ts(i.get("closed_at")) and i not in waitset) + sig["waiting"] = bool(waitset) and wait_days >= days(span) * 0.30 and moved == 0 + det["waiting"] = ("掛 Human 的票 %d 張、最長等 %.1f 天；期間其他票關掉 %d 張" + % (len(waitset), wait_days, moved)) + + # ⑥ 範圍變大：補收的次數、票數成長曲線 + late = [i for i in mine + if (ts(i.get("created_at")) or start) > start + span * 0.25] + sig["scope-creep"] = len(late) >= 1 and len(mine) and len(late) / len(mine) >= 0.20 + det["scope-creep"] = ("開跑之後才補進來的票 %d／%d 張：%s" + % (len(late), len(mine), + ", ".join("#%s" % i.get("number") for i in late[:6]))) + + # ⑦ 純粹估錯：以上都沒有 + sig["misestimate"] = not any(sig[c] for c in CODE_IDS if c != "misestimate") + det["misestimate"] = ("上面六個訊號%s成立" + % ("一個都沒有" if sig["misestimate"] else "有")) + return sig, det + + +def get_milestone(owner, repo, num): + ms = api("/repos/%s/%s/milestones/%d" % (owner, repo, num)) + if not isinstance(ms, dict) or not ms.get("id"): + die("🔴 抓不到里程碑 %s/%s#%d（編號對嗎？）" % (owner, repo, num)) + return ms + + +# ── 指令 ───────────────────────────────────────────────────────────────── +def cmd_codes(argv): + print("七個代號（封閉集合，inkstone/ISEP#85）——「能統計的前提是分類有限」\n") + for cid, label, plain, how in CODES: + print(" %-13s %-8s %-22s 從哪看出來：%s" % (cid, label, plain, how)) + print("\n真的歸不進去 ⇒ 開一張票請 leo 核准加一個，**不要自己加**。") + + +def _repos(argv): + rs = [r for r in (argv[i + 1] for i, a in enumerate(argv) + if a == "--repo" and i + 1 < len(argv))] + if rs: + return rs + org = None + for i, a in enumerate(argv): + if a == "--org" and i + 1 < len(argv): + org = argv[i + 1] + if not org: + die("用法：milestone-account list --org inkstone [--overdue] 或 --repo owner/repo") + rows = api("/orgs/%s/repos?limit=100" % org) + if not isinstance(rows, list): + die("🔴 撈不到 %s 底下的 repo" % org) + return [r["full_name"] for r in rows] + + +def cmd_list(argv): + overdue = "--overdue" in argv + n = 0 + for full in _repos(argv): + owner, repo = full.split("/", 1) + mss = api("/repos/%s/%s/milestones?state=open&limit=50" % (owner, repo)) + if not isinstance(mss, list): + continue + for ms in mss: + planned, actual, dev = numbers(ms) + late = dev is not None and dev > 0 + if overdue and not late: + continue + n += 1 + print("%s %-34s %-30s 估 %s天／已 %s天／%s" + % ("🔴" if (dev is not None and abs(dev) > THRESHOLD) else " ", + "%s#%s" % (full, ms.get("id")), (ms.get("title") or "")[:28], + fmt(planned), fmt(actual), + "—" if dev is None else "%+.0f%%" % dev)) + print("\n共 %d 個%s里程碑。🔴 ＝ 差超過 ±25%%，結案時一定要挑一個代號。" + % (n, "逾期的 " if overdue else "open ")) + print("挑代號之前先跑：milestone-account audit ") + + +def cmd_audit(argv): + if not argv: + die("用法：milestone-account audit ") + owner, repo, num = parse_ref(argv[0]) + ms = get_milestone(owner, repo, num) + planned, actual, dev = numbers(ms) + print("【%s/%s#%d】%s\n" % (owner, repo, num, ms.get("title") or "")) + print(three_lines(ms, planned, actual, dev)) + sig, det = evidence(owner, repo, ms) + print("\n【時間軸怎麼說】（全部取自 Gitea 的時間戳／欄位，一句話都沒讀）") + for cid, label, _plain, _how in CODES: + print(" %s %-13s %-8s %s" % ("🔴" if sig[cid] else " ", cid, label, det[cid])) + ok = [c for c in CODE_IDS if sig[c]] + print("\n可以挑的代號：%s" % " / ".join(ok)) + print("結案：milestone-account close %s/%s#%d --reason %s" % (owner, repo, num, ok[0])) + + +def _ledger(): + rows = [] + try: + with open(LEDGER) as f: + for line in f: + line = line.strip() + if line: + try: + rows.append(json.loads(line)) + except Exception: + pass + except Exception: + pass + return rows + + +def cmd_close(argv): + if not argv: + die("用法：milestone-account close [--reason 代號] [--dry-run]") + owner, repo, num = parse_ref(argv[0]) + ref = "%s/%s#%d" % (owner, repo, num) + reason = None + for i, a in enumerate(argv): + if a == "--reason" and i + 1 < len(argv): + reason = argv[i + 1] + + ms = get_milestone(owner, repo, num) + planned, actual, dev = numbers(ms) + print("【%s】%s\n" % (ref, ms.get("title") or "")) + print(three_lines(ms, planned, actual, dev)) + + sig, det = evidence(owner, repo, ms) + legal = [c for c in CODE_IDS if sig[c]] + need = dev is None or abs(dev) > THRESHOLD + + if need and not reason: + die("\n🚫 **差 %s，超過 ±25%%——挑不出代號不准結案。**\n\n" + "【inkstone/ISEP#85】「差超過四分之一（不管是超時還是提早太多，\n" + " **提早太多代表當初估太鬆**）就要挑一個原因，而且**只能從固定的幾個裡面挑**，\n" + " 不准用一段話帶過。」\n\n" + "時間軸撐得住的代號：%s\n" + "%s\n" + " 再送一次：milestone-account close %s --reason %s\n" + " 想看全部七個：milestone-account codes ／ 看證據：milestone-account audit %s" + % ("算不出來（期限沒填）" if dev is None else "%+.0f%%" % dev, + " / ".join(legal), + "\n".join(" %-13s %s" % (c, det[c]) for c in legal), ref, legal[0], ref)) + + if reason: + if reason not in CODE_IDS: + die("\n🚫 `%s` 不是那七個代號之一。\n" + " 【inkstone/ISEP#85】代號是**封閉集合**——「能統計的前提是分類有限」。\n" + " 七個：%s\n" + " 真的歸不進去 ⇒ 開票請 leo 核准加一個，不要自己造。" + % (reason, " / ".join(CODE_IDS))) + if reason not in legal: + die("\n🚫 `%s`（%s）**時間軸撐不住**——不接受。\n\n" + " 【inkstone/ISEP#85】「證據一律從 Gitea 的時間軸取" + "（留言、指派、標籤、commit 都有時間戳），**不採信我自己說的**。」\n\n" + " 這個代號的訊號：%s\n" + " 撐得住的是：%s\n" + " （訊號真的判錯了 ⇒ 那是 audit 的 bug，去修偵測器，" + "不是在這裡繞過去——這條線的意義就是「可以統計、可以迭代」。）" + % (reason, LABEL[reason], det[reason], " / ".join(legal))) + + rec = {"ref": ref, "title": ms.get("title") or "", + "created_at": ms.get("created_at"), "due_on": ms.get("due_on"), + "closed_at": ms.get("closed_at") or time.strftime( + "%Y-%m-%dT%H:%M:%SZ", time.gmtime(now())), + "planned_days": None if planned is None else round(planned, 2), + "actual_days": None if actual is None else round(actual, 2), + "deviation_pct": None if dev is None else round(dev, 1), + "over_threshold": bool(need), + "reason": reason, "reason_label": LABEL.get(reason or "", ""), + "signals": {c: bool(sig[c]) for c in CODE_IDS}, + "evidence": {c: det[c] for c in CODE_IDS}, + "recorded_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(now()))} + + if DRY: + print("\n[dry-run] 會寫進 %s：" % LEDGER) + print(json.dumps(rec, ensure_ascii=False, indent=2)[:900]) + print(" [dry-run] PATCH /repos/%s/%s/milestones/%d {\"state\": \"closed\"}" + % (owner, repo, num)) + print("[dry-run] 一筆都沒有真的寫出去。") + return + + # 🔴 順序：**先記帳、再關**。反過來的話，關成功而記帳失敗， + # 那個里程碑就永遠不會出現在統計裡——而那正是這張票要解的病。 + os.makedirs(DIR, exist_ok=True) + with open(LEDGER, "a") as f: + f.write(json.dumps(rec, ensure_ascii=False) + "\n") + print("\n✅ 已記帳：%s　估 %s天／花 %s天／%s%s" + % (ref, fmt(planned), fmt(actual), + "—" if dev is None else "%+.0f%%" % dev, + "　原因＝%s（%s）" % (reason, LABEL[reason]) if reason else "")) + + if (ms.get("state") or "") != "closed": + api("/repos/%s/%s/milestones/%d" % (owner, repo, num), + {"state": "closed"}, method="PATCH") + print("✅ 里程碑已關閉") + else: + print("ℹ️ 里程碑本來就是 closed，只補記帳") + write_report() + print("📊 累計統計已更新：%s" % os.path.join(DIR, "REPORT.md")) + + +def write_report(): + rows = _ledger() + cnt = {} + for r in rows: + if r.get("reason"): + cnt[r["reason"]] = cnt.get(r["reason"], 0) + 1 + devs = [r["deviation_pct"] for r in rows if r.get("deviation_pct") is not None] + lines = ["# 估多久／花多久／差多少——累計統計", "", + "> 這份檔案由 `scripts/milestone-account` 自動重寫，**不要手改**。", + "> 【inkstone/ISEP#85】「每次事後只能用『這次比較慢』這種話帶過，" + "下次還是一樣。」", "", + "- 累計結案 **%d** 個里程碑" % len(rows)] + if devs: + lines.append("\t- 平均偏差 **%+.0f%%**（正＝超時，負＝提早）" + % (sum(devs) / len(devs))) + lines.append("\t- 超過 ±25%% 的有 **%d** 個" + % sum(1 for d in devs if abs(d) > THRESHOLD)) + lines.append("- 哪一種原因最常發生（這才是迭代的依據）") + if not cnt: + lines.append("\t- 目前還沒有任何被挑過的代號。") + for cid, n in sorted(cnt.items(), key=lambda kv: -kv[1]): + lines.append("\t- **%s（%s）** ×%d" % (LABEL.get(cid, cid), cid, n)) + lines.append("- 逐筆") + for r in sorted(rows, key=lambda r: r.get("recorded_at") or "", reverse=True): + lines.append("\t- `%s` %s" % (r["ref"], r.get("title", ""))) + lines.append("\t\t- 估 %s 天／花 %s 天／差 %s" + % (r.get("planned_days"), r.get("actual_days"), + "—" if r.get("deviation_pct") is None + else "%+.0f%%" % r["deviation_pct"])) + if r.get("reason"): + lines.append("\t\t- 原因：**%s（%s）**" % (r.get("reason_label"), r["reason"])) + lines.append("\t\t- 時間軸證據：%s" + % (r.get("evidence") or {}).get(r["reason"], "—")) + try: + os.makedirs(DIR, exist_ok=True) + with open(os.path.join(DIR, "REPORT.md"), "w") as f: + f.write("\n".join(lines) + "\n") + except Exception as e: + die("🔴 寫不進 %s：%s" % (DIR, e)) + + +def cmd_report(argv): + rows = _ledger() + if not rows: + print("（帳本還是空的：%s）" % LEDGER) + print("關掉第一個里程碑就會有第一筆：milestone-account close ") + return + cnt = {} + for r in rows: + if r.get("reason"): + cnt[r["reason"]] = cnt.get(r["reason"], 0) + 1 + devs = [r["deviation_pct"] for r in rows if r.get("deviation_pct") is not None] + print("累計結案 %d 個里程碑" % len(rows)) + if devs: + print("平均偏差 %+.0f%%（正＝超時，負＝提早）；超過 ±25%% 的有 %d 個" + % (sum(devs) / len(devs), sum(1 for d in devs if abs(d) > THRESHOLD))) + print("\n哪一種原因最常發生：") + if not cnt: + print(" （還沒有任何被挑過的代號）") + for cid, n in sorted(cnt.items(), key=lambda kv: -kv[1]): + print(" %-13s %-8s ×%d %s" % (cid, LABEL.get(cid, cid), n, "█" * n)) + write_report() + print("\n人看的版本：%s" % os.path.join(DIR, "REPORT.md")) + + +def main(): + global DRY + argv = sys.argv[1:] + if "--dry-run" in argv: + DRY = True + argv = [a for a in argv if a != "--dry-run"] + if not argv: + print(__doc__) + return + cmd, rest = argv[0], argv[1:] + table = {"codes": cmd_codes, "list": cmd_list, "audit": cmd_audit, + "close": cmd_close, "report": cmd_report, + # 給 hooks/milestone-account-guard.sh 問「帳本在哪」用的。 + # 讓「怎麼找到帳本」只有一份答案，閘不必自己再實作一次解析。 + "ledger-path": lambda a: print(LEDGER)} + if cmd not in table: + print(__doc__) + die("🔴 沒有這個子指令：%s" % cmd) + table[cmd](rest) + + +if __name__ == "__main__": + main() diff --git a/scripts/release-manifest b/scripts/release-manifest new file mode 100755 index 0000000..7db1e67 --- /dev/null +++ b/scripts/release-manifest @@ -0,0 +1,410 @@ +#!/usr/bin/env python3 +"""release-manifest — 一次交貨 ＝ 一份清單（inkstone/ISEP#84）。 + +leo 的問題（票上原文）：「一次交貨常常同時動到好幾個 repo，但**沒有任何地方記著 +『這一版 ＝ 哪幾個 repo 的哪幾個版本』**⋯⋯要退版的時候，只退了其中一個 repo， +剩下的還停在新版 ⇒ **變成一組從來沒測過的組合**。」 + + release-manifest freeze R-2026.08.30 --part inkstone/Arcrun@v1.4.52 \ + --part inkstone/arcrun-collector@v0.18.36 + release-manifest current 我現在手上是哪一版、由什麼組成 + release-manifest list 全部清單，新的在上面 + release-manifest show R-2026.08.30 + release-manifest verify R-2026.08.30 清單上的版本號現在還抓得到嗎 + release-manifest diff R-2026.08.29 R-2026.08.30 + release-manifest rollback R-2026.08.29 退版：**整份一起退** + +🔴 三條硬規則，全部長在這支工具裡（不是寫在文件裡靠人記得）： + + ① **freeze 之前每一個版本號都真的去 Gitea 抓一次**。抓不到就不給凍結—— + 「寫上去」跟「存在」是兩件事，而清單的用處完全建立在後者。 + ② **凍結了就不准再加東西**。同名清單已存在 ⇒ 拒絕覆寫，新的需求進下一份。 + ③ **退版沒有「只退一個」這個選項**。`rollback` 一定吐出整份清單的每一格； + 指名單一 repo（`--only`）會被擋下，因為那正是票上那個病： + **剩下的還停在新版 ⇒ 一組從來沒測過的組合。** + +📌 跟 `release-tag-guard.sh` 是包含關係不是重複：那支管「打 tag 那一刻， + 單一 repo 內版本號三處一致」；這支管它上面那一層——**跨 repo 的組合**。 + +📌 單一 repo 的交貨不必特例：清單就退化成只有一格，規則一字不改。 + +離線測試：`scripts/test-release-manifest.sh`（走 `RELEASE_MANIFEST_FIXTURE`，不打網路）。 +""" +import json +import os +import re +import subprocess +import sys +import time +import urllib.error +import urllib.request + +HOST = os.environ.get("RELEASE_MANIFEST_HOST", "https://git.uncle6.me") +HERE = os.path.dirname(os.path.abspath(__file__)) +def _resolve_dir(): + """清單住哪裡。 + + 🔴 **不能住在 plugin 目錄裡**：ISEP 是用 marketplace 裝的， + `claude plugin update` 會把那個目錄整個換掉 ⇒ 所有出貨清單一次消失， + 而清單的用處全部發生在「以後要退版的那一天」。 + 順序：環境變數 → 這個 session 的專案根（有 `system-dev/` ＝總管的工作區， + 跨 repo 的出貨清單本來就屬於那一層）→ 這份原始碼所在 repo → `~/.claude/`。 + """ + v = os.environ.get("RELEASE_MANIFEST_DIR") + if v: + return v + root = os.path.dirname(HERE) + for base in (os.environ.get("CLAUDE_PROJECT_DIR") or "", root): + if base and os.path.isdir(os.path.join(base, "system-dev")): + return os.path.join(base, "releases") + return os.path.join(os.path.expanduser("~"), ".claude", "isep-releases") + + +DIR = _resolve_dir() +FIXTURE = os.environ.get("RELEASE_MANIFEST_FIXTURE", "") +DRY = False + +NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$") +PART_RE = re.compile(r"^([\w.-]+)/([\w.-]+)@(\S+)$") + + +def die(msg, code=2): + print(msg, file=sys.stderr) + sys.exit(code) + + +def token(): + root = os.environ.get("CLAUDE_PROJECT_DIR") or HERE + host = HOST.split("//")[-1].rstrip("/") + try: + out = subprocess.run(["git", "-C", root, "remote", "-v"], + capture_output=True, text=True, timeout=20).stdout + except Exception: + out = "" + for line in out.splitlines(): + if host in line: + m = re.search(r"//[^:/]+:([^@]+)@", line) + if m: + return m.group(1) + for env in ("GITEA_TOKEN_CLAUDE_CODE", "GITEA_TOKEN"): + if os.environ.get(env): + return os.environ[env] + return "" + + +def _fixture(): + try: + with open(FIXTURE) as f: + return json.load(f) + except Exception: + die("🔴 讀不到 RELEASE_MANIFEST_FIXTURE：%s" % FIXTURE) + + +def api(path): + """GET 一筆。回 dict／list，查不到回 None。fixture 模式完全不碰網路。""" + if FIXTURE: + return None + tk = token() + if not tk: + die("🔴 拿不到 %s 的 token（remote 沒帶憑證，也沒有 GITEA_TOKEN_CLAUDE_CODE）" % HOST) + try: + req = urllib.request.Request(HOST + "/api/v1" + path, + headers={"Authorization": "token " + tk}) + return json.load(urllib.request.urlopen(req, timeout=25)) + except urllib.error.HTTPError: + return None + except Exception as e: + die("🔴 連不上 %s：%s" % (HOST, e)) + + +def resolve(owner, repo, ver): + """這個版本號**真的存在嗎**。存在回一段可以貼給人看的證據，不存在回 None。 + + 先問 release，再問 tag：有些 repo 只打 tag 沒建 release，那也算存在 + （票上要的是「抓得到那個 release」＝抓得到那個版本，不是逼每個 repo 都建 release 頁）。 + """ + if FIXTURE: + fx = _fixture().get("versions") or {} + return fx.get("%s/%s@%s" % (owner, repo, ver)) + r = api("/repos/%s/%s/releases/tags/%s" % (owner, repo, ver)) + if isinstance(r, dict) and r.get("tag_name"): + return {"kind": "release", "url": r.get("html_url") or "", + "commit": (r.get("target_commitish") or "")[:12]} + t = api("/repos/%s/%s/tags/%s" % (owner, repo, ver)) + if isinstance(t, dict) and t.get("name"): + return {"kind": "tag", "url": (t.get("commit") or {}).get("url") or "", + "commit": ((t.get("commit") or {}).get("sha") or "")[:12]} + return None + + +# ── 清單的存取 ──────────────────────────────────────────────────────────── +def path_of(name): + return os.path.join(DIR, name + ".json") + + +def load(name): + try: + with open(path_of(name)) as f: + return json.load(f) + except Exception: + return None + + +def all_manifests(): + try: + names = [f[:-5] for f in os.listdir(DIR) if f.endswith(".json")] + except Exception: + return [] + rows = [load(n) for n in names] + rows = [m for m in rows if m] + # 🔴 排序鍵不能只用時間戳：同一分鐘凍兩份清單就會並列， + # 而並列之後「現在手上的是哪一份」會變成 os.listdir 的順序（等於隨機）。 + # seq 是 freeze 當下遞增的流水號 ⇒ 先後永遠有唯一解。 + rows.sort(key=lambda m: (m.get("seq", 0), m.get("frozen_at") or ""), reverse=True) + return rows + + +def parse_part(s): + m = PART_RE.match(s.strip()) + if not m: + die("🔴 寫法是 owner/repo@版本號，你給的是：%s" % s) + return m.group(1), m.group(2), m.group(3) + + +def opts(argv, name): + return [argv[i + 1] for i, a in enumerate(argv) if a == name and i + 1 < len(argv)] + + +def opt(argv, name, default=None): + v = opts(argv, name) + return v[0] if v else default + + +# ── INDEX.md：leo 打開就看得懂「我現在手上是哪一版」 ────────────────────── +def write_index(): + rows = all_manifests() + lines = ["# 出貨清單（哪一版由哪幾個 repo 的哪幾版組成）", "", + "> 這份檔案由 `scripts/release-manifest` 自動重寫，**不要手改**" + "（手改的那一份會安靜地騙人）。", "", + "- 每一列 ＝ 一次交貨。**最上面那一份就是現在手上的這一版。**"] + if not rows: + lines.append("\t- 目前還沒有任何凍結過的清單。") + for i, m in enumerate(rows): + head = "**%s**%s" % (m["name"], "　← 現在手上的這一版" if i == 0 else "") + lines.append("\t- " + head) + lines.append("\t\t- 凍結於 %s（UTC）" % m.get("frozen_at", "?")) + if m.get("note"): + lines.append("\t\t- 說明：%s" % m["note"]) + lines.append("\t\t- 由這些組成（沒有更動的 repo 不會出現在這裡）") + for p in m.get("parts", []): + ev = p.get("verified") or {} + lines.append("\t\t\t- `%s` @ **%s**　（凍結當下驗過：%s %s）" + % (p["repo"], p["version"], ev.get("kind", "?"), + ev.get("commit", ""))) + lines.append("\t\t- 要退回這一版：`scripts/release-manifest rollback %s`" % m["name"]) + lines.append("") + lines.append("- 為什麼要有這份東西（`inkstone/ISEP#84`）") + lines.append("\t- 退版只退了其中一個 repo，剩下的還停在新版" + " ⇒ **變成一組從來沒測過的組合**。") + lines.append("\t- 所以送測、放行、出貨、退版**全部以一份清單為單位**，" + "不以單一 repo 為單位。") + try: + os.makedirs(DIR, exist_ok=True) + with open(os.path.join(DIR, "INDEX.md"), "w") as f: + f.write("\n".join(lines) + "\n") + except Exception as e: + die("🔴 寫不進 %s：%s" % (DIR, e)) + + +# ── freeze ─────────────────────────────────────────────────────────────── +def cmd_freeze(argv): + if not argv: + die("用法：release-manifest freeze <清單名> --part owner/repo@版本 [--part …] " + "[--note 說明] [--dry-run]") + name = argv[0] + if not NAME_RE.match(name): + die("🔴 清單名只准英數與 . _ -（例：R-2026.08.30），你給的是：%s" % name) + raw = opts(argv[1:], "--part") + if not raw: + die("🚫 一份清單至少要有一格 --part owner/repo@版本號。\n" + " （單一 repo 的交貨也要開清單——它只是退化成一格，規則不變。）") + + if load(name) is not None: + die("🚫 %s 已經凍結過了，不准再加東西。\n" + " 【inkstone/ISEP#84】「清單一旦凍結就不再加東西，**新的需求進下一版**。」\n" + " 要出新的組合 ⇒ 換一個清單名重新 freeze（舊的留著，退版時要用）。" % name) + + seen, parts = set(), [] + for s in raw: + owner, repo, ver = parse_part(s) + full = "%s/%s" % (owner, repo) + if full in seen: + die("🔴 同一個 repo 在清單裡出現兩次：%s" % full) + seen.add(full) + ev = resolve(owner, repo, ver) + if not ev: + die("🚫 %s@%s **在 Gitea 上抓不到**——不給凍結。\n" + " 【inkstone/ISEP#84 驗收 1】「清單上的版本號**真的存在**" + "（不是寫上去而已，要抓得到那個 release）」。\n" + " 先把那個 repo 的版本打出來（tag／release），再回來 freeze。" + % (full, ver)) + parts.append({"repo": full, "version": ver, "verified": ev}) + + nxt = max([m.get("seq", 0) for m in all_manifests()] or [0]) + 1 + man = {"name": name, "seq": nxt, + "frozen_at": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()), + "note": opt(argv[1:], "--note", "") or "", + "parts": parts} + + if DRY: + print("[dry-run] 會寫進 %s" % path_of(name)) + print(json.dumps(man, ensure_ascii=False, indent=2)) + print("[dry-run] 一個檔都沒有真的寫出去。") + return + os.makedirs(DIR, exist_ok=True) + with open(path_of(name), "w") as f: + json.dump(man, f, ensure_ascii=False, indent=2) + write_index() + print("✅ 清單 %s 已凍結（%d 個 repo，每一格都驗過真的抓得到）" % (name, len(parts))) + for p in parts: + print(" %-34s %s" % (p["repo"], p["version"])) + print("\n📌 從現在起：送測／放行／出貨／退版都以 %s 為單位，不以單一 repo 為單位。" % name) + print(" 人看的版本：%s" % os.path.join(DIR, "INDEX.md")) + + +# ── verify / show / list / current / diff ──────────────────────────────── +def cmd_verify(argv): + if not argv: + die("用法：release-manifest verify <清單名>") + man = load(argv[0]) or die("🔴 沒有這份清單：%s" % argv[0]) + bad = 0 + for p in man["parts"]: + owner, repo = p["repo"].split("/", 1) + ev = resolve(owner, repo, p["version"]) + print("%s %-34s %s" % ("✅" if ev else "❌", p["repo"], p["version"])) + if not ev: + bad += 1 + if bad: + die("\n🔴 %d 格抓不到了——這份清單現在**退不回去**，" + "要嘛版本被刪了，要嘛當初就沒真的存在。" % bad) + print("\n✅ %s 全部 %d 格都還抓得到，可以拿它退版。" % (man["name"], len(man["parts"]))) + + +def cmd_show(argv): + if not argv: + die("用法：release-manifest show <清單名>") + man = load(argv[0]) or die("🔴 沒有這份清單：%s" % argv[0]) + print(json.dumps(man, ensure_ascii=False, indent=2)) + + +def cmd_list(argv): + rows = all_manifests() + if not rows: + print("（還沒有任何凍結過的清單。第一份用 release-manifest freeze 開。）") + return + for i, m in enumerate(rows): + print("%s %-18s %s %d 個 repo：%s" + % ("👉" if i == 0 else " ", m["name"], m.get("frozen_at", "?"), + len(m.get("parts", [])), + " + ".join("%s@%s" % (p["repo"].split("/")[-1], p["version"]) + for p in m.get("parts", [])))) + print("\n👉 ＝ 現在手上的這一版。人看的版本：%s" % os.path.join(DIR, "INDEX.md")) + + +def cmd_current(argv): + rows = all_manifests() + if not rows: + die("🔴 一份清單都沒有——「我現在手上是哪一版」目前沒有人答得出來。", 1) + m = rows[0] + print("現在手上的這一版：%s（凍結於 %s）" % (m["name"], m.get("frozen_at", "?"))) + for p in m["parts"]: + print(" %-34s %s" % (p["repo"], p["version"])) + + +def cmd_diff(argv): + if len(argv) < 2: + die("用法：release-manifest diff <舊清單> <新清單>") + a = load(argv[0]) or die("🔴 沒有這份清單：%s" % argv[0]) + b = load(argv[1]) or die("🔴 沒有這份清單：%s" % argv[1]) + va = {p["repo"]: p["version"] for p in a["parts"]} + vb = {p["repo"]: p["version"] for p in b["parts"]} + for repo in sorted(set(va) | set(vb)): + x, y = va.get(repo), vb.get(repo) + if x == y: + print(" = %-34s %s" % (repo, x)) + elif x is None: + print(" + %-34s %s（新進來的）" % (repo, y)) + elif y is None: + print(" - %-34s %s（新清單裡沒有了）" % (repo, x)) + else: + print(" ~ %-34s %s → %s" % (repo, x, y)) + + +# ── rollback：整份一起退，沒有「只退一個」這個選項 ──────────────────────── +def cmd_rollback(argv): + if not argv: + die("用法：release-manifest rollback <清單名> [--dry-run]") + name = argv[0] + man = load(name) or die("🔴 沒有這份清單：%s" % name) + + only = opts(argv[1:], "--only") + if only: + die("🚫 **退版沒有「只退一個」這個選項。**（你指名了：%s）\n\n" + " 【inkstone/ISEP#84】「要退版的時候，只退了其中一個 repo，\n" + " 剩下的還停在新版 ⇒ **變成一組從來沒測過的組合**。」\n\n" + " %s 這一版由 %d 個 repo 組成：\n%s\n" + " ⇒ 拿掉 --only，整份一起退：release-manifest rollback %s\n" + " ⇒ 真的只有一個 repo 要動 ⇒ 那就 freeze 一份**新的**清單，" + "把不動的那幾格照抄過去。" + % (", ".join(only), name, len(man["parts"]), + "\n".join(" %s @ %s" % (p["repo"], p["version"]) + for p in man["parts"]), name)) + + cur = all_manifests() + curv = {p["repo"]: p["version"] for p in cur[0]["parts"]} if cur else {} + curname = cur[0]["name"] if cur else "（沒有）" + + print("退版目標：%s（現在手上的是 %s）\n" % (name, curname)) + moves, stays = [], [] + for p in man["parts"]: + (stays if curv.get(p["repo"]) == p["version"] else moves).append(p) + + print("【要動的】") + if not moves: + print(" （沒有——現在手上的組合已經等於這份清單）") + for p in moves: + owner_repo = p["repo"] + print(" %-34s %s → %s" % (owner_repo, curv.get(owner_repo, "?"), p["version"])) + print(" git -C <%s 的工作目錄> fetch --tags && " + "git -C <同上> checkout %s" % (owner_repo.split("/")[-1], p["version"])) + if stays: + print("\n【已經在目標版本、不必動】（列出來是為了讓你確認**沒有一格被漏掉**）") + for p in stays: + print(" %-34s %s" % (p["repo"], p["version"])) + + print("\n🔴 這 %d 格是一組，要嘛全部到位，要嘛就不算退版完成。" + % len(man["parts"])) + print(" 退完跑一次複驗：release-manifest verify %s" % name) + + +def main(): + global DRY + argv = sys.argv[1:] + if "--dry-run" in argv: + DRY = True + argv = [a for a in argv if a != "--dry-run"] + if not argv: + print(__doc__) + return + cmd, rest = argv[0], argv[1:] + table = {"freeze": cmd_freeze, "verify": cmd_verify, "show": cmd_show, + "list": cmd_list, "current": cmd_current, "diff": cmd_diff, + "rollback": cmd_rollback} + if cmd not in table: + print(__doc__) + die("🔴 沒有這個子指令：%s" % cmd) + table[cmd](rest) + + +if __name__ == "__main__": + main() diff --git a/scripts/test-milestone-account.sh b/scripts/test-milestone-account.sh new file mode 100755 index 0000000..7418c25 --- /dev/null +++ b/scripts/test-milestone-account.sh @@ -0,0 +1,155 @@ +#!/usr/bin/env bash +# scripts/milestone-account 的迴歸測試（inkstone/ISEP#85） +# +# 驗收 1：關掉一個 milestone → 三個數字要自己算出來，不用手填 +# 驗收 2：差超過 25% → 要逼我挑一個代號，挑不出來不准結案 +# 驗收 3：累積幾次之後 → 看得出哪一種原因最常發生 +# 驗收 4：拿已經逾期的 milestone 進去算 → 要算得出數字 +# +# 🔴 全程離線（MILESTONE_ACCOUNT_FIXTURE ＝一份假的 Gitea 回應表）， +# 時鐘用 MILESTONE_ACCOUNT_NOW 定住，帳本寫在 mktemp 目錄。 +# **不打 Gitea、不關任何真的 milestone、不碰 repo 裡的 system-dev/estimates/。** +set -u +TOOL="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/milestone-account}" +TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT +PASS=0; FAIL=0; N=0 +NOW="2026-08-28T00:00:00Z" +FX="$TMP/fx.json" + +python3 - "$FX" <<'PY' +import json, sys, urllib.parse +api = {} + +def iso(d, h=0): + return "2026-08-%02dT%02d:00:00Z" % (d, h) + +def issue(n, created, closed=None, assignee=True, labels=(), ms=None): + return {"number": n, "created_at": created, "closed_at": closed, + "updated_at": closed or created, + "assignees": [{"login": "cc"}] if assignee else [], + "labels": [{"name": l} for l in labels], + "milestone": ({"id": ms} if ms else None)} + +def comment(n, at): + return {"issue_url": "https://x/api/v1/repos/o/r/issues/%d" % n, "created_at": at} + +def repo(full, mid, title, created, due, closed, issues, comments, open_ms=True): + o, r = full.split("/") + ms = {"id": mid, "title": title, "created_at": created, "due_on": due, + "closed_at": closed, "state": "open" if closed is None else "closed"} + api["/repos/%s/%s/milestones/%d" % (o, r, mid)] = ms + api["/repos/%s/%s/issues?state=all&type=issues&limit=50&page=1" % (o, r)] = issues + api["/repos/%s/%s/issues/comments?limit=100&since=%s" + % (o, r, urllib.parse.quote(created))] = comments + api["/repos/%s/%s/milestones?state=open&limit=50" % (o, r)] = [ms] if open_ms else [] + +# ① A#12 磨洋工：08-02 收掉一張之後，時間軸整整空了 24 天 +repo("inkstone/A", 12, "sprint-磨洋工", iso(1), "2026-08-08T23:59:59Z", None, + [issue(1, iso(1, 1), iso(2), ms=12), issue(2, iso(1, 2), ms=12), + issue(3, iso(1, 3), ms=12), issue(9, iso(10), ms=None)], + [comment(1, iso(26))]) + +# ② B#13 準時收掉：偏差只有 -6%，不必挑代號 +repo("inkstone/B", 13, "sprint-準時", iso(20), "2026-08-27T23:59:59Z", + "2026-08-27T12:00:00Z", + [issue(1, iso(20, 1), iso(25), ms=13), issue(2, iso(20, 2), iso(26), ms=13)], + [comment(1, iso(22)), comment(2, iso(24))], open_ms=False) + +# ③ C#14 過程沒異常、就是估錯：每兩天都有動作，其他六個訊號全不成立 +repo("inkstone/C", 14, "sprint-估錯", iso(1), "2026-08-10T23:59:59Z", + "2026-08-25T00:00:00Z", + [issue(1, iso(1, 1), iso(24), ms=14), issue(2, iso(1, 2), iso(23), ms=14)], + [comment(1, iso(d)) for d in range(3, 25, 2)], open_ms=False) + +# ④ D#15 範圍變大：開跑之後又補進來三張票 +repo("inkstone/D", 15, "sprint-範圍變大", iso(1), "2026-08-10T23:59:59Z", + "2026-08-25T00:00:00Z", + [issue(1, iso(1, 1), iso(24), ms=15), issue(2, iso(1, 2), iso(23), ms=15), + issue(3, iso(15), ms=15), issue(4, iso(15, 1), ms=15), + issue(5, iso(15, 2), ms=15)], + [comment(1, iso(d)) for d in range(3, 25, 2)], open_ms=False) + +api["/orgs/inkstone/repos?limit=100"] = [ + {"full_name": "inkstone/%s" % x} for x in "ABCD"] +json.dump({"api": api}, open(sys.argv[1], "w"), ensure_ascii=False) +PY + +run() { MILESTONE_ACCOUNT_FIXTURE="$FX" MILESTONE_ACCOUNT_DIR="$TMP/led" \ + MILESTONE_ACCOUNT_NOW="$NOW" python3 "$TOOL" "$@" 2>&1; } + +t() { + want="$1"; desc="$2"; must="$3"; shift 4 + N=$((N+1)); out=$(run "$@"); rc=$? + ok=1; [ "$rc" -eq "$want" ] || ok=0 + if [ -n "$must" ] && ! printf '%s' "$out" | grep -qF "$must"; then ok=0; fi + if [ "$ok" -eq 1 ]; then printf ' ✅ %s\n' "$desc"; PASS=$((PASS+1)) + else + printf ' ❌ %s —— 期望 exit=%s%s，實得 exit=%s\n' "$desc" "$want" \ + "${must:+ 且輸出含「$must」}" "$rc" + printf '%s\n' "$out" | sed -n '1,12p' | sed 's/^/ /'; FAIL=$((FAIL+1)) + fi +} + +echo "── 驗收 1：三個數字自己算出來 ─────────────────────────────" +t 0 "① audit 印出「當初訂的期限」" "當初訂的期限" -- audit inkstone/A#12 +t 0 "② audit 印出「實際花掉的」" "實際花掉的" -- audit inkstone/A#12 +t 0 "③ 偏差算得出來（A#12 逾期 +238%）" "+238%" -- audit inkstone/A#12 +t 0 "④ 期限是 08-08、實際算到今天 08-28 ⇒ 27 天" "27.0天" -- audit inkstone/A#12 + +echo "── 驗收 2：差超過 25% 逼你挑代號 ──────────────────────────" +t 2 "⑤ A#12 差 +237% 卻沒給 --reason ⇒ 不准結案" "挑不出代號不准結案" -- \ + close inkstone/A#12 +t 2 "⑥ 承上：訊息要直接列出撐得住的代號" "時間軸撐得住的代號：idle" -- close inkstone/A#12 +t 0 "⑦ B#13 只差 -6% ⇒ 不必挑代號，直接結得掉" "已記帳" -- close inkstone/B#13 +t 2 "⑧ 造一個不存在的代號 ⇒ 擋（封閉集合）" "不是那七個代號之一" -- \ + close inkstone/A#12 --reason 拖延症 +t 2 "⑨ 挑一個時間軸撐不住的代號 ⇒ 擋（不採信我自己說的）" "時間軸撐不住" -- \ + close inkstone/C#14 --reason idle +t 0 "⑩ C#14 六個訊號都不成立 ⇒ 唯一合法的是 misestimate" "misestimate" -- \ + audit inkstone/C#14 +t 0 "⑪ 承上：--reason misestimate 收得掉" "原因＝misestimate" -- \ + close inkstone/C#14 --reason misestimate +t 0 "⑫ A#12 挑 idle（時間軸真的有 24 天空白）⇒ 收得掉" "原因＝idle" -- \ + close inkstone/A#12 --reason idle +t 0 "⑬ D#15 開跑後補三張票 ⇒ scope-creep 撐得住" "原因＝scope-creep" -- \ + close inkstone/D#15 --reason scope-creep + +echo "── 驗收 3：看得出哪一種原因最常發生 ───────────────────────" +t 0 "⑭ report 數得出每個代號各幾次" "磨洋工" -- report +t 0 "⑮ report 算得出累計結案幾個" "累計結案 4 個里程碑" -- report +N=$((N+1)) +if grep -q "哪一種原因最常發生" "$TMP/led/REPORT.md" 2>/dev/null \ + && grep -q "時間軸證據" "$TMP/led/REPORT.md"; then + printf ' ✅ ⑯ REPORT.md 寫出來了，而且每一筆都帶時間軸證據\n'; PASS=$((PASS+1)) +else + printf ' ❌ ⑯ REPORT.md 內容不對\n'; FAIL=$((FAIL+1)) +fi +N=$((N+1)) +if [ "$(wc -l < "$TMP/led/ledger.jsonl")" = "4" ]; then + printf ' ✅ ⑰ 帳本剛好四筆（沒有被擋下的那幾次也記進去）\n'; PASS=$((PASS+1)) +else + printf ' ❌ ⑰ 帳本筆數不對：%s\n' "$(wc -l < "$TMP/led/ledger.jsonl" 2>/dev/null)" + FAIL=$((FAIL+1)) +fi + +echo "── 驗收 4：拿已經逾期的里程碑進去算 ───────────────────────" +t 0 "⑱ list --overdue 撈得到逾期的那一個，而且帶數字" "inkstone/A#12" -- \ + list --org inkstone --overdue +t 0 "⑲ 承上：逾期的要被標成「差超過 ±25%」那一類" "🔴" -- \ + list --org inkstone --overdue + +echo "── 其他 ───────────────────────────────────────────────────" +t 0 "⑳ codes 印得出七個代號，一個不多一個不少" "misestimate" -- codes +N=$((N+1)) +if [ "$(run codes | grep -cE '^ [a-z-]+ ')" = "7" ]; then + printf ' ✅ ㉑ 真的是七個（封閉集合）\n'; PASS=$((PASS+1)) +else + printf ' ❌ ㉑ 代號數量不是 7：%s\n' "$(run codes | grep -cE '^ [a-z-]+ ')"; FAIL=$((FAIL+1)) +fi +t 0 "㉒ --dry-run 印出要打的那通 API 但不送出" "一筆都沒有真的寫出去" -- \ + close inkstone/A#12 --reason idle --dry-run +t 2 "㉓ 里程碑編號寫錯 ⇒ 講清楚寫法" "寫法是 owner/repo#里程碑編號" -- audit ISEP-12 + +echo +echo "通過 $PASS 條，失敗 $FAIL 條（共 $N 條）" +[ "$FAIL" -eq 0 ] diff --git a/scripts/test-release-manifest.sh b/scripts/test-release-manifest.sh new file mode 100755 index 0000000..d88c87b --- /dev/null +++ b/scripts/test-release-manifest.sh @@ -0,0 +1,98 @@ +#!/usr/bin/env bash +# scripts/release-manifest 的迴歸測試（inkstone/ISEP#84） +# +# 兩個方向都要有證據： +# A 群「該擋」——版本號在 Gitea 抓不到／清單已凍結還想加東西／退版只退一個 +# B 群「該過」——版本號真的存在就凍結得起來、退版吐出整份、diff 看得出差在哪 +# C 群「leo 打開看得懂」——INDEX.md 真的被重寫，而且第一份標著「現在手上的這一版」 +# +# 🔴 全程離線（RELEASE_MANIFEST_FIXTURE），不打 Gitea、不建任何真的 release。 +# 清單寫在 mktemp 的目錄（RELEASE_MANIFEST_DIR），不碰 repo 裡的 releases/。 +set -u +TOOL="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/release-manifest}" +TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT +PASS=0; FAIL=0; N=0 + +FX="$TMP/fx.json" +cat > "$FX" <<'JSON' +{"versions": { + "inkstone/Arcrun@v1.4.52": {"kind":"release","url":"u1","commit":"aaaaaaaaaaaa"}, + "inkstone/Arcrun@v1.4.51": {"kind":"release","url":"u2","commit":"bbbbbbbbbbbb"}, + "inkstone/arcrun-collector@v0.18.36": {"kind":"tag","url":"u3","commit":"cccccccccccc"}, + "inkstone/arcrun-collector@v0.18.35": {"kind":"tag","url":"u4","commit":"dddddddddddd"} +}} +JSON + +run() { RELEASE_MANIFEST_FIXTURE="$FX" RELEASE_MANIFEST_DIR="$TMP/rel" python3 "$TOOL" "$@" 2>&1; } + +# t <期望 exit> <說明> <必須出現的字串（可空）> -- <參數…> +t() { + want="$1"; desc="$2"; must="$3"; shift 4 + N=$((N+1)) + out=$(run "$@"); rc=$? + ok=1 + [ "$rc" -eq "$want" ] || ok=0 + if [ -n "$must" ] && ! printf '%s' "$out" | grep -qF "$must"; then ok=0; fi + if [ "$ok" -eq 1 ]; then printf ' ✅ %s\n' "$desc"; PASS=$((PASS+1)) + else + printf ' ❌ %s —— 期望 exit=%s%s，實得 exit=%s\n' "$desc" "$want" \ + "${must:+ 且輸出含「$must」}" "$rc" + printf '%s\n' "$out" | sed -n '1,8p' | sed 's/^/ /'; FAIL=$((FAIL+1)) + fi +} + +echo "── B 群：該過 ──────────────────────────────────────────────" +t 0 "① 兩個 repo 的版本都真的存在 ⇒ 凍結得起來" "已凍結（2 個 repo" -- \ + freeze R-2026.08.29 --part inkstone/Arcrun@v1.4.51 --part inkstone/arcrun-collector@v0.18.35 +t 0 "② 單一 repo 的交貨不必特例（清單退化成一格）" "已凍結（1 個 repo" -- \ + freeze R-single --part inkstone/Arcrun@v1.4.51 +t 0 "③ 再凍一份新的（這才是「新的需求進下一版」）" "已凍結（2 個 repo" -- \ + freeze R-2026.08.30 --part inkstone/Arcrun@v1.4.52 --part inkstone/arcrun-collector@v0.18.36 +t 0 "④ current 答得出「我現在手上是哪一版」" "R-2026.08.30" -- current +t 0 "⑤ verify：每一格都還抓得到" "全部 2 格都還抓得到" -- verify R-2026.08.30 +t 0 "⑥ diff 看得出兩份差在哪一格" "v1.4.51 → v1.4.52" -- diff R-2026.08.29 R-2026.08.30 +t 0 "⑦ --dry-run 不寫檔" "一個檔都沒有真的寫出去" -- \ + freeze R-dryrun --part inkstone/Arcrun@v1.4.52 --dry-run +t 2 "⑧ 承上：--dry-run 那份真的沒被寫出去" "沒有這份清單" -- show R-dryrun + +echo "── A 群：該擋 ──────────────────────────────────────────────" +t 2 "⑨ 版本號在 Gitea 抓不到 ⇒ 不給凍結（驗收 1）" "在 Gitea 上抓不到" -- \ + freeze R-bad --part inkstone/Arcrun@v9.9.9 +t 2 "⑩ 承上：整份都不寫（不會留下半份清單）" "沒有這份清單" -- show R-bad +t 2 "⑪ 一格都不給 ⇒ 擋" "至少要有一格" -- freeze R-empty +t 2 "⑫ 同名清單已凍結 ⇒ 不准再加東西" "新的需求進下一版" -- \ + freeze R-2026.08.30 --part inkstone/Arcrun@v1.4.51 +t 2 "⑬ 同一個 repo 出現兩次 ⇒ 擋" "出現兩次" -- \ + freeze R-dup --part inkstone/Arcrun@v1.4.51 --part inkstone/Arcrun@v1.4.52 +t 2 "⑭ 清單名亂寫 ⇒ 擋" "清單名只准" -- freeze "R 2026/08" --part inkstone/Arcrun@v1.4.51 +t 2 "⑮ part 寫法不對 ⇒ 擋" "寫法是 owner/repo@版本號" -- \ + freeze R-x --part Arcrun-v1.4.52 + +echo "── 驗收 2／3：退版 ─────────────────────────────────────────" +t 0 "⑯ 退版吐出整份清單的每一格（驗收 2）" "這 2 格是一組" -- rollback R-2026.08.29 +t 0 "⑰ 承上：兩個 repo 都被列進「要動的」" "arcrun-collector" -- rollback R-2026.08.29 +t 2 "⑱ 試著只退其中一個 ⇒ 被擋下來（驗收 3）" "沒有「只退一個」這個選項" -- \ + rollback R-2026.08.29 --only inkstone/Arcrun +t 0 "⑲ 已經在目標版本的那幾格也要列出來（沒有一格被漏掉）" "不必動" -- \ + rollback R-2026.08.30 + +echo "── 驗收 4：leo 打開那份清單看得懂 ──────────────────────────" +N=$((N+1)) +IDX="$TMP/rel/INDEX.md" +if [ -f "$IDX" ] && grep -q "現在手上的這一版" "$IDX" \ + && grep -q "R-2026.08.30" "$IDX" && grep -q "從來沒測過的組合" "$IDX"; then + printf ' ✅ ⑳ INDEX.md 被重寫，標出「現在手上的這一版」與為什麼要有它\n'; PASS=$((PASS+1)) +else + printf ' ❌ ⑳ INDEX.md 內容不對\n'; sed -n '1,20p' "$IDX" 2>/dev/null | sed 's/^/ /' + FAIL=$((FAIL+1)) +fi +N=$((N+1)) +if head -20 "$IDX" 2>/dev/null | grep -A2 "R-2026.08.30" | grep -q "現在手上的這一版"; then + printf ' ✅ ㉑ 最新那一份（不是最舊那份）才被標成「現在手上的」\n'; PASS=$((PASS+1)) +else + printf ' ❌ ㉑ 標錯了哪一份是現在手上的\n'; FAIL=$((FAIL+1)) +fi + +echo +echo "通過 $PASS 條，失敗 $FAIL 條（共 $N 條）" +[ "$FAIL" -eq 0 ] -- 2.52.0