# Reporting Governance Plugin：現在做到哪、為什麼這樣切、還沒做到什麼

這份文件是給**不想先看程式碼的人**看的。

一句話先講白：
**這個 plugin 在做的事，是把「代理有沒有老實回報、有沒有卡住不講、有沒有把該交接的事真的交出去」這些規則，從口頭要求，慢慢做成可驗證的程式與紀錄。**

---

## 1) 目前已經做了什麼

現在不是只有概念，而是已經有一條**可以跑、會留下痕跡、能被測試證明**的最小鏈路。

### 已經有的骨架

`plugins/reporting-governance/` 這個 package 已經拉出基本邊界：

- `core/`：放規則判斷與決策邏輯
- `adapters/`：接現有 runtime / script
- `storage/`：放可保存的 artifact 與 store contract
- `profiles/`：放部署設定 artifact
- `capabilities/`：放能力描述

這很重要，因為它代表這件事開始不是散在 repo 各角落，而是有自己的 package 家。

### 已經有的決策能力

目前已經有最小可跑的：

- policy evaluator：根據事件/證據判斷要不要出手
- decision runner：把判斷結果轉成可執行意圖
- compatibility preflight：先檢查輸入/相容性，不對就 fail closed

白話講，就是：
**系統已經不只是「看到問題」，而是能把問題翻成明確決策，例如要不要強制 checkpoint、要不要擋下某動作。**

### 已經有的 OpenClaw 參考鏈

目前 repo 裡最真實的一條鏈，是 watchdog 逾時告警路徑：

`watchdog -> queue -> dispatcher -> bridge -> sender -> receipt`

這條鏈已經能做到：

- 產生 canonical event
- 進 queue / spool
- 經過 bridge / sender binding
- 留下 receipt
- 在不能真的送出的情況下，誠實標示成 `pending_external_send`，不是假裝已送達

這件事的價值很實際：
**它已經能防止「其實沒送到，卻說送到了」這種黑箱假成功。**

### 已經有的 package-owned profile artifact

目前已經有一個 package 自己擁有的部署設定 artifact：

- `plugins/reporting-governance/profiles/strict-manager-mode.profile.json`

而且不是擺著好看，已經有：

- loader
- validator
- binding contract projector
- 測試

白話講：
**這個 plugin 已經開始自己宣告：我依賴哪些腳本、哪些 artifact 目錄、哪些 runtime 邊界。**

不是再靠「大家心裡知道」或 README 暗示。

### 這一輪新補的最小 storage contract slice

這輪再往前推了一小刀：

- 定義 `DecisionRecordArtifact`
- 定義 decision artifact validator / filename contract
- 落一個最小 file-based decision store
- 用測試證明 decision 可以被寫入、讀回、驗證，而且不能亂寫出 repo root

白話講：
**決策紀錄開始有 package 自己的保存格式，而不是每次臨時拼 JSON。**

---

## 2) 為什麼要這樣設計 / 為什麼要這樣切 slices

### 原因一：這題太大，不能一口氣抽乾淨

Reporting governance 牽到的東西很多：

- 事件模型
- 證據模型
- 決策模型
- queue / spool / receipt
- runtime adapter
- 真正外送通知
- 未來的 audit/export

如果一次硬做成完整 framework，很容易出現兩種壞事：

1. 做很大，但沒有任何一塊真的可驗證
2. 名字切漂亮，實際上還是靠舊 repo 腳本在撐

所以現在的主線策略是：
**每次只切一塊最小、能被測試證明、而且不會假裝完成的 slice。**

### 原因二：先把「誠實邊界」做出來

這個 plugin 的核心不是炫技，而是**不能說謊**。

所以設計上優先做的是：

- capability descriptor：先講清楚 runtime 有什麼能力
- compatibility preflight：能力不夠就 fail，不硬裝能做
- truthful receipt states：沒送到就是沒送到，不能灌水成 acked
- package-owned artifacts：讓輸入/輸出有固定契約

這就是為什麼現在會先看到 profile artifact、receipt truth model、decision record 這些東西，而不是先衝一個很大的「全能治理引擎」。

### 原因三：把 package 真正養成自己的邊界

如果 `core`、`adapters`、`storage` 不分開，未來就會很難回答：

- 哪些是可重用的治理邏輯？
- 哪些只是 OpenClaw 這個 runtime 的接線？
- 哪些是資料保存契約？

現在這樣切，是為了讓未來能逐步達到：

- `core` 不依賴特定 runtime
- `adapters` 負責接現場
- `storage` 擁有 artifact contract

這樣才有機會從「repo 內一套特殊腳本」長成「可攜的 plugin」。

---

## 3) 這些工作帶來什麼實際好處

### 好處一：比較不容易再發生黑箱失聯

watchdog / queue / receipt 這條鏈已經讓「任務太久沒回報」有一條比較正式的處理路。

不是再靠人記得盯。

### 好處二：可以區分「真的做到」和「只是說做到」

receipt truth model 的意義很直接：

- 有證據送出，才叫 acked
- 沒證據，就停在 pending / blocked / dispatched 等誠實狀態

這會直接降低假完成、假外送、假交接。

### 好處三：未來比較能換 runtime，不用整組重寫

先把 core / adapter / storage 切開，未來若不是 OpenClaw，也比較有機會重用核心規則。

### 好處四：決策開始可保存、可追查

這輪 decision store slice 的實際價值是：

- 決策不只存在記憶體
- 可落成 artifact
- 檔名與內容有固定 contract
- 可追 policy、decision、receipt、source event

這對 audit、debug、回放都很關鍵。

---

## 4) 目前明確還沒做到什麼

這裡要講老實話。

### 還沒做到完整 storage framework

現在只有先落一個最小 decision store slice。

**還沒有**完整抽成：

- event store
- evidence store
- queue store
- spool store
- receipt store
- 統一 manifest / audit export

### 還沒做到所有決策都能真的執行

目前 package `core` 已經能做判斷與規劃，
但很多實際 side effects 還是 adapter / runtime 責任。

例如：

- 真正 inline 攔截所有訊息/狀態變更
- 完整 rewrite / placeholder / review / downgrade_status 執行
- 非 watchdog 路徑的全面治理攔截

### 還沒完全脫離 repo 既有 scripts

現在 adapter 仍大量包既有 scripts。
這代表 package 邊界雖然成形，但 runtime 實作還在過渡期。

### 還沒形成完整對外穩定 API

現在還是 `0.1.0-mainline`，屬於 pre-1.0。

意思是：

- package surface 還在收斂
- 深層 `src/` import 不算穩定公開 API
- 現在能跑，不代表介面已經定版

---

## 現在最準確的定位

如果要一句話描述現在狀態：

**它已經不是只有規格文件；已經有最小可跑、可測、會留痕跡的治理鏈。**

但同時：

**它也還不是完整成熟的 reporting-governance framework。**

現在主線是在做一件對的事：
**把最重要、最容易說謊、最需要證據的那幾刀，先變成 package-owned contracts。**

這樣後面每往前一步，才比較不會變成另一個大而空的治理殼。