reporting-governance-plugin/plugins/reporting-governance/INSTALL.md

@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:

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:

cd /home/alice/.openclaw/workspace/.worktrees/reporting-governance-plugin/plugins/reporting-governance
npm pack

That produces a tarball like:

openclaw-plugin-reporting-governance-0.1.0-mainline.tgz

Then in a separate consumer directory:

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:

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:

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:

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:

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:

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:

{
  "packageName": "@openclaw/plugin-reporting-governance",
  "hasRunWatchdogChain": "function",
  "hasRunOrchestratorAdapter": "function"
}

Then verify the installed bin:

./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

npm --prefix plugins/reporting-governance run smoke

Full package suite

npm --prefix plugins/reporting-governance test

Focused pack/install/export proof

node --test plugins/reporting-governance/test/exports-boundary.integration.test.mjs plugins/reporting-governance/test/packed-consumer-install.smoke.test.mjs

Focused runtime proof

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

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

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

import {
  runWatchdogAdapter,
  runDispatcherAdapter,
  runBridgeSupervisorAdapter,
  runSenderBindingAdapter,
  runOrchestratorAdapter,
} from '@openclaw/plugin-reporting-governance/adapters';

Declared leaf adapter subpaths

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

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:

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:

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:

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:

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.