diff --git a/docs/architecture/agent-reporting-governance-plugin.md b/docs/architecture/agent-reporting-governance-plugin.md index ee89c84..ab61164 100644 --- a/docs/architecture/agent-reporting-governance-plugin.md +++ b/docs/architecture/agent-reporting-governance-plugin.md @@ -64,6 +64,9 @@ watchdog -> queue -> dispatcher -> bridge -> sender binding -> acked|blocked|pen This is not just repo glue anymore. It is the first real reference runtime composition that the package architecture is being shaped around. +For clarity: the architectural source of truth is now the package-owned runtime surface under `plugins/reporting-governance/`, including package scripts and package profile artifacts. +Repo-root wrappers may still exist, but they are migration shims rather than the primary runtime contract. + ## 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”. diff --git a/docs/specs/reporting-governance-adapter-interface.md b/docs/specs/reporting-governance-adapter-interface.md index 2a87324..597a926 100644 --- a/docs/specs/reporting-governance-adapter-interface.md +++ b/docs/specs/reporting-governance-adapter-interface.md @@ -34,6 +34,9 @@ Separately, the repo now also has real runtime infrastructure for anti-blackhole Without an adapter interface, those runtime pieces remain implementation islands. This spec makes them first-class plugin architecture rather than incidental scripts. +For the current mainline slice, the package-owned runtime source of truth is the package adapter surface and package scripts under `plugins/reporting-governance/`. +Repo-root `scripts/*.mjs` files should be read as compatibility wrappers or operator conveniences unless explicitly stated otherwise. + ## Scope This document defines: diff --git a/docs/specs/reporting-governance-deployment-model.md b/docs/specs/reporting-governance-deployment-model.md index c7c686e..1713238 100644 --- a/docs/specs/reporting-governance-deployment-model.md +++ b/docs/specs/reporting-governance-deployment-model.md @@ -312,6 +312,9 @@ Examples: The completed watchdog chain is now treated as the first reference deployment composition. +For the current mainline slice, the package-owned source of truth is the package entrypoint set under `plugins/reporting-governance/scripts/` together with package profile artifacts under `plugins/reporting-governance/profiles/`. +Repo-root `scripts/*.mjs` wrappers and install helpers remain migration/deployment conveniences, not the architectural source of runtime truth. + ### Reference composition ```text diff --git a/docs/specs/reporting-governance-package-owned-runtime-story.md b/docs/specs/reporting-governance-package-owned-runtime-story.md new file mode 100644 index 0000000..69b9a30 --- /dev/null +++ b/docs/specs/reporting-governance-package-owned-runtime-story.md @@ -0,0 +1,108 @@ +# Reporting Governance Package-Owned Runtime / Operator / Deployment Story + +## Purpose + +This note closes the current mainline slice by stating the runtime story in package-owned terms. + +It is deliberately a **documentation / deployment-story closure**, not a new runtime feature. + +## What is now package-owned + +The `plugins/reporting-governance/` package now owns these deployable truths: + +- canonical schemas +- policy packs +- adapter modules +- package entry scripts under `plugins/reporting-governance/scripts/` +- package profile artifacts under `plugins/reporting-governance/profiles/` +- package capability examples under `plugins/reporting-governance/examples/` +- storage/binding loaders that resolve package artifacts into runtime bindings + +Repo-root `scripts/*.mjs` should now be read as **compatibility shims / operator convenience wrappers**, not the architectural source of truth. + +## Runtime story + +The current reference runtime composition is: + +```text +package-owned watchdog + -> canonical event artifact + -> package-declared queue artifact + -> package-owned dispatcher handoff + -> package-owned bridge supervisor + -> package-owned sender binding + -> honest terminal receipt: acked | blocked | pending_external_send +``` + +The important boundary is: + +- **package owns the contract and primary entrypoints** +- **deployment binds environment-local schedule / target / sender mode** +- **runtime executes and emits artifacts** +- **operator consumes visible updates and audit outputs** + +## Operator story + +For operators, the package now tells a clearer truth: + +1. Governance can require an operator-visible notice. +2. The local runtime may only be able to queue or hand off that notice. +3. Final delivery may depend on an upper runtime or privileged sender boundary. +4. The system must therefore report terminal state honestly as: + - `acked` + - `blocked` + - `pending_external_send` +5. No profile or document should imply that queue write == human-visible delivery. + +## Deployment story + +A deployment is now best understood as four layers: + +1. **Package** + - ships schemas, policy, adapters, package scripts, profile artifacts +2. **Profile artifact** + - selects operating posture and binding contract +3. **Runtime binding** + - supplies repo/workspace-local paths, schedule shape, sender mode, operator target +4. **Live runtime instance** + - runs orchestrator/watchdog/bridge flow and emits audit artifacts + +For the current OpenClaw reference path, the preferred deployable entrypoint is the package-owned orchestrator: + +- `plugins/reporting-governance/scripts/watchdog_auto_notify_orchestrator.mjs` + +Repo-root wrappers may remain for migration and operator convenience, but they are not the package boundary. + +## Completed and claimable now + +The following is honest to claim now: + +- package boundary is real enough to carry profile artifacts and package scripts +- deployment binding can be derived from package-owned artifacts +- orchestrator/runtime path can consume that binding and emit real queue/receipt side effects +- operator-notice truth model distinguishes `acked`, `blocked`, and `pending_external_send` +- repo-root script path is no longer the only source of runtime wiring truth + +## Not completed and must not be overstated + +The following is **not** done and should not be claimed: + +- not a finished general-purpose deployment system +- not full runtime/vendor portability across many runtimes +- not complete inline interception for every governance action +- not proof that every deployment has direct privileged send +- not a full operator UX / install UX / packaging distribution story +- not elimination of repo-root shims yet + +## Current risk / remaining gap + +Main remaining gaps after this closure: + +- some compatibility shims and examples still exist, so readers can still misread migration wrappers as mainline source unless docs stay explicit +- capability/example artifacts are still reference-level, not a full published runtime catalog +- deployment activation remains partly operator-script / cron-wrapper driven +- broader packaging/export/install ergonomics are still follow-up work + +## One-line summary + +This slice finishes the **documentation semantics and deployment story** for a package-owned reference runtime path; it does **not** add new core runtime capability. diff --git a/plugins/reporting-governance/examples/openclaw-watchdog-reference.descriptor.example.json b/plugins/reporting-governance/examples/openclaw-watchdog-reference.descriptor.example.json index ffb5a85..39226fd 100644 --- a/plugins/reporting-governance/examples/openclaw-watchdog-reference.descriptor.example.json +++ b/plugins/reporting-governance/examples/openclaw-watchdog-reference.descriptor.example.json @@ -19,7 +19,7 @@ "orchestrator", "storage" ], - "entrypoint": "scripts/watchdog_auto_notify_orchestrator.mjs" + "entrypoint": "plugins/reporting-governance/scripts/watchdog_auto_notify_orchestrator.mjs" }, "compatibility": { "plugin_spec_versions": [