From 97d96deeb6db3d528a4764309b1229cbde60cf4b Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Mon, 6 Apr 2026 05:08:22 -0400 Subject: [PATCH 1/4] docs(agentplane): add root README for public execution-control surface --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..32d175a --- /dev/null +++ b/README.md @@ -0,0 +1,53 @@ +# Agentplane + +Agentplane is an execution control plane for governed bundle runs. + +The public contract is deliberately simple and evidence-forward: + +1. **Bundle** — the deployment unit in `bundles/`. +2. **Validate** — `scripts/validate_bundle.py` enforces the minimum contract and compliance gates. +3. **Place** — `scripts/select-executor.py` selects an executor and emits a `PlacementDecision`. +4. **Run** — a runner backend executes the bundle and emits a `RunArtifact`. +5. **Replay** — `scripts/emit_replay_artifact.py` records the minimum replay inputs. +6. **Lifecycle** — promotion, reversal, and session artifacts extend the execution story. + +## Repository map + +- `bundles/` — example deployment bundles. +- `docs/system-space.md` — system-space strategy and execution model. +- `docs/sociosphere-bridge.md` — seam between `sociosphere` and `agentplane`. +- `docs/runtime-governance/control-matrix-integration.md` — governance/control-loop integration plan. +- `docs/replay-boundary.md` — replay scope, non-goals, and side-effect rules. +- `examples/receipts/` — receipt-oriented examples and trace assembly reference. +- `schemas/` — JSON Schemas for Bundle, RunArtifact, ReplayArtifact, PromotionArtifact, ReversalArtifact, SessionArtifact, plus the missing ValidationArtifact and PlacementDecision contracts added in this patch. +- `scripts/` — validation, placement, artifact emission, demo, and hygiene tooling. +- `runners/` — backend contract surface. + +## Evidence surface + +Agentplane already treats execution as evidence-producing work. The current public evidence types are: + +- `ValidationArtifact` +- `PlacementDecision` +- `RunArtifact` +- `ReplayArtifact` +- `PromotionArtifact` +- `ReversalArtifact` +- `SessionArtifact` + +The repo also carries receipt-oriented examples under `examples/receipts/` and runtime-governance planning under `docs/runtime-governance/`. + +## Current positioning + +Publicly, Agentplane is best described as **workflow orchestration / execution control** rather than an agent gateway. + +The repo is centered on bundle validation, executor selection, run artifacts, replay inputs, lifecycle artifacts, and governance-linked evidence. That is why the current external listing recommendation is **Workflow Orchestration**. + +## Known contract gap still worth closing + +Two concepts are already present in behavior and docs but were not yet first-class public schema files on `main` when this patch was prepared: + +- `ValidationArtifact` +- `PlacementDecision` + +This patch adds schemas for both and adds a concise replay-boundary document so the repo root is no longer just a file tree plus About text. From 397200c7ff0fe3bfdebed9fdfc151f27fbefc23e Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Mon, 6 Apr 2026 08:19:39 -0400 Subject: [PATCH 2/4] docs(agentplane): add replay boundary note for public contract --- docs/replay-boundary.md | 57 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 docs/replay-boundary.md diff --git a/docs/replay-boundary.md b/docs/replay-boundary.md new file mode 100644 index 0000000..57b7d94 --- /dev/null +++ b/docs/replay-boundary.md @@ -0,0 +1,57 @@ +# Replay boundary + +This document defines what the current public `ReplayArtifact` means in `agentplane` and, just as importantly, what it does **not** mean. + +## Current replay contract + +`ReplayArtifact` records the minimum inputs needed to attempt deterministic re-entry: + +- bundle path +- bundle revision when available +- artifact directory +- policy pack reference and hash when available +- required secret names (never secret values) +- upstream workspace evidence references when available + +This is an **input reconstruction contract**, not a claim that arbitrary side effects are automatically safe to reissue. + +## What is replayed today + +At the current public contract level, replay means: + +1. re-identifying the bundle and bundle revision, +2. re-establishing the evidence directory, +3. recovering policy pointers and required secret names, +4. recovering upstream workspace evidence references, +5. providing enough information for a runner or operator to attempt a controlled re-run. + +## What is not promised today + +The current public contract does **not** promise all of the following: + +- checkpoint-level continuation semantics, +- automatic side-effect suppression across arbitrary backends, +- cryptographic attestation of replay safety, +- full authority / delegation reconstruction, +- complete version-set pinning across runtime, model, connector, schema, and policy layers. + +Those may be added later, but they are not implied by the current `ReplayArtifact` alone. + +## Side-effect rule + +Until a stronger replay model is published, external effects should be treated conservatively: + +- effects may require explicit operator review before reissue, +- secret values must never be embedded in replay artifacts, +- policy and workspace evidence references should be reused rather than rediscovered, +- backends should prefer idempotent or evidence-first operations when possible. + +## Relationship to receipts + +The repo now also contains receipt-oriented examples under `examples/receipts/`. +Those examples enrich the broader runtime evidence story, but they do not replace the narrower `ReplayArtifact` contract. + +## Relationship to governance + +`docs/runtime-governance/control-matrix-integration.md` extends the evidence model toward row-level governance and incident linkage. +That document should be read as governance integration work layered above the current replay contract, not as proof that the replay contract already includes full control-loop semantics. From b1114649d52378550572471e1c0a10833c5ad3f2 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Mon, 6 Apr 2026 09:07:05 -0400 Subject: [PATCH 3/4] schema(agentplane): add ValidationArtifact public contract --- schemas/validation-artifact.schema.v0.1.json | 98 ++++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 schemas/validation-artifact.schema.v0.1.json diff --git a/schemas/validation-artifact.schema.v0.1.json b/schemas/validation-artifact.schema.v0.1.json new file mode 100644 index 0000000..2816350 --- /dev/null +++ b/schemas/validation-artifact.schema.v0.1.json @@ -0,0 +1,98 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Agentplane Validation Artifact v0.1", + "type": "object", + "required": [ + "kind", + "bundle", + "capturedAt", + "valid", + "checks" + ], + "properties": { + "kind": { + "const": "ValidationArtifact" + }, + "bundle": { + "type": "string" + }, + "bundlePath": { + "type": [ + "string", + "null" + ] + }, + "capturedAt": { + "type": "string", + "format": "date-time" + }, + "valid": { + "type": "boolean" + }, + "lane": { + "type": [ + "string", + "null" + ], + "enum": [ + "staging", + "prod", + null + ] + }, + "checks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "name", + "status" + ], + "properties": { + "name": { + "type": "string" + }, + "status": { + "enum": [ + "pass", + "fail", + "warn" + ] + }, + "message": { + "type": [ + "string", + "null" + ] + } + }, + "additionalProperties": false + } + }, + "bundleMetadata": { + "type": "object", + "properties": { + "name": { + "type": [ + "string", + "null" + ] + }, + "version": { + "type": [ + "string", + "null" + ] + }, + "createdAt": { + "type": [ + "string", + "null" + ] + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false +} From 9512996e7ebb34070ac53439e7df36948aab1b73 Mon Sep 17 00:00:00 2001 From: mdheller <21163552+mdheller@users.noreply.github.com> Date: Mon, 6 Apr 2026 09:08:20 -0400 Subject: [PATCH 4/4] schema(agentplane): add PlacementDecision public contract --- schemas/placement-decision.schema.v0.1.json | 73 +++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 schemas/placement-decision.schema.v0.1.json diff --git a/schemas/placement-decision.schema.v0.1.json b/schemas/placement-decision.schema.v0.1.json new file mode 100644 index 0000000..0dc52ed --- /dev/null +++ b/schemas/placement-decision.schema.v0.1.json @@ -0,0 +1,73 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Agentplane Placement Decision v0.1", + "type": "object", + "required": [ + "kind", + "capturedAt", + "backendIntent", + "requiresKvm", + "chosenExecutor", + "sshRef", + "caps", + "rejected" + ], + "properties": { + "kind": { + "const": "PlacementDecision" + }, + "capturedAt": { + "type": "string", + "format": "date-time" + }, + "backendIntent": { + "type": "string", + "enum": [ + "qemu", + "microvm", + "lima-process", + "fleet" + ] + }, + "requiresKvm": { + "type": "boolean" + }, + "chosenExecutor": { + "type": "string" + }, + "sshRef": { + "type": "string" + }, + "caps": { + "type": "object" + }, + "rejected": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": [ + "string", + "null" + ] + }, + "sshRef": { + "type": [ + "string", + "null" + ] + }, + "reason": { + "type": [ + "string", + "null" + ] + } + }, + "additionalProperties": false + } + } + }, + "additionalProperties": false +}