reporting-governance-plugin/docs/specs/reporting-governance-deployment-model.md

# Reporting Governance Deployment Model

## Purpose

This document defines how the reporting-governance plugin is packaged, deployed, configured, and audited across different runtimes and operating styles.

It is the mainline bridge between:

- the canonical governance contracts already defined in the event, evidence, decision, policy-pack, and adapter-interface specs
- the now-proven watchdog / queue / dispatcher / bridge / sender / orchestrator reference chain
- the practical need to ship the plugin as a portable bundle instead of a repo-local collection of scripts and conventions

The deployment model exists to answer five operational questions clearly:

1. What exactly is the **plugin package**?
2. What exactly is the **runtime adapter**?
3. What exactly is a **profile override**?
4. What exactly is a **portable audit artifact**?
5. How does the completed watchdog chain fit into deployable plugin architecture rather than remaining implementation glue?

## Relationship to other mainline specs

This document builds on:

- `docs/architecture/agent-reporting-governance-plugin.md`
- `docs/specs/reporting-governance-event-model.md`
- `docs/specs/reporting-governance-evidence-model.md`
- `docs/specs/reporting-governance-decision-model.md`
- `docs/specs/reporting-governance-policy-packs.md`
- `docs/specs/reporting-governance-adapter-interface.md`
- `CODER_WATCHDOG_REPORT.md`

Interpretation boundary:

- the **event model** defines canonical inputs
- the **evidence model** defines what claims can be supported
- the **decision model** defines canonical governance outcomes
- the **policy-pack spec** defines reusable rule bundles
- the **adapter-interface spec** defines runtime integration seams
- the **deployment model** defines how those pieces are assembled into a shippable and portable operational product

## Design goals

The deployment model must:

- make plugin distribution independent from one workspace prompt setup
- support multiple deployment shapes without forking the core governance model
- preserve honest delivery semantics for operator notifications
- make watchdog-driven governance a first-class deployable feature
- keep environment-specific wiring in profiles rather than in the core package
- produce audit artifacts that remain meaningful after files move across machines or runtimes

## Core deployment concepts

## 1. Plugin package

A **plugin package** is the versioned distributable unit of the reporting-governance product.

It includes the portable governance logic and declarative artifacts required to install or extract the plugin into a target environment.

At minimum, a plugin package should contain:

- canonical schemas
- policy packs
- adapter modules or adapter entrypoints
- capability descriptors
- deployment profile definitions or profile examples
- audit-artifact conventions
- version metadata
- optional reference scripts used as migration bridge adapters

A plugin package is **not** the same thing as a live runtime process.
It is the deployable bundle from which runtime behavior is assembled.

### Plugin package responsibilities

A plugin package should be responsible for shipping:

- stable governance contracts
- reusable enforcement behavior
- adapter composition points
- default profile inputs
- compatibility metadata
- upgrade/downgrade version boundaries

A plugin package should **not** hardcode:

- one operator target
- one sender credential
- one cron schedule for every environment
- one storage directory root
- one privileged send runtime

Those belong in runtime bindings and profile overrides.

## 2. Runtime adapter

A **runtime adapter** is the environment-facing integration layer that turns local runtime facts into canonical governance behavior.

It is responsible for observing, normalizing, evaluating, enforcing, and receipting according to the adapter interface.

Runtime adapters may be implemented as:

- hook interceptors
- watchdog runners
- queue/dispatcher bridges
- sender bindings
- orchestrators
- mixed compositions of the above

The runtime adapter is where deployment reality enters the plugin.

### Runtime adapter responsibilities in deployment terms

In deployment terms, the adapter answers:

- where task and subagent facts come from
- how canonical events are emitted
- where evidence and receipts are stored
- whether operator notifications can be sent directly or only handed off
- how watchdog schedules are installed or invoked
- which capabilities are truly available in this environment

## 3. Profile override

A **profile override** is an environment-specific configuration layer applied on top of the plugin package defaults.

Its purpose is to bind the portable package to a concrete operating mode without rewriting core specs or forking policy packs.

A profile override may change things like:

- enabled policy packs
- severity thresholds
- required checkpoint cadence
- whether direct sender integration is allowed
- whether dry-run or queue-only notification mode is required
- storage roots and retention windows
- operator channel defaults
- escalation expectations
- audit export behavior

A profile override must not redefine canonical event semantics or falsify capability declarations.

### Hard rule

A profile override can tune enforcement and wiring, but it cannot turn:

- `dispatched` into `acked`
- weak evidence into verified evidence
- unsupported runtime capability into declared support

## 4. Portable audit artifact

A **portable audit artifact** is a versioned artifact that preserves governance-relevant truth across runtime boundaries and machine boundaries.

It should remain interpretable even when copied outside the originating runtime.

Portable audit artifacts include:

- canonical event files
- evidence records
- policy decision outputs
- queue items
- dispatch spool artifacts
- bridge receipts
- sender-attempt receipts
- capability descriptors
- deployment-profile snapshots captured at execution time

### Required properties of portable audit artifacts

Portable audit artifacts should be:

- content-addressable or hashable when practical
- timestamped
- correlated by `task_id` and `correlation_id` when applicable
- explicit about runtime boundary and delivery state
- self-describing enough for later audit without prompt context
- safe to move between machines without losing meaning

Portable does **not** mean globally self-sufficient for every secret or binary dependency.
It means the governance record remains intelligible and reviewable after export.

## Deployment layers

The plugin should be deployed as four distinct layers.

### Layer A: Core package layer

Contains:

- schemas
- core evaluation logic
- policy packs
- adapter contracts
- profile schema and examples

This layer should be runtime-agnostic.

### Layer B: Adapter layer

Contains runtime-specific integration modules such as:

- hook adapter
- watchdog adapter
- queue adapter
- dispatcher adapter
- bridge adapter
- sender-binding adapter
- orchestrator adapter

This layer is where environment capability truth is declared.

### Layer C: Profile layer

Contains versioned deployment profiles that select and tune behaviors for concrete operating styles.

Examples in this repo:

- `profiles/strict-manager-mode.yaml`
- `profiles/standard-team-mode.yaml`
- `profiles/minimal-solo-mode.yaml`

### Layer D: Runtime binding layer

Contains the environment-local bindings that cannot be assumed portable by default, such as:

- cron installation or scheduler registration
- actual sender commands
- local channel / target identities
- filesystem roots
- runtime secrets
- privileged execution boundaries

## Reference package structure

A deployable mainline package should converge toward a structure like:

```text
plugins/reporting-governance/
  package-manifest.json
  src/
    core/
    adapters/
    storage/
  schemas/
    reporting-governance/
  policy-packs/
  profiles/
  capabilities/
  docs/
  examples/
```

Minimum package content expectations:

| Path area | Required | Purpose |
| --- | --- | --- |
| `schemas/` | yes | validation contracts for events, evidence, decisions, capabilities, profiles |
| `policy-packs/` | yes | reusable governance policy bundles |
| `profiles/` | yes | deployable mode presets and overrides |
| `capabilities/` | yes | runtime adapter capability declarations |
| `src/adapters/` or equivalent | yes | integration surfaces for hook/watchdog/queue/bridge/sender/orchestrator |
| `docs/` | recommended | operator/reviewer-facing deployment and audit explanation |
| `examples/` | recommended | sample configs and receipts |

## Deployment unit boundaries

To avoid architectural drift, the deployment model distinguishes these units.

### Package unit

Versioned distribution boundary.

Examples:

- plugin release tarball
- internal package directory snapshot
- signed artifact bundle

### Profile unit

Versioned configuration preset.

Examples:

- strict manager mode
- team default mode
- solo minimal mode

### Runtime instance unit

Actual live deployment of the package plus one selected profile plus local bindings.

Examples:

- an OpenClaw manager workspace with queue + bridge + direct send
- a CI validation runtime with queue-only behavior
- a solo workstation using dry-run watchdog receipts for self-review

### Audit unit

Exportable governance record set for one task, time window, or incident.

Examples:

- all artifacts for a missed checkpoint incident
- all receipts for one watchdog firing
- review bundle for one claimed-complete task

## How the watchdog chain fits the deployment model

The completed watchdog chain is now treated as the first reference deployment composition.

### Reference composition

```text
watchdog runner
  -> canonical event
  -> operator notification queue
  -> dispatcher spool handoff
  -> bridge supervisor
  -> sender binding
  -> acked | blocked | pending_external_send receipt
```

### Deployment interpretation

| Runtime piece | Deployment role |
| --- | --- |
| `scripts/long_task_watchdog.mjs` | watchdog adapter executable in the deployed package |
| `state/long-task-watchdog/*.json` | portable runtime-artifact evidence |
| `state/long-task-watchdog-events/*.json` | portable canonical event artifacts |
| `state/operator-notify-queue/*.json` | queue-layer audit artifacts and deferred notice obligations |
| `scripts/operator_notify_dispatcher.mjs` | dispatcher adapter for handoff generation |
| `state/operator-notify-dispatch-spool/*.json` | spool/handoff audit artifacts proving dispatch, not delivery |
| `scripts/operator_notify_bridge_supervisor.mjs` | bridge adapter for upper-runtime send boundary |
| `scripts/operator_notify_sender_binding.mjs` | sender-binding adapter selectable by deployment profile |
| `state/operator-notify-bridge-receipts/*.json` | portable delivery-state receipts |
| `scripts/watchdog_auto_notify_orchestrator.mjs` | orchestrator adapter and single deployment entrypoint |
| cron installer / wrapper | runtime binding for scheduled execution |

### Mainline conclusion

The watchdog chain is no longer just an implementation repair.
Within this deployment model it becomes:

- the first packageable adapter composition
- the default deployable path for forced operator-notice recovery
- the baseline proof for portable audit artifact design
- the first profile-sensitive notification pipeline

## Delivery truth model in deployment terms

Deployment profiles and package defaults MUST preserve the adapter truth model.

### Allowed operator-notice states

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

### Hard deployment rules

1. A package may support queue creation without direct send.
2. A runtime adapter may support bridge handoff without final ack proof.
3. A profile may intentionally keep the system in dry-run or pending mode.
4. No deployment profile may claim final human-visible delivery unless `acked` evidence exists.

This is the deployment-level guardrail that keeps profile tuning from reintroducing fake reporting.

## Deployment profile model

A deployment profile is a versioned YAML artifact that binds package defaults to an operating mode.

### Required top-level shape

```yaml
apiVersion: reporting-governance/v1alpha1
kind: DeploymentProfile
metadata:
  id: strict-manager-mode
  version: 1.0.0
  runtime: openclaw
spec:
  package:
    pluginVersion: 0.1.0-mainline
  adapters:
    orchestrator:
      enabled: true
```

### Required profile sections

| Section | Purpose |
| --- | --- |
| `metadata` | profile identity and versioning |
| `spec.package` | package compatibility and expected plugin version |
| `spec.policies` | enabled packs, thresholds, overrides |
| `spec.adapters` | enabled adapter surfaces and runtime bindings |
| `spec.notifications` | queue / bridge / sender expectations |
| `spec.audit` | artifact retention/export expectations |
| `spec.capability_expectations` | minimum runtime capabilities required or optional |

## Profile inheritance and override semantics

Profiles should be read as:

1. package defaults
2. adapter defaults
3. selected profile values
4. environment-local secrets and targets

Override rules:

- profiles may narrow or strengthen policy
- profiles may relax only where the policy model explicitly allows tuning
- profiles may switch sender modes (`dry-run`, `shim`, `openclaw-cli`, explicit external command binding)
- profiles may change retention and export defaults
- profiles may not mutate canonical schemas or lie about capability support

## Reference profiles

## 1. Strict manager mode

Use when:

- a primary operator supervises multiple agents
- anti-blackhole reporting is high priority
- direct or ackable operator notification is expected when available
- review and evidence standards should be strong by default

Expected stance:

- all core packs enabled
- watchdog active
- queue + bridge + sender path enabled
- completion claims strongly gated
- placeholder labeling required
- escalation more aggressive

## 2. Standard team mode

Use when:

- a team needs shared governance defaults
- direct send may or may not exist in every environment
- queue-backed visibility is acceptable pending upper-runtime send

Expected stance:

- all core packs enabled
- watchdog active
- queue + dispatcher + bridge enabled
- direct send optional
- `pending_external_send` accepted as honest boundary when sender is unavailable

## 3. Minimal solo mode

Use when:

- one operator mainly wants self-discipline and portable receipts
- direct send is optional or absent
- auditability is still desired without forcing heavy infrastructure

Expected stance:

- essential packs enabled
- watchdog optional but available
- queue/dry-run path acceptable
- escalation lighter
- portable artifacts still required for completion and overdue reporting

## Capability-aware deployment

Every deployment should validate intended profile expectations against actual adapter capabilities.

Questions the deployment layer must ask:

- Can this runtime block completion or dispatch inline?
- Can it only queue a required notice?
- Can it bridge to a privileged sender?
- Can it prove final send with ack receipts?
- Can it schedule watchdog execution?
- Can it export artifacts for later audit?

If a profile asks for stronger behavior than the runtime supports, deployment must fail closed or degrade honestly.

### Safe fallback examples

| Requested behavior | Capability missing | Safe fallback |
| --- | --- | --- |
| direct final send proof | no direct sender or ack path | queue + `pending_external_send` receipt |
| inline completion block | no pre-send hook | `downgrade_status` + forced review notice |
| scheduled watchdog | no scheduler integration | manual orchestrator invocation + explicit capability gap note |
| aggressive escalation | no escalation channel | operator notice with `blocked` or `force_checkpoint` audit trail |

## Portable audit artifact model

The deployment model requires artifact classes that can be exported together.

### Required artifact classes

- canonical events
- evidence records
- decision records
- queue items
- spool artifacts
- bridge receipts
- sender-attempt outputs when available
- profile snapshot or profile identifier
- capability descriptor used at execution time

### Recommended export manifest

A portable audit export should include a manifest like:

```json
{
  "artifact_bundle_version": "1.0.0",
  "plugin_package_version": "0.1.0-mainline",
  "deployment_profile": "standard-team-mode@1.0.0",
  "capability_descriptor": "openclaw-watchdog-reference@1.0.0",
  "task_id": "task-123",
  "correlation_id": "corr-123",
  "artifacts": [
    {"kind": "event", "ref": "state/long-task-watchdog-events/...json"},
    {"kind": "queue", "ref": "state/operator-notify-queue/...json"},
    {"kind": "receipt", "ref": "state/operator-notify-bridge-receipts/...json"}
  ]
}
```

### Why the artifact model matters

This is what makes the plugin portable for:

- peer review
- incident review
- compliance-style audit
- migration between runtime implementations
- proving that a report was queued, blocked, pending, or acked without relying on prompt memory

## Deployment lifecycle

A typical deployment should follow this lifecycle.

### Stage 1: Package selection

Choose plugin package version and compatible schemas/policy packs.

### Stage 2: Capability declaration

Install or generate the runtime capability descriptor.

### Stage 3: Profile selection

Choose one deployment profile and apply environment-local bindings.

### Stage 4: Validation

Validate:

- profile schema
- policy references
- adapter capability compatibility
- storage path writability
- sender-mode compatibility

### Stage 5: Activation

Activate runtime entrypoints such as:

- hook registration
- watchdog scheduler or cron wrapper
- queue/bridge sender boundary
- orchestrator invocation path

### Stage 6: Audit and export

Verify that artifacts can be produced and exported without breaking truth semantics.

## Verification expectations for deployment

A deployment should be verified at four levels.

### Level 1: Artifact/schema validation

Validate:

- event artifacts
- evidence artifacts
- decision outputs
- capability descriptors
- deployment profiles

### Level 2: Surface verification

Verify individual runtime surfaces:

- watchdog creates canonical event + queue item
- dispatcher creates spool and updates queue
- bridge writes truthful receipt
- sender binding preserves `sent|blocked|pending`

### Level 3: Profile verification

Verify that each profile produces the expected enforcement posture.

Examples:

- strict manager mode rejects weak completion signaling
- standard team mode preserves queue/bridge truth without faking ack
- minimal solo mode still produces portable receipts in dry-run

### Level 4: End-to-end deployment verification

Verify orchestrated composition:

- `runner -> queue -> dispatcher -> bridge -> sender -> acked`
- `runner -> queue -> dispatcher -> bridge -> pending_external_send`
- `runner -> queue -> dispatcher -> bridge -> blocked`

These are the deployability checks that convert the plugin from spec-only into package-ready mainline.

## Mainline deployment decisions

This document fixes the following mainline decisions.

1. **The plugin package is the distributable product boundary.**
   Scripts alone are not the architecture; they are transitional adapter implementations inside a package boundary.

2. **Runtime adapters are deployable integration units, not incidental helpers.**
   Hook, watchdog, queue, dispatcher, bridge, sender, and orchestrator surfaces are all valid deployment-facing modules.

3. **Profiles own environment-specific enforcement posture.**
   Different operating modes must be expressed as versioned profiles, not prompt edits or repo forks.

4. **Portable audit artifacts are mandatory, not optional nice-to-haves.**
   Exportable events, queue items, spool artifacts, and receipts are part of the product contract.

5. **Watchdog closure is part of the deployment model.**
   A watchdog deployment is incomplete until the notice path reaches `acked`, `blocked`, or `pending_external_send` honestly.

## Minimal roadmap synchronization

With this document in place, the adapter-interface roadmap item:

- `define deployment profile format once adapter composition is stable`

is now materially advanced.

Mainline next steps should therefore be interpreted as:

1. publish capability descriptor(s) for the OpenClaw reference runtime
2. validate deployment profiles against a profile schema
3. extract reference scripts behind package-level adapter modules
4. add portable audit export manifest support

## Summary

The deployment model turns the reporting-governance plugin into something that can be shipped, installed, tuned, and audited across environments.

It makes four boundaries explicit:

- **plugin package** = distributable governance product
- **runtime adapter** = environment-facing integration layer
- **profile override** = deployment-specific policy and wiring configuration
- **portable audit artifact** = exportable record of what the system observed, decided, attempted, and proved

Most importantly, it formally absorbs the completed watchdog / queue / dispatcher / bridge / sender / orchestrator chain into the plugin mainline as the first deployable reference composition rather than leaving it as repo-local glue.