docs: add reporting governance deployment model
This commit is contained in:
@@ -676,7 +676,8 @@ Suggested mainline next steps after this document:
|
|||||||
1. define default OpenClaw adapter capability profile JSON using the new schema
|
1. define default OpenClaw adapter capability profile JSON using the new schema
|
||||||
2. extract current runtime scripts behind named adapter modules
|
2. extract current runtime scripts behind named adapter modules
|
||||||
3. add adapter-level schema validation tests
|
3. add adapter-level schema validation tests
|
||||||
4. define deployment profile format once adapter composition is stable
|
4. formalize deployment profile format and package/deployment model around the now-stable watchdog adapter composition
|
||||||
|
5. add portable audit export manifest support
|
||||||
|
|
||||||
## Summary
|
## Summary
|
||||||
|
|
||||||
|
|||||||
674
docs/specs/reporting-governance-deployment-model.md
Normal file
674
docs/specs/reporting-governance-deployment-model.md
Normal file
@@ -0,0 +1,674 @@
|
|||||||
|
# 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.
|
||||||
97
profiles/minimal-solo-mode.yaml
Normal file
97
profiles/minimal-solo-mode.yaml
Normal file
@@ -0,0 +1,97 @@
|
|||||||
|
apiVersion: reporting-governance/v1alpha1
|
||||||
|
kind: DeploymentProfile
|
||||||
|
metadata:
|
||||||
|
id: minimal-solo-mode
|
||||||
|
title: Minimal Solo Mode
|
||||||
|
version: 1.0.0
|
||||||
|
runtime: openclaw
|
||||||
|
summary: >-
|
||||||
|
Lightweight deployment for a solo operator who still wants governed checkpoints,
|
||||||
|
portable receipts, and honest watchdog artifacts without requiring privileged send.
|
||||||
|
spec:
|
||||||
|
package:
|
||||||
|
pluginVersion: 0.1.0-mainline
|
||||||
|
compatibility:
|
||||||
|
adapterInterface: reporting-governance-adapter-interface
|
||||||
|
deploymentModel: reporting-governance-deployment-model
|
||||||
|
policies:
|
||||||
|
enabledPacks:
|
||||||
|
- no-silence
|
||||||
|
- verified-completion-only
|
||||||
|
overrides:
|
||||||
|
completion:
|
||||||
|
minQuality: moderate
|
||||||
|
requireReviewOnVerifiedCompletion: false
|
||||||
|
progress:
|
||||||
|
minNewEvidenceItems: 1
|
||||||
|
qualityFloor: weak
|
||||||
|
checkpoints:
|
||||||
|
overdueAction: force_checkpoint
|
||||||
|
escalationAfterMisses: 3
|
||||||
|
placeholder:
|
||||||
|
requireExplicitLabel: true
|
||||||
|
adapters:
|
||||||
|
hook:
|
||||||
|
enabled: true
|
||||||
|
requireReportAnchorBeforeDispatch: false
|
||||||
|
blockSilentTaskLaunch: false
|
||||||
|
downgradeUnsupportedCompletionClaims: true
|
||||||
|
watchdog:
|
||||||
|
enabled: true
|
||||||
|
scheduleMode: manual_or_cron
|
||||||
|
intervalMinutes: 20
|
||||||
|
emitsCanonicalEvent: true
|
||||||
|
queue:
|
||||||
|
enabled: true
|
||||||
|
outputState: queued
|
||||||
|
dispatcher:
|
||||||
|
enabled: true
|
||||||
|
spoolHandoffRequired: true
|
||||||
|
bridge:
|
||||||
|
enabled: true
|
||||||
|
truthfulDeliveryStates:
|
||||||
|
- dispatched
|
||||||
|
- pending_external_send
|
||||||
|
- acked
|
||||||
|
- blocked
|
||||||
|
sender:
|
||||||
|
mode: dry-run_or_external
|
||||||
|
directAckPreferred: false
|
||||||
|
allowDryRunFallback: true
|
||||||
|
orchestrator:
|
||||||
|
enabled: true
|
||||||
|
executionOrder:
|
||||||
|
- runner
|
||||||
|
- queue
|
||||||
|
- dispatcher
|
||||||
|
- bridge
|
||||||
|
- sender
|
||||||
|
- ack_or_blocked_or_pending
|
||||||
|
notifications:
|
||||||
|
operatorVisibleRecoveryRequired: true
|
||||||
|
allowedTerminalStates:
|
||||||
|
- acked
|
||||||
|
- blocked
|
||||||
|
- pending_external_send
|
||||||
|
treatPendingExternalSendAsIncidentOpen: false
|
||||||
|
audit:
|
||||||
|
portableArtifactsRequired: true
|
||||||
|
exportManifestRequired: false
|
||||||
|
retainOriginalAttemptedMessageOnRewrite: true
|
||||||
|
retentionDays: 14
|
||||||
|
requiredArtifacts:
|
||||||
|
- canonical_events
|
||||||
|
- evidence_records
|
||||||
|
- queue_items
|
||||||
|
- spool_artifacts
|
||||||
|
- bridge_receipts
|
||||||
|
- profile_snapshot
|
||||||
|
capability_expectations:
|
||||||
|
required:
|
||||||
|
- emit_canonical_events
|
||||||
|
- create_queue_items
|
||||||
|
- create_spool_handoff
|
||||||
|
- write_bridge_receipts
|
||||||
|
preferred:
|
||||||
|
- evaluate_watchdog_overdue
|
||||||
|
- final_delivery_ack
|
||||||
101
profiles/standard-team-mode.yaml
Normal file
101
profiles/standard-team-mode.yaml
Normal file
@@ -0,0 +1,101 @@
|
|||||||
|
apiVersion: reporting-governance/v1alpha1
|
||||||
|
kind: DeploymentProfile
|
||||||
|
metadata:
|
||||||
|
id: standard-team-mode
|
||||||
|
title: Standard Team Mode
|
||||||
|
version: 1.0.0
|
||||||
|
runtime: openclaw
|
||||||
|
summary: >-
|
||||||
|
Balanced default for team environments: enforce core reporting governance,
|
||||||
|
keep watchdog recovery active, and allow honest pending_external_send boundaries
|
||||||
|
when direct sender proof is unavailable.
|
||||||
|
spec:
|
||||||
|
package:
|
||||||
|
pluginVersion: 0.1.0-mainline
|
||||||
|
compatibility:
|
||||||
|
adapterInterface: reporting-governance-adapter-interface
|
||||||
|
deploymentModel: reporting-governance-deployment-model
|
||||||
|
policies:
|
||||||
|
enabledPacks:
|
||||||
|
- no-silence
|
||||||
|
- no-fake-progress
|
||||||
|
- verified-completion-only
|
||||||
|
- mandatory-checkpoint-structure
|
||||||
|
overrides:
|
||||||
|
completion:
|
||||||
|
minQuality: moderate
|
||||||
|
requireReviewOnVerifiedCompletion: false
|
||||||
|
progress:
|
||||||
|
minNewEvidenceItems: 1
|
||||||
|
qualityFloor: weak
|
||||||
|
checkpoints:
|
||||||
|
overdueAction: force_checkpoint
|
||||||
|
escalationAfterMisses: 2
|
||||||
|
placeholder:
|
||||||
|
requireExplicitLabel: true
|
||||||
|
adapters:
|
||||||
|
hook:
|
||||||
|
enabled: true
|
||||||
|
requireReportAnchorBeforeDispatch: true
|
||||||
|
blockSilentTaskLaunch: true
|
||||||
|
downgradeUnsupportedCompletionClaims: true
|
||||||
|
watchdog:
|
||||||
|
enabled: true
|
||||||
|
scheduleMode: cron
|
||||||
|
intervalMinutes: 15
|
||||||
|
emitsCanonicalEvent: true
|
||||||
|
queue:
|
||||||
|
enabled: true
|
||||||
|
outputState: queued
|
||||||
|
dispatcher:
|
||||||
|
enabled: true
|
||||||
|
spoolHandoffRequired: true
|
||||||
|
bridge:
|
||||||
|
enabled: true
|
||||||
|
truthfulDeliveryStates:
|
||||||
|
- dispatched
|
||||||
|
- pending_external_send
|
||||||
|
- acked
|
||||||
|
- blocked
|
||||||
|
sender:
|
||||||
|
mode: shim_or_openclaw_cli
|
||||||
|
directAckPreferred: true
|
||||||
|
allowDryRunFallback: true
|
||||||
|
orchestrator:
|
||||||
|
enabled: true
|
||||||
|
executionOrder:
|
||||||
|
- runner
|
||||||
|
- queue
|
||||||
|
- dispatcher
|
||||||
|
- bridge
|
||||||
|
- sender
|
||||||
|
- ack_or_blocked_or_pending
|
||||||
|
notifications:
|
||||||
|
operatorVisibleRecoveryRequired: true
|
||||||
|
allowedTerminalStates:
|
||||||
|
- acked
|
||||||
|
- blocked
|
||||||
|
- pending_external_send
|
||||||
|
treatPendingExternalSendAsIncidentOpen: false
|
||||||
|
audit:
|
||||||
|
portableArtifactsRequired: true
|
||||||
|
exportManifestRequired: false
|
||||||
|
retainOriginalAttemptedMessageOnRewrite: true
|
||||||
|
retentionDays: 21
|
||||||
|
requiredArtifacts:
|
||||||
|
- canonical_events
|
||||||
|
- evidence_records
|
||||||
|
- queue_items
|
||||||
|
- spool_artifacts
|
||||||
|
- bridge_receipts
|
||||||
|
- capability_descriptor
|
||||||
|
capability_expectations:
|
||||||
|
required:
|
||||||
|
- emit_canonical_events
|
||||||
|
- evaluate_watchdog_overdue
|
||||||
|
- create_queue_items
|
||||||
|
- create_spool_handoff
|
||||||
|
- write_bridge_receipts
|
||||||
|
preferred:
|
||||||
|
- direct_sender_binding
|
||||||
|
- final_delivery_ack
|
||||||
103
profiles/strict-manager-mode.yaml
Normal file
103
profiles/strict-manager-mode.yaml
Normal file
@@ -0,0 +1,103 @@
|
|||||||
|
apiVersion: reporting-governance/v1alpha1
|
||||||
|
kind: DeploymentProfile
|
||||||
|
metadata:
|
||||||
|
id: strict-manager-mode
|
||||||
|
title: Strict Manager Mode
|
||||||
|
version: 1.0.0
|
||||||
|
runtime: openclaw
|
||||||
|
summary: >-
|
||||||
|
High-governance deployment for manager-led multi-agent operation with aggressive
|
||||||
|
checkpoint enforcement, watchdog recovery, and strong completion controls.
|
||||||
|
spec:
|
||||||
|
package:
|
||||||
|
pluginVersion: 0.1.0-mainline
|
||||||
|
compatibility:
|
||||||
|
adapterInterface: reporting-governance-adapter-interface
|
||||||
|
deploymentModel: reporting-governance-deployment-model
|
||||||
|
policies:
|
||||||
|
enabledPacks:
|
||||||
|
- no-silence
|
||||||
|
- no-fake-progress
|
||||||
|
- verified-completion-only
|
||||||
|
- mandatory-checkpoint-structure
|
||||||
|
overrides:
|
||||||
|
completion:
|
||||||
|
minQuality: strong
|
||||||
|
requireReviewOnVerifiedCompletion: true
|
||||||
|
progress:
|
||||||
|
minNewEvidenceItems: 1
|
||||||
|
qualityFloor: moderate
|
||||||
|
checkpoints:
|
||||||
|
overdueAction: force_checkpoint
|
||||||
|
escalationAfterMisses: 1
|
||||||
|
placeholder:
|
||||||
|
requireExplicitLabel: true
|
||||||
|
adapters:
|
||||||
|
hook:
|
||||||
|
enabled: true
|
||||||
|
requireReportAnchorBeforeDispatch: true
|
||||||
|
blockSilentTaskLaunch: true
|
||||||
|
downgradeUnsupportedCompletionClaims: true
|
||||||
|
watchdog:
|
||||||
|
enabled: true
|
||||||
|
scheduleMode: cron
|
||||||
|
intervalMinutes: 10
|
||||||
|
emitsCanonicalEvent: true
|
||||||
|
queue:
|
||||||
|
enabled: true
|
||||||
|
outputState: queued
|
||||||
|
dispatcher:
|
||||||
|
enabled: true
|
||||||
|
spoolHandoffRequired: true
|
||||||
|
bridge:
|
||||||
|
enabled: true
|
||||||
|
truthfulDeliveryStates:
|
||||||
|
- dispatched
|
||||||
|
- pending_external_send
|
||||||
|
- acked
|
||||||
|
- blocked
|
||||||
|
sender:
|
||||||
|
mode: openclaw-cli
|
||||||
|
directAckPreferred: true
|
||||||
|
allowDryRunFallback: false
|
||||||
|
orchestrator:
|
||||||
|
enabled: true
|
||||||
|
executionOrder:
|
||||||
|
- runner
|
||||||
|
- queue
|
||||||
|
- dispatcher
|
||||||
|
- bridge
|
||||||
|
- sender
|
||||||
|
- ack_or_blocked_or_pending
|
||||||
|
notifications:
|
||||||
|
operatorVisibleRecoveryRequired: true
|
||||||
|
allowedTerminalStates:
|
||||||
|
- acked
|
||||||
|
- blocked
|
||||||
|
- pending_external_send
|
||||||
|
treatPendingExternalSendAsIncidentOpen: true
|
||||||
|
audit:
|
||||||
|
portableArtifactsRequired: true
|
||||||
|
exportManifestRequired: true
|
||||||
|
retainOriginalAttemptedMessageOnRewrite: true
|
||||||
|
retentionDays: 30
|
||||||
|
requiredArtifacts:
|
||||||
|
- canonical_events
|
||||||
|
- evidence_records
|
||||||
|
- decision_records
|
||||||
|
- queue_items
|
||||||
|
- spool_artifacts
|
||||||
|
- bridge_receipts
|
||||||
|
- capability_descriptor
|
||||||
|
- profile_snapshot
|
||||||
|
capability_expectations:
|
||||||
|
required:
|
||||||
|
- emit_canonical_events
|
||||||
|
- evaluate_watchdog_overdue
|
||||||
|
- create_queue_items
|
||||||
|
- create_spool_handoff
|
||||||
|
- write_bridge_receipts
|
||||||
|
preferred:
|
||||||
|
- direct_sender_binding
|
||||||
|
- final_delivery_ack
|
||||||
|
- inline_dispatch_blocking
|
||||||
Reference in New Issue
Block a user