openclaw/reporting-governance-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8c7aca145e90faed31d1d6a9d1efd056790905f6
reporting-governance-plugin/docs/roadmaps/reporting-governance-plugin-mvp.md

19 KiB
Raw Blame History

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:

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

  • canonical event model exists
  • canonical evidence model exists
  • canonical decision model exists
  • initial policy-pack model exists
  • adapter-interface spec exists
  • deployment model exists

Reference runtime proof

  • watchdog overdue path emits canonical event artifacts
  • queue -> dispatcher -> bridge -> sender -> receipt flow exists
  • truthful terminal states distinguish acked, blocked, and pending_external_send
  • 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 View Git Blame Copy Permalink