From ef424cdd62a7e86871478dcf8ed7d1622e1a4fea Mon Sep 17 00:00:00 2001
From: Eve <eve@ai.cowbay.org>
Date: Mon, 11 May 2026 10:54:00 +0800
Subject: [PATCH] docs: add reporting governance install guide

---
 plugins/reporting-governance/INSTALL.md | 492 ++++++++++++++++++++++++
 plugins/reporting-governance/README.md  |  10 +
 2 files changed, 502 insertions(+)
 create mode 100644 plugins/reporting-governance/INSTALL.md

diff --git a/plugins/reporting-governance/INSTALL.md b/plugins/reporting-governance/INSTALL.md
new file mode 100644
index 0000000..059963a
--- /dev/null
+++ b/plugins/reporting-governance/INSTALL.md
@@ -0,0 +1,492 @@
+# @openclaw/plugin-reporting-governance Installation Guide for AI Agents
+
+> Goal: let another AI agent install, verify, and consume the current package **without guessing**.
+
+This guide is intentionally narrow and aligned to the package's **current** state:
+
+- package name: `@openclaw/plugin-reporting-governance`
+- version: `0.1.0-mainline`
+- package root in this repo: `plugins/reporting-governance/`
+- current public API is controlled by `package.json#exports`
+- current proof path is the **watchdog reference chain** and its package smoke/tests
+
+---
+
+## 1. What this package is right now
+
+This package is a **pre-1.0 reporting-governance plugin slice**.
+
+It currently gives you:
+
+- a real npm package boundary
+- a narrow public JS export surface
+- package-owned capability/profile/schema artifacts
+- runnable adapter entrypoints for the OpenClaw watchdog reference chain
+- smoke and test coverage proving:
+  - tarball packing works
+  - clean-consumer install works
+  - public exports/bin work
+  - watchdog/orchestrator truth model stays honest
+
+It does **not** yet give you:
+
+- a stable 1.0 API
+- a full production installer
+- a generalized governance framework for every runtime decision
+- permission to deep-import arbitrary `src/*` files
+
+---
+
+## 2. Prerequisites
+
+Assume the following before installing:
+
+### Required
+
+- **Node.js**: modern Node with ESM + `node --test` support
+  - the repo runtime shown during this task is Node `v22.22.1`
+  - safest assumption: use Node 20+; Node 22 is known-good here
+- **npm** available in PATH
+- access to this repo or to a tarball produced from `plugins/reporting-governance/`
+
+### For repo-local verification
+
+If working inside this repository, assume:
+
+- repo root contains the package at `plugins/reporting-governance/`
+- package dependencies can be installed with `npm --prefix plugins/reporting-governance install`
+
+### For clean-consumer verification
+
+You need:
+
+- permission to create a temporary directory
+- ability to run `npm pack` and `npm install <tarball>`
+
+### What you do **not** need to assume
+
+Do **not** assume:
+
+- an OpenClaw daemon is running
+- Telegram credentials are configured
+- live sender delivery is available
+- cron is installed or configured
+- repo-root wrapper scripts are the package API
+
+The current smoke/tests are intentionally built so that dry-run/pending states are acceptable and truthful.
+
+---
+
+## 3. Install paths: choose the right mode
+
+There are two practical install modes.
+
+### Mode A — work in this repo/package directly
+
+Use this when you are validating or developing the package in-place.
+
+Package directory:
+
+```bash
+cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin
+npm --prefix plugins/reporting-governance install
+```
+
+### Mode B — install as a packed dependency into a clean consumer
+
+Use this when you need proof that the package works through its shipped boundary only.
+
+From repo root:
+
+```bash
+cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin/plugins/reporting-governance
+npm pack
+```
+
+That produces a tarball like:
+
+```text
+openclaw-plugin-reporting-governance-0.1.0-mainline.tgz
+```
+
+Then in a separate consumer directory:
+
+```bash
+mkdir -p /tmp/reporting-governance-consumer
+cd /tmp/reporting-governance-consumer
+npm init -y
+npm install /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin/plugins/reporting-governance/openclaw-plugin-reporting-governance-0.1.0-mainline.tgz
+```
+
+---
+
+## 4. Exact install steps for the current repo state
+
+## A. Repo-local install
+
+From repo root:
+
+```bash
+cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin
+npm --prefix plugins/reporting-governance install
+```
+
+Expected result:
+
+- installs package dependencies declared in `plugins/reporting-governance/package.json`
+- creates/updates `plugins/reporting-governance/node_modules/`
+- does **not** mean the package is globally installed
+
+## B. Repo-local smoke run
+
+From repo root:
+
+```bash
+cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin
+npm --prefix plugins/reporting-governance run smoke
+```
+
+What this currently does:
+
+- runs `node ./scripts/package-smoke.mjs --compact`
+- creates a temporary workspace unless `--workspace` is supplied
+- generates a profile artifact from `profiles-src/strict-manager-mode.yaml`
+- runs the orchestrator adapter in `dryRun: true`
+- returns JSON only
+
+Current success shape to expect:
+
+- top-level `ok: true`
+- `tool: "reporting-governance-package-smoke"`
+- `orchestrator.ok: true`
+- `orchestrator.dispatchedCount: 1`
+- `orchestrator.pendingCount: 1`
+- `orchestrator.notificationCount: 1`
+
+Do **not** require a final external delivery ack for this smoke path.
+
+## C. Full package test run
+
+From repo root:
+
+```bash
+cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin
+npm --prefix plugins/reporting-governance test
+```
+
+This currently runs the package's declared `node --test` suite, including:
+
+- package structure
+- descriptor entrypoint resolution
+- policy evaluator
+- compatibility preflight
+- profile artifact / generator
+- decision runner / decision store
+- governance contract integration
+- watchdog chain integration
+- orchestrator execution
+- runtime-integrated flow
+- exports boundary enforcement
+- packed consumer install smoke
+
+## D. Clean-consumer install proof
+
+If you specifically need install proof through the distributed tarball boundary:
+
+```bash
+cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin/plugins/reporting-governance
+npm pack
+mkdir -p /tmp/reporting-governance-consumer
+cd /tmp/reporting-governance-consumer
+npm init -y
+npm install /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin/plugins/reporting-governance/openclaw-plugin-reporting-governance-0.1.0-mainline.tgz
+```
+
+Then verify public exports:
+
+```bash
+node --input-type=module --eval '
+import * as plugin from "@openclaw/plugin-reporting-governance";
+import { runOrchestratorAdapter } from "@openclaw/plugin-reporting-governance/adapters/orchestrator";
+process.stdout.write(JSON.stringify({
+  packageName: plugin.packageName,
+  hasRunWatchdogChain: typeof plugin.runWatchdogChain,
+  hasRunOrchestratorAdapter: typeof runOrchestratorAdapter
+}, null, 2));
+'
+```
+
+Expected shape:
+
+```json
+{
+  "packageName": "@openclaw/plugin-reporting-governance",
+  "hasRunWatchdogChain": "function",
+  "hasRunOrchestratorAdapter": "function"
+}
+```
+
+Then verify the installed bin:
+
+```bash
+./node_modules/.bin/reporting-governance-package-smoke --compact
+```
+
+Expected shape:
+
+- valid JSON output
+- `ok: true`
+- `orchestrator.ok: true`
+
+---
+
+## 5. Exact verification commands
+
+Use these commands exactly for the current package state.
+
+### Minimal smoke
+
+```bash
+npm --prefix plugins/reporting-governance run smoke
+```
+
+### Full package suite
+
+```bash
+npm --prefix plugins/reporting-governance test
+```
+
+### Focused pack/install/export proof
+
+```bash
+node --test plugins/reporting-governance/test/exports-boundary.integration.test.mjs plugins/reporting-governance/test/packed-consumer-install.smoke.test.mjs
+```
+
+### Focused runtime proof
+
+```bash
+node --test plugins/reporting-governance/test/watchdog-chain.integration.test.mjs plugins/reporting-governance/test/runtime-integrated.integration.test.mjs
+```
+
+### Public export probe in current repo
+
+```bash
+node --input-type=module --eval '
+import * as plugin from "./plugins/reporting-governance/src/index.mjs";
+process.stdout.write(JSON.stringify({
+  packageName: plugin.packageName,
+  packageVersion: plugin.packageVersion,
+  hasEvaluatePolicyPack: typeof plugin.evaluatePolicyPack,
+  hasRunWatchdogChain: typeof plugin.runWatchdogChain
+}, null, 2));
+'
+```
+
+Note: this last command is a **repo-source probe**, not proof of package export boundaries. Use the consumer/tarball tests for boundary proof.
+
+---
+
+## 6. Safe import/use map
+
+These are the **safe public JS entrypoints** today, because they are declared in `package.json#exports`.
+
+### Root export
+
+```js
+import {
+  packageName,
+  packageVersion,
+  evaluatePolicyPack,
+  evaluatePolicies,
+  planDecisionExecution,
+  executeGovernanceContract,
+  executeRuntimeIntegratedGovernance,
+  runCompatibilityPreflight,
+  createRuntimeBinding,
+  runWatchdogAdapter,
+  runDispatcherAdapter,
+  runBridgeSupervisorAdapter,
+  runSenderBindingAdapter,
+  runOrchestratorAdapter,
+  runWatchdogChain,
+  createDecisionRecordArtifact,
+  createDecisionRecordFileName,
+  createFileDecisionStore,
+  validateDecisionRecordArtifact,
+} from '@openclaw/plugin-reporting-governance';
+```
+
+### Adapter barrel
+
+```js
+import {
+  runWatchdogAdapter,
+  runDispatcherAdapter,
+  runBridgeSupervisorAdapter,
+  runSenderBindingAdapter,
+  runOrchestratorAdapter,
+} from '@openclaw/plugin-reporting-governance/adapters';
+```
+
+### Declared leaf adapter subpaths
+
+```js
+import { runWatchdogAdapter } from '@openclaw/plugin-reporting-governance/adapters/watchdog';
+import { runDispatcherAdapter } from '@openclaw/plugin-reporting-governance/adapters/dispatcher';
+import { runBridgeSupervisorAdapter } from '@openclaw/plugin-reporting-governance/adapters/bridge-supervisor';
+import { runSenderBindingAdapter } from '@openclaw/plugin-reporting-governance/adapters/sender-binding';
+import { runOrchestratorAdapter } from '@openclaw/plugin-reporting-governance/adapters/orchestrator';
+```
+
+### Declared script-like subpath
+
+```js
+import '@openclaw/plugin-reporting-governance/package-smoke';
+```
+
+This subpath points to the package smoke script entry file, but in most cases you should prefer the CLI/bin or npm script rather than importing it as a library dependency.
+
+---
+
+## 7. Unsafe imports: do not assume these are supported
+
+Do **not** treat these as stable package API:
+
+```js
+import '.../src/core/policy-evaluator.mjs';
+import '.../src/storage/profile-artifact.mjs';
+import '.../src/adapters/runtime-binding.mjs';
+```
+
+And do **not** do this from a consumer:
+
+```js
+import '@openclaw/plugin-reporting-governance/src/storage/profile-artifact.mjs';
+```
+
+Current tests explicitly enforce that some deep paths are **not exported**, including:
+
+- `@openclaw/plugin-reporting-governance/src/storage/profile-artifact.mjs`
+- `@openclaw/plugin-reporting-governance/src/adapters/runtime-binding.mjs`
+
+If you need a capability that exists only behind private files, treat it as **not yet public**.
+
+---
+
+## 8. Current boundaries and what not to assume
+
+Another AI agent should keep these boundaries explicit.
+
+### Do not assume stable API beyond declared exports
+
+This is still:
+
+- version `0.1.0-mainline`
+- pre-1.0
+- surface-tightening
+
+### Do not assume full runtime enforcement
+
+Current strongest path is:
+
+```text
+watchdog -> queue -> dispatcher -> bridge -> sender binding -> pending/blocked/acked truth
+```
+
+This does **not** mean every governance decision in the project is already wired into generalized runtime interception.
+
+### Do not assume external send success
+
+The package is intentionally honest about partial completion. In current smoke/integration flows, a result that stays pending is often the **correct** result.
+
+### Do not assume repo-private files are package API
+
+Files existing under `src/`, `storage/`, or package-local docs do not automatically become public imports.
+
+### Do not assume docs/ or state/ are shipped in tarball
+
+The tarball tests explicitly reject obvious junk in the packed artifact, including:
+
+- nested `.tgz`
+- `state/`
+- `docs/`
+- `node_modules/`
+
+So if you need something at runtime, confirm it ships in `files` and/or is reachable through declared exports.
+
+---
+
+## 9. Where to use this package safely
+
+Use it safely in these ways today:
+
+### Safe use case A — verification/CI
+
+Use the package to prove:
+
+- package export boundaries
+- tarball installability
+- profile artifact generation path
+- watchdog notification truth behavior
+
+### Safe use case B — reference runtime composition
+
+Use `runOrchestratorAdapter(...)` or `runWatchdogChain(...)` as the current package-home entry to the OpenClaw watchdog reference chain.
+
+### Safe use case C — governance core experiments behind root exports
+
+Use root-exported functions such as:
+
+- `evaluatePolicyPack(...)`
+- `planDecisionExecution(...)`
+- `executeGovernanceContract(...)`
+- `executeRuntimeIntegratedGovernance(...)`
+- `runCompatibilityPreflight(...)`
+
+Only if you accept the current pre-1.0 compatibility posture.
+
+### Avoid for now
+
+Avoid treating it as:
+
+- a fully generalized governance SDK
+- a production deployment installer
+- a stable long-term public API without version pinning and revalidation
+
+---
+
+## 10. Recommended reading order for an AI agent
+
+If you need to understand before changing anything:
+
+1. `plugins/reporting-governance/package.json`
+2. `plugins/reporting-governance/README.md`
+3. this file: `plugins/reporting-governance/INSTALL.md`
+4. `plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md`
+5. `plugins/reporting-governance/test/exports-boundary.integration.test.mjs`
+6. `plugins/reporting-governance/test/packed-consumer-install.smoke.test.mjs`
+7. `plugins/reporting-governance/test/runtime-integrated.integration.test.mjs`
+
+That order keeps you aligned to actual shipped boundary + actual verification.
+
+---
+
+## 11. One-command checklist for current repo state
+
+From repo root:
+
+```bash
+npm --prefix plugins/reporting-governance install && npm --prefix plugins/reporting-governance test && npm --prefix plugins/reporting-governance run smoke
+```
+
+Interpretation:
+
+- if install succeeds
+- and tests pass
+- and smoke returns `ok: true`
+
+then the current package is installed and verified at the level this repo currently promises.
+
+That is the correct claim.
+
+A stronger claim such as "production-ready installer complete" would be inaccurate.
diff --git a/plugins/reporting-governance/README.md b/plugins/reporting-governance/README.md
index 4f5f336..b7235ec 100644
--- a/plugins/reporting-governance/README.md
+++ b/plugins/reporting-governance/README.md
@@ -103,6 +103,12 @@ npm --prefix plugins/reporting-governance test
 npm --prefix plugins/reporting-governance run smoke
 ```
 
+若你是另一個 AI agent，要照目前 package 真實邊界安裝/驗證，請直接讀：
+
+- `plugins/reporting-governance/INSTALL.md`
+
+這份文件會對齊目前 `exports`、smoke、tarball install test、以及「哪些不能假設」的邊界。
+
 #### 當作程式依賴使用
 
 優先只依賴：
@@ -180,6 +186,10 @@ Run tests:
 npm test
 ```
 
+For an exact AI-agent-facing install/verify flow, read:
+
+- `plugins/reporting-governance/INSTALL.md`
+
 ### Practical install/use guidance
 
 Use public exports only: