docs: add reporting governance plugin MVP roadmap
This commit is contained in:
Eve
628
docs/roadmaps/reporting-governance-plugin-mvp.md
Normal file
628
docs/roadmaps/reporting-governance-plugin-mvp.md
Normal file
@@ -0,0 +1,628 @@
|
||||
# Reporting Governance Plugin MVP Roadmap
|
||||
|
||||
## Purpose
|
||||
|
||||
This roadmap explains how the reporting-governance workstream moves from:
|
||||
|
||||
- spec-complete governance contracts
|
||||
- plus an already-working watchdog auto-notify runtime chain
|
||||
|
||||
into:
|
||||
|
||||
- a genuinely installable reporting-governance plugin package
|
||||
- with explicit package boundaries, runtime adapters, deployment profiles, and verification milestones
|
||||
|
||||
It is intended to make one thing unambiguous: **the project is no longer at the idea stage, but it is also not yet at the package-ready plugin stage**.
|
||||
|
||||
---
|
||||
|
||||
## Current state at a glance
|
||||
|
||||
## 1. Spec-complete mainline items
|
||||
|
||||
The following mainline design artifacts are now materially defined and should be treated as the MVP governance contract baseline:
|
||||
|
||||
- Product / architecture definition
|
||||
- `docs/architecture/agent-reporting-governance-plugin.md`
|
||||
- Canonical event model
|
||||
- `docs/specs/reporting-governance-event-model.md`
|
||||
- Canonical evidence model
|
||||
- `docs/specs/reporting-governance-evidence-model.md`
|
||||
- Canonical decision model
|
||||
- `docs/specs/reporting-governance-decision-model.md`
|
||||
- MVP policy-pack model and initial packs
|
||||
- `docs/specs/reporting-governance-policy-packs.md`
|
||||
- Runtime adapter interface
|
||||
- `docs/specs/reporting-governance-adapter-interface.md`
|
||||
- Deployment / package / profile model
|
||||
- `docs/specs/reporting-governance-deployment-model.md`
|
||||
- Reference deployment profiles
|
||||
- `profiles/strict-manager-mode.yaml`
|
||||
- `profiles/standard-team-mode.yaml`
|
||||
- `profiles/minimal-solo-mode.yaml`
|
||||
|
||||
### Interpretation
|
||||
|
||||
The governance model itself is no longer the main blocker.
|
||||
The remaining MVP work is primarily about **implementation convergence**:
|
||||
|
||||
- package extraction
|
||||
- adapter modularization
|
||||
- runtime integration
|
||||
- capability declaration
|
||||
- validation and end-to-end packaging proof
|
||||
|
||||
---
|
||||
|
||||
## 2. Implemented infrastructure already in repo
|
||||
|
||||
The repo already contains a real anti-blackhole runtime chain for watchdog-driven operator notification.
|
||||
|
||||
Implemented pieces:
|
||||
|
||||
- watchdog runner
|
||||
- canonical watchdog event emission
|
||||
- operator notification queue
|
||||
- dispatcher spool handoff
|
||||
- bridge supervisor
|
||||
- sender binding
|
||||
- single-entry orchestrator
|
||||
- cron-facing wrapper/glue
|
||||
- receipts with truthful terminal states
|
||||
|
||||
Primary evidence:
|
||||
|
||||
- `CODER_WATCHDOG_REPORT.md`
|
||||
- `scripts/long_task_watchdog.mjs`
|
||||
- `scripts/operator_notify_dispatcher.mjs`
|
||||
- `scripts/operator_notify_bridge_supervisor.mjs`
|
||||
- `scripts/operator_notify_sender_binding.mjs`
|
||||
- `scripts/watchdog_auto_notify_orchestrator.mjs`
|
||||
|
||||
### Required mainline interpretation
|
||||
|
||||
These pieces must be understood in **two roles at once**:
|
||||
|
||||
1. **Completed infrastructure**
|
||||
- They already solve a real reporting-governance failure path.
|
||||
- They already produce queue / spool / receipt artifacts.
|
||||
- They already prove honest `acked | blocked | pending_external_send` closure semantics.
|
||||
|
||||
2. **First reference runtime composition for the plugin**
|
||||
- They are the first concrete runtime realization of the plugin’s adapter model.
|
||||
- They are the reference composition for watchdog-triggered `force_checkpoint` / notify-operator flows.
|
||||
- They are the migration seed for package extraction, not disposable glue.
|
||||
|
||||
This is the key mainline positioning decision for MVP.
|
||||
|
||||
---
|
||||
|
||||
## 3. What is still missing
|
||||
|
||||
Although the specs are strong and the watchdog chain is real, the project is **not yet a cleanly installable plugin package**.
|
||||
|
||||
The missing pieces are mostly in these categories:
|
||||
|
||||
### A. Package boundary is not fully extracted
|
||||
|
||||
Current state:
|
||||
|
||||
- core logic is still largely represented by docs, schemas, policy packs, and repo-level scripts
|
||||
- the runtime chain exists, but it is not yet extracted behind a stable package module layout
|
||||
|
||||
Missing:
|
||||
|
||||
- package manifest and versioned distributable boundary for reporting governance
|
||||
- package-level `src/core` and `src/adapters` implementation surfaces
|
||||
- importable adapter entrypoints rather than only repo scripts
|
||||
|
||||
### B. Capability declaration is not yet published as a real runtime contract
|
||||
|
||||
Current state:
|
||||
|
||||
- the adapter and deployment specs define capability requirements
|
||||
- the repo behavior strongly implies an OpenClaw watchdog reference profile
|
||||
|
||||
Missing:
|
||||
|
||||
- explicit capability descriptor artifact(s) for the current OpenClaw reference runtime
|
||||
- schema-validated capability JSON checked into the package path
|
||||
|
||||
### C. Policy evaluation engine is specified but not yet fully packaged as reusable code
|
||||
|
||||
Current state:
|
||||
|
||||
- decision vocabulary, evidence thresholds, and pack semantics are documented
|
||||
|
||||
Missing:
|
||||
|
||||
- package-level evaluator implementation that ingests canonical event/evidence inputs
|
||||
- deterministic policy-to-decision runner wired to the adapter surfaces
|
||||
- reusable decision execution layer for `block | rewrite | force_checkpoint | downgrade_status | annotate_placeholder`
|
||||
|
||||
### D. Runtime integration is real for watchdog notice recovery, but not yet generalized
|
||||
|
||||
Current state:
|
||||
|
||||
- watchdog overdue -> queue -> dispatcher -> bridge -> sender -> receipt is working
|
||||
|
||||
Missing:
|
||||
|
||||
- inline hook/invocation path for non-watchdog governance decisions
|
||||
- explicit integration for completion-claim gating
|
||||
- explicit integration for checkpoint structure enforcement
|
||||
- explicit integration for report-anchor / dispatch gating
|
||||
|
||||
### E. Portable audit export is not yet formalized
|
||||
|
||||
Current state:
|
||||
|
||||
- the repo already creates portable-looking artifacts across event / queue / spool / receipt directories
|
||||
|
||||
Missing:
|
||||
|
||||
- bundle/export manifest generator
|
||||
- package-level audit export contract
|
||||
- verification that exported bundles remain self-describing outside the repo
|
||||
|
||||
---
|
||||
|
||||
## MVP scope boundary
|
||||
|
||||
The MVP is **not** “solve every governance rule in every runtime.”
|
||||
|
||||
The MVP is:
|
||||
|
||||
1. package the canonical governance model into a coherent plugin boundary
|
||||
2. extract the proven watchdog chain as the first reference adapter composition
|
||||
3. publish capability/profile artifacts that make deployment honest and portable
|
||||
4. prove at least one end-to-end installable runtime shape for OpenClaw
|
||||
5. establish the extension points for additional inline governance gates after package extraction
|
||||
|
||||
---
|
||||
|
||||
## Delivery lanes
|
||||
|
||||
To keep the roadmap legible, MVP work is split into five lanes.
|
||||
|
||||
## Lane 1 — Governance contracts and schemas
|
||||
|
||||
### Status
|
||||
**Mostly complete at spec level**
|
||||
|
||||
### Already done
|
||||
|
||||
- product definition
|
||||
- event model
|
||||
- evidence model
|
||||
- decision model
|
||||
- policy-pack model
|
||||
- adapter interface
|
||||
- deployment model
|
||||
- profile direction
|
||||
|
||||
### Remaining MVP work
|
||||
|
||||
- final consistency pass across schema filenames, package paths, and profile references
|
||||
- capability schema consumption by real artifacts
|
||||
- roadmap-driven terminology normalization where needed
|
||||
|
||||
### Exit criteria
|
||||
|
||||
- all canonical governance documents align on package terminology
|
||||
- all referenced artifact classes have a concrete home in package structure
|
||||
|
||||
---
|
||||
|
||||
## Lane 2 — Watchdog reference runtime composition
|
||||
|
||||
### Status
|
||||
**Implemented infrastructure; serves as first reference runtime composition**
|
||||
|
||||
### Included components
|
||||
|
||||
- `scripts/long_task_watchdog.mjs`
|
||||
- `scripts/operator_notify_dispatcher.mjs`
|
||||
- `scripts/operator_notify_bridge_supervisor.mjs`
|
||||
- `scripts/operator_notify_sender_binding.mjs`
|
||||
- `scripts/watchdog_auto_notify_orchestrator.mjs`
|
||||
|
||||
### MVP positioning
|
||||
|
||||
This lane is already the most concrete runtime proof in the project.
|
||||
It should be treated as:
|
||||
|
||||
- the completed infra path for anti-blackhole watchdog recovery
|
||||
- the first reference runtime composition of the plugin
|
||||
- the baseline implementation to extract behind adapter modules
|
||||
|
||||
### What this lane already proves
|
||||
|
||||
- canonical watchdog-triggered runtime events can be emitted
|
||||
- operator notice obligations can survive multi-hop runtime boundaries
|
||||
- delivery truth can remain honest across `queued`, `dispatched`, `pending_external_send`, `acked`, and `blocked`
|
||||
- orchestrated closure is possible without collapsing handoff into fake success
|
||||
|
||||
### Remaining MVP work in this lane
|
||||
|
||||
- move from repo-script composition to package adapter composition
|
||||
- publish a named OpenClaw reference capability descriptor for this chain
|
||||
- keep current scripts as executable fixtures / compatibility entrypoints during extraction
|
||||
|
||||
### Exit criteria
|
||||
|
||||
- watchdog chain is represented as named adapter modules under the plugin package
|
||||
- one reference capability profile points to this composition explicitly
|
||||
- verification covers both script-compat and package-entrypoint paths
|
||||
|
||||
---
|
||||
|
||||
## Lane 3 — Core plugin package extraction
|
||||
|
||||
### Status
|
||||
**Not yet complete**
|
||||
|
||||
### Goal
|
||||
|
||||
Create a real plugin package boundary that absorbs the existing docs/specs/schemas/policies plus the watchdog reference composition.
|
||||
|
||||
### Required extraction targets
|
||||
|
||||
Proposed target shape:
|
||||
|
||||
```text
|
||||
plugins/reporting-governance/
|
||||
package-manifest.json
|
||||
src/
|
||||
core/
|
||||
event-normalizer.*
|
||||
evidence-builder.*
|
||||
policy-evaluator.*
|
||||
decision-runner.*
|
||||
adapters/
|
||||
watchdog-adapter.*
|
||||
queue-adapter.*
|
||||
dispatcher-adapter.*
|
||||
bridge-adapter.*
|
||||
sender-binding-adapter.*
|
||||
orchestrator-adapter.*
|
||||
schemas/
|
||||
policy-packs/
|
||||
profiles/
|
||||
capabilities/
|
||||
docs/
|
||||
examples/
|
||||
```
|
||||
|
||||
### Minimum MVP tasks
|
||||
|
||||
1. establish package directory and manifest
|
||||
2. move or mirror canonical schemas into package boundary
|
||||
3. move or mirror policy packs into package boundary
|
||||
4. add adapter module wrappers around existing watchdog-chain scripts
|
||||
5. add core module placeholders or initial implementations for normalization/evaluation/decision execution
|
||||
6. define compatibility stance for existing repo scripts during migration
|
||||
|
||||
### Exit criteria
|
||||
|
||||
- plugin package can be identified as a discrete installable unit
|
||||
- watchdog runtime path can be invoked through package-owned entrypoints
|
||||
- policy packs, profiles, schemas, and capabilities are all package-addressable artifacts
|
||||
|
||||
---
|
||||
|
||||
## Lane 4 — Capability, profile, and deployment binding
|
||||
|
||||
### Status
|
||||
**Spec-complete, implementation incomplete**
|
||||
|
||||
### Goal
|
||||
|
||||
Turn the deployment model from description into enforceable runtime metadata.
|
||||
|
||||
### Minimum MVP tasks
|
||||
|
||||
1. publish `capabilities/default-openclaw-watchdog.json` or equivalent
|
||||
2. validate capability descriptor against `schemas/reporting-governance/adapter-capabilities.schema.json`
|
||||
3. validate reference profiles against a deployment-profile schema
|
||||
4. document profile-to-capability compatibility expectations
|
||||
5. ensure profile language does not overclaim delivery or runtime powers
|
||||
|
||||
### MVP deliverables
|
||||
|
||||
- one real OpenClaw reference capability descriptor
|
||||
- validated strict / standard / minimal profiles
|
||||
- one documented reference deployment shape for queue+bridge+sender composition
|
||||
|
||||
### Exit criteria
|
||||
|
||||
- deployment posture is machine-readable, not only prose
|
||||
- profile selection can be checked against actual adapter capability claims
|
||||
- reference deployment does not rely on prompt memory or repo folklore
|
||||
|
||||
---
|
||||
|
||||
## Lane 5 — Runtime integration milestones beyond watchdog
|
||||
|
||||
### Status
|
||||
**Still missing core plugin pieces**
|
||||
|
||||
### Goal
|
||||
|
||||
Extend the plugin from watchdog-only runtime proof toward broader governance enforcement.
|
||||
|
||||
### Priority order for MVP-adjacent integration
|
||||
|
||||
#### Milestone 5.1 — Completion-claim governance
|
||||
|
||||
Implement the first non-watchdog policy path:
|
||||
|
||||
- intake `task_claimed_complete`
|
||||
- evaluate evidence threshold
|
||||
- emit `downgrade_status` / `require_review` when needed
|
||||
|
||||
Why first:
|
||||
|
||||
- it directly operationalizes the decision and evidence models
|
||||
- it produces high-value governance even before every inline hook exists
|
||||
|
||||
#### Milestone 5.2 — Mandatory checkpoint structure enforcement
|
||||
|
||||
Implement report-shape validation for required checkpoint fields:
|
||||
|
||||
- current status
|
||||
- completed this segment
|
||||
- next step
|
||||
- next report condition
|
||||
- operator intervention needed
|
||||
|
||||
Why next:
|
||||
|
||||
- it reduces fake-progress and structurally empty updates
|
||||
- it converts a policy pack into visible runtime value
|
||||
|
||||
#### Milestone 5.3 — No-fake-progress enforcement
|
||||
|
||||
Implement repeated/no-new-evidence checkpoint evaluation:
|
||||
|
||||
- compare checkpoint evidence deltas
|
||||
- rewrite or annotate placeholder when updates are narrative-only
|
||||
|
||||
#### Milestone 5.4 — Pre-dispatch report-anchor / silent-task gate
|
||||
|
||||
Implement the stronger inline/preflight governance paths:
|
||||
|
||||
- report-anchor presence check
|
||||
- silent-launch blocking or forced disclosure path
|
||||
|
||||
Why later than 5.1/5.2:
|
||||
|
||||
- they are more runtime-hook dependent
|
||||
- they benefit from the package/evaluator/capability groundwork first
|
||||
|
||||
### Exit criteria
|
||||
|
||||
- at least one non-watchdog inline or near-inline governance path is packaged and verified
|
||||
- the plugin no longer depends on watchdog composition alone to demonstrate runtime value
|
||||
|
||||
---
|
||||
|
||||
## Phase plan
|
||||
|
||||
## Phase 0 — Mainline spec baseline
|
||||
|
||||
### Status
|
||||
**Complete enough for MVP entry**
|
||||
|
||||
Includes:
|
||||
|
||||
- architecture/product definition
|
||||
- canonical event/evidence/decision models
|
||||
- policy-pack spec
|
||||
- adapter-interface spec
|
||||
- deployment model
|
||||
- profiles
|
||||
|
||||
Primary outcome:
|
||||
|
||||
- the governance contract is now sufficiently defined to support extraction
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — Reference runtime proof
|
||||
|
||||
### Status
|
||||
**Completed for watchdog auto-notify path**
|
||||
|
||||
Includes:
|
||||
|
||||
- watchdog runner
|
||||
- queue
|
||||
- dispatcher
|
||||
- bridge
|
||||
- sender binding
|
||||
- orchestrator
|
||||
- cron glue
|
||||
- truthful receipt states
|
||||
|
||||
### Lane placement
|
||||
|
||||
This is the roadmap lane where the current watchdog work belongs:
|
||||
|
||||
- **Lane:** Watchdog reference runtime composition
|
||||
- **Phase role:** Phase 1 completed reference runtime proof
|
||||
|
||||
Primary outcome:
|
||||
|
||||
- plugin architecture now has a real runtime composition, not only abstract specs
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Package extraction
|
||||
|
||||
### Status
|
||||
**Next required phase**
|
||||
|
||||
Objective:
|
||||
|
||||
- convert the current reference runtime proof into package-owned adapters and entrypoints
|
||||
|
||||
Key outputs:
|
||||
|
||||
- package manifest
|
||||
- package directory structure
|
||||
- adapter wrappers/modules
|
||||
- capability descriptor
|
||||
- package-local schema/policy/profile organization
|
||||
|
||||
Success condition:
|
||||
|
||||
- the watchdog chain can be described and invoked as plugin package functionality, not merely repo-local scripts
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Core decision/evaluator implementation
|
||||
|
||||
### Status
|
||||
**Missing**
|
||||
|
||||
Objective:
|
||||
|
||||
- implement reusable policy evaluation + decision execution paths against canonical events/evidence
|
||||
|
||||
Key outputs:
|
||||
|
||||
- event normalization helpers
|
||||
- evidence aggregation helpers
|
||||
- policy evaluator
|
||||
- decision runner
|
||||
- first validated non-watchdog governance flows
|
||||
|
||||
Success condition:
|
||||
|
||||
- plugin can enforce at least one major governance rule outside the watchdog overdue path
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Runtime enforcement expansion
|
||||
|
||||
### Status
|
||||
**Missing**
|
||||
|
||||
Objective:
|
||||
|
||||
- add additional integration surfaces beyond the reference watchdog flow
|
||||
|
||||
Key outputs:
|
||||
|
||||
- completion-claim gate
|
||||
- checkpoint-structure gate
|
||||
- no-fake-progress gate
|
||||
- optional pre-dispatch report-anchor gate
|
||||
|
||||
Success condition:
|
||||
|
||||
- plugin is clearly installable and useful for both overdue recovery and active reporting correctness
|
||||
|
||||
---
|
||||
|
||||
## Phase 5 — Package-ready MVP release proof
|
||||
|
||||
### Status
|
||||
**Target state**
|
||||
|
||||
Objective:
|
||||
|
||||
- prove the plugin can be installed, configured, and audited as a coherent unit
|
||||
|
||||
Required MVP release proof:
|
||||
|
||||
- package boundary exists
|
||||
- capability descriptor exists
|
||||
- profiles validate
|
||||
- at least one OpenClaw reference deployment path is documented and runnable
|
||||
- watchdog reference runtime composition works through package entrypoints
|
||||
- at least one non-watchdog governance path is implemented and verified
|
||||
- portable audit manifest/export exists
|
||||
|
||||
Success condition:
|
||||
|
||||
- the project can honestly be called a packageable reporting-governance plugin MVP
|
||||
|
||||
---
|
||||
|
||||
## Recommended implementation order
|
||||
|
||||
1. **Freeze roadmap + positioning**
|
||||
- establish the canonical interpretation of what is complete vs missing
|
||||
2. **Publish capability descriptor for current watchdog reference runtime**
|
||||
- make current runtime truth machine-readable
|
||||
3. **Extract package skeleton and adapter wrappers**
|
||||
- package boundary before broadening runtime scope
|
||||
4. **Wire package-level evaluator/decision runner**
|
||||
- so policy packs become executable logic
|
||||
5. **Implement completion-claim governance path first**
|
||||
- best first non-watchdog policy proof
|
||||
6. **Implement checkpoint-structure path**
|
||||
- visible operator value and good pack validation target
|
||||
7. **Add audit export manifest support**
|
||||
- completes portability story
|
||||
8. **Broaden to fake-progress and pre-dispatch gating**
|
||||
- after package boundary and evaluator are stable
|
||||
|
||||
---
|
||||
|
||||
## MVP acceptance checklist
|
||||
|
||||
The reporting-governance plugin MVP should only be considered package-ready when all of the following are true.
|
||||
|
||||
### Governance contracts
|
||||
- [x] canonical event model exists
|
||||
- [x] canonical evidence model exists
|
||||
- [x] canonical decision model exists
|
||||
- [x] initial policy-pack model exists
|
||||
- [x] adapter-interface spec exists
|
||||
- [x] deployment model exists
|
||||
|
||||
### Reference runtime proof
|
||||
- [x] watchdog overdue path emits canonical event artifacts
|
||||
- [x] queue -> dispatcher -> bridge -> sender -> receipt flow exists
|
||||
- [x] truthful terminal states distinguish `acked`, `blocked`, and `pending_external_send`
|
||||
- [x] orchestrator provides a single entrypoint
|
||||
|
||||
### Still required for package-ready MVP
|
||||
- [ ] plugin package manifest and stable package directory
|
||||
- [ ] package-owned adapter modules wrapping current reference runtime pieces
|
||||
- [ ] OpenClaw reference capability descriptor
|
||||
- [ ] validated deployment-profile contract
|
||||
- [ ] package-level policy evaluation engine
|
||||
- [ ] package-level decision execution path
|
||||
- [ ] at least one non-watchdog governance flow implemented
|
||||
- [ ] portable audit export manifest/bundle support
|
||||
|
||||
---
|
||||
|
||||
## Mainline decisions fixed by this roadmap
|
||||
|
||||
1. **Specs are far enough along that roadmap effort should now bias toward extraction and implementation, not more concept splitting.**
|
||||
2. **The watchdog / queue / dispatcher / bridge / sender / orchestrator chain is both completed infrastructure and the plugin’s first reference runtime composition.**
|
||||
3. **The next major blocker is package extraction, not more watchdog repair.**
|
||||
4. **Capability descriptors and profile validation are mandatory MVP artifacts, because deployment truth cannot remain implicit.**
|
||||
5. **The first non-watchdog implementation target should be completion-claim governance, followed by checkpoint-structure enforcement.**
|
||||
6. **The plugin is not package-ready until runtime proof extends beyond the watchdog lane into reusable evaluator-driven enforcement.**
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
The reporting-governance plugin mainline is now in a transitional but healthy state:
|
||||
|
||||
- the **governance specification surface is largely complete**
|
||||
- the **watchdog auto-notify chain is already a real implemented infrastructure path**
|
||||
- but the project still needs **package extraction, capability publication, evaluator implementation, and additional runtime enforcement milestones** before it becomes a truly installable plugin package
|
||||
|
||||
In roadmap terms:
|
||||
|
||||
- **Phase 0:** specs are largely complete
|
||||
- **Phase 1:** watchdog reference runtime composition is already implemented
|
||||
- **Phase 2+:** package extraction and reusable runtime enforcement are the remaining path to MVP
|
||||
Reference in New Issue
Block a user