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:

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.

For the current mainline slice, the package-owned source of truth is the package entrypoint set under plugins/reporting-governance/scripts/ together with package profile artifacts under plugins/reporting-governance/profiles/. Within package-owned artifacts such as capability descriptors, runtime.entrypoint: "scripts/..." means package-root-relative to plugins/reporting-governance/. Within deployment profile artifacts, spec.bindings.entrypoint and spec.bindings.scripts.* remain repo-root-relative paths like plugins/reporting-governance/scripts/..., because they bind the installed package back into a concrete workspace/repo runtime. Repo-root scripts/*.mjs wrappers and install helpers remain migration/deployment conveniences, not the architectural source of runtime truth.

Reference composition

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
package scripts/long_task_watchdog.mjs	watchdog adapter executable in the deployed package (scripts/... here means package-root-relative inside plugins/reporting-governance/)
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
package scripts/operator_notify_dispatcher.mjs	dispatcher adapter for handoff generation
state/operator-notify-dispatch-spool/*.json	spool/handoff audit artifacts proving dispatch, not delivery
package scripts/operator_notify_bridge_supervisor.mjs	bridge adapter for upper-runtime send boundary
package scripts/operator_notify_sender_binding.mjs	sender-binding adapter selectable by deployment profile
state/operator-notify-bridge-receipts/*.json	portable delivery-state receipts
package 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

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:

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