docs: add public repo front door and missing execution contracts

README.md

@@ -1,3 +1,56 @@
+# 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.
 # agentplane
 
 Agentplane is the tenant-side control and execution plane for local-first and hybrid agents.

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.

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
+}

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
+}