wooo/awoooi
1
1
Fork 0
Code Issues 2 Pull Requests 1 Actions 2 Packages Projects Releases Wiki Activity
Files
2a2cb16c135fd7e5b159d94de9b5ff04f6cf31f5
awoooi/docs/security/SOURCE-CONTROL-REF-TRUTH-OWNER-RESPONSE.md

213 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Source Control Ref Truth Owner Response 收件包
| 項目 | 內容 |
|------|------|
| 日期 | 2026-06-04 |
| 狀態 | 草案，等待 owner response |
| 資料契約 | `docs/schemas/source_control_ref_truth_owner_response_v1.schema.json` |
| 快照 | `docs/security/source-control-ref-truth-owner-response.snapshot.json` |
| 來源契約 | `source_control_ref_truth_classification_v1` |
| 目標契約 | `source_control_reconcile_plan_v1` |
| 模式 | `owner_ref_truth_response_intake_only` |
| 執行面授權 | `false` |
## 0. 核心結論
S4.11 補的是「AwoooP 要怎麼請 owner 回覆，以及 owner 要怎麼回覆 current `194` 個 refs review items 的真相來源、deprecated 候選、release tag retention 與 GitHub-only refs disposition」。
S4.11 不是 refs sync approval、不是 delete approval、不是 force-push approval，也不是 GitHub primary approval。它只把 owner response 的欄位、可接受決策、驗收規則、拒收規則與允許輸出固定下來，讓 AwoooP 可以只讀顯示並等待人工補證。
此文件不要求貼 token，不接受 raw secret，不 fetch、不 push refs、不 delete refs、不 rewrite branch/tag、不建立 repo、不修改 visibility、不切 primary，也不停用 Gitea。
## 1. Response 摘要
| 指標 | 值 |
|------|----|
| owner response 狀態 | `waiting_owner_response` |
| repos | 3 |
| ref review items | 194 |
| 需要人工指定真相來源 | 4 |
| deprecated / archive 候選 | 142 |
| release tag 待審核 | 3 |
| GitHub-only ref 待審核 | 20 |
| owner response request packet | 1 |
| template status ledger | 5 |
| audit event templates | 3 |
| redaction examples | 5 |
| collection checks | 6 |
| intake preflight checks | 6 |
| response templates | 5 |
| 已收到 response | 0 |
| 已接受 response | 0 |
| 已拒收 response | 0 |
| acceptance checks | 8 |
| rejection rules | 10 |
| 授權 sync refs | `false` |
| 授權 delete refs | `false` |
| 授權 force push | `false` |
| 授權切換 GitHub primary | `false` |
| 允許收集 secret value | `false` |
| 允許 action button | `false` |
## 1.1 Owner Response Request Packet
| 欄位 | 值 |
|------|----|
| request id | `s4_11_ref_truth_owner_response_request` |
| 顯示狀態 | `ready_to_request_owner_response` |
| 要求回覆 templates | 5 |
| 顯示模式 | `display_owner_response_request_only` |
| 執行授權 | `false` |
| 是否為批准 | `false` |
這個 request packet 只讓 AwoooP 顯示「請 owner 回覆哪五類 refs truth 問題、允許填哪些欄位、evidence 要怎麼脫敏、哪些 payload 必須拒收」。它不是 request sent、不是 response received、不是 response accepted，也不是 refs sync / delete / force push / primary approval。
Owner 回覆只能使用脫敏 metadata 或既有文件引用。不得貼 token、secret、private clone URL credential、git object pack、repo archive、API raw body、fetch/push/delete/force-push 指令或任何 execution request payload。
## 1.2 Template Status Ledger
| Template | 狀態 | request | received / accepted / rejected |
|----------|------|---------|--------------------------------|
| `response-main-branch-truth-source` | `waiting_owner_response` | `request_ready_not_sent` | `0 / 0 / 0` |
| `response-active-dev-branch-truth-source` | `waiting_owner_response` | `request_ready_not_sent` | `0 / 0 / 0` |
| `response-drift-deprecated-candidate-batch` | `waiting_owner_response` | `request_ready_not_sent` | `0 / 0 / 0` |
| `response-release-tag-retention` | `waiting_owner_response` | `request_ready_not_sent` | `0 / 0 / 0` |
| `response-github-only-ref-review` | `waiting_owner_response` | `request_ready_not_sent` | `0 / 0 / 0` |
Template status ledger 只讓 AwoooP 逐項顯示哪一類 refs truth response 還在等待 owner。`request_ready_not_sent` 不代表 request 已送出，`waiting_owner_response` 不代表 owner 已回覆，任何單項狀態也不代表 refs sync、delete、force push、tag rewrite、backfill 或 GitHub primary approval。
## 1.3 Audit Event Templates
| Template | 觸發點 | emitted |
|----------|--------|---------|
| `audit-ref-truth-response-request-shown` | 顯示 S4.11 request packet | 0 |
| `audit-ref-truth-response-received-metadata` | 收到脫敏 owner response metadata pointer | 0 |
| `audit-ref-truth-response-outcome-classified` | 依 acceptance checks / rejection rules 分類 outcome | 0 |
Audit event templates 只定義 AwoooP 未來可記錄的脫敏 metadata 欄位，全部維持 `template_only_not_emitted`、`emitted_event_count=0`、`stored_raw_payload_allowed=false`。它們不是 production ingestion，不代表 owner response 已收到，也不授權 refs sync、delete、force push、backfill、tag rewrite 或 GitHub primary。
## 1.4 Redaction Examples
| Example | 用途 |
|---------|------|
| `redaction-ref-truth-existing-doc-ref` | 用既有文件 / snapshot 引用 main truth evidence |
| `redaction-main-branch-truth-metadata` | 用角色、短 SHA 或 snapshot ref 表示 truth source |
| `redaction-deprecated-batch-disposition` | 用 ref pattern / count 表示 deprecated batch disposition |
| `redaction-release-tag-retention-metadata` | 用 artifact / rollback owner metadata 表示 release tag retention |
| `redaction-ref-truth-quarantine-pointer` | 不確定是否含敏感值時只留下 quarantine pointer |
Redaction examples 只示範安全回覆形狀，全部維持 `template_example_only`、`stored_raw_payload_allowed=false`。它們不是 owner response received、不是 accepted，也不讓 AwoooP 保存 git object pack、repo archive、API raw body、token、secret、private clone URL credential 或 execution request payload。
## 1.5 Collection Checks
| Check | 用途 |
|-------|------|
| `collection-ref-truth-request-packet-displayed` | 確認只顯示 S4.11 request packet，不夾帶 refs 執行要求 |
| `collection-ref-truth-read-only-submission-mode` | 確認 owner 只能用 read-only / redacted metadata 方式回覆 |
| `collection-five-ref-truth-template-tracking` | 確認五個 refs truth templates 分開追蹤 received / accepted / rejected |
| `collection-ref-truth-redacted-evidence-only` | 確認只收 repo 內文件、snapshot、短 SHA 或脫敏 metadata pointer |
| `collection-ref-truth-no-approval-language` | 確認 owner wording 不會升級成 refs sync / delete / force push / primary approval |
| `collection-ref-truth-audit-metadata-only` | 確認只記錄脫敏 audit metadata，不保存 raw payload |
Collection checks 只維持 request / received / accepted 狀態分離。它們不是 owner response received、不是 owner response accepted，也不授權 fetch、push、delete refs、force push、tag rewrite、backfill 或 GitHub primary。
## 1.6 Intake Preflight Checks
| Check | 用途 |
|-------|------|
| `preflight-known-ref-truth-lane` | 確認 response 對應 S4.11 已知 refs truth lane |
| `preflight-required-ref-truth-owner-fields` | 確認 owner、decision、repo/ref scope、truth/disposition 與 evidence_refs 完整 |
| `preflight-allowed-ref-truth-decision` | 確認 decision 在對應 template 允許值內 |
| `preflight-ref-truth-redacted-evidence-only` | 確認 evidence_refs 只含文件、snapshot、短 SHA 或脫敏 metadata pointer |
| `preflight-no-refs-execution-request` | 拒收 fetch / push / delete / force push / rewrite / backfill / primary 等執行要求 |
| `preflight-all-five-ref-truth-lanes-before-accepted` | 確認五個 templates 全部可驗收前不得標成 accepted |
Intake preflight checks 只把收到的 response 分類成可審、補證、隔離、拒收或繼續等待。Preflight pass 不是 owner response accepted，也不是 refs sync、delete、force push、tag rewrite、backfill、GitHub primary、workflow / secret / runner 或 Kali scan 授權。
## 2. Owner Response 必填欄位
每筆 response 至少要能回答：
1. `owner_role_or_team`：回覆者角色或團隊，不要求個人敏感資訊。
2. `decision`：必須是該 lane template 允許的決策值。
3. `decision_reason`：為什麼做此真相來源、retention 或 disposition 判定。
4. `repo` 與 `ref_name` / `tag_name` / `ref_pattern_or_ref_list`：批次回覆必須能重現範圍。
5. `truth_source_or_sha`、`branch_disposition`、`retention_disposition` 或 `github_only_owner`：依 lane 補齊。
6. `deploy_marker_owner`、`artifact_owner`、`rollback_point_owner` 或 `workflow_owner`：高風險 branch/tag 必須有 owner 或補證 owner。
7. `evidence_refs`：只能指向 repo 內文件、snapshot 或 owner 提供的脫敏 metadata。
## 3. 五個 Response Template
| Template | Lane | 覆蓋範圍 | 驗收重點 |
|----------|------|----------|----------|
| `response-main-branch-truth-source` | `main_truth_required` | 3 個 repo main branch | 指定 truth source、deploy marker owner、production source owner、rollback point owner |
| `response-active-dev-branch-truth-source` | `active_branch_truth_required` | `wooo/awoooi dev` | 判定 active workflow、legacy candidate 或需補 workflow owner |
| `response-drift-deprecated-candidate-batch` | `archive_or_deprecate_candidate` | `wooo/awoooi` 142 個 drift/adopt refs | deprecated candidate 只代表人工 disposition，不代表 delete approval |
| `response-release-tag-retention` | `release_tag_missing_on_github` | `awoooi` 2 個 release tags、`clawbot-v5` 1 個 tag | 指定 artifact / deploy marker owner，維持 tag action disabled |
| `response-github-only-ref-review` | `github_only_manual_review` | `wooo-aiops` 1 個 branch + 19 個 UAT tags | backfill 只能是 candidate，不代表 push approval |
## 4. 可接受決策值
| Lane | Decision |
|------|----------|
| `main_truth_required` | `choose_gitea_as_truth_candidate`、`choose_github_as_truth_candidate`、`choose_specific_sha_as_truth_candidate`、`hold_pending_deploy_marker`、`unknown_requires_more_evidence` |
| `active_branch_truth_required` | `keep_active_branch_candidate`、`mark_branch_legacy_candidate`、`hold_pending_workflow_owner`、`unknown_requires_more_evidence` |
| `archive_or_deprecate_candidate` | `mark_deprecated_candidate`、`keep_audit_retention_candidate`、`split_batch_requires_more_evidence`、`unknown_requires_more_evidence` |
| `release_tag_missing_on_github` | `keep_release_tag_candidate`、`mark_tag_legacy_candidate`、`hold_pending_artifact_owner`、`unknown_requires_more_evidence` |
| `github_only_manual_review` | `keep_github_only_candidate`、`backfill_to_gitea_candidate`、`mark_legacy_github_only_candidate`、`hold_pending_audit_owner`、`unknown_requires_more_evidence` |
## 5. 驗收規則
1. response 必須對應既有 refs truth lane。
2. `decision` 必須在該 lane template 的允許值內。
3. 必須標示 repo 與 ref scope；批次回覆必須有可重現範圍。
4. 必須說明 truth source 或 disposition；未知時要明確選 hold / unknown。
5. high-risk main branch 與 release tag 必須有 deploy、artifact、rollback 或補證 owner。
6. 不得夾帶 fetch、push refs、delete refs、force push、mirror sync、tag rewrite 或 branch rewrite 要求。
7. 不得夾帶 GitHub primary、repo creation、visibility change、disable Gitea 或 archive Gitea 要求。
8. `evidence_refs` 必須已脫敏，不得包含 token、credential、secret value、private key、deploy key value、cookie 或 session。
## 6. 必須拒收
1. token value、PAT、cookie、session、CSRF token、private key、deploy key value 或 partial credential。
2. fetch、push refs、delete refs、force push、mirror sync、tag rewrite、branch rewrite 或 prune refs。
3. 切 GitHub primary 或把 GitHub primary readiness 視為已完成。
4. 建立 repo、修改 repo visibility 或改 remote URL。
5. 把 deprecated candidate 當成 delete approval。
6. 把 backfill candidate 當成 push approval。
7. 缺 repo/ref/lane 或批次範圍無法重現。
8. main / release high-risk 回覆缺 deploy marker、artifact、rollback 或補證 owner。
9. 要求停用、刪除、封存或降級 Gitea。
10. 任何不確定是否含敏感值、私有 URL 憑證或未脫敏截圖的回覆。
## 7. AwoooP 可做
1. 顯示 1 個 owner response request packet。
2. 顯示 5 個 template statuses，逐項維持 `waiting_owner_response`。
3. 顯示 3 個 audit event templates，全部維持 `template_only_not_emitted` 與 `emitted_event_count=0`。
4. 顯示 5 個 redaction examples，全部維持 `template_example_only` 與 `stored_raw_payload_allowed=false`。
5. 顯示 6 個 collection checks，維持 request / received / accepted 分離。
6. 顯示 6 個 intake preflight checks，只分類可審、補證、隔離、拒收或等待。
7. 顯示 5 個 owner response templates。
8. 顯示 8 個 acceptance checks 與 10 個 rejection rules。
9. 在 owner response 到來後，只更新 read-only classification、draft reconcile plan、primary readiness blocker wording 與 status rollup。
10. 將不完整或可疑 response 放進 mirror quarantine。
11. 持續顯示 `received_response_count=0`、`accepted_response_count=0`，直到真的收到脫敏 response。
## 8. AwoooP 不可做
1. 不要求使用者貼 token、secret、private key、cookie、session 或 deploy key。
2. 不把 response 當成 refs sync approval。
3. 不把 response 當成 delete refs approval。
4. 不把 response 當成 force-push approval。
5. 不把 response 當成 GitHub primary approval。
6. 不建立 GitHub repo。
7. 不修改 GitHub/Gitea repo。
8. 不新增執行按鈕。
## 9. 階段定位
S4.11 是 S4.0 GitHub primary readiness 與 S4.10 GitHub target owner decision 後面的 refs owner response 收件包。
它讓 current 194 個 ref review items 的 owner response 變得可審、可驗收、可拒收，但仍停在框架期。真正進入 refs migration 或 GitHub primary 前，仍必須等 Gitea inventory、GitHub target response、workflow-secret parity、rollback ADR、owner approval 與後續 runtime gate 全部補齊。
Reference in New Issue View Git Blame Copy Permalink