# Reporting Governance Plugin / 回報治理外掛

> 讓「代理有沒有按規則回報、卡住時有沒有誠實升級、通知到底有沒有真的送出去」變成**可驗證的流程與 artifact**，而不是只靠口頭承諾。

## 中文說明

### 這個 repo 在做什麼？

這個 repo 正在把一套 **agent reporting governance** 規則，整理成可安裝、可測試、可留痕跡的 OpenClaw plugin。

目前最具體的能力是：

- 定義 governance 的事件 / 證據 / 決策 / capability / deployment profile 契約
- 提供一個正在成形的 package：`plugins/reporting-governance/`
- 提供一條已可執行的 **watchdog auto-notify reference chain**
  - `watchdog -> queue -> dispatcher -> bridge -> sender binding -> receipt`
- 誠實區分通知狀態，例如：
  - `dispatched`
  - `pending_external_send`
  - `acked`
  - `blocked`

白話說：它不是通用聊天 plugin，而是要處理這類問題：

- long task 太久沒回報時，能不能自動留下證據並產生通知義務？
- 通知在多段 handoff 之後，能不能還是看得出「真的送到了」還是「其實還沒」？
- policy / profile / capability 能不能從文件變成 package 自己擁有的 contract？

### 目前狀態：哪些真的可用、哪些還沒完整？

#### 已經可用 / 有測試證據

1. **Package skeleton 已存在**
   - 位置：`plugins/reporting-governance/`
   - 已有 `core/`, `adapters/`, `storage/`, `profiles/`, `capabilities/`, `schemas/`, `scripts/`

2. **最小 governance core 已可執行**
   - policy evaluator
   - decision runner
   - compatibility preflight
   - runtime-integrated execution slice

3. **Watchdog reference chain 已可執行且有整合測試**
   - 會產生 event / queue / spool / receipt
   - 不會把「尚未證明送達」假裝成 `acked`

4. **Package-owned profile / capability artifacts 已落地**
   - `plugins/reporting-governance/profiles/strict-manager-mode.profile.json`
   - `plugins/reporting-governance/capabilities/openclaw-watchdog-reference.json`

5. **打包 / 安裝 smoke test 已存在**
   - 代表目前 package 至少能以受測方式被打包、安裝、再透過公開 exports/bin 驗證

#### 還沒完成 / 不能誇大宣稱的部分

1. **還不是 1.0 穩定 API**
   - 版本目前是 `0.1.0-mainline`
   - package surface 仍在收斂
   - 不應依賴 repo 內部 `src/` 深層 private 路徑

2. **還不是完整通用治理框架**
   - 現在最成熟的是 watchdog-driven notify path
   - 還沒把所有 inline governance decision 都接成完整 runtime enforcement

3. **adapter 仍有過渡成分**
   - 一部分 adapter 目前仍是 package 對既有 repo scripts 的包裝/收斂
   - 這是 MVP 過程中的刻意設計，不是假裝全部已抽乾淨

4. **storage / audit export 仍未全面完成**
   - 已有最小 decision/profile artifact slice
   - 但還不是完整 event/evidence/decision/audit framework

### 如何驗證它目前真的有在工作？

最實用的驗證方式有三種。

#### 1) 跑 package smoke

```bash
npm --prefix plugins/reporting-governance run smoke
```

目前預期：
- 指令成功
- 會輸出 JSON
- `ok: true`
- `orchestrator.ok: true`
- 在 sender 未完整配置時，通常會誠實停在 `pending` / `pending_external_send` 類狀態，而不是假裝已送達

#### 2) 跑 package tests

```bash
node --test \
  plugins/reporting-governance/test/package-structure.test.mjs \
  plugins/reporting-governance/test/watchdog-chain.integration.test.mjs \
  plugins/reporting-governance/test/runtime-integrated.integration.test.mjs \
  plugins/reporting-governance/test/packed-consumer-install.smoke.test.mjs
```

這組測試重點驗證：
- package 結構存在
- tarball 可安裝到乾淨 consumer
- 公開 exports / bin 可用
- watchdog chain truth model 正常
- mixed terminal outcomes 不會被錯誤提升成 `acked`

#### 3) 直接看參考 artifact / profile / capability

可先從這幾個檔案讀起：

- `plugins/reporting-governance/README.md`
- `plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md`
- `plugins/reporting-governance/capabilities/openclaw-watchdog-reference.json`
- `plugins/reporting-governance/profiles/strict-manager-mode.profile.json`
- `docs/roadmaps/reporting-governance-plugin-status-plain-language.md`

### 目前適合怎麼使用？

#### 如果你是來理解這個專案

建議閱讀順序：

1. 先看這份 `README.md`
2. 再看 `plugins/reporting-governance/README.md`
3. 想看白話版現況，讀：
   - `docs/roadmaps/reporting-governance-plugin-status-plain-language.md`
4. 想看 watchdog 參考鏈，讀：
   - `plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md`

#### 如果你想驗證 package 現況

```bash
npm --prefix plugins/reporting-governance install
npm --prefix plugins/reporting-governance test
npm --prefix plugins/reporting-governance run smoke
```

#### 如果你想把它當成「OpenClaw reference runtime slice」來試

目前最合適的理解方式是：

- 它已經提供一個 **reference runtime composition**
- 不是完整 production installer
- 也不是所有治理規則都已接上 live runtime
- 最成熟的入口是 watchdog/orchestrator 這條鏈

### Repo 結構重點

```text
plugins/reporting-governance/   # 主 package
  capabilities/                # capability descriptors
  profiles/                    # generated deployment profile artifacts
  profiles-src/                # profile source
  schemas/                     # package-owned schemas
  scripts/                     # executable entrypoints / smoke helpers
  src/
    core/                      # policy/decision/runtime-integrated core slice
    adapters/                  # runtime adapter boundary
    storage/                   # artifact/store contracts
    reference/                 # reference runtime docs
  test/                        # package tests

docs/specs/                    # mainline specs
docs/roadmaps/                 # status + roadmap docs
scripts/                       # repo-level compatibility / fixture scripts
state/                         # runtime artifact examples / local state
```

### 誠實的專案定位

最準確的說法是：

- **不是只有 spec**
- **也還不是完整成熟產品**
- **目前是一個已有真實可測 slice 的 plugin package 主線**

也就是：

> 已經能證明某些治理邊界真的成立，尤其是 watchdog 通知鏈與 truthful delivery state；但整體仍在往更完整、可攜、可安裝的 plugin 收斂中。

---

## English

### What does this repository do?

This repository is turning a set of **agent reporting governance** rules into an installable, testable, artifact-backed OpenClaw plugin.

Today, the most concrete slice is a **watchdog auto-notify reference chain** that can:

- detect overdue reporting situations,
- emit canonical events,
- create queue/spool/receipt artifacts,
- and preserve truthful delivery states instead of claiming success too early.

In plain English: this project is about making agent reporting obligations auditable and automatable, especially around “silent long task” failures and notification handoff truth.

### Honest current status

What works now:

- a real package boundary under `plugins/reporting-governance/`
- package-owned schemas, capability descriptors, and deployment profile artifacts
- a minimal runnable governance core
- a tested OpenClaw watchdog reference composition
- packaging/install smoke coverage via public exports and bin entrypoints

What is not complete yet:

- this is still **pre-1.0** (`0.1.0-mainline`)
- the API surface is still tightening
- not all governance decisions are wired into a generalized runtime enforcement layer
- some adapters still wrap existing repo scripts as part of MVP extraction
- this is not yet a finished production-wide governance framework

### How to verify the current state

Run the package smoke check:

```bash
npm --prefix plugins/reporting-governance run smoke
```

Run a focused package verification set:

```bash
node --test \
  plugins/reporting-governance/test/package-structure.test.mjs \
  plugins/reporting-governance/test/watchdog-chain.integration.test.mjs \
  plugins/reporting-governance/test/runtime-integrated.integration.test.mjs \
  plugins/reporting-governance/test/packed-consumer-install.smoke.test.mjs
```

Or run the package test suite:

```bash
npm --prefix plugins/reporting-governance test
```

### Practical usage guidance

Use the repository today as:

- a **reference implementation** for reporting-governance package boundaries,
- a **tested watchdog notification chain** for OpenClaw,
- and a **working MVP package slice** for further extraction.

Do **not** treat it yet as:

- a stable 1.0 public API,
- a complete governance framework for every runtime,
- or a finished production installer.

### Start here

- Repo overview: `README.md`
- Package details: `plugins/reporting-governance/README.md`
- Plain-language status: `docs/roadmaps/reporting-governance-plugin-status-plain-language.md`
- Reference chain: `plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md`

---

## See also

- `plugins/reporting-governance/README.md`
- `docs/roadmaps/reporting-governance-plugin-status-plain-language.md`
- `docs/roadmaps/reporting-governance-plugin-mvp.md`
- `docs/specs/reporting-governance-capability-descriptor.md`
- `docs/specs/reporting-governance-deployment-model.md`
- `plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md`
- `CODER_WATCHDOG_REPORT.md`