> 📦 **這是原稿存檔，不是現行規範。** > 由 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|question|blocker|progress|proposal)\]` 或 > 600 字元 reject;同票同 session > 3 則 reject | | 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 形成第二份清單而漂移。