diff --git a/docs/TESTING.md b/docs/TESTING.md index 8ea71fc..ee1a488 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -131,6 +131,42 @@ bash hooks/tests/prod-write-guard.test.sh hooks/prod-write-guard.sh - 「卡點二」2 條任一紅 ⇒ 「談論它」又被當成「執行它」（同款第八次）， 或是剝了內文之後連真的部署都放行了 +### A16 — 下游做完時頂層跟著關：49 條 +``` +bash scripts/test-ticket-handoff-writeback.sh +``` +**該看到**：`通過 49 條，失敗 0 條`。**全程離線**——`TICKET_HOST` 指到連不上的位址， +會打 API 的兩段（`_writeback`／`cmd_subtask`）把 `api()` 換成錄音機跑， +**不打真實 Gitea、不開票、不關票、不留任何測試票**。 + +**它在守什麼**（`inkstone/ISEP#92`）： +「開在頂層的票，下游做完了卻沒人回來關⋯⋯頂層票會永遠掛著，**而 leo 是看頂層的**。」 + +四格對應票上的四條驗收條件： +- ①②③ 純函式（`is_loose`／`writeback_plan`／`journey_label`）——**判準本身**， + 不必開真票就驗得動 +- ④⑤ `subtask`／`handoff` 的參數閘：該擋的擋、齊全的放得過 +- ⑦ **完工回寫的接線**（驗收第 2 條）：關掉一張下游票之後，它到底對頂層票做了什麼 +- ⑧ **雙向連結的接線**（驗收第 1 條）：兩張票互相看得到對方，不是靠人記得補 + +**失敗**： +- ①「open ＋ 從來沒有下游 → 不撈」紅 ⇒ **誤攔**：`ticket loose` 會把每一張普通票 + 都列出來，那張表就變成雜訊，人學會忽略它（本 repo 心法第 2 條） +- ②「還有別的下游沒關 → 只記一筆」紅 ⇒ 母票會在下游還沒做完時被指派回總管， + 假綠 +- ⑦「沒有去關母票」變綠 ⇒ 回寫從「處理」滑成「自動關掉」。 + **默默關掉跟默默留著是同一個病的兩面**——關票要有交付物、要有人看過 +- ⑦「留言第一行有身份欄」紅 ⇒ 機器貼的留言看起來像某個人寫的， + 下一個讀票的人會去找那個人（`reply-identity-guard` 管的是同一件事） +- ⑧「母子兩端都被貼」剩 1 ⇒ journey 只貼了一端，**聚類時撈得到一半**， + 比完全沒貼更危險 +- ⑤ 任何一條紅 ⇒ 誤攔，合規的交辦被擋掉等於這條路不能走 + +🔴 **這支測不到的那一格（要 leo 或總管接手）**：`labels.yaml` 的 `j/` 段 +**刻意是空的**——旅程怎麼切、叫什麼名字是方向題，不由工具代決。 +在有人往那裡加第一條旅程之前，`--journey` 只會擋、不會貼。 +機制驗過了，**資料還沒有**。 + ### A5 — 開票前的搜尋是跨 repo 的 ``` python3 scripts/ticket where 標籤 模組化 @@ -326,6 +362,7 @@ B2（信標那行）／B3（setup 輸出）／B4（閘的訊息）三個畫面 | **A13 戳記證明看過不是跑過** | 總管 | ✅ 17/17（2026-08-27，inkstone/ISEP#72→4873） | | **A14 回覆自己說出拖了多久** | 總管 | ✅ 20/20（2026-08-28，inkstone/ISEP#63） | | **A15 發通知不等於部署** | 總管 | ✅ 37/37（2026-08-28，inkstone/ISEP#63） | +| **A16 下游做完頂層跟著關** | 總管 | ✅ 49/49（2026-08-28，inkstone/ISEP#92） | | A5 搜尋跨 repo | 總管 | ✅ | | A6 標籤對齊＋冪等 | 總管 | ✅ 14 repo，第二次 0/0 | | **A9 人閘警察管路** | 總管 | ✅ 14/14（2026-08-26） | diff --git a/labels.yaml b/labels.yaml index 83f2897..32888a0 100644 --- a/labels.yaml +++ b/labels.yaml @@ -101,6 +101,26 @@ labels: exclusive: true description: "雜務、整理、不改行為" + # ── 使用者旅程（正交，`j/` scope）────────────────── + # + # inkstone/ISEP#92：「這件事服務哪個使用者旅程，沒有記錄⋯⋯後面要把相關的票 + # 聚成一包時，只能靠人重新讀一遍每張票在講什麼。」 + # + # `ticket subtask/handoff --journey <名>` 會把 `j/<名>` **同時貼在母子兩端** + # （只貼一端就聚不起來）。標籤不存在時它會擋下來並指回本檔—— + # **「要求標籤在場」，不是「猜哪些名字合法」**。 + # + # 🔴 這裡刻意是空的。旅程怎麼切、叫什麼名字，是方向題（四題公式第 4 題）， + # 不該由工具或 subagent 代決；隨手造名字會讓同一條旅程長出三個拼法。 + # 要新增一條就照這個形狀加一筆，然後跑 scripts/gitea-labels-sync.sh： + # + # - name: "j/收件匣" + # color: "fbca04" + # exclusive: false + # description: "🧭 旅程：<一句話講這條旅程的頭和尾>" + # + # （票上明講「對不上就不貼，不硬湊」——沒有對應旅程的票就不要加 --journey。） + # ── 結構（正交）────────────────────────────────── - name: "hub" color: "0052cc" diff --git a/scripts/test-ticket-handoff-writeback.sh b/scripts/test-ticket-handoff-writeback.sh new file mode 100755 index 0000000..d3fe65c --- /dev/null +++ b/scripts/test-ticket-handoff-writeback.sh @@ -0,0 +1,274 @@ +#!/bin/bash +# 「下游做完時頂層跟著關」的測試（inkstone/ISEP#92） +# +# 這支測三件事： +# ① 判準本身（純函式 is_loose／writeback_plan／journey_label） +# —— 這三支不打網路，所以「撈得對不對」「回寫該做什麼」測得動， +# 不必真的開票、關票來驗。 +# ② `subtask`／`handoff` 的參數閘：該擋的擋、齊全的放得過 +# ③ `loose` 這個動詞真的接得上（走到網路那一層才炸） +# +# 怎麼在「不真的動任何票」的前提下分辨擋／放行（沿用 test-ticket-where-seen-guard.sh）： +# TICKET_HOST 指到一個連不上的位址（127.0.0.1:9） +# 離開碼 2 ＝ 閘擋下（die） +# 離開碼 1 ＝ 閘全部放行，走到網路那一層才炸（Connection refused） +# 全程離線、不打真實 Gitea、不產生任何票、不關任何票。 +cd "$(dirname "$0")/.." || exit 1 +T=scripts/ticket +TMP=$(mktemp -d) +trap 'rm -rf "$TMP"' EXIT +PASS=0; FAIL=0 + +cat > "$TMP/body.md" <<'MD' +## 目標 +測試用內文。 + +## 驗收條件 +離開碼 2 ＝ 被擋；離開碼 1 ＝ 放行（走到網路才炸）。 + +## deliverable 類型 +code +MD +BAD_BODY="$TMP/bad.md"; echo "沒有模板欄位" > "$BAD_BODY" +TITLE="身為看頂層票的人，我要下游做完時頂層跟著關，我才不會看到一堆早就做完的票" + +# ── 純函式探針：把 scripts/ticket 當模組載進來問 ──────────────────────── +probe() { # probe → 印出結果 + python3 - "$1" <<'PY' +import sys, importlib.util as u +from importlib.machinery import SourceFileLoader as L +spec = u.spec_from_loader("t", L("t", "scripts/ticket")) +m = u.module_from_spec(spec); spec.loader.exec_module(m) +print(eval(sys.argv[1], {"m": m})) +PY +} + +p() { # p <說明> + got=$(probe "$3" 2>&1) + if [ "$got" = "$2" ]; then PASS=$((PASS+1)); printf ' ✅ '; else FAIL=$((FAIL+1)); printf ' ❌ '; fi + printf 'want=%s got=%s %s\n' "$2" "$got" "$1" +} + +O='{"state":"open"}'; C='{"state":"closed"}' + +echo "── ① is_loose：「下游都關了、自己還開著」是機械事實 ──" +p "★ open ＋ 下游全關 → 撈得到（票上驗收第 3 條）" "True" "m.is_loose('open',[$C,$C])" +p "open ＋ 還有一張下游開著 → 不撈（它還在跑）" "False" "m.is_loose('open',[$C,$O])" +p "open ＋ 從來沒有下游 → 不撈（它根本不是頂層票）" "False" "m.is_loose('open',[])" +p "closed ＋ 下游全關 → 不撈（自己都關了）" "False" "m.is_loose('closed',[$C,$C])" +p "open ＋ 下游全開 → 不撈" "False" "m.is_loose('open',[$O,$O])" + +echo +echo "── ② writeback_plan：下游關掉之後，頂層票該被怎麼處理 ──" +p "★ 最後一張下游關掉 → handback（指派回總管＋s/review，不默默留著）" \ + "('handback', [])" "m.writeback_plan('open',[$C,$C])" +p "還有別的下游沒關 → 只記一筆，別假裝它可以收了" \ + "('note', [{'state': 'open'}])" "m.writeback_plan('open',[$C,$O])" +p "頂層票自己已經關了 → skip" \ + "('skip', [])" "m.writeback_plan('closed',[$C,$C])" +p "頂層票已關但還有 open 下游 → 一樣 skip（不去吵已關的票）" \ + "('skip', [{'state': 'open'}])" "m.writeback_plan('closed',[$O])" +p "防禦：頂層票沒有任何下游（實務上到不了這裡）→ 不會炸" \ + "('handback', [])" "m.writeback_plan('open',[])" + +echo +echo "── ③ journey_label：只加前綴，不猜名字合不合法 ──" +p "收件匣 → j/收件匣" "j/收件匣" "m.journey_label('收件匣')" +p "已經帶前綴 → 不重複加" "j/收件匣" "m.journey_label('j/收件匣')" +p "前後空白 → 修掉" "j/收件匣" "m.journey_label(' 收件匣 ')" + +echo +echo "── ④ subtask／handoff 的參數閘（該擋）──" +run() { # run <說明> [參數...] + want=$1; what=$2; verb=$3; shift 3 + out=$(TICKET_HOST=http://127.0.0.1:9 GITEA_TOKEN=x \ + python3 "$T" "$verb" inkstone/ISEP#92 "$@" 2>&1) + got=$? + LAST_OUT="$out" + if [ "$got" = "$want" ]; then PASS=$((PASS+1)); printf ' ✅ '; else FAIL=$((FAIL+1)); printf ' ❌ '; fi + printf 'want=%s got=%s %s\n' "$want" "$got" "$what" +} +has() { if printf '%s' "$LAST_OUT" | grep -q "$1"; then PASS=$((PASS+1)); printf ' ✅ ' + else FAIL=$((FAIL+1)); printf ' ❌ '; fi; printf '訊息裡有「%s」 %s\n' "$1" "$2"; } + +run 2 "缺 --title" subtask -F "$TMP/body.md" +run 2 "缺 -F" subtask --title "$TITLE" +run 2 "標題不是 User Story" subtask --title "整理一下票" -F "$TMP/body.md" +run 2 "內文缺模板欄位" subtask --title "$TITLE" -F "$BAD_BODY" +run 2 "指派了人卻沒寫 --next" subtask --title "$TITLE" -F "$TMP/body.md" --assign someone +run 2 "--journey 給了空字串（對不上就不要加這個參數）" \ + subtask --title "$TITLE" -F "$TMP/body.md" --journey "" +has "不硬湊" "空 journey 的訊息講的是「不硬湊」，不是叫人隨便填一個" + +echo +echo "── ⑤ 齊全就放得過（誤攔比漏擋更該修）──" +run 1 "subtask 齊全 → 走到網路才炸" subtask --title "$TITLE" -F "$TMP/body.md" +run 1 "★ handoff 是同一個動作的別名，一樣放得過" handoff --title "$TITLE" -F "$TMP/body.md" --to arcrun-rag +run 1 "帶 --journey 一樣放得過" subtask --title "$TITLE" -F "$TMP/body.md" --journey 收件匣 +run 1 "--assign 有配 --next → 放行" subtask --title "$TITLE" -F "$TMP/body.md" --assign someone --next "先看一眼" + +echo +echo "── ⑥ loose 這個動詞接得上 ──" +out=$(TICKET_HOST=http://127.0.0.1:9 GITEA_TOKEN=x python3 "$T" loose 2>&1); got=$? +if [ "$got" = 1 ]; then PASS=$((PASS+1)); printf ' ✅ '; else FAIL=$((FAIL+1)); printf ' ❌ '; fi +printf 'want=1 got=%s loose 走到網路那一層才炸（動詞有註冊、參數不擋）\n' "$got" + +out=$(python3 "$T" 2>&1) +if printf '%s' "$out" | grep -q "ticket loose"; then PASS=$((PASS+1)); printf ' ✅ ' +else FAIL=$((FAIL+1)); printf ' ❌ '; fi +printf '不帶參數的說明裡列得出 loose（撈不到的東西等於不存在）\n' + +echo +echo "── ⑦ 完工回寫的接線（票上驗收第 2 條）──" +echo " 把 api() 換成錄音機跑一次 _writeback，驗它到底打了哪些端點、送了什麼。" +echo " 不打網路、不動任何真票；/blocks 的回應形狀取自 2026-08-28 實查 inkstone/ISEP#75。" +w() { # w <說明> + got=$(python3 - "$3" <<'PY' 2>&1 +import sys, json, importlib.util as u +from importlib.machinery import SourceFileLoader as L +spec = u.spec_from_loader("t", L("t", "scripts/ticket")) +m = u.module_from_spec(spec); spec.loader.exec_module(m) + +SCEN = json.loads(__import__("os").environ["SCEN"]) +rec = [] +def fake_api(path, payload=None, method=None): + rec.append((method or ("POST" if payload is not None else "GET"), path, payload)) + if path.endswith("/blocks"): + return SCEN["blocks"] + if path.endswith("/dependencies"): + return SCEN["deps"] + if "/labels" in path and (method or "GET") == "GET": + return [{"name": n, "id": i} for i, n in enumerate(SCEN.get("labels", []), 1)] + return {} +m.api = fake_api +# _writeback 會把進度印出來——那是給人看的，不是這支測試的判準。 +# 判準是**它打了哪些端點、送了什麼**（rec），所以把它的輸出吞掉。 +import contextlib, io +buf = io.StringIO() +with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf): + m._writeback("inkstone", "arcrun-rag", 143, "https://example/pr/1") +print(eval(sys.argv[1], {"rec": rec, "m": m})) +PY +) + if [ "$got" = "$2" ]; then PASS=$((PASS+1)); printf ' ✅ '; else FAIL=$((FAIL+1)); printf ' ❌ '; fi + printf 'want=%s got=%s %s\n' "$2" "$got" "$1" +} + +PARENT='{"number":136,"state":"open","title":"頂層票","labels":[{"name":"s/doing"},{"name":"p/high"}],"repository":{"full_name":"inkstone/arcrun-rag"}}' +LBL='["s/todo","s/doing","s/review","p/high"]' + +# 情境 A：這是最後一張下游 → 母票要被指派回總管＋改 s/review +export SCEN="{\"blocks\":[$PARENT],\"deps\":[{\"state\":\"closed\",\"number\":143,\"title\":\"x\",\"repository\":{\"full_name\":\"inkstone/arcrun-rag\"}}],\"labels\":$LBL}" +w "★ 有去問子票的 /blocks（誰在等我）" "True" \ + "any(p.endswith('/issues/143/blocks') for _,p,_ in rec)" +w "★ 有在母票的時間軸貼回寫留言" "True" \ + "any(mm=='POST' and p=='/repos/inkstone/arcrun-rag/issues/136/comments' for mm,p,_ in rec)" +w "★ 留言裡點名了剛關掉的那張下游票" "True" \ + "any('arcrun-rag#143' in (pl or {}).get('body','') for _,p,pl in rec if p.endswith('/136/comments'))" +w "★ 留言裡有交付物連結（不是空口說做完了）" "True" \ + "any('https://example/pr/1' in (pl or {}).get('body','') for _,p,pl in rec if p.endswith('/136/comments'))" +w "★ 留言第一行有身份欄（機器貼的留言一樣要標）" "True" \ + "all((pl or {}).get('body','').startswith('【身份】') for _,p,pl in rec if p.endswith('/136/comments'))" +w "★ 母票被指派回總管（欄位，不是一句話）" "['claude-code']" \ + "[(pl or {}).get('assignees') for mm,p,pl in rec if mm=='PATCH' and p=='/repos/inkstone/arcrun-rag/issues/136'][0]" +w "★ 母票的 s/* 換成 s/review，而非 s/* 的標籤留著" "True" \ + "[sorted(pl['labels'])==sorted([3,4]) for mm,p,pl in rec if mm=='PUT' and p.endswith('/136/labels')][0]" +w "沒有去關母票（關票要有人驗——默默關掉跟默默留著是同一個病）" "False" \ + "any((pl or {}).get('state')=='closed' for _,_,pl in rec)" + +# 情境 B：母票還有別的下游沒關 → 只記一筆，不准指派、不准改 tag +export SCEN="{\"blocks\":[$PARENT],\"deps\":[{\"state\":\"closed\",\"number\":143,\"title\":\"x\",\"repository\":{\"full_name\":\"inkstone/arcrun-rag\"}},{\"state\":\"open\",\"number\":150,\"title\":\"還沒做的\",\"repository\":{\"full_name\":\"inkstone/Arcrun\"}}],\"labels\":$LBL}" +w "還有下游沒關 → 只貼留言，不指派" "False" "any(mm=='PATCH' for mm,_,_ in rec)" +w "還有下游沒關 → 不改 tag" "False" "any(mm=='PUT' for mm,_,_ in rec)" +w "留言裡把還沒關的那張列出來（跨 repo 也要列全稱）" "True" \ + "any('inkstone/Arcrun#150' in (pl or {}).get('body','') for _,p,pl in rec if p.endswith('/136/comments'))" + +# 情境 C：母票自己已經關了 → 完全不動它 +PARENT_CLOSED='{"number":136,"state":"closed","title":"頂層票","labels":[],"repository":{"full_name":"inkstone/arcrun-rag"}}' +export SCEN="{\"blocks\":[$PARENT_CLOSED],\"deps\":[{\"state\":\"closed\",\"number\":143,\"title\":\"x\",\"repository\":{\"full_name\":\"inkstone/arcrun-rag\"}}],\"labels\":$LBL}" +w "母票已關 → 一則留言都不貼（不去吵已關的票）" "False" \ + "any(p.endswith('/136/comments') for _,p,_ in rec)" + +# 情境 D：這張票沒有任何頂層票在等它 → 不要吵 +export SCEN="{\"blocks\":[],\"deps\":[],\"labels\":$LBL}" +w "沒有頂層票在等它 → 只問一次 /blocks 就收工" "1" "len(rec)" +unset SCEN + +echo +echo "── ⑧ 雙向連結的接線（票上驗收第 1 條）──" +echo " 同樣用錄音機跑一次 subtask：驗「兩張票互相看得到對方」不是靠人記得補。" +b() { # b <說明> [額外 argv...] + what=$1; want=$2; frag=$3; shift 3 + got=$(ARGS_JSON=$(printf '%s\n' "$@" | python3 -c "import sys,json;print(json.dumps([l.rstrip('\n') for l in sys.stdin if l.strip()!='']))") \ + python3 - "$frag" <<'PY' 2>&1 +import sys, os, json, contextlib, io, importlib.util as u +from importlib.machinery import SourceFileLoader as L +spec = u.spec_from_loader("t", L("t", "scripts/ticket")) +m = u.module_from_spec(spec); spec.loader.exec_module(m) + +rec = [] +def fake_api(path, payload=None, method=None): + rec.append((method or ("POST" if payload is not None else "GET"), path, payload)) + if path.endswith("/labels?limit=100"): + return [{"name": n, "id": i} for i, n in + enumerate(["s/todo", "s/review", "p/high", "j/收件匣"], 1)] + if path.endswith("/dependencies"): + return [{"state": "open", "number": 900, "title": "子票", + "repository": {"full_name": "inkstone/arcrun-rag"}}] + if path == "/repos/inkstone/ISEP/issues": + return {"number": 900, "html_url": "https://git.uncle6.me/inkstone/ISEP/issues/900"} + if path == "/repos/inkstone/arcrun-rag/issues": + return {"number": 900, "html_url": "https://git.uncle6.me/inkstone/arcrun-rag/issues/900"} + if path == "/repos/inkstone/ISEP/issues/92": + return {"number": 92, "labels": [{"name": "p/high"}]} + return {} +m.api = fake_api +argv = ["inkstone/ISEP#92"] + json.loads(os.environ["ARGS_JSON"]) +buf = io.StringIO() +blocked = False +with contextlib.redirect_stdout(buf), contextlib.redirect_stderr(buf): + try: + m.cmd_subtask(argv) + except SystemExit: + blocked = True # 被閘擋下也是一種結果，不該讓整支測試靜靜掛掉 +print(eval(sys.argv[1], {"rec": rec, "m": m, "blocked": blocked, "buf": buf.getvalue()})) +PY +) + if [ "$got" = "$want" ]; then PASS=$((PASS+1)); printf ' ✅ '; else FAIL=$((FAIL+1)); printf ' ❌ '; fi + printf 'want=%s got=%s %s\n' "$want" "$got" "$what" +} + +A_BASE=(--title "$TITLE" -F "$TMP/body.md" --to arcrun-rag) + +b "★ 子票內文寫著它的頂層票是誰（下游看得到上游）" "True" \ + "any('Parent: inkstone/ISEP#92' in (pl or {}).get('body','') for mm,p,pl in rec if p=='/repos/inkstone/arcrun-rag/issues')" \ + "${A_BASE[@]}" +b "★ 有掛上 Gitea 原生相依（不是只寫在內文裡）" "True" \ + "any(mm=='POST' and p=='/repos/inkstone/ISEP/issues/92/dependencies' for mm,p,pl in rec)" \ + "${A_BASE[@]}" +b "★ 頂層票的時間軸上有一則指向下游的留言（上游看得到下游）" "True" \ + "any('inkstone/arcrun-rag#900' in (pl or {}).get('body','') for mm,p,pl in rec if p=='/repos/inkstone/ISEP/issues/92/comments')" \ + "${A_BASE[@]}" +b "★ 那則留言明講「不會因為轉出去就自動關」（第 2 條的預告）" "True" \ + "any('不會因為轉出去就自動關' in (pl or {}).get('body','') for mm,p,pl in rec if p=='/repos/inkstone/ISEP/issues/92/comments')" \ + "${A_BASE[@]}" +b "沒給 --journey → 留言裡誠實寫「沒有貼」（不硬湊，也不假裝有）" "True" \ + "any('沒有貼' in (pl or {}).get('body','') for mm,p,pl in rec if p=='/repos/inkstone/ISEP/issues/92/comments')" \ + "${A_BASE[@]}" +b "沒給 --journey → 不去動任何一端的標籤軸（只設子票的 s/*）" "1" \ + "len([1 for mm,p,pl in rec if mm=='PUT' and p.endswith('/labels')])" \ + "${A_BASE[@]}" +b "★ 給了 --journey → 母子兩端都被貼（只貼一端就聚不起來）" "2" \ + "len([1 for mm,p,pl in rec if mm=='PUT' and p.endswith('/labels') and 4 in pl['labels']])" \ + "${A_BASE[@]}" --journey 收件匣 +b "★ 貼在頂層票上時保留它原本的標籤（不是整組蓋掉）" "True" \ + "any(mm=='PUT' and p=='/repos/inkstone/ISEP/issues/92/labels' and sorted(pl['labels'])==[3,4] for mm,p,pl in rec)" \ + "${A_BASE[@]}" --journey 收件匣 +b "labels.yaml 沒有的旅程名 → 擋下來（要求標籤在場，不是猜名字合不合法）" "True" \ + "blocked" "${A_BASE[@]}" --journey 沒這條旅程 +b "擋下來時直接指回 labels.yaml（不叫人自己猜怎麼修）" "True" \ + "'labels.yaml' in buf" "${A_BASE[@]}" --journey 沒這條旅程 + +echo +echo "通過 $PASS 條，失敗 $FAIL 條" +[ "$FAIL" = 0 ] || exit 1 diff --git a/scripts/ticket b/scripts/ticket index 6ba4fa6..75e6ffc 100755 --- a/scripts/ticket +++ b/scripts/ticket @@ -21,8 +21,10 @@ leo 2026-08-16 三句話，本工具就是它們的機械化： 三個 Gitea 原生欄位（leo 2026-08-27「這些全部都要」，缺一個就會掉棒）： ticket subtask <母票> --title -F <檔> 討論串裡的一件事 → 看得見的子票＋相依 + ticket handoff <頂層票> --to … 同一個動作，換個名字：頂層 → 下游 repo ticket handback <票> --to <誰> --next <一句> 收工＝指派＋改 tag＋寫下一步，一個動作 ticket mine [--user <誰>] 撈一次：棒子在誰手上、每根下一步是什麼 + ticket loose 撈一次：下游都關了、自己還開著的頂層票 票的寫法：`owner/repo#N`，例：`inkstone/InkStoneCo#44` """ @@ -452,10 +454,87 @@ def cmd_close(argv): if deliv: api(f"/repos/{owner}/{repo}/issues/{num}/comments", - {"body": f"{os.environ.get('ISEP_IDENTITY') or f'【身份】總管／{owner}/{repo}／-'}\n\n✅ 結案。交付物：{deliv}"}) + {"body": f"{_identity(owner, repo)}\n\n✅ 結案。交付物：{deliv}"}) api(f"/repos/{owner}/{repo}/issues/{num}", {"state": "closed"}, method="PATCH") print(f"✅ {owner}/{repo}#{num} 已關（交付物：{deliv or ('PR' if has_pr else '票上回報')}）") + # ── 完工回寫（inkstone/ISEP#92 最痛的那一格）───────────────────────── + # 關掉一張下游票之後，**同一個動作**回頭處理它的頂層票。 + # 不做這件事的後果票上寫得很清楚：「頂層票會永遠掛著，而 leo 是看頂層的」。 + _writeback(owner, repo, num, deliv or ("PR" if has_pr else "票上回報")) + + +def _writeback(owner, repo, num, deliv): + """子票關掉 → 回頭處理每一張在等它的頂層票。 + + 🔴 失敗要吵。回寫悄悄失敗 ＝ 這格等於沒做，而沒有人會發現 + （那正是本票在治的病）。所以任何一張處理失敗就非零離開。 + """ + child = f"{owner}/{repo}#{num}" + try: + parents = _blocks(owner, repo, num) + except SystemExit: + print(f"\n⚠️ 撈不到 {child} 的頂層票（/blocks 讀失敗）——" + f"回寫這一格**沒有做**，請手動確認或跑 `ticket loose`", file=sys.stderr) + sys.exit(1) + + if not parents: + print("\n📌 這張票沒有任何頂層票在等它（沒有相依邊）⇒ 不需要回寫。") + return + + print(f"\n🔗 有 {len(parents)} 張頂層票在等這張票，逐一回寫：") + failed = [] + for pt in parents: + pfull = pt["repository"]["full_name"] + po, pr = pfull.split("/") + pn = pt["number"] + try: + pdeps = _deps(po, pr, pn) + action, open_left = writeback_plan(pt.get("state"), pdeps) + + if action == "skip": + print(f" · {pfull}#{pn}　已經是 closed ⇒ 不動") + continue + + lines = [_identity(po, pr), "", + f"⬇️ **下游完工回寫**：`{child}` 已關（交付物：{deliv}）"] + if open_left: + lines += ["", f"這張票還在等 {len(open_left)} 張下游（都關了才輪到它）："] + lines += [f"- ◻ {i['repository']['full_name']}#{i['number']}　{i['title'][:60]}" + for i in open_left] + lines += ["", "⇒ 本票維持原狀，不要當成可以收了。"] + else: + lines += ["", "**這是最後一張下游——本票的下游已經全部關閉。**", "", + f"{BATON_MARK}　→ `{HANDBACK_TO}`", "", + "**下一步**：驗一次頂層要的東西真的到齊了，到齊就 " + f"`ticket close {pfull}#{pn} --deliverable `；" + "沒到齊就開下一張下游票，不要把它留在原地。", "", + "（本則由 `ticket close` 的完工回寫自動貼上，" + "機制見 `inkstone/ISEP#92`）"] + api(f"/repos/{po}/{pr}/issues/{pn}/comments", {"body": "\n".join(lines)}) + + if action == "handback": + # 指派 ＋ 改 tag：**欄位**才撈得到，留言撈不到。 + # 08-26 那次掉棒就是話有說、欄位沒動，棒子躺在地上 14 小時。 + api(f"/repos/{po}/{pr}/issues/{pn}", + {"assignees": [HANDBACK_TO]}, method="PATCH") + cur = [l["name"] for l in (pt.get("labels") or [])] + keep = [n for n in cur if not n.startswith("s/")] + ["s/review"] + _set_labels(po, pr, pn, keep) + print(f" · {pfull}#{pn}　下游全關 ⇒ 已指派 {HANDBACK_TO}＋s/review（等人驗）") + else: + print(f" · {pfull}#{pn}　還有 {len(open_left)} 張下游沒關 ⇒ 只記一筆") + except SystemExit: + failed.append(f"{pfull}#{pn}") + except Exception as e: + failed.append(f"{pfull}#{pn}（{e}）") + + if failed: + print(f"\n⚠️ 這幾張頂層票**沒有回寫成功**：{'、'.join(failed)}\n" + f" 回寫失敗要吵——悄悄失敗等於這格沒做。手動補，或稍後跑 `ticket loose` 對帳。", + file=sys.stderr) + sys.exit(1) + # ── decide ─────────────────────────────────────────────────────────────── @@ -526,6 +605,10 @@ def cmd_decide(argv): BATON_MARK = "🏃 **棒子交回**" +# 棒子的預設終點：總管。**這是 Gitea 的 assignee 欄位，不是一句話**—— +# 撈「指派給你的」一頁就看得到，撈留言看不到。 +HANDBACK_TO = os.environ.get("ISEP_HANDBACK_TO") or "claude-code" + def _labels_of(owner, repo): return {l["name"]: l["id"] for l in api(f"/repos/{owner}/{repo}/labels?limit=100")} @@ -545,6 +628,97 @@ def _deps(owner, repo, num): return api(f"/repos/{owner}/{repo}/issues/{num}/dependencies") or [] +def _blocks(owner, repo, num): + """反方向：**誰把這張票當相依**——也就是這張票的頂層票（可能不只一張、可能跨 repo）。 + + Gitea 原生兩個端點是同一條邊的兩端，方向不可混淆： + /issues//dependencies 這張票在等誰 → 它的下游 + /issues//blocks 誰在等這張票 → 它的頂層 + `subtask` POST 的是**母票的 dependencies**，所以子票這端看到的是 `blocks`。 + """ + return api(f"/repos/{owner}/{repo}/issues/{num}/blocks") or [] + + +def _identity(owner, repo): + """票上的每一則留言第一行要表明身份（規約見 docs/governance/dispatch-and-reply-format.md §3）。 + + 機器自動貼的留言同樣要標——不標的話，回寫留言看起來像某個人寫的， + 而下一個讀票的人會去找那個人。 + """ + return os.environ.get("ISEP_IDENTITY") or f"【身份】總管／{owner}/{repo}／-" + + +# ══════════════════════════════════════════════════════════════════════════ +# inkstone/ISEP#92 — 「下游做完時頂層跟著關」的三格 +# +# 票上的原話：「開在頂層的票，下游做完了卻沒人回來關⋯⋯頂層票會永遠掛著， +# 而 leo 是看頂層的。」 +# +# 缺的三格，各由下面一段承接： +# ① 雙向連結的強制 → cmd_subtask 一個動作同時掛相依 ＋ 在母票留下指回來的留言 +# ② journey 標籤 → journey_label()（對不上就不貼，不硬湊） +# ③ 完工回寫 → writeback_plan() ＋ cmd_close 關完子票立刻回頭處理母票 +# ④ 撈得出來 → is_loose() ＋ cmd_loose（③ 走側門漏掉的，這張網補回來） +# +# 🔴 這四格的判準**全部是機械事實**（相依邊在不在、state 是什麼）， +# 沒有一格在猜文字。leo 2026-08-17 已證偽關鍵字黑名單那條路 +# （8 次誤攔、0 次正確攔截）。 +# ══════════════════════════════════════════════════════════════════════════ + +JOURNEY_PREFIX = "j/" + + +def journey_label(name): + """`--journey 收件匣` → `j/收件匣`。只加前綴，不做語意判斷。 + + 標籤存不存在由 `_set_labels` 去問 Gitea（不存在就擋，並指回 labels.yaml）—— + **「要求某個東西在場」，不是「猜哪些名字合法」**。 + ⇒ 新的一條旅程要先加進 labels.yaml 再 sync，這是刻意的： + journey 是**跨票聚類的軸**，隨手造名字會讓同一條旅程長出三個拼法。 + """ + n = (name or "").strip() + if not n: + die("🚫 --journey 後面要接旅程名（例：--journey 收件匣）。\n" + " 對不上任何旅程就**不要加這個參數**——票上明講不硬湊。") + return n if n.startswith(JOURNEY_PREFIX) else JOURNEY_PREFIX + n + + +def is_loose(state, deps): + """這張票是不是「下游都關了、自己還開著」的頂層票。 + + 純函式（不打網路）⇒ 判準本身測得動，不必開真的票來驗。 + + 三個條件缺一不可： + · 自己還 open 關掉的票不用管 + · 曾經有下游 沒有相依邊 ⇒ 它根本不是頂層票，不要拿它來吵 + · 沒有任何 open 下游 有一張還開著就還在跑，不是掉在地上 + """ + if state != "open": + return False + if not deps: + return False + return not any(d.get("state") == "open" for d in deps) + + +def writeback_plan(parent_state, parent_deps): + """下游關掉之後，它的頂層票該被怎麼處理。**只回計畫，不做副作用**⇒ 離線測得動。 + + 回 (動作, 還開著的下游)： + "skip" 頂層票自己已經關了 ⇒ 沒事 + "note" 還有別的下游沒關 ⇒ 只在頂層票記一筆，別假裝它可以收了 + "handback" 下游全關了 ⇒ 這張票現在**只等人驗**： + 指派回總管 ＋ s/review，讓它出現在「指派給你的」 + + 🔴 為什麼不自動關母票：關票要有交付物、要有人看過（`ticket close` 的既有閘）。 + 票上要的是「不能默默留著」，不是「自動消失」—— + 默默關掉跟默默留著是同一個病的兩面。 + """ + open_left = [d for d in (parent_deps or []) if d.get("state") == "open"] + if parent_state != "open": + return "skip", open_left + return ("note" if open_left else "handback"), open_left + + # ── subtask ────────────────────────────────────────────────────────────── def cmd_subtask(argv): """把「討論串裡的一件事」長成看得見的子票，並掛成母票的 Gitea 原生相依。 @@ -565,7 +739,9 @@ def cmd_subtask(argv): if len(argv) < 1: die("用法：ticket subtask <母票 owner/repo#N> --title \"\" -F <內文檔>\n" " [--repo <收件 repo，預設跟母票同一個>] [--label ]\n" - " [--assign <誰做> --next \"<他第一件事要做什麼>\"]　← 指派了就一定要寫下一步") + " [--journey <旅程名>]　← 這件事服務哪條使用者旅程（對不上就不要加）\n" + " [--assign <誰做> --next \"<他第一件事要做什麼>\"]　← 指派了就一定要寫下一步\n" + "\n（`ticket handoff` 是同一個動作的別名：頂層票 → 下游 repo）") powner, prepo, pnum = parse_ref(argv[0]) def opt(name, default=None): @@ -585,10 +761,13 @@ def cmd_subtask(argv): " leo 2026-08-27：『每個事情沒有歷史記錄才是大問題』，\n" " 而沒寫驗收條件的票，關掉之後就沒有歷史，只剩一個關字）") - repo = opt("--repo", prepo) + # `--to ` 是 `ticket handoff` 那個名字底下比較自然的講法，同一個東西。 + # （handback 的 `--to` 是「交給誰」，subtask 沒有那個參數，不會撞。） + repo = opt("--repo", opt("--to", prepo)) label = opt("--label", "s/todo") assign = opt("--assign") nxt = opt("--next") + jlabel = journey_label(opt("--journey")) if "--journey" in argv else None if assign and not nxt: die("🚫 指派了人卻沒寫 --next。\n" " **有人被指到這張票，他撈到它的第一件事就是問「所以我要做什麼」**——\n" @@ -597,7 +776,8 @@ def cmd_subtask(argv): body = (f"Parent: {powner}/{prepo}#{pnum}\n" f"> 這張票是從母票的討論串裡長出來的一件事。\n" - f"> **它沒關，母票關不掉**（Gitea 原生相依，實測 412 硬擋）。\n\n") + body + f"> **它沒關，母票關不掉**（Gitea 原生相依，實測 412 硬擋）。\n" + f"> **它關掉時，母票會收到一則回寫**（`ticket close` 自動做，見 `inkstone/ISEP#92`）。\n\n") + body d = api(f"/repos/{ORG}/{repo}/issues", {"title": title, "body": body}) cnum = d["number"] @@ -619,6 +799,38 @@ def cmd_subtask(argv): deps = _deps(powner, prepo, pnum) openn = [i for i in deps if i["state"] == "open"] print(f" 相依：已掛上 {powner}/{prepo}#{pnum}（它存在、且擋著母票）") + + # 🔴 雙向連結：相依邊只長在 Gitea 的側欄，**母票的時間軸上什麼都沒有**。 + # 票上的原話：「頂層票寫了『轉去某個 repo』，但那邊的票沒有指回來， + # 從下游那張票看不出它從哪來，脈絡就斷了。」 + # ⇒ 兩端各留一個看得見的指標：子票內文的 `Parent:`（上面），母票時間軸的這一則。 + # 跨 repo 時尤其重要——側欄的相依很容易被當成同 repo 的東西。 + plines = [_identity(powner, prepo), "", + f"➡️ **已轉往下游**：`{ORG}/{repo}#{cnum}`　{title}", "", + f"{d['html_url']}", "", + f"- 收件 repo：`{ORG}/{repo}`　tag：`{label}`" + + (f"　旅程：`{jlabel}`" if jlabel else "") + + (f"　指派：`{assign}`" if assign else "　（還沒指派，留在票池等人領）")] + if jlabel is None: + plines += ["- 旅程：**沒有貼**（開票時判定對不上任何一條，不硬湊）"] + plines += ["", + "**這張頂層票不會因為轉出去就自動關**——下游那張關掉時，" + "`ticket close` 會回頭在這裡貼一則回寫；" + "全部下游關完，這張票會被指派回總管等驗。（機制：`inkstone/ISEP#92`）"] + api(f"/repos/{powner}/{prepo}/issues/{pnum}/comments", {"body": "\n".join(plines)}) + print(f" 回指：已在母票 {powner}/{prepo}#{pnum} 的時間軸貼上指向子票的留言") + + # journey 標籤：兩端都貼，聚類才聚得起來（只貼一端＝撈不到另一端） + if jlabel: + _set_labels(ORG, repo, cnum, [label, jlabel]) + pcur = [l["name"] for l in (api(f"/repos/{powner}/{prepo}/issues/{pnum}") + .get("labels") or [])] + if jlabel not in pcur: + _set_labels(powner, prepo, pnum, pcur + [jlabel]) + print(f" 旅程：`{jlabel}`（母子兩端都貼——只貼一端就聚不起來）") + else: + print(" 旅程：沒有貼（沒給 --journey）。對得上就補一次：" + f"`ticket subtask … --journey <旅程名>`；對不上就不要硬湊。") print(f"\n📌 母票 {powner}/{prepo}#{pnum} 目前有 {len(openn)} 張未關的相依：") for i in deps: mark = "◻" if i["state"] == "open" else "☑" @@ -747,9 +959,86 @@ def _last_next(owner, repo, num): return None +# ── loose ──────────────────────────────────────────────────────────────── +def cmd_loose(argv): + """撈一次：**下游都關了、自己還開著**的頂層票。 + + 票上的驗收條件第 3、4 條（`inkstone/ISEP#92`）： + 「撈一次『已經沒有 open 下游票、但自己還開著的頂層票』→ 要撈得出來（現在撈不出來）」 + 「拿現有的頂層票跑一次 → 要能指出哪幾張是這種情況」 + + 這是 `ticket close` 自動回寫的**補網**：回寫只在走正門（`ticket close`）時發生， + 而關票的側門（直接 PATCH `state=closed`）是刻意放行的 + （見 `hooks/ticket-api-bypass-guard.sh`：「帶了 ID 的子路徑」一律放行）。 + ⇒ 側門漏掉的，由這張網撈回來。**不是輪詢**——掛在開場／收工對帳跑一次。 + """ + def opt(name, default=None): + return argv[argv.index(name) + 1] if name in argv else default + + org = opt("--org", ORG) + only = opt("--repo") + + print(f"🔎 掃 `{org}` 的 open 票，找「下游都關了、自己還開著」的頂層票" + + (f"（只看 {only}）" if only else "") + " …") + + items, page = [], 1 + while page <= 12: + q = urllib.parse.urlencode({"state": "open", "type": "issues", + "limit": 50, "page": page, "owner": org}) + got = api(f"/repos/issues/search?{q}") or [] + if not got: + break + items += got + page += 1 + if only: + items = [i for i in items if i["repository"]["full_name"].split("/")[-1] == only] + print(f" open 票 {len(items)} 張，逐張問它的下游 …") + + def probe(it): + full = it["repository"]["full_name"] + o, r = full.split("/") + try: + deps = _deps(o, r, it["number"]) + except SystemExit: + return None # 讀不到 ≠ 沒有下游；寧可漏報也不要編一筆出來 + except Exception: + return None + return (full, it, deps) + + from concurrent.futures import ThreadPoolExecutor + with ThreadPoolExecutor(max_workers=12) as ex: + probed = [x for x in ex.map(probe, items) if x] + + parents = [x for x in probed if x[2]] + loose = [x for x in parents if is_loose("open", x[2])] + + print(f"\n 有下游相依的頂層票：{len(parents)} 張") + print(f" 其中「下游都關了、自己還開著」：**{len(loose)} 張**\n") + + if not loose: + print("✅ 一張都沒有——每張頂層票都還有下游在跑，或已經跟著關了。") + for full, it, deps in loose: + n = it["number"] + st = [l["name"] for l in it.get("labels") or []] + who = [a["login"] for a in (it.get("assignees") or [])] or ["（沒有人）"] + print(f" ● {full}#{n}　{st}　指派：{'、'.join(who)}") + print(f" {it['title'][:64]}") + for d in deps: + print(f" ☑ {d['repository']['full_name']}#{d['number']}" + f"　{d['title'][:52]}") + print(f" → 驗過就關：ticket close {full}#{n} --deliverable ") + print(f" 還缺東西：ticket subtask {full}#{n} --title \"\" -F <檔>") + print() + + print("📌 這張表撈的是**機械事實**（相依邊的 state），不是猜文字。") + print(" 走 `ticket close` 關下游時會自動回寫、這張表就不會長；") + print(" 會長出來的都是走側門關掉的那些。") + return loose + + CMDS = {"where": cmd_where, "say": cmd_say, "new": cmd_new, "close": cmd_close, - "decide": cmd_decide, "subtask": cmd_subtask, "handback": cmd_handback, - "mine": cmd_mine} + "decide": cmd_decide, "subtask": cmd_subtask, "handoff": cmd_subtask, + "handback": cmd_handback, "mine": cmd_mine, "loose": cmd_loose} if __name__ == "__main__": if len(sys.argv) < 2 or sys.argv[1] not in CMDS: