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

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

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.

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, but the remaining enforcement surface is still intentionally honest about adapter gaps.