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

Reporting Governance Plugin

This package is the emerging package boundary for the reporting-governance mainline.

Current purpose:

• give the plugin a real package home
• publish capability descriptors as package artifacts
• fix boundaries between core/, adapters/, storage/, and reference implementations
• prepare the next implementation round for evaluator / decision-runner extraction
• provide a minimal package-level policy evaluator and decision runner skeleton that can be verified in isolation

Package skeleton

plugins/reporting-governance/
  package.json
  README.md
  capabilities/
  docs/
  examples/
  src/
    core/
      index.mjs
      policy-evaluator.mjs
      decision-runner.mjs
      execute-governance-contract.mjs
    adapters/
    storage/
    reference/
    index.mjs
  test/

Boundary rules

src/core/

Runtime-agnostic governance logic:

• canonical event normalization
• evidence building
• policy evaluation
• decision running
• capability/profile compatibility

src/adapters/

Runtime-facing adapter modules:

• watchdog adapter
• dispatcher adapter
• bridge adapter
• sender-binding adapter
• orchestrator adapter

These may initially wrap existing repo scripts while extraction is still in progress.

src/storage/

Durable I/O contracts for governance artifacts:

• events
• evidence
• queue items
• spool artifacts
• receipts
• future decisions / audit manifests

src/reference/

Reference runtime compositions and migration notes.

The watchdog reference runtime composition belongs here, as a reference implementation for OpenClaw rather than as package core logic.

Public surface and compatibility

Current public package surface is intentionally narrow:

• root export: @openclaw/plugin-reporting-governance
• adapter exports:
  • @openclaw/plugin-reporting-governance/adapters
  • @openclaw/plugin-reporting-governance/adapters/watchdog
  • @openclaw/plugin-reporting-governance/adapters/dispatcher
  • @openclaw/plugin-reporting-governance/adapters/bridge-supervisor
  • @openclaw/plugin-reporting-governance/adapters/sender-binding
  • @openclaw/plugin-reporting-governance/adapters/orchestrator

What is currently exposed from the root export:

• evaluatePolicyPack(...)
• evaluatePolicies(...)
• planDecisionExecution(...)
• executeGovernanceContract(...)
• package metadata helpers such as packageName
• package-owned adapter entrypoints and runWatchdogChain(...)

Compatibility posture for this slice:

• 0.1.0-mainline should be treated as pre-1.0, surface-tightening phase.
• Deep imports into src/ are not supported API even if files exist in-repo.
• Tests now explicitly enforce that private paths like src/adapters/runtime-binding.mjs stay outside exports.
• Adding a symbol to a file under src/ does not mean it is public unless wired through package exports.
• Future tightening of root/adapters exports may still be a breaking change until a stable 1.0 surface is declared.

Practical migration rule:

• depend on package root exports or declared adapter subpaths only
• do not couple runtime integrations to repo-private file paths
• treat capability descriptors and schemas as package artifacts, but not as guaranteed JS import entrypoints unless exported later

Current reference composition

The current reference composition is the OpenClaw watchdog chain:

watchdog -> queue -> dispatcher -> bridge -> sender binding -> acked|blocked|pending_external_send

Package-home documentation:

• src/reference/openclaw-watchdog-chain.md
• capabilities/openclaw-watchdog-reference.json

Mainline background specs remain in:

• docs/specs/reporting-governance-capability-descriptor.md
• docs/specs/reporting-governance-adapter-interface.md
• docs/specs/reporting-governance-deployment-model.md

Minimal evaluator / decision runner now included

The current package now includes a small but runnable core/ implementation:

• src/core/policy-evaluator.mjs
• src/core/decision-runner.mjs
• src/core/execute-governance-contract.mjs
• src/core/index.mjs

Current package-core responsibilities:

• normalize evaluator facts from canonical event payload + evidence + local context
• match policy-pack rules by trigger and structured conditions
• produce canonical decision-model shaped decision objects
• choose the highest-precedence decision when multiple rules match
• convert a canonical decision into an execution plan, enforcement intent, and receipt skeleton
• truthfully degrade unsupported enforcement paths based on the capability descriptor
• provide one minimal contract path from capability descriptor -> policy decision -> execution planning

Still runtime-adapter responsibility at this stage:

• intercepting real outgoing messages or status transitions inline
• actually sending operator notices
• acking final delivery to external channels
• persisting decisions/receipts into a production decision store
• installing schedulers / watchdog loops / bridge sender bindings

This means core/ now owns evaluation and planning semantics, while adapters still own actual enforcement side effects.

Minimal end-to-end contract slice now included

This slice now has one small but testable contract path:

1. capability descriptor advertises real enforcement support
2. policy evaluator emits a canonical decision from event/evidence/context
3. decision runner converts that decision into execution planning
4. the result declares:
   • adapter-dispatch actions required
   • package-core actions possible locally
   • blocked mandatory actions when capability support is missing
   • truthful delivery / receipt state

This is intentionally planning-level end-to-end, not full live inline interception. It proves contract alignment without pretending all runtime enforcement is already extracted.

Not yet included

This package still does not claim full implementation of:

• generalized event normalization modules
• generalized evidence builder modules
• production decision persistence
• complete rewrite / placeholder / review / status-downgrade adapter execution
• non-watchdog full runtime governance interception

It now provides the first package-mainline evaluator / decision-runner core, plus a minimal end-to-end contract proof, but the remaining enforcement surface is still intentionally honest about adapter gaps.