# @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.