ISEP/docs/governance/_draft-claude-ai-v0.5.0.md

📦 這是原稿存檔，不是現行規範。 由 claude.ai 於 2026-08-20 寫成（v0.5.0 draft），leo 交給總管落地。 現行規範是同目錄的 sdd-gitea-governance.md（v0.6.0）， 兩者的逐條分歧與理由寫在 DIVERGENCE-v0.5.0-to-v0.6.0.md。

保留原稿的理由：它的物件模型與封路哲學是這套治理的骨架， 修訂版只動「與現場實況對不上」的部分。要追某條規則的來歷，看這裡。

---

SDD × Gitea 治理規範

version: 0.5.0 status: draft(本文件自身的修改依 §9 走 issue) scope: 適用於所有安裝本 plugin 的環境(地端 CC 與雲端薄殼) distribution: 本規範隨治理 plugin 發佈,plugin repo 為唯一編輯點(§11)

---

0. 公理

1. 意圖真相在 SDD,狀態真相在 Gitea,知識真相在 Wiki。 時態分工:SDD 未來式、Gitea 現在式、Wiki 過去式(§12)。禁止交叉寫入。
2. Issue 是唯一任務介面。 任何工作不經 issue 不得開始。issue = spec,PR = deliverable,release = 交付原子單位。
3. 封路優於守規。 凡可結構性擋掉的違規路徑,不依賴代理或人的自律。
4. 兩軸正交。 Tracking issue 管 scope 軸,milestone 管 time 軸。
5. 治理本體只有一份。 封裝於治理 plugin;地端與雲端皆為安裝目標,不是編輯目標(§11)。
6. 審核不是任務,是路徑。 審核 = review PR 並 merge,為交付唯一必經動作(§3.0)。
7. 人是特殊 executor。 人的兩種介入——審核者(gate/human)與執行者(exec/human)——分別建模;人執票走同一狀態機,派工通道為 Telegram(§6)。

---

1. 物件模型(五層 + 一橫切)

SDD 文件(docs/)
  └─ Tracking issue(label: hub)          ← scope 軸
       └─ Leaf issue                      ← 最小工作單位
            └─ PR(closes #n)             ← deliverable
                 └─ Release tag           ← 交付原子單位

Milestone ──────────────────────────────  ← time 軸,橫切上樹

物件	職責	明確不做
SDD 文件	意圖、範圍、非目標、驗收哲學、驗收腳本位置	不含 leaf task、不記進度
Tracking issue	scope 聚合、討論容器、驗收閘	不掛 milestone、不直接對應 PR
Leaf issue	一個 PR 的 spec(或一個人執動作,§6.2)	不再拆子票(要拆=升格,§5.5)
Milestone	一個可測試版本的 timebox	不承載討論、不表達語意分組
PR	實作 + 測試,merge 時自動關 leaf	不手動關票
Release	milestone 關閉時打 tag	—

---

2. 連結規則

• R2.1 SDD 的 tasks/journey 段落只連 tracking issue,禁止連 leaf。
• R2.2 每張 leaf 必屬恰好一個 tracking issue(task list 登記 + leaf 首行回鏈 Parent: #n)。
• R2.3 每張 leaf 最多屬一個 milestone。未排程 = 不掛(即 backlog)。
• R2.4 Tracking issue 不掛 milestone。其子票可分屬多個 milestone。
• R2.5 順序關係一律用 Gitea 原生 dependency,禁止只寫文字。

---

3. 完成語意與票的狀態機

3.0 狀態機(每個轉移 = 一個可 hook 的 API 動作)

s/todo ──領票──▶ s/doing ──完成──▶ s/review ──總管 merge──▶ closed
         (executor              (開 PR +              (closes #n
          self-assign            轉 label)             自動關票)
          + 轉 label)

• S3.0.1(領票) Executor(subagent 或人)領任務 = self-assign + 轉 s/doing。禁止留言認領——留言不改變狀態。
• S3.0.2(完成) 宣告完成 = 開 PR(含 closes #n)+ 轉 s/review。留言說做完不構成完成。(人執票例外見 §6.2)
• S3.0.3(審核) 總管審核 = review PR 並 merge,merge 即自動關票。審核沒有其他形式,也沒有獨立審核票。
• S3.0.4 審核不通過:PR request changes,票退回 s/doing,續作。禁止關 PR 重開新票(保留審核軌跡)。

3.1–3.3 完成語意

• D3.1 Leaf 關閉 = local_done。唯一觸發:PR merge 且含 closes #n(人執票例外 §6.2)。禁止手動關閉(例外見 §5、§6.2)。
• D3.2 Tracking issue 關閉 = path_done:(1) 子票全關(必要);(2) SDD 驗收腳本通過(充分);(3) gate/human 已放行。
• D3.3 子票全關但驗收未過:tracking 保持開啟,開新 leaf 修復掛回。禁止「先關再說」。

---

4. Milestone 規則(= sprint = 可測試版本)

• M4.1 命名 vX.Y,必設 due date。
• M4.2 Deliverable:所有掛入 leaf 關閉後,可從預設分支打出通過驗收腳本的版本。
• M4.3 Timebox 不可延長。 到期:強制關閉 → 未完成 leaf 搬下一 milestone → 打 tag(即使 scope 縮水)。排程 job 執行。
• M4.4 Milestone 關閉 = release tag,一對一。「已交付」唯一合法形式是 tag 存在;打 tag 前置 open issues = 0(E12)。
• M4.5 Description 只寫版本目標一句 + tracking 連結。討論回 tracking issue。

---

5. Issue 關閉分類(taxonomy)

關閉必掛恰好一個 close/*:

Label	語意	關閉者
close/merged	PR merge 自動關	系統
close/human-exec	人執票完成,人手動關(§6.2)	人
close/duplicate	重複,指向舊票(新關舊留)	人或代理
close/wontfix	討論後不做	人
close/stale	逾期無資訊	排程 job
close/split	拆分後關(§5.5)	人
close/transferred	屬別的 repo	人或代理

• C5.5(拆分) (a) 升格 tracking(加 hub)或 (b) 關閉掛 close/split,子票掛原 parent。
• C5.6 close/wontfix 只有人可執行。代理只能提議。

---

6. 人的兩種介入(gate/human 與 exec/human)

6.1 gate/human——人是審核者(overlay)

• H6.1.1 gate/human + assignee = richblack:工作由代理完成,人只放行或否決。
• H6.1.2 代理不得關閉帶此標籤的 issue、不得 merge 帶此標籤的 PR(hook + Gitea 權限雙重擋)。
• H6.1.3 只有人可移除標籤;移除即放行。
• H6.1.4 必設節點(可增不可減):tracking issue 關閉前、close/wontfix、milestone 建立與 scope 圈選、治理 plugin 修改 PR、部署至 prod 的 PR。

6.2 exec/human——人是執行者(票的屬性)

• H6.2.1 當 deliverable 所需的「tool」只有人擁有(GUI-only 設定、實體權限開通、法定簽署),票掛 exec/human + assignee = richblack。人視為一個特殊 subagent,走 §3.0 同一狀態機。
• H6.2.2 人執票的 deliverable 是環境狀態改變,不是 PR。完成方式:人在票上留 [decision] 已完成:做了什麼 → 人手動關票,系統自動掛 close/human-exec(此為 E3 唯一合法的手動關票路徑,hook 放行條件:label 含 exec/human 且操作者為人)。
• H6.2.3 驗證不靠自述:人執票通常是下游票的 dependency;關票解鎖後,接手代理執行時若設定未生效會 fail fast——下游失敗即自動 reopen 人執票並重新通知。有驗收腳本者,orchestrator 於關票後立即執行驗證。
• H6.2.4 代理判定「這件事我做不到、只有人能做」時:開 exec/human 票 + 設好 dependency + 觸發通知,然後繼續做不被 block 的其他票,不空轉等待。

6.3 Telegram 通知(人閘的開路配套)

• H6.3.1 觸發:gate/human 或 exec/human 被掛上且 assignee = richblack 時,hook 即時發 Telegram(走小六 bot 通道)。
• H6.3.2 訊息格式(BLUF,與 §10.2 同構):

🔔 #123 需要你|[gate] 或 [exec]
一句話:這張票要你做什麼(≤40 字)
動作:review PR #45 並 merge / 到 CF 後台開啟 X 權限
卡誰:此票 block 了 #124 #125
連結:https://git.uncle6.me/...

• H6.3.3 節流:同票同狀態只通知一次;24 小時未處理提醒一次;之後併入每日 digest(一則彙總所有 pending 人閘),不轟炸。
• H6.3.4 E13 的 orchestrator 連續 block 升級、E12 的交付被擋,同走此通道。
• H6.3.5 通知是投影不是狀態:Telegram 訊息遺失不影響治理正確性,真相永遠在 Gitea 票上(單向依賴,同 §12.4)。

---

7. 討論路由(社群模式相容)

新 issue → 討論 →
  ├─ 可做,獨立     → 掛入 tracking,排 milestone → 走 §3
  ├─ 可做,有依賴   → 同上 + dependency(§2.5)
  ├─ 只有人能做     → 掛 exec/human + dependency + 通知(§6.2)
  ├─ 重複           → close/duplicate
  ├─ 不做           → close/wontfix(人閘)
  ├─ 太大           → 升格 hub 或拆分(§5.5)
  └─ 走錯棚         → close/transferred

多票收斂:建 tracking issue(scope),不是直接建 milestone。當且僅當「這批票 = 恰好一個可出貨版本」才同時建 milestone,tracking 保留作討論與驗收容器。

---

8. 封路清單(結構性強制)

#	封什麼路	用什麼封
E1	直接 push 預設分支	branch protection: PR-only
E2	PR 不關聯 issue	PR 模板必含 closes #,CI 缺漏即 fail
E3	手動關 leaf	hook 攔截;僅放行 close/* 例外與 §6.2 人執路徑(exec/human + 操作者為人)
E4	被 block 的票先關	Gitea issue dependency 開啟
E5	Milestone 延期	排程 job:到期自動關 + 搬票 + 打 tag
E6	代理越過人閘	PreToolUse hook + orchestrator token 無 code write 權限
E7	SDD 內出現 leaf 連結	pre-commit lint
E8	Tracking issue 掛 milestone	排程 job 摘除並告警
E9	留言不合格式或超長	hook:首行不匹配 `^[(decision
E10	就地修改治理檔案	安裝目錄唯讀 + hook,導向 plugin repo 開 issue
E11	地端雲端版本漂移	SessionStart hook 比對 manifest,不一致 fail-fast
E12	宣稱交付但票未關	release tag / 關 milestone hook:open issues > 0 即 reject,列出未關票號,同步 Telegram
E13	審核被遺忘	Orchestrator Stop hook:s/review 佇列非空即 block stop;連續 block 逾 N 次 → gate/human + Telegram 升級
E14	Subagent 空口宣稱完成	SubagentStop hook:領票須處於 s/review 且掛含 closes #n 的 PR,否則回報「未達交付態」
E15	代理硬做只有人能做的事	對 GUI-only / 憑證外資源的操作路徑,代理端無對應 tool 或 token;唯一出口是開 exec/human 票(§6.2.4)
E16	標籤漂移(repo 標籤與規範不符)	排程 job 走 Gitea labels API,依 plugin labels.yaml 校正所有受治理 repo:缺的補、改的還原、多的告警;不依賴模板檔與重啟(§11.4)

---

9. 本規範的迭代

• 存於治理 plugin repo docs/;各環境為唯讀安裝副本。
• 修改:plugin repo 開 leaf(掛 governance tracking)→ PR → gate/human → merge → release → 各端升級。
• 版本:規則增刪 = minor,措辭 = patch,公理 = major。plugin 版本 = 規範版本。
• 每次 milestone 回顧:規範有無被繞過?有 → 補 §8,不加「請遵守」。

---

10. 留言規範

10.1 OP 唯一狀態原則

• OP 是票的唯一狀態容器,持續編輯;留言是 append-only 稽核 log,只記 delta。了解一張票只讀 OP。
• 討論收斂即寫回 OP,留言留 [decision] 已更新 OP:改了 X,因為 Y。

10.2 留言格式(BLUF + 類型標籤,全文 ≤ 600 字元)

[類型] 一句話結論(≤40 字)

理由:
- (最多 3 個 bullet,每個 ≤ 1 行)

下一步: (一行,或「無」)
詳細: (連結至 PR / commit / wiki,禁止貼內文)

類型枚舉:decision question blocker progress proposal。 能用 OP task list 打勾表達的進度不留言;重大 proposal 加掛 gate/human。

10.3 推理軌跡出口

推理、嘗試、失敗分析走 wiki-capture 進 Wiki/KBDB,留言以 詳細: 指向。推理進 wiki,結論進留言,留言只帶指標。

---

11. 治理 Plugin(單點分發與同步)

11.1 結構

governance-plugin/
├── docs/sdd-gitea-governance.md
├── labels.yaml       # 標籤唯一真相(§11.4)
├── hooks/            # E1–E16
├── templates/        # issue / PR / 留言 / Telegram 通知模板
├── jobs/             # E5 / E8 / E16 / stale / digest
├── manifest.json     # 版本 + checksum + shell-safe 清單
└── install.sh

11.2 分發規則

• P11.2.1 地端與雲端安裝同一個 release;來源只有 plugin repo release tag。
• P11.2.2 治理修改只發生在 plugin repo;執行環境發現需調整 → 去 plugin repo 開 issue(E10)。
• P11.2.3 Session 啟動比對 manifest(E11);不一致 fail-fast,不降級執行。
• P11.2.4 升級是原子動作:整包替換,禁止 cherry-pick。
• P11.2.5 薄殼只裝 manifest 標記 shell-safe 的子集;薄殼不自行決定。

11.3 與既有 plugin 收斂

治理規則集中本 plugin;各專案 dispatch/harness hook 一律 import 本 plugin,不得複製(複製即 fork,fork 即漂移)。

11.4 標籤分發(labels.yaml)

• P11.4.1(唯一真相) 全部標籤定義(名稱、顏色、描述、exclusive)只存在於 plugin repo 的 labels.yaml。本規範附錄與 Gitea 上所見皆為投影;修改標籤 = 修改 labels.yaml,走 §9 流程。
• P11.4.2(雙通道分發) 同一份 labels.yaml 走兩條通道:
  1. 模板通道(便利,弱):install/升級時部署至 Gitea 伺服器 $GITEA_CUSTOM/options/label/governance.yaml,供建新 repo 時 GUI 一鍵播種。此通道生效需重啟 Gitea,且僅為一次性播種,不校正既有 repo。
  2. API 通道(真相,強):排程 job(E16)走 labels API 掃所有受治理 repo,依 labels.yaml 校正——缺的補、改的還原、多出的非規範標籤留言告警(不自動刪,避免誤殺專案自用標籤)。不需重啟,對既有 repo 立即生效。
• P11.4.3(依賴方向) 正確性只依賴 API 通道。忘記重啟的後果僅是「建新 repo 的 GUI 下拉是舊版」,而新 repo 納入治理後第一次 E16 掃描即被校正——模板通道壞掉不影響治理正確性(同 §12.4 單向依賴)。
• P11.4.4(升級程序) plugin release 若含 labels.yaml 變更,install.sh 依序執行:(1) 部署模板檔;(2) 重啟 Gitea(systemctl restart gitea,寫在腳本裡,不靠人記得);(3) 立即觸發一次 E16 全量 sync;(4) 驗證:抽查一個 repo 的標籤集與 labels.yaml 一致才回報升級成功。
• P11.4.5(平台級不變量) s/* 與 close/* 一律 exclusive: true:同 scope 同票至多一個標籤,由 Gitea 平台保證(轉移時自動摘除舊標籤)。狀態唯一性與關閉分類唯一性因此無需 hook 維護——非法狀態不可表示。

---

12. 書寫路由(SDD × Gitea × Wiki)

12.1 時態原則

載體	時態	回答的問題	變動頻率	寫入者
SDD	未來式	要做什麼、為什麼、怎樣算完成	低(人閘審)	人(代理僅提案)
Gitea	現在式	誰在做、做到哪、卡在哪、順序	高(狀態機)	人與代理
Wiki	過去式	怎麼想、試過什麼、學到什麼	append-only	主要是代理

12.2 路由判準(寫之前問一句:這段內容改變的是什麼?)

• 「要做什麼」(範圍、驗收、非目標)→ SDD,必經 issue + 人閘(改意圖 = 改合約)
• 「現在狀態」(認領、進度、卡點、定案)→ Gitea(OP 或合規留言)
• 「我們知道什麼」(推理、失敗、可復用教訓)→ Wiki

12.3 典型錯置與矯正

錯置	矯正
SDD 長出 task 清單、進度勾選	移至 Gitea;E7 攔截
Issue 留言寫滿推理長文	移至 Wiki 留指標;E9 攔截
Wiki 記錄「目前進度」	刪除;進度只存在於 Gitea。Wiki 引用票寫「當時」
Issue OP 修改驗收標準	退回:先開 SDD 修改 issue(人閘),定案後 OP 才同步
代理直接編輯 SDD	SDD 目錄對代理唯讀,提案走 issue

12.4 連結方向(單向依賴)

SDD → 只連 tracking(R2.1)。Gitea → 可連 SDD 錨點與 wiki。Wiki → 可連票號與 commit,皆為歷史快照語意。Telegram 通知 → 純投影(H6.3.5)。Wiki 壞不影響 Gitea,Gitea 壞不影響 SDD,通知丟不影響一切。

---

附:Label 全集(快照;唯一真相為 plugin labels.yaml,§11.4)

hub                        # tracking issue 標記
s/todo s/doing s/review    # 狀態機三態(Stage,§3.0),exclusive;closed 為系統態
gate/human                 # 人是審核者(§6.1)
exec/human                 # 人是執行者(§6.2)
close/*                    # 七種關閉分類(§5),exclusive
type/*                     # type/bug type/feature type/governance

本附錄不逐項列 close/*,以免與 labels.yaml 形成第二份清單而漂移。