docs: add reporting governance install guide
This commit is contained in:
Eve
492
plugins/reporting-governance/INSTALL.md
Normal file
492
plugins/reporting-governance/INSTALL.md
Normal file
@@ -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.
|
||||||
@@ -103,6 +103,12 @@ npm --prefix plugins/reporting-governance test
|
|||||||
npm --prefix plugins/reporting-governance run smoke
|
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
|
npm test
|
||||||
```
|
```
|
||||||
|
|
||||||
|
For an exact AI-agent-facing install/verify flow, read:
|
||||||
|
|
||||||
|
- `plugins/reporting-governance/INSTALL.md`
|
||||||
|
|
||||||
### Practical install/use guidance
|
### Practical install/use guidance
|
||||||
|
|
||||||
Use public exports only:
|
Use public exports only:
|
||||||
|
|||||||
Reference in New Issue
Block a user