122 lines
5.2 KiB
Markdown
122 lines
5.2 KiB
Markdown
# Agent Reporting Governance Plugin
|
|
|
|
## Why this exists
|
|
|
|
This plugin exists to turn reporting norms into enforceable, auditable behavior across agent runtimes.
|
|
|
|
The core problem is not only whether work happened, but whether reporting about the work was:
|
|
|
|
- timely
|
|
- truthful
|
|
- operator-visible when required
|
|
- backed by inspectable evidence
|
|
- portable across runtime boundaries
|
|
|
|
A prompt can encourage this behavior, but prompts alone cannot reliably guarantee it.
|
|
|
|
## Architectural stance
|
|
|
|
This product therefore treats prompts as guidance, but not as the sole enforcement mechanism. Governance must be embodied in plugin logic, policy artifacts, adapters, receipts, and verifiable state transitions.
|
|
|
|
The plugin boundary is deliberately split into:
|
|
|
|
- `core/` for runtime-agnostic governance meaning
|
|
- `adapters/` for runtime-facing execution seams
|
|
- `storage/` for durable artifact I/O contracts
|
|
- package artifacts for deployable truth such as profiles and capability descriptors
|
|
- reference compositions for concrete runtime wiring
|
|
|
|
## Package artifact posture
|
|
|
|
The plugin should treat policy packs and deployment profiles as versioned artifacts.
|
|
|
|
That means:
|
|
|
|
- policy packs can be pinned, reviewed, diffed, promoted, and rolled back like other versioned operational artifacts
|
|
- deployment profiles should evolve from external prose/YAML into package-owned deployable artifacts
|
|
- capability descriptors should honestly declare what a runtime can and cannot do
|
|
|
|
This is essential because runtime truth cannot remain implicit.
|
|
|
|
## Runtime truth model
|
|
|
|
A runtime is not trustworthy because it says it sent a notice.
|
|
It is trustworthy when it can preserve state transitions and artifacts that prove what happened.
|
|
|
|
For the current OpenClaw reference path, that means durable visibility across:
|
|
|
|
- watchdog evidence artifacts
|
|
- canonical event artifacts
|
|
- queue items
|
|
- spool / handoff artifacts
|
|
- bridge receipts
|
|
- sender attempt artifacts
|
|
- final ack / blocked / pending delivery state
|
|
|
|
## Reference runtime composition
|
|
|
|
The current mainline reference composition is the watchdog chain:
|
|
|
|
```text
|
|
watchdog -> queue -> dispatcher -> bridge -> sender binding -> acked|blocked|pending_external_send
|
|
```
|
|
|
|
This is not just repo glue anymore.
|
|
It is the first real reference runtime composition that the package architecture is being shaped around.
|
|
|
|
## Minimal package profile artifact trajectory
|
|
|
|
Architecture is also now advanced one notch from “profiles are external YAML docs” toward “profiles are package artifacts with a loader boundary”.
|
|
|
|
Current minimal slice:
|
|
|
|
- package-owned profile artifact snapshot: `plugins/reporting-governance/profiles/strict-manager-mode.profile.json`
|
|
- package loader: `src/storage/profile-artifact.mjs#loadDeploymentProfileArtifact(...)`
|
|
- binding contract projector: `src/storage/profile-artifact.mjs#createDeploymentBindingContract(...)`
|
|
|
|
Architectural meaning:
|
|
|
|
- package can carry one portable profile artifact under its own boundary
|
|
- storage layer owns loading/package-artifact interpretation
|
|
- runtime binding can be derived from the artifact rather than hardcoded entirely in docs
|
|
- tests prove the artifact resolves into concrete script and runtime-artifact paths
|
|
- `artifact_roots` enforcement is now two-layered for this slice: lexical boundary rejection plus realpath-level symlink escape rejection
|
|
- specifically for `queueItems`, the path is checked twice: once at profile-artifact load/validation time, and again at orchestrator use-time before runtime consumption
|
|
|
|
This is intentionally still a **minimal verifiable slice**, not the full deployment system.
|
|
It proves the package boundary can own profile artifacts and bind them into runtime execution inputs.
|
|
|
|
## Minimal runtime-integrated trajectory
|
|
|
|
The next notch is no longer documentation-only binding exposure.
|
|
There is now a minimal runtime-integrated path that connects:
|
|
|
|
- `executeGovernanceContract(...)`
|
|
- validated profile artifact / `deploymentBinding`
|
|
- orchestrator adapter runtime invocation
|
|
|
|
Meaning:
|
|
|
|
- core still evaluates and plans first
|
|
- runtime execution is attempted only when the contract truthfully requires adapter action such as `notify_operator`
|
|
- the same validated deployment binding is reused as the adapter input instead of re-declaring runtime wiring out of band
|
|
- tests prove this path produces real queue + receipt side effects under dry-run orchestration
|
|
|
|
This is still intentionally not full inline interception.
|
|
It is the smallest verifiable seam that shows planning and runtime composition are genuinely wired.
|
|
|
|
Primary follow-on specs:
|
|
|
|
- `docs/specs/reporting-governance-adapter-interface.md`
|
|
- `schemas/reporting-governance/adapter-capabilities.schema.json`
|
|
|
|
Roadmap for package extraction and MVP implementation sequencing:
|
|
|
|
- `docs/roadmaps/reporting-governance-plugin-mvp.md`
|
|
|
|
## Summary
|
|
|
|
The Agent Reporting Governance Plugin is a portable enforcement layer for trustworthy agent reporting. It exists because prompts alone cannot reliably prevent missing reports, late reports, fake progress, skipped checkpoints, unverified completion claims, dropped subagent results, or mislabeled placeholder/proxy reporting.
|
|
|
|
Its value is simple: operators should be able to trust not only that work happened, but that reporting about the work was timely, honest, verifiable, and transferable across environments.
|