awoooi/docs/security/SOURCE-CONTROL-PRIMARY-ROLLBACK-ADR.md

GitHub Primary Rollback ADR 草案

項目	內容
日期	2026-06-04
狀態	草案與 P1-5 rollback owner handoff 已整理，等待 owner review
Schema	docs/schemas/source_control_primary_rollback_adr_v1.schema.json
Snapshot	docs/security/source-control-primary-rollback-adr.snapshot.json
模式	rollback_adr_only
runtime 執行授權	false

0. 核心結論

S4.4 補上 GitHub primary cutover 前必備的 rollback ADR 草案。2026-06-04 P1-5 再把逐 repo rollback owner handoff 補齊，讓 owner 可以用同一套欄位回覆 fallback 角色、trigger、1h / 24h 驗證窗口與 follow-up owner。

這不是 cutover plan，也不是 rollback 執行計畫。它只定義：每個 repo 在未來要切 GitHub primary 前，必須先有什麼 evidence、誰是 rollback owner、哪些狀況要停下來、以及切換後 1 小時 / 24 小時要看什麼。

目前 owner_approved_count=0、rollback_owner_response_received_count=0、rollback_owner_response_accepted_count=0、dry_run_completed_count=0、active_cutover_count=0，所以 primary_ready_count 仍必須維持 0。

1. 摘要

指標	數量
Candidate repos	8
In-scope repos	7
External scope review	1
Repo rollback plan drafts	7
Owner approved	0
Dry-run completed	0
Active cutover	0
P1-5 rollback owner handoff package	ready
Handoff completion	100%
Handoff preflight checks	6
Handoff packet fields	11
Rollback owner response received / accepted / rejected	0 / 0 / 0
Rollback owner request dispatch authorized	false
Rollback execution authorized	false
GitHub primary switch authorized	false
Gitea disable authorized	false

1.0 2026-06-04 P1-5 Primary Rollback Owner Handoff

本段把 S4.4 從「rollback ADR 草案已存在」推到「7 個 in-scope repo 的 rollback owner / fallback / trigger / validation window 可交接請 owner 回覆」。這是 handoff readiness，不是 request sent、不是 owner response received、不是 owner approval、不是 dry-run，也不是 GitHub primary cutover 或 rollback 執行批准。

指標	值
P1-5 handoff package	ready
handoff completion	100%
repo templates	7
preflight checks	6
handoff packet fields	11
request dispatch authorized	false
rollback owner response received	0
rollback owner response accepted	0
rollback owner response rejected	0
owner approved	0
dry-run completed	0
active cutover	0
GitHub primary switch authorized	false

1.0.1 送件前檢查

順序	檢查項	完成條件	目前狀態
1	source-control 基線同步	送件前確認 gitea/main、P1-2、P1-3、P1-4 與 S4.13 最新狀態	已定義，未送件
2	七個 in-scope repo	只向 7 個 in-scope repo 收 rollback owner / fallback / trigger / validation 回覆	已定義，未送件
3	fallback 角色保留	回覆必須確認 Gitea 或現行來源仍保留 fallback 角色	已定義，未送件
4	validation window 對齊	每個 repo 必須對應 pre-cutover、1h、24h 三個驗證窗口	已定義，未送件
5	metadata only	只收 owner role/team、決策理由、脫敏 evidence ref 與 follow-up owner	已定義，未送件
6	執行要求拒收	primary switch、rollback execution、refs sync、workflow / secret 變更與 Gitea disable 全部 hard reject	已定義，未送件

1.0.2 交接封套欄位

欄位	內容規則
request_id	p1_5_primary_rollback_owner_handoff
stage_id	S4.4
prerequisite_gates	S4.9、P1-2、P1-3、P1-4、S4.13 只讀 handoff / validation rollup
requested_repo_templates	awoooi、clawbot-v5、wooo-aiops、wooo-infra-config、ewoooc、bitan-pharmacy、tsenyang-website
recipient_role_or_team	只填 repo owner / release owner / fallback owner 的角色或團隊，不收個人 credential
required_response_fields	owner role/team、decision、decision reason、fallback role confirmation、rollback trigger scope、validation window owner、redacted evidence refs、followup owner
validation_window_refs	pre_cutover_freeze_review、post_cutover_one_hour_observe、post_cutover_twenty_four_hour_review
allowed_evidence_refs	只引用 repo 內文件、snapshot、decision record id 或脫敏 metadata pointer
forbidden_inputs	token、secret、private key、runner token、webhook secret、repo write instruction、refs sync/delete instruction、primary switch、rollback execution、Gitea disable、active scan 或 host maintenance request
not_approval	必須為 true
request_dispatch_authorized	必須為 false，除非另有人工送件批准與 audit evidence

1.0.3 七個 repo response template

Repo	需要 owner 回覆	驗證窗口	目前狀態
owenhytsai/awoooi	rollback owner、fallback role、trigger、validation owner、脫敏 evidence refs	pre-cutover / 1h / 24h	waiting owner response
owenhytsai/clawbot-v5	rollback owner、fallback role、trigger、validation owner、脫敏 evidence refs	pre-cutover / 1h / 24h	waiting owner response
owenhytsai/wooo-aiops	rollback owner、fallback role、trigger、validation owner、脫敏 evidence refs	pre-cutover / 1h / 24h	waiting owner response
owenhytsai/wooo-infra-config	rollback owner、fallback role、trigger、validation owner、脫敏 evidence refs	pre-cutover / 1h / 24h	waiting owner response
owenhytsai/ewoooc	rollback owner、fallback role、trigger、validation owner、脫敏 evidence refs	pre-cutover / 1h / 24h	waiting owner response
owenhytsai/bitan-pharmacy	rollback owner、fallback role、trigger、validation owner、脫敏 evidence refs	pre-cutover / 1h / 24h	waiting owner response
owenhytsai/tsenyang-website	rollback owner、fallback role、trigger、validation owner、脫敏 evidence refs	pre-cutover / 1h / 24h	waiting owner response

1.0.4 送件後不變條件

即使後續 owner 實際回覆，也只能先進 intake preflight 與 reviewer validation。通過後可更新 read-only rollback ADR、primary readiness blocker wording、approval board 與 status rollup；不得直接切 GitHub primary、執行 rollback、sync / delete refs、force push、改 workflow / secret、啟用 runner、停用 Gitea、改主機或觸發 active scan。

2. Rollback 原則

1. GitHub primary 是長期方向，但每個 repo 必須先有 owner-approved rollback plan 才能進入 cutover review。
2. Gitea 在 cutover 前後都必須保留為本地 mirror / fallback，不得因 GitHub primary 準備而停用、刪除或封存。
3. Rollback ADR 只定義人工決策、驗證窗口與回退條件；不授權任何 refs sync、primary switch 或 webhook 修改。
4. 任何回退都必須有新的 runtime gate、人工批准與 evidence snapshot，不得由本 ADR 自動觸發。
5. 初期只做 observe / approval_required，不把缺 LOW / MEDIUM evidence 變成 production blocker。

3. 切換前必要 Gate

Gate	目前狀態	必要 evidence
Gitea authenticated inventory	blocked	private/internal 全量 repo list、redacted admin export 或 read-only token evidence
refs truth / parity	waiting owner review	main/dev、release tags、deprecated refs 的 owner 判定
workflow / secret export	draft only	webhook、runner、deploy key、branch protection、repository secret name parity redacted evidence
owner / visibility / canonical	waiting owner review	7 個 in-scope repo 的 owner / target / canonical 決策
rollback owner / monitoring	draft only	每個 repo 的 rollback owner、1h / 24h 驗證窗口與 decision record 格式

4. Repo Rollback Draft

Repo	Risk	Rollback state	主要缺口
owenhytsai/awoooi	HIGH	waiting owner review	refs parity、deploy workflow、webhook single-sender、runner owner、secret name parity
owenhytsai/clawbot-v5	MEDIUM	waiting owner review	tag policy、workflow / secret need attestation、rollback owner
owenhytsai/wooo-aiops	MEDIUM	waiting owner review	GitHub-only refs、webhook owner、runner owner
owenhytsai/wooo-infra-config	MEDIUM	waiting owner review	110 internal remote、deploy key、infra secret name parity
owenhytsai/ewoooc	HIGH	waiting owner review	target access、canonical repo、unrelated history risk
owenhytsai/bitan-pharmacy	MEDIUM	waiting owner review	active status、GitHub target、secret / deploy owner
owenhytsai/tsenyang-website	MEDIUM	waiting owner review	active status、GitHub target、secret / deploy owner
nexu-io/open-design	LOW	scope review only	不進 AWOOOI primary cutover queue

5. Rollback 觸發條件

1. main/dev SHA 或 tag parity 與 owner-approved truth 不一致。
2. workflow、webhook、runner、deploy key、branch protection 或 repository secret name parity evidence 不完整。
3. GitHub hosted runner 使用量或 billing risk 超出 owner-approved 範圍。
4. deploy marker、release workflow 或 required status check 在 cutover 後失敗。
5. duplicate webhook 造成重複部署、重複通知或 approval queue 重複事件。
6. owner / visibility / canonical decision 被撤回或出現衝突。
7. post-cutover 1h 或 24h validation window 未通過。

6. AwoooP 可做

1. 顯示 7 個 in-scope repo 的 rollback ADR draft。
2. 顯示 owner-approved count、dry-run completed count、active cutover count 都是 0。
3. 將 rollback owner、precondition、validation window 與 trigger 顯示在 Operator Console。
4. 把 rollback ADR 缺口寫入 Audit evidence。
5. 若未來 owner 提交決策，另寫入 security_approval_decision_record_v1。

7. AwoooP 不可做

1. 不把 ADR 草案當成 cutover approval。
2. 不切 GitHub primary。
3. 不執行 rollback。
4. 不 sync refs、不 delete refs、不 force push。
5. 不修改 webhook、workflow、branch protection 或 secret。
6. 不停用、刪除、封存或降級 Gitea repo。
7. 不新增 repo、refs、primary switch、rollback 類 action button。

8. 階段定位

S4.0 定義 primary readiness gate，S4.1 到 S4.3 補 workflow / secret inventory 與 export request，S4.4 補 rollback ADR 草案。

這讓「長期改回 GitHub primary」有更完整的安全出口，但仍然停在框架期：先讓 AwoooP 看見風險與 owner review，不啟動任何切換、不執行任何回退。