reporting-governance-plugin/docs/roadmaps/reporting-governance-plugin-mvp.md

# 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