From 59bfbb0c5549d9bddf8ae0c2b9551a9199d9715e Mon Sep 17 00:00:00 2001
From: Aine <aine@Aines-Mac-mini.local>
Date: Sun, 15 Mar 2026 16:16:21 -0600
Subject: [PATCH] docs(plugins): add execution spine contract, health schema,
 handoff packet, retry/dead-letter policy

---
 docs/plugins/EXECUTION_SPINE_CONTRACT.md | 12 ++++++++++++
 docs/plugins/HANDOFF_PACKET_SCHEMA_V1.md | 13 +++++++++++++
 docs/plugins/PLUGIN_HEALTH_SCHEMA.md     | 12 ++++++++++++
 docs/plugins/RETRY_DEADLETTER_POLICY.md  |  9 +++++++++
 4 files changed, 46 insertions(+)
 create mode 100644 docs/plugins/EXECUTION_SPINE_CONTRACT.md
 create mode 100644 docs/plugins/HANDOFF_PACKET_SCHEMA_V1.md
 create mode 100644 docs/plugins/PLUGIN_HEALTH_SCHEMA.md
 create mode 100644 docs/plugins/RETRY_DEADLETTER_POLICY.md

diff --git a/docs/plugins/EXECUTION_SPINE_CONTRACT.md b/docs/plugins/EXECUTION_SPINE_CONTRACT.md
new file mode 100644
index 00000000000..1753e9c20e3
--- /dev/null
+++ b/docs/plugins/EXECUTION_SPINE_CONTRACT.md
@@ -0,0 +1,12 @@
+# Plugin Execution Spine Contract (v1)
+
+## Flow
+`propose -> approve(if risky) -> execute -> verify`
+
+## ACK-first
+Actionable requests SHOULD emit immediate ACK before long-running work.
+
+## Goals
+- Lean core, stronger plugins
+- Predictable safety behavior
+- Auditable execution trail
diff --git a/docs/plugins/HANDOFF_PACKET_SCHEMA_V1.md b/docs/plugins/HANDOFF_PACKET_SCHEMA_V1.md
new file mode 100644
index 00000000000..b01198de81a
--- /dev/null
+++ b/docs/plugins/HANDOFF_PACKET_SCHEMA_V1.md
@@ -0,0 +1,13 @@
+# Resumable Handoff Packet (v1)
+
+## Purpose
+Allow model/agent/plugin swap mid-run without continuity loss.
+
+## Core fields
+- `runId`
+- `goalId`
+- `currentStep`
+- `acceptance`
+- `artifacts[]`
+- `status`
+- `updatedAt`
diff --git a/docs/plugins/PLUGIN_HEALTH_SCHEMA.md b/docs/plugins/PLUGIN_HEALTH_SCHEMA.md
new file mode 100644
index 00000000000..55597355e09
--- /dev/null
+++ b/docs/plugins/PLUGIN_HEALTH_SCHEMA.md
@@ -0,0 +1,12 @@
+# Plugin Health Schema (v1)
+
+## Status enum
+- `healthy`
+- `degraded`
+- `blocked`
+
+## Required fields
+- `status`
+- `lastError` (nullable)
+- `nextAction` (nullable)
+- `updatedAt`
diff --git a/docs/plugins/RETRY_DEADLETTER_POLICY.md b/docs/plugins/RETRY_DEADLETTER_POLICY.md
new file mode 100644
index 00000000000..98970a897b9
--- /dev/null
+++ b/docs/plugins/RETRY_DEADLETTER_POLICY.md
@@ -0,0 +1,9 @@
+# Retry + Dead-letter Policy (v1)
+
+## Retry
+- Bounded retries only (no infinite loops)
+- Explicit retry count + backoff
+
+## Dead-letter
+- Failed items after max retries move to dead-letter queue
+- Must include failure reason + next operator action