# Nexus Capital OS Type 3：AI Agent 啟動入口

版本：2.0  
正式 Manual：https://capital-demo.rwa.nexus/manual  
機器可讀 Menu：https://capital-demo.rwa.nexus/manual/agent-menu.json  
完整 Runbook：https://capital-demo.rwa.nexus/manual/nexus-capital-os-partner-ai-runbook.zh-TW.md

## 給 AI Agent 的任務

你正在協助第三類深度合作夥伴建立或維護其 private Nexus Capital OS。合作夥伴必須完整 fork 授權的 `capital-demo` repo；這個 private fork 是長期開發與維護單位。`dist/workspace` 與 Docker image 只是可重建產物，不是另一個 repo。合作夥伴可在 fork 內開發 private extensions，並持續接收 upstream module 升級。

先完整讀取本文件、機器可讀 Menu、完整 Runbook，以及 checked-out repository 中適用的 `AGENTS.md`／`CLAUDE.md`。Repository 當前 revision 所定義的命令與安全規則優先；不得只根據公開網頁範例猜測命令。

核准的 private repository 是 `https://github.com/rwanexus/capital-fork`。取得存取權並 clone／fork 後，第一個實際命令是：

```bash
./caas --format json doctor
```

接著在 fork 內設定 partner-owned `origin` 與 canonical `upstream`，並執行 `./caas --format json fork-check`。可用 `./caas --format json inventory --include-paths` 盤點 23 個模組與 source surface，並加上 `--include-semantic` 取得 route、API、form、RBAC、workflow-state、navigation、table 與 storage ownership；`./caas validate` 與 `./caas compose` 驗證 partner profile 並建立 deterministic composition lock；`./caas test` 執行 contract tests；`./caas workspace` 從 hash-pinned packages 與 fork 內的 `partner/extensions/*` 重建 workspace；最後以 `./caas build --tag capital-distribution:<唯一標籤>` 建立本機 image。含 private extension 時標籤須為 `capital-distribution:private-<唯一標籤>`，image 會標示 `vendor-certified=false`。現階段 factory 只認證既定 22-module 組合（除 `billing` 外皆啟用），不同選擇會 fail closed。T5/T6 已提供 `./caas deploy-plan --help` 與 `./caas recovery-plan --help` 產生不含秘密、cloud-neutral 的部署與災難復原契約；真正變更目標環境仍須明確授權。

## 固定起點：先執行 T0

第一個任務永遠是 `T0 Inspect & Readiness`，而且只做唯讀盤點：

- repo URL、remotes、branch、commit、working tree；
- package manager、runtime 與真正存在的 commands；
- module registry、manifest、composition、lock 與 integrity metadata；
- profile、extensions、providers、database、storage、jobs 與 external dependencies；
- pages、APIs、forms、roles、permissions、workflows、migrations 的 module owner；
- clean install、authn/authz、tenant isolation、role/page/link/API/form E2E、backup/restore、upgrade/rollback 測試能力；
- 使用者已明確授權的 repo、host、cloud account/project 與 environment。

只列出秘密變數名稱及是否設定，不得輸出值。若必要能力、命令、權限或明確目標缺失，回報 `NOT_READY`；不得建立假檔案、假命令或假證據讓 Gate 看似通過。

## 任務 Menu

完成 T0 後，只執行使用者明確要求且已具備授權的任務：

| ID | 任務 | 核心成果 |
|---|---|---|
| T1 | Fork & Bootstrap | partner private fork、upstream baseline、feature branch |
| T2 | Compose Modules | validated profile/composition、exact lock、dependency report |
| T3 | Customize Safely | profile/workflow/form/private extension 與 affected tests |
| T4 | Build & Certify | immutable image digest、tests、SBOM/provenance |
| T5 | Install / Deploy | partner 選定環境中的健康 release 與 rollback point |
| T6 | Operate & Recover | backup、verified restore、monitoring、diagnostic evidence |
| T7 | Upgrade Modules | 單一 module upgrade PR、migration/test plan、新 lock |
| T8 | Report / Contribute | `contribute-plan`、sanitized Issue、private security report 或 upstream PR |
| T9 | Audit / Rollback | `evidence-verify`、`rollback-plan` 或已驗證的 restored release |

每個任務依序執行：

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

唯讀檢查可直接執行。Repo write、external message、cloud、deployment、DNS、migration、資料或服務變更，必須確認精確目標及授權。授權不足時回報 `WAITING_AUTHORIZATION`，不要擴張工作範圍。

## 客製化規則

依序優先使用：

1. profile／configuration；
2. workflow 或 form definition；
3. `partner/extensions/*` 與 stable module contracts；
4. 只有可重用或無法避免時才修改 shared module。

Partner-specific 品牌、流程、資料與 proprietary integration 不得提交 upstream。Shared bug 應限制在 owning module、先加 regression test、以 synthetic data 重現，再送 upstream-candidate PR。Upstream 發布後，升級 module 並移除 temporary patch。

## Module 升級規則

- 只更新目標 module、必要 dependencies、composition lock、migration 與 affected tests；
- Type 3 source update 使用 three-way merge，不直接覆寫 partner code；
- 若雙方修改相同 line、contract、schema 或 migration，停止並列出 conflict；
- 資料變更先驗證 backup/restore 與 migration rehearsal；
- 未通過 fresh install、N-1→N、extension preservation、authn/authz、tenant isolation 與 rollback，不得宣稱獨立升級完成。

## Hosting 規則

不指定合作夥伴一定使用 GCP、AWS 或其他雲端。優先使用 repo 支援的 Docker/Compose 介面。只有在使用者明確指定 target host、account/project、environment 並授權後才能部署。PostgreSQL、Redis、object storage 不可直接公開；秘密不可進 Git；公開面只開 HTTP/HTTPS；備份必須離機並驗證還原。

## 必要 Evidence Envelope

每一次任務都要回傳：

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

只有 local build 或 staging test 時不得回報 `DEPLOYED`。沒有執行的測試必須標示 `NOT_RUN`，不能省略或推論為通過。
