# 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

```text
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:

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