reporting-governance-plugin/docs/specs/reporting-governance-capability-descriptor.md

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:

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

The canonical validation schema remains under:

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:

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:

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:

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:

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