diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 1e694d1..70b255c 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "isep", - "description": "InkStone Environment Plugin —— leo 的 Claude Code 環境唯一真相源：54 支機械閘（71 條註冊，白話盤點見 docs/hooks-inventory.md）、7 支 slash command、2 支 skill、40 支腳本，外加治理規範與標籤真相源。本機與雲端裝同一份，沒有子集。", + "description": "InkStone Environment Plugin —— leo 的 Claude Code 環境唯一真相源：54 支機械閘（71 條註冊，白話盤點見 docs/hooks-inventory.md）、7 支 slash command、2 支 skill、43 支腳本，外加治理規範與標籤真相源。本機與雲端裝同一份，沒有子集。", "version": "0.13.0", "keywords": [ "inkstone", diff --git a/docs/TESTING.md b/docs/TESTING.md index eec4750..8a34708 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -268,7 +268,6 @@ bash hooks/tests/isep-presence-beacon.test.sh - ⑤⑦ 紅 ⇒ 舊複本遮蔽正門抓不到（`InkStoneCo/scripts/ticket` 那件） - ⑥ 紅 ⇒ **誤攔**：同步過的複本被念，人就學會忽略它 - ⑪ 紅 ⇒ 內層迴圈變數撞名的回歸（同一個 `.claude` 下第二個殘骸會被靜靜跳過） - ### A19 — 下游做完時頂層跟著關：49 條 ``` bash scripts/test-ticket-handoff-writeback.sh @@ -305,6 +304,49 @@ bash scripts/test-ticket-handoff-writeback.sh 在有人往那裡加第一條旅程之前，`--journey` 只會擋、不會貼。 機制驗過了，**資料還沒有**。 +### A20 — 舊票每天有固定管道被撈出來：47 條 +``` +bash scripts/test-debt-worklist.sh +``` +**該看到**：`通過 47 條，失敗 0 條`。**全程離線**：資料走 `ISEP_DEBT_FIXTURE`、 +時鐘走 `ISEP_DEBT_NOW`、狀態走 `ISEP_DEBT_STATE_DIR`、主線走 `ISEP_COUNTDOWN_STATE_DIR` +——**不打 Gitea、不留測試票、不碰 `$HOME`**。 + +**它在守什麼**（`inkstone/ISEP#83`，leo 2026-08-27）： +「現在每天都在追新的，所以**要用 Routine 去消化舊的**，可以有多個條件」。 +全 org 229 張 open 票，每天在動的只有掛在 open milestone 上的那 56 張； +其餘的不是不重要，是**沒有任何機制會去拿它們**。 + +🔴 **兩條線各用各的判準，不是二選一**（leo 當場訂正總管的誤解）： +掛 milestone ＝緊急線，用「距離目標的遠近」排；沒掛的＝還債線，用多條件排 +（事故／擋人／承諾／票齡／估工）——後者就是 `scripts/debt-worklist`。 + +**失敗**： +- 「驗收 1」那組紅 ⇒ 清單沒有附「我查了哪些 repo」的證明。 + **沒有證明的清單分不出「今天真的沒有」與「查詢壞了」**，而後者會靜靜地零產出 +- 「驗收 2」紅 ⇒ 空清單默默結束。這是這支工具最貴的失效方式： + 它看起來跑完了，於是沒有人再去看那 180 張 +- 「驗收 3」紅 ⇒ 領走的票明天又冒出來，這份清單就會變成每天一樣的一坨，人就不看了 +- 「成包」兩條紅 ⇒ 互相指著／母子票被拆開領，做到一半才發現卡在另一張 +- **「單向引用不成包」紅 ⇒ 這是誤攔的那一面**：第一版用單向引用成包， + 結果 190 張裡 121 張黏成一包（大家都會順手引用 hub 票）＝**一包沒有人領得動** +- 「接上主線」那組紅 ⇒ 還債線又自己養了一套「哪個是 active」的判斷。 + 唯一答案在 `hooks/lib/mainline.py`（`inkstone/ISEP#82`），**兩份必然漂移**。 + 特別看「沒標主線」那兩條：**沒有答案時要退回保守**（掛 open milestone 的一律不領）， + 不准猜一條出來 +- 最後一組（SessionStart）紅 ⇒ 要嘛沒有人會被提醒去撈， + 要嘛那一段偷偷去打網路——**開 session 自動撈就是輪詢**，紅線擋著 + +**手動驗真實資料**（會打 Gitea，唯讀 GET）： +``` +python3 scripts/debt-worklist list --top 5 +``` +**該看到**：15 個 repo 逐一列出 issue／PR 數，講得出**現在的主線是哪一條** +（或誠實說沒標），扣除數字講得出來（掛 open milestone 的幾張、等 leo 的幾張、已領走的幾張）， +前幾名旁邊看得到「為什麼排這裡」的分項。 +**失敗**：前幾名一眼看不出為什麼在那裡 ⇒ 那些權重就是錯的，去改 `score()`， +**不要改成「總管覺得」**——這份清單的價值就在於它不靠記憶。 + ### A5 — 開票前的搜尋是跨 repo 的 ``` python3 scripts/ticket where 標籤 模組化 @@ -512,6 +554,7 @@ B2（信標那行）／B3（setup 輸出）／B4（閘的訊息）三個畫面 | **A17 未推警察不誤攔雲端分支** | 總管 | ✅ 10/10（2026-08-28，inkstone/ISEP#90） | | **A18 信標會報雲端接線缺陷** | 總管 | ✅ 14/14（2026-08-28，inkstone/ISEP#90） | | **A19 下游做完頂層跟著關** | 總管 | ✅ 49/49（2026-08-28，inkstone/ISEP#92） | +| **A20 舊票有固定管道被撈** | 總管 | ✅ 47/47（2026-08-28，inkstone/ISEP#83）＋真實 229 張唯讀實跑 | | A7 plugin 裝得起來 | 總管 | ✅ | | **A8 新 session 閘會觸發** | 總管 | 見本版 release note | | **B1–B5 雲端** | **leo** | 還沒跑（機器碰不到 Cloud environment） | diff --git a/hooks/session-start-recall.sh b/hooks/session-start-recall.sh index 5c09865..55b3422 100755 --- a/hooks/session-start-recall.sh +++ b/hooks/session-start-recall.sh @@ -144,6 +144,33 @@ if [ -f "$MISTAKES_FILE" ] && grep -q 'MISTAKE' "$MISTAKES_FILE" 2>/dev/null; th echo "" fi +# ── push 6：還債線今天撈過了沒（inkstone/ISEP#83）────────────────────────── +# 🔴 **這裡不打網路、不撈票**——只看狀態檔的日期，講一句話。 +# 要真的撈是人（或這個 session）自己跑那一行；SessionStart 只負責讓它被想起來。 +# 「每天都在追新的，所以要用 Routine 去消化舊的」（leo 2026-08-27）—— +# 沒有這一句，沒掛 milestone 的那 170 多張永遠不會被任何人拿起來。 +DEBT_STATE="${ISEP_DEBT_STATE_DIR:-$HOME/.claude/isep-debt}/claimed.json" +DEBT_LINE=$(python3 - "$DEBT_STATE" <<'PY' 2>/dev/null || true +import json, sys, datetime +try: + d = json.load(open(sys.argv[1])) +except Exception: + d = {} +last = (d.get("last_run") or "")[:10] +today = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d") +n = len(d.get("claims") or {}) +if last == today: + print(f"✅ 今天撈過了（手上領著 {n} 張）") +else: + print("🔴 今天還沒撈過還債清單" + (f"（手上還領著 {n} 張沒關）" if n else "")) +PY +) +echo "────────────────────────────────────────────────" +echo "🧾 還債線（inkstone/ISEP#83）：${DEBT_LINE:-🔴 今天還沒撈過還債清單}" +echo " 撈一次 ＝ python3 ${CLAUDE_PLUGIN_ROOT:-.}/scripts/debt-worklist list" +echo " 它排的是「沒掛 milestone 的舊票」——掛著的歸緊急線（milestone）管，兩條線不互搶。" +echo "" + echo "────────────────────────────────────────────────" echo "以上是 index，不是內容——它只讓你知道「有這件事、去哪裡找」。" echo "要完整脈絡（decisions / mistakes / SDD）→ 執行 /wiki-recall" diff --git a/scripts/debt-worklist b/scripts/debt-worklist new file mode 100755 index 0000000..6b3f006 --- /dev/null +++ b/scripts/debt-worklist @@ -0,0 +1,559 @@ +#!/usr/bin/env python3 +"""debt-worklist — 還債線：每天固定撈一次「今天可以領什麼」，整包整包地領。 + +leo 2026-08-27（inkstone/ISEP#83 的來由，他當場訂正總管的誤解）： + 「這是兩件不同的事，你根本沒搞清楚，距離是在確定有個緊急事件要儘速達成時， + 現在每天都在追新的，所以**要用 Routine 去消化舊的**，可以有多個條件」 + +⇒ **兩條線，各用各的判準**，不是二選一： + + 緊急線 有事要趕 → 用「距離目標的遠近」排（＝掛在 open milestone 上的那些） + 還債線 每天消化舊的 → 用多條件排（事故／擋人／承諾／票齡／估工） ← 本工具 + +病根：全 org 229 張 open 票，每天在動的只有掛在 active milestone 上的那些。 +沒掛的不是不重要，是**沒有任何機制會去拿它們**。`worklist-guard.sh` 擋的是 +「這一輪已經領到的工作沒做完就收工」——它不會去把舊票撈出來。本工具補的是供給面。 + +三個動詞： + + debt-worklist list 撈一次，排好序印出來（預設動作） + debt-worklist claim <票...> 領走（今天領的，明天就不會再出現在清單上） + debt-worklist forget <票...> 放回去（領錯了、或那條線改方向了） + +票的寫法：`owner/repo#N`，例：`inkstone/InkStoneCo#44` + +🔴 **不是輪詢。** 這支腳本自己不會醒——是人跑它、或 SessionStart 那一次順手跑。 + 不准掛 Gitea Actions／webhook fan-out（CLAUDE.md 避免再被 flag 的硬規則， + `issue-handle` 明寫「有事才讀」，換成 Gitea 也不放寬）。 + +離線可測：設 `ISEP_DEBT_FIXTURE=` 就完全不打網路（測試用）。 +狀態檔位置可用 `ISEP_DEBT_STATE_DIR` 改（測試用，預設 `~/.claude/isep-debt/`）。 +""" +import json +import os +import re +import subprocess +import sys +import urllib.error +import urllib.parse +import urllib.request +from datetime import datetime, timezone + +HOST = os.environ.get("TICKET_HOST") or "https://git.uncle6.me" +ORG = os.environ.get("ISEP_DEBT_ORG") or "inkstone" + +# ── 「現在的主線是哪一個」只有一份答案（inkstone/ISEP#82 → hooks/lib/mainline.py）── +# 本工具排除的是**緊急線正在管的那些**。在 #82 之前，「哪個是 active」沒有指涉對象 +# （14 個 open milestone 同時亮著），所以第一版只能粗暴地「掛 open milestone 就排除」。 +# 現在有唯一答案了 ⇒ 接上去，**不要自己養第二套判斷**（兩份必然漂移）。 +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "hooks", "lib")) +try: + import mainline as ML +except Exception: # 拿不到共用零件就退回舊行為（fail-open），不讓還債線整個癱掉 + ML = None + +# 等 leo 的票不進「可領清單」——不是它們不重要，是**沒有人能替他領**： +# Human／human/exec ＝ 要他親手批示或動手 +# s/stage ＝ 已經部到 stage，等他驗（session-start-recall 就是這樣定義的） +# 這些的正確動作是「催」不是「領」，而催辦是 inkstone/ISEP#93 的事。本票是供給面。 +WAITING_LEO_LABELS = {"Human", "human/exec", "s/stage"} + +# 已經有人在做／已經有 PR 的狀態：這是「答應過人家的」，債比沒開工的還硬。 +STARTED_LABELS = {"s/doing", "s/review"} + + +def die(msg, code=2): + print(msg, file=sys.stderr) + sys.exit(code) + + +# ── 連線（跟 scripts/ticket 同一套：先找帶憑證的 remote，再退環境變數）──────── +def token(): + root = os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd() + 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] + die(f"""🔴 拿不到 {host} 的 token + +擇一： + • 讓某個 remote 帶憑證（多數 repo 的 gitea/origin 本來就有） + • 或設環境變數 GITEA_TOKEN_CLAUDE_CODE""") + + +def api(path): + url = f"{HOST}/api/v1{path}" + req = urllib.request.Request(url, headers={"Authorization": f"token {token()}"}) + try: + return json.load(urllib.request.urlopen(req, timeout=60)) + except urllib.error.HTTPError as e: + die(f"🔴 Gitea {e.code}：{e.read().decode()[:300]}\n （path={path}）") + except Exception as e: + die(f"🔴 打不到 {HOST}：{e}\n （path={path}）") + + +# ── 收集：全 org 每個 repo 的 open issue ＋ open PR ────────────────────────── +def collect(): + """回 (repos, items)。repos 是「我查了哪些」的證明，items 是原始票。 + + fixture 模式（測試用）：完全不打網路，資料從 json 檔讀。 + """ + fx = os.environ.get("ISEP_DEBT_FIXTURE") + if fx: + with open(fx) as f: + data = json.load(f) + return data["repos"], data["items"] + + repos, items = [], [] + for r in api(f"/orgs/{ORG}/repos?limit=100") or []: + full = r["full_name"] + if not r.get("has_issues", True): + repos.append({"name": full, "issues": 0, "prs": 0, "skipped": "issues 關閉"}) + continue + got, page = [], 1 + while True: + q = urllib.parse.urlencode({"state": "open", "limit": 50, "page": page}) + batch = api(f"/repos/{full}/issues?{q}") or [] + got.extend(batch) + if len(batch) < 50: + break + page += 1 + if page > 20: # 保險絲：不可能有一千張，有的話是我寫錯了 + break + for it in got: + it.setdefault("repository", {"full_name": full}) + n_pr = sum(1 for it in got if it.get("pull_request")) + repos.append({"name": full, "issues": len(got) - n_pr, "prs": n_pr}) + items.extend(got) + return repos, items + + +# ── 工具 ─────────────────────────────────────────────────────────────────── +def ref_of(it): + return f"{it['repository']['full_name']}#{it['number']}" + + +def labels_of(it): + return {l["name"] for l in (it.get("labels") or [])} + + +def is_pr(it): + return bool(it.get("pull_request")) + + +def parse_ts(s): + if not s: + return None + try: + return datetime.fromisoformat(s.replace("Z", "+00:00")) + except Exception: + return None + + +def now(): + """時鐘可以被定住——測試要能重現，不能今天跑綠明天跑紅。""" + inj = os.environ.get("ISEP_DEBT_NOW") + if inj: + d = parse_ts(inj) + if d: + return d + return datetime.now(timezone.utc) + + +def days_since(s): + d = parse_ts(s) + if not d: + return 0.0 + return max(0.0, (now() - d).total_seconds() / 86400) + + +REF_RE = re.compile(r"(?:([\w.-]+)/([\w.-]+))?#(\d+)") + + +def refs_in(it): + """從標題＋內文抓出它指到的別張票。裸 `#12` 算同 repo。 + + 只認得出「文字上指了誰」——這是零成本的訊號（內文本來就在清單裡）。 + Gitea 原生的 dependencies 要一張票打一次 API，229 張＝229 次，不值得。 + """ + owner, repo = it["repository"]["full_name"].split("/") + out = set() + text = f"{it.get('title') or ''}\n{it.get('body') or ''}" + for o, r, n in REF_RE.findall(text): + out.add(f"{o or owner}/{r or repo}#{n}") + out.discard(ref_of(it)) + return out + + +# ── 排序：多個條件，每一條都看得見自己貢獻了幾分 ───────────────────────────── +# +# leo 給的順序（票上原文）：出事的 → 擋住別人的 → 答應過人家的 → 放最久的 → 最快做完的。 +# 分數只是把這個順序寫成可重現的東西；**每一項都會印在票旁邊**， +# 排出來覺得不對可以直接指著說「這一項給太多」，而不是猜它為什麼在第一名。 +def score(it, in_degree): + lab = labels_of(it) + parts = [] + + if "type/bug" in lab: + parts.append(("事故", 40)) + if "p/high" in lab: + parts.append(("高優先", 20)) + if "p/low" in lab: + parts.append(("低優先", -12)) + + blocked = in_degree.get(ref_of(it), 0) + if blocked: + parts.append((f"擋住{blocked}張", min(12 * blocked, 36))) + if is_pr(it): + # 躺著沒結論的 PR 擋的是 merge 那條路（inkstone/ISEP#81 是它的另一半） + parts.append(("PR躺著", 25)) + + started = lab & STARTED_LABELS + if started: + parts.append((f"已開工({'/'.join(sorted(started))})", 18)) + if it.get("assignees") or it.get("assignee"): + parts.append(("有人接了", 12)) + + ms = it.get("milestone") or {} + if ms and (ms.get("state") or "open") == "open" and ML is not None: + due = ML.due_of(ms) + if due and due < now(): + # 掛在**別條**（非主線）而且期限已經過去的 milestone ⇒ 這是承諾過的日期， + # 而那個日期已經過了。它之所以還在這份清單上，正是因為沒有人在管那條線。 + parts.append((f"逾期{int((now() - due).total_seconds() // 86400)}天的承諾", 15)) + + age = days_since(it.get("updated_at")) + if age >= 1: + parts.append((f"擱置{int(age)}天", round(min(age * 0.6, 30), 1))) + + body_len = len(it.get("body") or "") + if "type/chore" in lab or body_len < 800: + parts.append(("看起來小", 10)) + + total = round(sum(p[1] for p in parts), 1) + return total, parts + + +def pick(items, claimed): + """把原始票分成三堆：可領的／緊急線的／要 leo 動手的。並回統計。""" + open_refs = {ref_of(it) for it in items} + in_degree = {} + for it in items: + for target in refs_in(it): + if target in open_refs: + in_degree[target] = in_degree.get(target, 0) + 1 + + ml = ML.load() if ML is not None else None + pool, stats = [], {"milestone": 0, "human": 0, "claimed": 0, "total": len(items), + "other_ms": 0, "mainline": ml} + for it in items: + ref = ref_of(it) + ms = it.get("milestone") + if ms and (ms.get("state") or "open") == "open": + if ml is None: + # 現在沒有主線 ⇒ 分不出哪一條是緊急線在管的。退回保守做法： + # 掛 open milestone 的一律不領（寧可少領，不要跟緊急線搶同一張）。 + stats["milestone"] += 1 + continue + if ML.belongs(ref, ml, ms.get("title")): + stats["milestone"] += 1 # 這張真的在主線上 ⇒ 緊急線在管，不重複領 + continue + # 掛在**別條** milestone 上：那條線現在沒有人在推 ⇒ 它就是債 + stats["other_ms"] += 1 + if labels_of(it) & WAITING_LEO_LABELS: + stats["human"] += 1 # 沒有人能替 leo 領（催辦是 ISEP#93） + continue + if ref in claimed: + stats["claimed"] += 1 # 昨天領走的，今天不再出現 + continue + s, parts = score(it, in_degree) + pool.append({"ref": ref, "title": it.get("title") or "", "score": s, + "why": parts, "labels": sorted(labels_of(it)), + "pr": is_pr(it), "url": it.get("html_url"), + "age": round(days_since(it.get("updated_at")), 1), + "refs": sorted(refs_in(it) & open_refs)}) + pool.sort(key=lambda d: (-d["score"], d["ref"])) + return pool, stats, in_degree + + +# ── 成包：互相指著的必然同包（票上原文「相關的票要成包一起領，不要拆散」）────── +# +# 🔴 **只認強訊號，寧可少成包**。第一版用「單向文字引用」成包，結果是 +# **前 190 張裡有 121 張黏成一包**——因為大家都會順手引用 hub 票。 +# 一包 121 張＝沒有人領得動＝跟沒分包一樣。所以只認這兩種： +# ① 互相指著（A 的內文提 B，且 B 的內文提 A）——單向不算 +# ② Gitea 原生相依（`ticket subtask` 建的母子票就是這個） +# 代價：同一條使用者旅程但沒有互指、也沒建相依的兩張票不會成包。 +# 這是誠實的取捨——**寧可漏成包，不要成一包沒人領得動的**。 +BUNDLE_CAP = 8 # 一包最多印幾張；超過就說「還有幾張」 +DEPS_TOP_K = 25 # 只對前 K 名查原生相依（一張一次 API，不對全部查） + + +def dep_edges(pool, enabled=True): + """回 [(a, b)…]：前 K 名的原生相依邊，只留兩端都在 pool 裡的。""" + fx = os.environ.get("ISEP_DEBT_FIXTURE") + if fx: + with open(fx) as f: + deps = (json.load(f).get("deps") or {}) + in_pool = {d["ref"] for d in pool} + return [(a, b) for a, bs in deps.items() for b in bs + if a in in_pool and b in in_pool] + if not enabled: + return [] + in_pool = {d["ref"] for d in pool} + edges = [] + for d in pool[:DEPS_TOP_K]: + owner, rest = d["ref"].split("/", 1) + repo, num = rest.split("#") + try: + got = api(f"/repos/{owner}/{repo}/issues/{num}/dependencies") or [] + except SystemExit: + continue + for i in got: + other = f"{i['repository']['full_name']}#{i['number']}" + if other in in_pool: + edges.append((d["ref"], other)) + return edges + + +def mutual_edges(pool): + idx = {d["ref"]: set(d["refs"]) for d in pool} + out = [] + for ref, targets in idx.items(): + for t in targets: + if t in idx and ref in idx[t] and ref < t: + out.append((ref, t)) + return out + + +def bundle(pool, edges): + idx = {d["ref"]: d for d in pool} + parent = {r: r for r in idx} + + def find(x): + while parent[x] != x: + parent[x] = parent[parent[x]] + x = parent[x] + return x + + def union(a, b): + ra, rb = find(a), find(b) + if ra != rb: + parent[rb] = ra + + for a, b in edges: + if a in idx and b in idx: + union(a, b) + + groups = {} + for d in pool: + groups.setdefault(find(d["ref"]), []).append(d) + out = [] + for members in groups.values(): + members.sort(key=lambda d: (-d["score"], d["ref"])) + out.append({"lead": members[0], "members": members, + "score": members[0]["score"]}) + out.sort(key=lambda b: (-b["score"], b["lead"]["ref"])) + return out + + +# ── 狀態：領走了什麼（明天的清單要看得出昨天領走的不見了）─────────────────── +def state_dir(): + d = os.environ.get("ISEP_DEBT_STATE_DIR") or os.path.expanduser("~/.claude/isep-debt") + os.makedirs(d, exist_ok=True) + return d + + +def state_path(): + return os.path.join(state_dir(), "claimed.json") + + +def load_state(): + try: + with open(state_path()) as f: + d = json.load(f) + except Exception: + d = {} + d.setdefault("claims", {}) + d.setdefault("last_run", None) + return d + + +def save_state(d): + with open(state_path(), "w") as f: + json.dump(d, f, ensure_ascii=False, indent=1) + + +# ── 印 ───────────────────────────────────────────────────────────────────── +def print_proof(repos, stats): + scanned = [r for r in repos if not r.get("skipped")] + n_iss = sum(r["issues"] for r in scanned) + n_pr = sum(r["prs"] for r in scanned) + print(f"🔎 查過的 repo：{len(repos)} 個（{ORG} 全組織）" + f"　open issue {n_iss}、open PR {n_pr}") + for r in sorted(repos, key=lambda x: -(x["issues"] + x["prs"])): + mark = f"（跳過：{r['skipped']}）" if r.get("skipped") else "" + print(f" · {r['name']}　issue {r['issues']}／PR {r['prs']} {mark}") + ml = stats.get("mainline") + if ml: + print(f"\n🎯 現在的主線：{ML.ref_of(ml)}「{ml.get('title')}」" + f"（唯一答案來自 scripts/mainline，本工具不自己判）") + print(f" 掛在**別條** milestone 上的 {stats['other_ms']} 張仍算債" + "——那條線現在沒有人在推") + else: + print("\n🎯 現在沒有標主線（`scripts/mainline set …`）" + "⇒ 分不出哪條是緊急線在管的，保守起見：掛 open milestone 的一律不領") + print(f"\n 扣掉：掛在 open milestone 上的 {stats['milestone']} 張（那些歸緊急線管）" + f"／等 leo 的 {stats['human']} 張" + f"（Human・human/exec・s/stage——那些要催不是要領，見 inkstone/ISEP#93）" + f"／已經領走的 {stats['claimed']} 張") + + +def print_carry(state, items): + """昨天領走的，今天怎麼了——**這一段就是「看得出領走的不在清單上」**。""" + claims = state.get("claims") or {} + if not claims: + return + open_refs = {ref_of(it) for it in items} + done = [r for r in claims if r not in open_refs] + doing = [r for r in claims if r in open_refs] + print(f"\n📦 之前領走的 {len(claims)} 張：已關 {len(done)}、還開著 {len(doing)}") + for r in sorted(doing): + c = claims[r] + print(f" ◻ {r}　（{c.get('at', '?')[:10]} 領的）{c.get('title', '')[:40]}") + for r in sorted(done): + print(f" ✅ {r}　已關") + if doing: + print(" 🔴 還開著的沒有回到可領清單裡——做完就關票，或 " + "`debt-worklist forget <票>` 把它放回去。") + + +def print_bundle(i, b, verbose): + lead = b["lead"] + kind = "PR" if lead["pr"] else "票" + print(f"\n {i}. [{lead['score']}] {lead['ref']}（{kind}）") + print(f" {lead['title'][:72]}") + print(" 為什麼排這裡：" + "、".join(f"{n}{v:+g}" for n, v in lead["why"])) + if lead["labels"]: + print(f" 標籤：{lead['labels']}") + others = b["members"][1:] + if others: + print(f" ↳ 同一包（互相指著／原生相依，要一起領）共 {len(b['members'])} 張：") + shown = others if verbose else others[:BUNDLE_CAP] + for m in shown: + print(f" · [{m['score']}] {m['ref']}　{m['title'][:56]}") + if len(others) > len(shown): + print(f" · …另外 {len(others) - len(shown)} 張（`--all` 看全部）") + + +def cmd_list(argv): + top = int(argv[argv.index("--top") + 1]) if "--top" in argv else 6 + verbose = "--all" in argv + as_json = "--json" in argv + + repos, items = collect() + state = load_state() + pool, stats, _ = pick(items, set(state.get("claims") or {})) + edges = mutual_edges(pool) + dep_edges(pool, enabled="--no-deps" not in argv) + bundles = bundle(pool, edges) + + if as_json: + print(json.dumps({ + "at": now().isoformat(), "repos": repos, "stats": stats, + "claimed": sorted(state.get("claims") or {}), + "bundles": [{"score": b["score"], + "members": [{"ref": m["ref"], "score": m["score"], + "title": m["title"], "why": m["why"]} + for m in b["members"]]} for b in bundles], + }, ensure_ascii=False, indent=1)) + else: + print(f"🧾 還債清單　{now().strftime('%Y-%m-%d %H:%M UTC')}\n") + print_proof(repos, stats) + print_carry(state, items) + print(f"\n── 今天可以領的：{len(pool)} 張，收斂成 {len(bundles)} 包 " + f"────────────────────") + if not pool: + # 🔴 空清單要說話。默默結束＝人分不出「查過沒東西」跟「根本沒查」。 + print("\n ✅ **查詢跑過了，結果是零。**" + f"\n {len(repos)} 個 repo 都掃過（見上面那份清單），" + "沒有一張是「沒掛 milestone、沒等 leo、還沒被領走」的。" + "\n 這代表舊債清乾淨了——不是查詢壞掉。") + for i, b in enumerate(bundles[:len(bundles) if verbose else top], 1): + print_bundle(i, b, verbose) + if not verbose and len(bundles) > top: + print(f"\n …另外 {len(bundles) - top} 包（`--top N` 或 `--all` 看更多）") + if pool: + first = " ".join(m["ref"] for m in bundles[0]["members"][:BUNDLE_CAP]) + print(f""" +── 領走它 ────────────────────────────────────────────────── + debt-worklist claim {first} + + 領走 ＝ 今天要做它。領了之後它就不會再出現在這份清單上， + 直到你把票關掉、或 `debt-worklist forget` 把它放回去。 + 🔴 **整包一起領**：同一包是互相指著的，拆開做會做到一半發現卡在另一張。""") + + state["last_run"] = now().isoformat() + save_state(state) + return 0 + + +def _titles(items): + return {ref_of(it): (it.get("title") or "") for it in items} + + +def cmd_claim(argv): + refs = [a for a in argv if not a.startswith("-")] + if not refs: + die("用法：debt-worklist claim [更多…]") + for r in refs: + if not re.match(r"^[\w.-]+/[\w.-]+#\d+$", r): + die(f"🔴 票的寫法是 owner/repo#N，你給的是：{r}") + _, items = collect() + titles = _titles(items) + unknown = [r for r in refs if r not in titles] + if unknown: + die("🔴 這幾張不在 open 清單裡（打錯了？已經關了？）：" + "、".join(unknown)) + state = load_state() + for r in refs: + state["claims"][r] = {"at": now().isoformat(), "title": titles[r]} + save_state(state) + print(f"📦 領走 {len(refs)} 張，明天的清單不會再出現它們：") + for r in refs: + print(f" · {r}　{titles[r][:60]}") + print("\n🔴 領了就是今天要做它。做完關票；改方向就 `debt-worklist forget`。") + return 0 + + +def cmd_forget(argv): + refs = [a for a in argv if not a.startswith("-")] + if not refs: + die("用法：debt-worklist forget [更多…]") + state = load_state() + gone = [r for r in refs if state["claims"].pop(r, None) is not None] + save_state(state) + print(f"↩️ 放回清單 {len(gone)} 張：" + ("、".join(gone) or "（本來就沒領過）")) + return 0 + + +CMDS = {"list": cmd_list, "claim": cmd_claim, "forget": cmd_forget} + +if __name__ == "__main__": + if len(sys.argv) < 2: + sys.exit(cmd_list([])) + if sys.argv[1] in ("-h", "--help", "help"): + print(__doc__) + sys.exit(0) + if sys.argv[1] not in CMDS: + print(__doc__) + sys.exit(2) + sys.exit(CMDS[sys.argv[1]](sys.argv[2:])) diff --git a/scripts/test-debt-worklist.sh b/scripts/test-debt-worklist.sh new file mode 100755 index 0000000..b49c3c4 --- /dev/null +++ b/scripts/test-debt-worklist.sh @@ -0,0 +1,222 @@ +#!/bin/bash +# 還債清單（scripts/debt-worklist）的測試——inkstone/ISEP#83 的四條驗收條件，一條一組。 +# +# 全程離線：資料走 ISEP_DEBT_FIXTURE、時鐘走 ISEP_DEBT_NOW、狀態走 ISEP_DEBT_STATE_DIR。 +# **不打 Gitea、不留任何測試票、不碰 $HOME**。 +# +# 為什麼要能離線測：這支工具的判斷（誰排前面、誰算緊急線、領走的還在不在） +# 全都是純函式，只有「撈」那一步要網路。把撈的那一步換掉，其餘每一條都測得動—— +# 否則就只剩「今天跑起來看起來對」，那不是測試（本 repo 心法：跑過 ≠ 驗過）。 +cd "$(dirname "$0")/.." || exit 1 +W=scripts/debt-worklist +PASS=0; FAIL=0 +T=$(mktemp -d); trap 'rm -rf "$T"' EXIT +NOW=2026-08-28T00:00:00Z + +ok(){ # $1=條件 $2=說明 + if eval "$1"; then PASS=$((PASS+1)); printf ' ✅ %s\n' "$2" + else FAIL=$((FAIL+1)); printf ' ❌ %s\n 判準：%s\n' "$2" "$1"; fi +} + +run(){ # 跑 list（或任何子命令），輸出留在 $OUT，離開碼留在 $RC + # 🔴 ISEP_COUNTDOWN_STATE_DIR 也要指到暫存目錄：主線（hooks/lib/mainline.py）住在那裡， + # 不隔離的話這支測試的結果會取決於「這台機器現在標了哪條主線」——那就不是測試了。 + OUT=$(ISEP_DEBT_FIXTURE="$FX" ISEP_DEBT_STATE_DIR="$T/state" ISEP_DEBT_NOW="$NOW" \ + ISEP_COUNTDOWN_STATE_DIR="$ML_DIR" python3 "$W" "$@" 2>&1); RC=$? +} + +ML_DIR="$T/mainline"; mkdir -p "$ML_DIR" +set_mainline(){ # $1=主線 milestone 標題（空＝沒有主線） + if [ -z "$1" ]; then rm -f "$ML_DIR/mainline.json"; return; fi + python3 - "$ML_DIR/mainline.json" "$1" <<'PY' +import json, sys +path, title = sys.argv[1], sys.argv[2] +json.dump({"ref": "inkstone/A#1", "owner": "inkstone", "repo": "A", "id": 1, + "title": title, "members": [], "due_on": ""}, open(path, "w")) +PY +} + +# ── 造資料：一份長得像 Gitea 回應的 fixture ───────────────────────────────── +mkfx(){ FX="$T/$1.json"; python3 - "$FX" "$1" <<'PY' +import json, sys +path, which = sys.argv[1], sys.argv[2] + +def it(repo, n, title, labels=(), ms=None, ms_state="open", assignees=(), + updated="2026-08-01T00:00:00Z", body="", pr=False): + d = {"number": n, "title": title, "body": body, "updated_at": updated, + "created_at": "2026-07-01T00:00:00Z", "state": "open", + "labels": [{"name": l} for l in labels], + "assignees": [{"login": a} for a in assignees] or None, + "repository": {"full_name": repo}, + "html_url": f"https://git.uncle6.me/{repo}/issues/{n}"} + if ms: + d["milestone"] = {"title": ms, "state": ms_state} + if ms == "上個 sprint": + d["milestone"]["due_on"] = "2026-08-10T23:59:59Z" # 已經過了 18 天 + if pr: + d["pull_request"] = {"merged": False} + return d + +repos = [{"name": "inkstone/A", "issues": 0, "prs": 0}, + {"name": "inkstone/B", "issues": 0, "prs": 0}] +deps, items = {}, [] + +if which == "full": + items = [ + # 事故＋擋住別人的 → 該排第一 + it("inkstone/A", 1, "壞掉了", ["type/bug"], updated="2026-08-20T00:00:00Z", + body="x" * 2000), + it("inkstone/A", 2, "我等 A#1", updated="2026-08-27T00:00:00Z", + body="被 inkstone/A#1 擋住" + "y" * 2000), + it("inkstone/B", 9, "我也等 A#1", updated="2026-08-27T00:00:00Z", + body="要先解 inkstone/A#1" + "y" * 2000), + # 掛在 open milestone 上＝緊急線在管，不該出現 + it("inkstone/A", 3, "緊急線的票", ["p/high", "type/bug"], ms="這週出貨"), + # 掛在**別條**（非主線）milestone 上，而且期限已經過了 + it("inkstone/A", 8, "別條線的票", ms="上個 sprint", body="q" * 2000), + # milestone 已關但票還開著＝孤兒，該出現 + it("inkstone/A", 4, "孤兒票", ms="上週", ms_state="closed", body="z" * 2000), + # 等 leo 的三種，都不該出現在可領清單 + it("inkstone/A", 5, "等 leo 批", ["Human", "p/high", "type/bug"]), + it("inkstone/A", 6, "等 leo 動手", ["human/exec"]), + it("inkstone/A", 7, "等 leo 驗", ["s/stage", "p/high"]), + # 放很久沒人動 vs 昨天才動過：同條件下前者要排前面 + it("inkstone/B", 10, "放了很久", updated="2026-06-01T00:00:00Z", body="w" * 2000), + it("inkstone/B", 11, "昨天才動過", updated="2026-08-27T00:00:00Z", body="w" * 2000), + # 躺著的 PR 也是債 + it("inkstone/B", 12, "躺著的 PR", pr=True, updated="2026-08-10T00:00:00Z", + body="v" * 2000), + # p/low：往後排 + it("inkstone/B", 13, "晚點沒關係", ["p/low"], body="u" * 2000), + # 互相指著＝必然同包 + it("inkstone/B", 20, "雙胞胎甲", body="跟 inkstone/B#21 是同一件事" + "t" * 2000, + updated="2026-08-05T00:00:00Z"), + it("inkstone/B", 21, "雙胞胎乙", body="見 inkstone/B#20" + "t" * 2000, + updated="2026-08-05T00:00:00Z"), + # 母票／子票：只有原生相依看得出來（內文沒有互指） + it("inkstone/B", 30, "母票", body="s" * 2000, updated="2026-08-05T00:00:00Z"), + it("inkstone/B", 31, "子票", body="s" * 2000, updated="2026-08-05T00:00:00Z"), + ] + deps = {"inkstone/B#30": ["inkstone/B#31"]} + +elif which == "empty": + items = [it("inkstone/A", 3, "緊急線的票", ["p/high"], ms="這週出貨"), + it("inkstone/A", 5, "等 leo 批", ["Human"])] + +elif which == "onedone": + # 「昨天領走的今天關掉了」——它從 open 清單消失 + items = [it("inkstone/A", 2, "我等 A#1", body="y" * 2000)] + +json.dump({"repos": repos, "items": items, "deps": deps}, open(path, "w")) +PY +} + +mkfx full; FULL="$T/full.json" +mkfx empty +mkfx onedone + +echo "── 驗收 1：跑一次要吐出排好序的清單＋「我查了哪些 repo」的證明 ──" +FX="$FULL"; run list --top 20 +ok '[ "$RC" = 0 ]' '離開碼 0' +ok 'grep -q "查過的 repo：2 個" <<<"$OUT"' '證明段落列出查過的 repo 數' +ok 'grep -q "inkstone/A" <<<"$OUT" && grep -q "inkstone/B" <<<"$OUT"' '每個 repo 都列名（不是只給總數）' +ok 'grep -q "1\. \[.*\] inkstone/A#1" <<<"$OUT"' '事故＋擋住兩張 ⇒ 排第一名' +ok 'grep -q "事故+40" <<<"$OUT"' '每張票旁邊看得到「為什麼排這裡」的分項' +ok 'grep -q "擋住2張" <<<"$OUT"' '「擋住別人的」算得出來（兩張指著 A#1）' + +echo "── 驗收 1b：排序的五個條件真的有作用 ──" +pos(){ grep -n "$1" <<<"$OUT" | head -1 | cut -d: -f1; } +ok '[ "$(pos "inkstone/B#10")" -lt "$(pos "inkstone/B#11")" ]' '放最久的排在昨天才動過的前面' +ok '[ "$(pos "inkstone/B#12")" -lt "$(pos "inkstone/B#13")" ]' '躺著的 PR 排在 p/low 前面' +ok 'grep -q "PR躺著+25" <<<"$OUT"' 'PR 被認出來（不是只算 issue）' +ok '! grep -q "inkstone/A#3" <<<"$OUT"' '掛 open milestone 的不進清單（那歸緊急線）' +ok 'grep -q "inkstone/A#4" <<<"$OUT"' 'milestone 已關但票還開著 ⇒ 是債，要進清單' +ok '! grep -q "inkstone/A#5" <<<"$OUT" && ! grep -q "inkstone/A#6" <<<"$OUT"' \ + 'Human／human-exec 不進可領清單（沒有人能替 leo 領）' +ok '! grep -q "inkstone/A#7" <<<"$OUT"' 's/stage＝等 leo 驗，要催不是要領' +ok 'grep -q "等 leo 的 3 張" <<<"$OUT"' '被扣掉的有講數字，不是靜靜消失' + +echo "── 驗收 1c：成包——相關的要一起領，但不准黏成一坨 ──" +ok 'grep -A6 "inkstone/B#20（票）" <<<"$OUT" | grep -q "inkstone/B#21"' '互相指著的成同一包' +ok 'grep -A6 "inkstone/B#30（票）" <<<"$OUT" | grep -q "inkstone/B#31"' '原生相依（母票→子票）成同一包' +ok '! (grep -A6 "inkstone/A#1（票）" <<<"$OUT" | grep -q "同一包")' \ + '單向引用不成包（A#2、B#9 都指著 A#1，但 A#1 沒指回來 ⇒ 不能黏成一坨）' + +echo "── 接上「現在的主線是哪一個」（inkstone/ISEP#82 的唯一答案）──" +set_mainline ""; FX="$FULL"; run list --top 20 +ok 'grep -q "現在沒有標主線" <<<"$OUT"' '沒標主線 ⇒ 照實說，不編一條出來' +ok '! grep -q "inkstone/A#3" <<<"$OUT" && ! grep -q "inkstone/A#8" <<<"$OUT"' \ + '沒標主線 ⇒ 保守：掛 open milestone 的一律不領（不跟緊急線搶同一張）' +set_mainline "這週出貨"; run list --top 20 +ok 'grep -q "現在的主線" <<<"$OUT" && grep -q "這週出貨" <<<"$OUT"' \ + '標了主線 ⇒ 清單上講得出用的是哪一條（判斷來自 scripts/mainline，不是自己算的）' +ok '! grep -q "inkstone/A#3" <<<"$OUT"' '在主線上的票仍然不領（那是緊急線在管的）' +ok 'grep -q "inkstone/A#8" <<<"$OUT"' '掛在別條 milestone 的是債（那條線現在沒人推）' +ok 'grep -q "逾期17天的承諾+15" <<<"$OUT"' '別條 milestone 已逾期 ⇒ 算「答應過人家的」加分' +ok 'grep -q "別條\*\* milestone 上的 1 張仍算債" <<<"$OUT"' '被改判成債的有幾張，講出來' +set_mainline "" # 收回去，後面幾組回到「沒有主線」的世界 + +echo "── 驗收 2：清單是空的要說話，不能默默結束 ──" +FX="$T/empty.json"; run list +ok '[ "$RC" = 0 ]' '離開碼 0（沒東西可領不是錯誤）' +ok 'grep -q "查詢跑過了，結果是零" <<<"$OUT"' '明講「查過了，結果是零」' +ok 'grep -q "查過的 repo：2 個" <<<"$OUT"' '空清單一樣附查詢證明（分得出「沒東西」與「沒查」）' + +echo "── 驗收 3：今天領走的，明天不在清單上 ──" +rm -rf "$T/state"; FX="$FULL" +run claim inkstone/B#20 inkstone/B#21 +ok '[ "$RC" = 0 ]' '領走兩張成功' +run list --top 20 +PICK=$(sed -n '/今天可以領的/,$p' <<<"$OUT") +ok '! grep -q "inkstone/B#21" <<<"$PICK"' '領走的不再出現在可領清單（只看清單那一段）' +ok 'grep -q "之前領走的 2 張" <<<"$OUT"' '第二天看得到「之前領走的」那一段' +ok 'grep -q "還開著 2" <<<"$OUT"' '還開著的照實說（沒關就是還沒做完）' +ok 'grep -q "已經領走的 2 張" <<<"$OUT"' '扣除數字對得上' + +echo "── 驗收 3b：領走的票關掉之後，狀態要跟著變 ──" +FX="$T/onedone.json"; run list +ok 'grep -q "已關 2" <<<"$OUT"' '票已經不在 open 清單 ⇒ 認定它做完了' + +echo "── 驗收 3c：放回去 ──" +FX="$FULL"; run forget inkstone/B#20 inkstone/B#21 +ok '[ "$RC" = 0 ]' 'forget 成功' +run list --top 20 +ok 'grep -q "inkstone/B#20" <<<"$OUT"' '放回去之後又回到可領清單' + +echo "── 誤用：擋得住，而且說得出怎麼改 ──" +run claim B#20 +ok '[ "$RC" = 2 ] && grep -q "owner/repo#N" <<<"$OUT"' '票號寫錯 ⇒ 擋下並示範正確寫法' +run claim inkstone/B#999 +ok '[ "$RC" = 2 ]' '領一張不存在／已關的票 ⇒ 擋下' +run claim +ok '[ "$RC" = 2 ] && grep -q "用法" <<<"$OUT"' '沒給票號 ⇒ 印用法' + +echo "── 機器可讀（要接進別的東西時不用 parse 中文）──" +run list --json +ok 'python3 -c "import json,sys;d=json.load(sys.stdin);sys.exit(0 if d[\"bundles\"] and d[\"repos\"] else 1)" <<<"$OUT"' \ + '--json 吐得出合法 JSON，且有 bundles／repos' + +echo "── 紅線：這支腳本自己不會醒（不准做成輪詢／fan-out）──" +ok '! grep -nE "time\\.sleep|crontab|sched|urlopen.*hooks" '"$W" \ + '原始碼裡沒有等待／排程／裝 webhook 的動作（只有註解在談紅線，那不算）' + +echo "── SessionStart 那一句：不用有人記得下指令，也不准偷偷打網路 ──" +# 把 session-start-recall.sh 裡「還債線」那一段切出來單獨跑（其餘段落會打雲端，這裡不要）。 +FRAG="$T/frag.sh" +sed -n '/push 6：還債線/,/^echo ""$/p' hooks/session-start-recall.sh > "$FRAG" +ok '[ -s "$FRAG" ]' 'session-start-recall.sh 裡真的有那一段（被刪掉就會紅）' +rm -rf "$T/nudge"; mkdir -p "$T/nudge" +OUT=$(set -euo pipefail; ISEP_DEBT_STATE_DIR="$T/nudge" bash "$FRAG" 2>&1); RC=$? +ok '[ "$RC" = 0 ]' '沒有狀態檔也跑得過（第一次開 session）' +ok 'grep -q "今天還沒撈過" <<<"$OUT"' '今天沒撈過 ⇒ 開 session 就會說' +ok 'grep -q "debt-worklist list" <<<"$OUT"' '順手把要跑的那一行給出來' +printf '{"claims":{"a/b#1":{}},"last_run":"%sT00:00:00Z"}' "$(date -u +%Y-%m-%d)" > "$T/nudge/claimed.json" +OUT=$(ISEP_DEBT_STATE_DIR="$T/nudge" bash "$FRAG" 2>&1) +ok 'grep -q "今天撈過了" <<<"$OUT"' '今天撈過了 ⇒ 不再重複催' +ok 'grep -q "手上領著 1 張" <<<"$OUT"' '手上還領著幾張講出來' +ok '! grep -qE "curl|urlopen|http" <<<"$(cat "$FRAG")"' \ + 'SessionStart 那一段完全不打網路（撈是人決定的動作，不是開機自動去撈）' + +echo +echo "通過 $PASS 條，失敗 $FAIL 條" +[ "$FAIL" = 0 ]