awoooi/docs/security/SECURITY-SUPPLY-CHAIN-CONTRACT-MANIFEST.md

# 資安供應鏈契約索引

| 項目 | 內容 |
|------|------|
| 日期 | 2026-05-17 |
| 狀態 | 草案 |
| JSON snapshot | `docs/security/security-supply-chain-contract-manifest.snapshot.json` |
| Schema | `docs/schemas/security_supply_chain_contract_manifest_v1.schema.json` |
| 預設 enforcement | `mirror_only` |
| 原則 | AwoooP 先讀 manifest，再依合約 mirror / read-only policy / approval queue 消費 |

## 0. 核心結論

目前 Security Supply Chain 已有 35 個主要契約可交給 AwoooP 消費。Manifest 的用途是把分散的 schema、snapshot、人讀文件、允許動作與禁止動作收成一份入口，避免不同 Session 各自解讀。

初期預設仍是 `mirror_only`。Manifest 不授權 runtime enforcement、不授權 GitHub/Gitea 主控切換、不授權 repo 建立或 refs sync。

## 1. Contract 清單

| Contract | Consumption | 主要用途 | Snapshot |
|----------|-------------|----------|----------|
| `security_rollout_policy_v1` | read-only policy | 低摩擦 observe-first policy | `docs/security/security-rollout-policy.snapshot.json` |
| `security_finding_v1` | mirror-only | Kali / code / infra finding | `security-finding-kali-sample.snapshot.json` |
| `kali_integration_status_v1` | mirror-only | Kali 112 live health / update / gap evidence | `kali-integration-status.snapshot.json` |
| `kali_scan_scope_approval_v1` | approval-only | Kali scan scope、111/168 observe-only、active/credentialed/execute gate | `kali-scan-scope-approval.snapshot.json` |
| `security_approval_queue_v1` | approval-only | AwoooP 可 mirror 的 Security Supply Chain approval queue | `security-approval-queue.snapshot.json` |
| `security_approval_gate_v1` | approval-only | S3 人工批准 gate 與 follow-up runtime gate 邊界 | `security-approval-gate.snapshot.json` |
| `security_approval_decision_record_v1` | approval-only | S3 人工決策稽核紀錄 | `security-approval-decision-record.snapshot.json` |
| `security_approval_review_packet_v1` | approval-only | S3 人工審查封包與 review lane | `security-approval-review-packet.snapshot.json` |
| `security_approval_state_transition_v1` | approval-only | S3 人工決策狀態轉移語義 | `security-approval-state-transition.snapshot.json` |
| `security_followup_runtime_gate_v1` | approval-only | S3 後續 runtime gate 準備模板 | `security-followup-runtime-gate.snapshot.json` |
| `security_mirror_readiness_v1` | mirror-only | AwoooP mirror/read-only readiness index | `security-mirror-readiness.snapshot.json` |
| `security_mirror_intake_plan_v1` | mirror-only | AwoooP mirror-only intake waves 與 acceptance gates | `security-mirror-intake-plan.snapshot.json` |
| `security_mirror_event_v1` | mirror-only | AwoooP mirror event envelope | `security-mirror-event-sample.snapshot.json` |
| `security_mirror_route_v1` | mirror-only | AwoooP 鏡像目的地、channel policy 與 review lane 路由 | `security-mirror-route.snapshot.json` |
| `security_mirror_acceptance_v1` | mirror-only | AwoooP 只讀鏡像接入驗收 checks | `security-mirror-acceptance.snapshot.json` |
| `security_mirror_quarantine_v1` | mirror-only | AwoooP 鏡像驗收失敗隔離與 retry gate | `security-mirror-quarantine.snapshot.json` |
| `security_mirror_dry_run_v1` | mirror-only | AwoooP 鏡像接入演練回報格式 | `security-mirror-dry-run.snapshot.json` |
| `security_mirror_status_rollup_v1` | mirror-only | AwoooP / Security Supply Chain 跨 Session 狀態總覽；S4.13 owner response validation rollup 與 next collection candidate | `security-mirror-status-rollup.snapshot.json` / `source-control-owner-response-validation-rollup.snapshot.json` |
| `coding_task_v1` | suggest-only | Code Review 接 Codex patch-only | 無正式 snapshot |
| `source_control_migration_event_v1` | mirror-only | Gitea/GitHub refs 差異 | `gitea-github-awoooi`、`clawbot-v5`、`wooo-aiops` |
| `gitea_repo_inventory_v1` | mirror-only | Gitea repo inventory；S4.5 已補認證清冊匯出請求，S4.6 已補匯入驗收契約，S4.7 已補 owner coverage attestation，S4.9 已補 owner response request packet、template status ledger、audit event templates、redaction examples、display sections、collection checks、owner response 收件包、intake preflight checks 與 outcome lanes | public-only / blocked endpoint / S4.5 export request / S4.6 import acceptance / S4.7 coverage attestation / S4.9 response snapshots |
| `local_git_remote_inventory_v1` | mirror-only | 本機 remote coverage | `local-git-remote-inventory.snapshot.json` |
| `github_target_probe_v1` | mirror-only | GitHub target visibility | `github-target-probe.snapshot.json` |
| `github_target_decision_v1` | mirror-only | GitHub target 決策；S4.10 已補 owner response request packet、template status ledger 與 owner decision response 收件包 | `github-target-decision.snapshot.json` / `github-target-owner-decision-response.snapshot.json` |
| `github_target_repo_approval_package_v1` | approval-only | 逐 repo approval queue draft；S4.10 response 通過前不得視為 repo / visibility / refs 批准 | `github-target-repo-approval-package.snapshot.json` / `github-target-owner-decision-response.snapshot.json` |
| `source_control_approval_board_v1` | approval-only | 逐 repo owner / visibility / canonical / refs 決策 board | `source-control-approval-board.snapshot.json` |
| `source_control_reconcile_plan_v1` | approval-only | refs-blocked repo 的 draft reconcile plan；S4.11 response 通過前只更新草案 wording | `source-control-reconcile-plan.snapshot.json` / `source-control-ref-truth-owner-response.snapshot.json` |
| `source_control_ref_detail_diff_v1` | mirror-only | refs-blocked repo 的 branch/tag 明細 diff | `source-control-ref-detail-diff.snapshot.json` |
| `source_control_ref_truth_classification_v1` | approval-only | refs diff 的真相來源候選與 deprecated 候選分類；S4.11 已補 owner response 收件包，5 templates、received 0 | `source-control-ref-truth-classification.snapshot.json` / `source-control-ref-truth-owner-response.snapshot.json` |
| `source_control_primary_readiness_gate_v1` | approval-only | GitHub primary readiness / parity gate | `source-control-primary-readiness-gate.snapshot.json` |
| `source_control_primary_rollback_adr_v1` | approval-only | GitHub primary rollback ADR 草案與 validation window | `source-control-primary-rollback-adr.snapshot.json` |
| `source_control_workflow_secret_name_inventory_v1` | approval-only | workflow / webhook / runner / deploy key / branch protection / CODEOWNERS / secret 名稱 inventory gate；S4.2 已補 local evidence，S4.3 已補 redacted export request，S4.12 已補 owner response 收件包 | `source-control-workflow-secret-name-inventory.snapshot.json` / `source-control-workflow-secret-name-local-evidence.snapshot.json` / `source-control-workflow-secret-name-export-request.snapshot.json` / `source-control-workflow-secret-name-owner-response.snapshot.json` |
| `local_repo_canonical_probe_v1` | mirror-only | momo/ewoooc lineage evidence | `local-repo-canonical-ewoooc-momo.snapshot.json` |
| `git_remote_refs_probe_v1` | mirror-only | 110 / GitHub remote refs readiness | `bitan-tsenyang`、`wooo-infra-config` |
| `approval_required_event_v1` | approval-only | 高風險 / 敏感邊界 approval | `gitea-readonly-inventory-approval.snapshot.json` |

## 2. AwoooP 消費順序

1. 先讀 `security_rollout_policy_v1`，確認目前仍是 `mirror_only`。
2. 再讀本 manifest，取得可消費 contract 與禁止動作。
3. 將 snapshot mirror 成 Runtime State / Channel Event / Audit evidence。
4. 讀到 `source-control-ref-truth-owner-response.snapshot.json` 時，只顯示 S4.11 response templates、acceptance checks 與 rejection rules；不得新增 refs action。
5. 讀到 `source-control-owner-response-validation-rollup.snapshot.json` 時，只顯示 S4.9/S4.10/S4.11/S4.12 四個 response packets 的總覽：22 個 templates、received / accepted / rejected 皆為 0、cross-packet checks 10 個；不得把 rollup 當成 approval 或 execution authorization。
6. 只對 `approval_required_event_v1`、repo approval package、`security_approval_review_packet_v1`、`security_approval_state_transition_v1`、`security_followup_runtime_gate_v1`、`source_control_primary_readiness_gate_v1`、`source_control_primary_rollback_adr_v1` 與 `source_control_workflow_secret_name_inventory_v1` 建 approval candidate / review lane / next-state display / runtime gate preparation / primary readiness display / rollback ADR display / workflow-secret name inventory gate / redacted export request display；`github_target_decision_v1` 只能顯示 S4.10 owner response request packet、template status ledger、owner decision response templates、received_response_count=0、acceptance checks 與 rejection rules，不得觸發 repo creation、visibility change、refs sync 或 primary switch；`gitea_repo_inventory_v1` 只能顯示 S4.5 認證匯出請求、S4.6 匯入驗收契約、S4.7 owner coverage attestation request、S4.9 owner response request packet、template status ledger、audit event templates、redaction examples、display sections、collection checks、owner response 收件包、intake preflight checks、outcome lanes 與覆蓋缺口，不得觸發 token collection 或 Gitea write。
7. 不新增執行按鈕，不做 runtime enforcement。

## 3. 永久禁止

1. 不保存 raw secret、token、cookie、private key。
2. 不直接啟動 Kali active scan。
3. 不直接呼叫 Codex patch runner。
4. 不直接建立 GitHub repo 或修改 visibility。
5. 不直接同步 refs。
6. 不切 GitHub primary。
7. 不停用、刪除、封存 Gitea repo。

## 4. 下一步

1. AwoooP 主線可把 manifest 當作 mirror-only contract index。
2. Security Supply Chain Session 後續新增 schema / snapshot 時，必須同步更新本 manifest。
3. 等 runtime integration 被正式批准前，本 manifest 只作文件與 evidence 路由，不作 execution router。