# Nexus Capital OS 第三類深度合作夥伴 — AI Agent Runbook

版本：2.0  
正式手冊：https://capital-demo.rwa.nexus/manual?locale=zh-TW  
AI Agent 啟動入口：https://capital-demo.rwa.nexus/manual/agent-bootstrap.zh-TW.md  
機器可讀 Menu：https://capital-demo.rwa.nexus/manual/agent-menu.json

## 目的

本 Runbook 用於從獲得授權的 private `reyerchu/capital-demo` 合作夥伴 repo，建立並維護合作夥伴自己的 Nexus Capital OS。合作夥伴擁有自己的 fork、profile、extensions、hosting 與資料；共用模組仍可追溯至 upstream 版本。

這是一份操作契約，不代表每一個 repo revision 都已經達到可發布狀態。

## Task Menu 與執行狀態機

每次新工作先執行唯讀 `T0`，再依使用者明確需求選擇一項任務：

| ID | 任務 | 主要輸出 |
|---|---|---|
| `T0` | Inspect & Readiness | readiness、inventory、blockers |
| `T1` | Fork & Bootstrap | remotes、baseline、partner workspace |
| `T2` | Compose Modules | composition lock、dependency report |
| `T3` | Customize Safely | profile／workflow／form／extension + tests |
| `T4` | Build & Certify | image digest、tests、release evidence |
| `T5` | Install / Deploy | healthy release、rollback point |
| `T6` | Operate & Recover | backup、verified restore、monitoring |
| `T7` | Upgrade Modules | scoped upgrade PR、migration/test plan |
| `T8` | Report / Contribute | sanitized Issue／security report／PR |
| `T9` | Audit / Rollback | audit 或 restored release evidence |

所有任務使用同一狀態機：

```text
DISCOVER → PREFLIGHT → PLAN → AUTHORIZE → EXECUTE → VERIFY → EVIDENCE
```

Repo write、外部訊息、cloud、deployment、DNS、migration、資料或服務變更，都必須在 `AUTHORIZE` 確認精確目標。權限不足時回報 `WAITING_AUTHORIZATION`。

## 不可違反的規則

1. 動作前讀完適用的 `AGENTS.md` 與 `CLAUDE.md`。
2. 先做唯讀盤點；盤點期間不得變更基礎設施。
3. 不得把正式客戶資料複製到 demo、fixture、測試或合作夥伴環境。
4. 不得 commit 憑證、token、cookie、私鑰、`.env` 或資料庫 dump。
5. 不得捏造不存在的指令、模組版本、artifact、digest、憑證或測試結果。
6. 未取得明確指定主機與環境的授權，不得部署或執行 migration。
7. 能用設定或 extension 完成的合作夥伴專屬需求，不應修改共用模組。
8. 沒有測試、health check 與證據，不得宣稱升級成功。

## Repo 模型

預期 remotes：

```text
origin    合作夥伴自己的 private fork
upstream  經授權的 reyerchu/capital-demo repo
```

預期客製化層級：

```text
partner/profile.json                    品牌、網域、語系與安全設定
partner/locks/composition.lock.json     精確模組版本、digest 與相依
partner/extensions/*                    私有流程、報表與整合
source/modules/*                        upstream 共用產品模組
```

實際檔名可隨 repo 演進。以 checked-out revision 的文件為準；不得為了通過檢查而自行建立看似相同的路徑。

## T0 / Phase 1 — 唯讀盤點

回報以下項目：

- repo URL、branch、commit 與 working-tree 狀態；
- 適用的指令文件；
- package manager 與支援的 runtime 版本；
- module manifest 與 composition 位置；
- 啟用模組的 ID、版本與 digest；
- repo 真正定義的 build、test、composition validation 與 deployment 指令；
- database、file storage、provider 與外部服務相依；
- 已明確授權的目標環境；
- 缺少的資訊與風險。

不得輸出秘密值；只列出環境變數名稱與是否已設定。

## T0 / Phase 2 — 就緒閘門

下列任一條件失敗時，停止並回報 `NOT_READY`：

- 存在有文件說明的 partner workspace 與受支援 build 指令；
- 每個啟用模組都有 ID、版本、相依範圍與 integrity metadata；
- profile 與 composition 通過 repo schema 驗證；
- 未偵測到秘密或正式客戶資料；
- 存在受支援的 clean-install 測試；
- 存在 tenant isolation、authentication 與 authorization 測試；
- release 定義 migration、backup/restore 與 rollback 行為；
- 部署前已確認唯一且明確的主機與環境。

不得建立假檔案或略過檢查，把 `NOT_READY` 偽裝成 `READY`。

## T1 — Fork 與 branch

1. 完整 fork `reyerchu/capital-demo`；這個 fork 是唯一長期開發與維護工作樹。
2. 確認 `origin` 是合作夥伴自己的 private fork。
3. 確認 `upstream` 是核准的 Nexus Capital OS repo，並執行 `./caas --format json fork-check`。
4. Fetch，但不要直接 merge。
5. 記錄 upstream baseline commit。
6. 建立 feature branch；不得直接在受保護的 `main` 開發。
7. `dist/workspace`、generated files 與 secrets 不得進 Git。

建議流程：

```text
upstream/main
    → partner upgrade branch
    → compatibility 與 affected-flow tests
    → reviewed PR 進 partner/main
    → immutable image build
    → partner-controlled deployment
```

## T2–T3 — 組裝及設定合作夥伴系統

依下列優先順序實作需求：

1. configuration；
2. workflow 或 form definition；
3. partner extension；
4. 只有在可重用或無法避免時才修改 shared module。

每項需求都要標示 owning module、受影響角色與權限、routes/APIs/forms/jobs、database/file-storage 影響、provider 相依，以及 unit/contract/integration/E2E coverage。

若必須修改共用模組：

1. 將變更限制在 owning module；
2. 加入 regression test；
3. 建立 upstream-candidate PR；
4. upstream 發布修正版後，升級模組並移除 local patch。

## T4 — Build 與驗證

只能使用 checked-out revision 已記載的指令。必要結果：

```bash
./caas test
./caas workspace
./caas build --tag capital-distribution:<唯一標籤>
```

目前 `workspace` 只認證 repository 隨附的 22-module composition（除 `billing` 外皆啟用）；若 partner profile 選擇不同集合，工具會回報 `WORKSPACE_PROFILE_SELECTION_NOT_YET_SUPPORTED`，不得改用未驗證的手工組裝繞過。

Partner 客製應提交在 private fork 的 `partner/extensions/*`。Extension 的每個新增或覆寫檔案都綁定 hash；upstream 若修改同一檔案，workspace 會停止並回報 conflict。含 extension 的 build 使用 `capital-distribution:private-<唯一標籤>`，並標示 `vendor-certified=false`。

- profile、composition 與 dependency graph 驗證通過；
- lint/type/unit/contract/integration tests 依 repo 政策通過；
- 受影響的角色、頁面、連結、API 與表單 E2E 通過；
- tenant isolation 與 authorization regression tests 通過；
- fresh database installation 通過；
- 從最舊支援版本升級的測試通過；
- Docker/Compose config 驗證通過；
- image 以 immutable digest 識別；
- repo 支援時產出 SBOM 與 provenance。

除非 reproducibility check 通過，否則不得聲稱 build 可重現。

## Hosting 建議 — 非強制

合作夥伴自行選擇 hosting，並負責帳戶、網路、可用性與成本控制。不得強制使用 GCP 或 AWS。優先維持標準 Docker/Compose 介面，讓相同 application 能部署到任一合適 Linux 環境。

| 用途 | 起始規格 | 服務範例 |
|---|---|---|
| POC／試行 | 2 vCPU、8 GB RAM、30 GB boot、50–100 GB SSD | GCP Compute Engine 或 AWS EC2 + Docker Compose |
| 小型正式環境 | 4 vCPU、16 GB RAM、受監控 SSD | VM，可選 Cloud SQL/RDS 與 GCS/S3 |
| 既有平台團隊 | 依 load test 決定 | 團隊已能維運的 container platform；Kubernetes 非必要 |

最低安全基線：只公開 HTTP/HTTPS；PostgreSQL、Redis 與物件儲存保持私有；優先使用 IAP、AWS SSM 或核准的 bastion；秘密不得進 Git；加密備份須離機保存並驗證還原；log 不得記錄秘密。

## T5 — 部署計畫

部署前先產出書面計畫，包含：

- 精確 host、cloud project/account 與 environment；
- current/target image digest；
- 啟用模組版本；
- 環境變數名稱與 secret storage 位置，不含秘密值；
- database 與 object storage logical endpoint；
- backup 與已驗證 restore point；
- migration 順序與可逆性；
- health、smoke、role 與 business-flow checks；
- canary、traffic switch 與 rollback 程序；
- 負責核准者。

若尚未取得針對該目標環境的明確授權，必須等待，不得部署。

## T5 — 安全部署

1. 再次確認目標 identity。
2. 備份 database、objects 與 configuration。
3. 依 release policy 在隔離目標驗證 restore。
4. 依 immutable digest 取得 image。
5. 執行 preflight 與 compatibility checks。
6. 只執行已核准 migration。
7. 啟動 canary 或 replacement service，不刪除舊 release。
8. 執行 health、authentication、authorization、tenant-isolation 與 affected-flow tests。
9. 全部通過後才切換流量。
10. 在觀察期內保留舊 image 與 restore point。

除非 repo runbook 已精確證明目標集合，否則不得對共用 Compose project 使用 destructive cleanup flags。

## T6–T7 — 維運與後續模組維護

收到 upstream release notice 後：

1. Fetch upstream，將要評估的精確 commit checkout 到獨立 worktree；
2. 執行 `./caas upstream-status --target-checkout <path> --expected-target-commit <40-hex-commit>`，建立 commit 對 module/version 的對映；
3. 以 clean、commit-pinned 的 accepted-baseline 與 target checkout 執行 `./caas fork-debt`；`partner/**` 保持 partner-owned，shared bytes 若兩邊都不匹配就必須人工審閱；
4. 比對 installed 與 available module versions；
5. 閱讀 release notes、compatibility range、security impact 與 migration classification；
6. 建立 upgrade branch 或自動 upgrade PR；
7. 只更新選定模組、lockfile 與必要 dependencies；
8. Partner fork 使用 three-way merge，不得直接覆蓋 partner code；
9. 執行 affected tests 與政策要求的 composition gates；
10. 涉及資料時，先 rehearsal backup/restore 與 migration；
11. 使用 canary 部署並記錄新 digest；
12. 以證據關閉 upgrade。

若 partner 與 upstream 修改相同程式碼或 contract，必須回報 conflict；任何工具都不能保證此情況可自動無衝突升級。

## T8 — Bug、Issue 與 upstream PR

先以 `./caas contribute-plan --module <id> --kind bugfix|feature|security --out <path>` 產生該次貢獻契約。此命令只建立本機計畫，不會自行送出 Issue 或 PR；`security` 類型會強制標示為 private disclosure。

開 issue 前：搜尋既有 issue/release notes；確認 module、version 及移除 partner extensions 後能否重現；使用 synthetic data 建立最小重現；移除 credentials、個資、private domains 與 proprietary code。

一般 bug issue 應包含：module 與 version/digest、severity/impact、role 與 route/API、可重現步驟、expected/actual、去識別化 log/screenshot/request ID、regression 與 workaround。

疑似 vulnerability、tenant escape、authentication bypass、secret exposure 或可利用 data leak 不得建立 public issue；必須使用 upstream private security reporting path。

Upstream PR 必須包含：問題與 module、最小 scoped implementation、能證明修正的 tests、compatibility/migration/security/tenant-isolation impact、changelog，以及不含 partner 秘密、品牌與 proprietary data 的確認。

```text
issue
 → fix/<module>-<short-description>
 → failing regression test
 → minimal module-scoped fix
 → compatibility/migration/security notes
 → upstream PR
 → reviewed merge
 → new module version
 → partner upgrade PR
 → remove temporary local patch
```

不得在同一 PR 混合 refactor、partner branding 與 upstream bug fix。

## T9 與必要完成報告

用 `./caas evidence-verify --evidence <path> --require-current-repo` 驗證證據與目前 commit／composition 的綁定。需要 rollback 時，先以 `./caas rollback-plan --evidence <path> --target-id <id> --environment <env> --previous-image <immutable-image> --migration-mode <mode> --out <path>` 建立計畫；涉及不相容 migration 時必須提供明確 rollback point，且任何遠端執行仍需授權。

```text
Status: READY | NOT_READY | WAITING_AUTHORIZATION | COMPLETE | DEPLOYED | FAILED | ROLLED_BACK
Task ID:
Repository/branch/commit:
Upstream baseline:
Changed files:
Enabled modules and versions:
Partner extensions:
Tests and results:
Database migrations:
Backup and restore evidence:
Image digest:
Target environment:
Deployment and health result:
Rollback point:
Unresolved risks:
Next maintenance action:
```

只有 local build 或 staging test 時，不得回報 `DEPLOYED`。
