# Reporting Governance Capability Descriptor

## Purpose

This document defines the **capability descriptor** for the reporting-governance plugin.

It turns runtime support from implied prose into a machine-readable contract that can be:

- validated before deployment
- checked against deployment profiles
- attached to audit bundles
- used by the next implementation stage for evaluator / decision-runner wiring

This spec is intentionally the next step after:

- `docs/specs/reporting-governance-adapter-interface.md`
- `docs/specs/reporting-governance-deployment-model.md`
- `schemas/reporting-governance/adapter-capabilities.schema.json`

The adapter-interface spec defines **what adapters must be able to describe**.
This capability-descriptor spec defines **how one concrete runtime publishes that description as a package artifact**.

## Why this exists now

The current mainline already has:

- canonical event / evidence / decision / policy-pack contracts
- deployment profiles
- a validated watchdog reference runtime composition

But the plugin still lacks one package-level truth source answering:

- which runtime surfaces exist in this deployment
- which enforcement actions are actually available
- whether the runtime can only queue, can bridge, or can truly ack final delivery
- which storage and receipt guarantees are real

Without a capability descriptor, the next evaluator / decision-runner stage would still have to guess runtime powers from docs and scripts.

## Scope

This spec defines:

1. the package role of a capability descriptor
2. the minimum descriptor shape
3. the OpenClaw reference descriptor for the watchdog composition
4. package-boundary implications for `core/`, `adapters/`, `storage/`, `artifacts/`, and reference implementations
5. how evaluator / decision-runner should consume descriptor data next

This spec does **not** define:

- the policy evaluator itself
- the deployment-profile schema
- one mandatory programming language API
- the full audit export manifest format

## Mainline decision

The reporting-governance plugin now uses this package distinction:

- **schema**: validation contract for descriptor shape
- **capability descriptor**: one concrete runtime claim validated by that schema
- **deployment profile**: requested operating posture
- **adapter modules**: implementation surfaces that may satisfy some or all requested posture

In short:

- profiles express **desired behavior**
- capability descriptors express **actual runtime power**
- evaluator / decision-runner must operate from the intersection of both

## Package location

Capability descriptors belong under the plugin package boundary:

```text
plugins/reporting-governance/
  capabilities/
    openclaw-watchdog-reference.json
  examples/
    openclaw-watchdog-reference.descriptor.example.json
```

The canonical validation schema remains under:

```text
schemas/reporting-governance/capability-descriptor.schema.json
```

This keeps the split clear:

- `schemas/` = canonical validation contracts
- `plugins/reporting-governance/capabilities/` = package-owned runtime declarations; `runtime.entrypoint: "scripts/..."` is resolved relative to the package root
- `plugins/reporting-governance/examples/` = copyable reference inputs using the same package-root-relative `scripts/...` semantics

## Descriptor responsibilities

A capability descriptor must answer five questions.

### 1. What runtime is this?

Examples:

- `openclaw`
- future host runtimes
- future embedded or CI-only runtimes

### 2. Which adapter surfaces are present?

Examples:

- `watchdog`
- `queue`
- `dispatcher`
- `bridge`
- `sender_binding`
- `orchestrator`

### 3. Which governance actions are truly available?

Examples:

- block transition
- rewrite message
- annotate placeholder
- force checkpoint
- request review
- downgrade status
- escalate

### 4. What notification truth model is supported?

At minimum, whether the runtime distinguishes:

- `prepared`
- `queued`
- `dispatched`
- `pending_external_send`
- `acked`
- `blocked`

### 5. What persistence and audit guarantees exist?

Examples:

- can events be persisted?
- can receipts be written?
- can original attempted messages be preserved?
- can decision outputs be stored yet, or is that still pending the next phase?

## Descriptor shape

The canonical descriptor shape is validated by:

- `schemas/reporting-governance/capability-descriptor.schema.json`

The schema reuses the same top-level resource model already established for adapter capabilities:

- `apiVersion`
- `kind`
- `metadata`
- `runtime`
- `compatibility`
- `capabilities`
- optional `defaults`
- optional `notes`

## OpenClaw reference descriptor

The first package-mainline descriptor is the **OpenClaw watchdog reference composition**.

Descriptor identity:

- runtime: `openclaw`
- mode: `hybrid`
- runtime `entrypoint`: `scripts/watchdog_auto_notify_orchestrator.mjs` resolved from `plugins/reporting-governance/` package root
- surfaces:
  - `watchdog`
  - `queue`
  - `dispatcher`
  - `bridge`
  - `sender_binding`
  - `orchestrator`
  - `scheduler`
  - `storage`

### What it must claim

This reference descriptor should claim support for:

- watchdog overdue observation
- canonical watchdog event generation
- queue-backed operator notices
- spool/handoff dispatch
- bridge-supervised sender invocation
- truthful `acked | blocked | pending_external_send` outcomes
- persistence of events, evidence, queue items, spool artifacts, and receipts

### What it should not overclaim

At this stage, the reference descriptor should **not** overclaim:

- full inline hook interception as complete
- final delivery proof in every deployment
- fully packaged decision persistence if the evaluator / decision runner is not extracted yet
- all completion-claim governance paths

This is why some support levels remain `partial` rather than `full`.

## Package boundary decisions

This spec fixes the package skeleton boundaries needed for the next implementation round.

## `src/core/`

`core/` contains runtime-agnostic governance logic.

It should own:

- canonical event normalization
- evidence building / evidence-reference shaping
- policy evaluation
- decision execution planning
- capability/profile compatibility checks

It should **not** own:

- cron installation
- filesystem-specific queue scanning loops
- OpenClaw sender invocations
- repo-local wrapper scripts

Minimum package direction:

```text
src/core/
  capability-profile-compatibility.mjs
  decision-runner.mjs
  evidence-builder.mjs
  event-normalizer.mjs
  policy-evaluator.mjs
```

## `src/adapters/`

`adapters/` contains runtime-facing integration modules.

It should own:

- OpenClaw watchdog adapter wrapper
- queue / dispatcher adapter wrapper
- bridge adapter wrapper
- sender-binding adapter wrapper
- orchestrator adapter wrapper

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

It should **not** absorb canonical policy semantics that belong in `core/`.

Minimum package direction:

```text
src/adapters/
  bridge-adapter.mjs
  dispatcher-adapter.mjs
  orchestrator-adapter.mjs
  sender-binding-adapter.mjs
  watchdog-adapter.mjs
```

## `src/storage/`

`storage/` contains package-level readers/writers for durable governance artifacts.

It should own contracts for:

- event store
- evidence store
- receipt store
- queue-item store
- spool-artifact store
- future decision store
- future audit export manifest support

It should not define governance meaning; it only persists governed artifacts.

Minimum package direction:

```text
src/storage/
  decision-store.mjs
  event-store.mjs
  evidence-store.mjs
  queue-store.mjs
  receipt-store.mjs
  spool-store.mjs
```

## `artifacts/` boundary

The plugin package does not need a required checked-in `artifacts/` source directory yet.
Instead, **artifacts** are the runtime outputs produced by storage contracts and runtime bindings.

For current OpenClaw reference behavior, the artifact classes are still represented by runtime directories such as:

- `state/long-task-watchdog/`
- `state/long-task-watchdog-events/`
- `state/operator-notify-queue/`
- `state/operator-notify-dispatch-spool/`
- `state/operator-notify-bridge-receipts/`
- `state/operator-notify-sender-attempts/`

Mainline interpretation:

- these are **runtime artifact locations**
- package `src/storage/` should become the code boundary that reads/writes them
- future audit export bundles should consume these classes through storage abstractions rather than raw script coupling

## Reference implementations boundary

Reference implementations are executable, runtime-specific realizations of the package contracts.

For this MVP stage, the main reference implementation is the watchdog chain described in:

- `CODER_WATCHDOG_REPORT.md`

Within the package skeleton, it belongs under:

```text
plugins/reporting-governance/src/reference/openclaw-watchdog-chain.md
```

and is represented in code-adjacent terms by:

- `src/adapters/watchdog-adapter.mjs`
- `src/adapters/dispatcher-adapter.mjs`
- `src/adapters/bridge-adapter.mjs`
- `src/adapters/sender-binding-adapter.mjs`
- `src/adapters/orchestrator-adapter.mjs`

This means the **watchdog reference runtime composition is categorized as a reference implementation, not as plugin core**.

That is the key boundary that keeps the next evaluator / decision-runner work clean.

## Consumption by evaluator / decision runner

The next implementation stage should use the capability descriptor in two places.

### 1. Preflight compatibility

Before executing a policy action, the runtime should compare:

- requested profile behavior
- policy-required action
- actual adapter capability support

Examples:

- if `force_checkpoint` is requested but only queue/bridge notice is available, downgrade to honest deferred notice + receipt
- if direct send is requested but only `pending_external_send` is supportable, preserve the weaker truthful state

### 2. Action planning

The decision runner should use capability support to choose execution paths such as:

- inline block
- queue-only notice
- bridge-mediated send
- status downgrade + review request
- blocked-with-gap receipt

This keeps the evaluator portable and avoids encoding OpenClaw-specific assumptions inside `core/`.

## Verification expectations

Capability descriptor work should be verified at minimum by:

1. schema validation of the descriptor JSON
2. package skeleton presence checks
3. consistency review against:
   - adapter-interface spec
   - deployment model
   - roadmap lane terminology

## Minimal synchronization with roadmap and deployment model

This capability-descriptor step advances:

- roadmap lane 3: package extraction
- roadmap lane 4: capability/profile/deployment binding

The deployment model does not need redesign.
It only needs to recognize that the first concrete package artifact for this lane is now:

- a package-owned OpenClaw capability descriptor
- plus the minimal package skeleton that gives it a stable home

## Summary

This spec establishes the reporting-governance capability descriptor as the package-level truth contract between:

- runtime-specific adapter power
- deployment-profile intent
- future evaluator / decision-runner behavior

It also fixes the package boundaries needed for the next phase:

- `core/` = runtime-agnostic governance logic
- `adapters/` = runtime integration surfaces
- `storage/` = durable artifact I/O contracts
- runtime `artifacts/` = produced outputs, not core source
- watchdog chain = reference implementation housed under the package skeleton, not plugin core