From a5c2cc04b8ddbaaa9f16e2f8d2c8da638de5a7e6 Mon Sep 17 00:00:00 2001
From: Aine <aine@Aines-Mac-mini.local>
Date: Sun, 15 Mar 2026 16:29:32 -0600
Subject: [PATCH] docs(plugins): align spine docs with frontmatter, naming, and
 schema clarifications

---
 docs/plugins/HANDOFF_PACKET_SCHEMA_V1.md      | 13 ------------
 docs/plugins/PLUGIN_HEALTH_SCHEMA.md          | 12 -----------
 docs/plugins/RETRY_DEADLETTER_POLICY.md       |  9 --------
 ...ONTRACT.md => execution-spine-contract.md} |  8 +++++++
 docs/plugins/handoff-packet-schema-v1.md      | 21 +++++++++++++++++++
 docs/plugins/plugin-health-schema.md          | 20 ++++++++++++++++++
 docs/plugins/retry-deadletter-policy.md       | 19 +++++++++++++++++
 7 files changed, 68 insertions(+), 34 deletions(-)
 delete mode 100644 docs/plugins/HANDOFF_PACKET_SCHEMA_V1.md
 delete mode 100644 docs/plugins/PLUGIN_HEALTH_SCHEMA.md
 delete mode 100644 docs/plugins/RETRY_DEADLETTER_POLICY.md
 rename docs/plugins/{EXECUTION_SPINE_CONTRACT.md => execution-spine-contract.md} (53%)
 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/HANDOFF_PACKET_SCHEMA_V1.md b/docs/plugins/HANDOFF_PACKET_SCHEMA_V1.md
deleted file mode 100644
index b01198de81a..00000000000
--- a/docs/plugins/HANDOFF_PACKET_SCHEMA_V1.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# 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
deleted file mode 100644
index 55597355e09..00000000000
--- a/docs/plugins/PLUGIN_HEALTH_SCHEMA.md
+++ /dev/null
@@ -1,12 +0,0 @@
-# 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
deleted file mode 100644
index 98970a897b9..00000000000
--- a/docs/plugins/RETRY_DEADLETTER_POLICY.md
+++ /dev/null
@@ -1,9 +0,0 @@
-# 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
diff --git a/docs/plugins/EXECUTION_SPINE_CONTRACT.md b/docs/plugins/execution-spine-contract.md
similarity index 53%
rename from docs/plugins/EXECUTION_SPINE_CONTRACT.md
rename to docs/plugins/execution-spine-contract.md
index 1753e9c20e3..e61b65c2f92 100644
--- a/docs/plugins/EXECUTION_SPINE_CONTRACT.md
+++ b/docs/plugins/execution-spine-contract.md
@@ -1,3 +1,11 @@
+---
+summary: "Plugin execution spine contract: propose → approve(if risky) → execute → verify."
+read_when:
+  - You are designing plugin execution flows
+  - You need a shared safety/approval contract
+title: "Plugin Execution Spine Contract"
+---
+
 # Plugin Execution Spine Contract (v1)
 
 ## Flow
diff --git a/docs/plugins/handoff-packet-schema-v1.md b/docs/plugins/handoff-packet-schema-v1.md
new file mode 100644
index 00000000000..e7cba488b58
--- /dev/null
+++ b/docs/plugins/handoff-packet-schema-v1.md
@@ -0,0 +1,21 @@
+---
+summary: "Resumable handoff packet schema to preserve continuity across model/agent/plugin swaps."
+read_when:
+  - You are implementing resumable handoffs
+  - You need run continuity across worker/model changes
+title: "Resumable Handoff Packet Schema (v1)"
+---
+
+# Resumable Handoff Packet (v1)
+
+## Purpose
+Allow model/agent/plugin swap mid-run without continuity loss.
+
+## Core fields
+- `runId`
+- `goalId`
+- `currentStep`
+- `acceptance` — approval record from the `approve` gate (null if not required)
+- `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..6f437d1455a
--- /dev/null
+++ b/docs/plugins/plugin-health-schema.md
@@ -0,0 +1,20 @@
+---
+summary: "Standard plugin health schema for operator visibility and recovery handoffs."
+read_when:
+  - You are exposing plugin runtime health
+  - You need a consistent healthy/degraded/blocked status model
+title: "Plugin Health Schema"
+---
+
+# 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..298c462a898
--- /dev/null
+++ b/docs/plugins/retry-deadletter-policy.md
@@ -0,0 +1,19 @@
+---
+summary: "Plugin-scoped bounded retry and dead-letter policy to prevent silent task loss."
+read_when:
+  - You are implementing plugin retry behavior
+  - You need dead-letter handling for failed plugin tasks
+title: "Retry + Dead-letter Policy"
+---
+
+# Retry + Dead-letter Policy (v1)
+
+Related: [Core retry policy](/concepts/retry)
+
+## 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