docs: point AgentSwarm at Agent Substrate as its platform (SPE-5051 mirror)

04-integration-plan.md

@@ -40,6 +40,10 @@ This plan defines how the 15 agents interact, share data, and resolve conflicts
 
 **Correlation invariant:** one business request = one `correlation_id`; every artifact, message, PR, run, and release carries it. This is what makes the whole system auditable end-to-end.
 
+### 2.1 Platform substrate
+
+**[Agent Substrate](https://github.com/swcstudiospace/agent-substrate)** is the shared platform AgentSwarm runs on. It provides four of the substrates above: events over substrate-mcp (message bus), governed memory (the memory plane), leases and handoffs (offer/claim and single-writer ownership), and the Graph ID that a `correlation_id` maps onto. The artifact registry and secrets stay externally provisioned, and the telemetry plane stays OTel. The table above stays authoritative for what flows where; the integration decision itself — including the id mapping and cross-platform trace correlation — is an ADR in that repo (`docs/adr/*-swarm-substrate-integration.md`), tracked as Linear [SPE-5050](https://linear.app/swcstudio/issue/SPE-5050) / [SPE-5051](https://linear.app/swcstudio/issue/SPE-5051). See [docs/substrate-integration.md](docs/substrate-integration.md) for the vocabulary map. No swarm runtime behaviour depends on it today.
+
 ## 3. Reference event flows
 
 ### 3.1 Greenfield feature (happy path)

README.md

@@ -14,6 +14,20 @@ A complete design specification for a distributed swarm of 15 specialized AI age
 | 6 | [06-testing-protocols.md](06-testing-protocols.md) | 7-level validation: golden tasks → contracts → integration flows → chaos → E2E benchmark → security red-team → prod invariants |
 | 7 | [07-scalability.md](07-scalability.md) | Manifest schema, new-agent onboarding (shadow→probation→full), traffic shaping, contract evolution, multi-swarm |
 | 8 | [CLAUDE.md](CLAUDE.md) · [prompts/](prompts/) · [scripts/](scripts/) · [swarm/](swarm/) | Runnable implementation: subagent prompts, per-agent Python tools, orchestration runtime |
+| 9 | [docs/substrate-integration.md](docs/substrate-integration.md) | Platform pointer: how the spec's substrates map onto [Agent Substrate](https://github.com/swcstudiospace/agent-substrate) |
+
+## Platform
+
+AgentSwarm runs on **[Agent Substrate](https://github.com/swcstudiospace/agent-substrate)**, the shared
+platform providing four of the infrastructure substrates this spec assumes ([01 §2.2](01-architecture.md),
+[04 §2](04-integration-plan.md)): events over substrate-mcp, governed memory, leases and handoffs, and the
+Graph ID a `correlation_id` maps onto. The artifact registry, secrets and the OTel telemetry plane are not
+in that set. The integration ADR lives in that repo
+(`docs/adr/*-swarm-substrate-integration.md`), tracked as Linear
+[SPE-5050](https://linear.app/swcstudio/issue/SPE-5050) /
+[SPE-5051](https://linear.app/swcstudio/issue/SPE-5051);
+[docs/substrate-integration.md](docs/substrate-integration.md) is the mirror pointer here. No swarm
+runtime behaviour depends on it today.
 
 ## The 15 agents
 

docs/substrate-integration.md

@@ -0,0 +1,62 @@
+# AgentSwarm on Agent Substrate — platform pointer
+
+**Status:** pointer / cross-link only. This document records *where* the swarm's shared platform lives
+and how its vocabulary maps onto the existing AgentSwarm spec. It changes no runtime behaviour: nothing
+in `swarm/`, `scripts/`, `omp/` or `hooks/` reads or depends on it.
+
+- **Platform repo:** [swcstudiospace/agent-substrate](https://github.com/swcstudiospace/agent-substrate)
+- **Primary ADR** (lands in that repo, not here): `docs/adr/*-swarm-substrate-integration.md`
+- **Tracking:** Linear [SPE-5050](https://linear.app/swcstudio/issue/SPE-5050) (platform) ·
+  [SPE-5051](https://linear.app/swcstudio/issue/SPE-5051) (swarm ↔ substrate integration)
+
+## Why this exists
+
+[01-architecture.md §2.2](../01-architecture.md) lists the swarm's infrastructure services (message bus,
+Task Store, artifact registry, memory, secrets, observability) as *shared, not agents*, and
+[04-integration-plan.md §2](../04-integration-plan.md) lists the substrates those services expose.
+**Agent Substrate is the platform providing the four capabilities in the map below** — events,
+governed memory, leases/handoffs and the Graph ID. AgentSwarm is one tenant of it, not its owner: the
+swarm keeps its agent roster, gates and task DAG; the substrate supplies that transport, that governed
+memory and those coordination primitives underneath.
+
+It does not follow that substrate provides every service in §2.2. The artifact registry (Git + OCI) and
+secrets (Vault/KMS) stay externally provisioned and are out of scope for this pointer, and the OTel
+telemetry plane stays OTel — see the map's last row. Which side provisions what, and the trace-to-graph
+correlation across the two platforms, is for the ADR to settle; do not read this page as a provisioning
+list.
+
+The local `.swarm/` store (SQLite Task Store, `events.jsonl`, signed verdicts) remains the offline,
+single-host implementation of the same contracts — see the runnable-swarm sections of
+[CLAUDE.md](../CLAUDE.md) and the [README](../README.md), not
+[05-deployment-guide.md](../05-deployment-guide.md), which covers the containerized
+NATS/Postgres/etcd/Vault deployment instead. Substrate is the hosted form of the same seams, not a
+replacement for them.
+
+## Vocabulary map
+
+| Substrate capability | AgentSwarm concept | Where it is already specified |
+|---|---|---|
+| Events over **substrate-mcp** | Message bus, `swarm.v1` envelope, `evt./req./offer./ctl./esc.` subjects | [02-message-protocol.md](../02-message-protocol.md) · [04 §2](../04-integration-plan.md) |
+| **Governed memory** | Memory plane (vector + KV): decisions, patterns, retrospectives, estimates, written via `memory.write` | [01 §2.2](../01-architecture.md) · [04 §2](../04-integration-plan.md) |
+| **Leases / handoffs** | `task.offer` → claim → `task.assign`, single-writer artifact ownership, A01-only state transitions | [01 §3](../01-architecture.md) · [02 lifecycle](../02-message-protocol.md) |
+| **Graph ID** | `correlation_id` — one business request, one id, carried by every artifact, message, PR, run and release | [04 §2 correlation invariant](../04-integration-plan.md) |
+| Telemetry (*not claimed by substrate here*) | OTel telemetry plane: traces/metrics/logs correlated by `trace_id`, A13 operates, all agents emit | [01 §2.2](../01-architecture.md) · [04 §2](../04-integration-plan.md) |
+
+The Graph ID row is the load-bearing one, and it is a **correspondence, not string equality**: because the
+swarm already guarantees a single `correlation_id` per business request (invariant 4 in the
+[README](../README.md)), one swarm run corresponds to exactly one substrate graph. The identifiers
+themselves are shaped differently — the swarm mints a UUID (`str(uuid.uuid4())`, see
+[`scripts/orch_plan.py`](../scripts/orch_plan.py) and [`swarm/envelope.py`](../swarm/envelope.py)) — so
+joining substrate-side audit to the swarm's own run log needs an explicit `correlation_id` ↔ Graph ID
+mapping. Defining it (and how `trace_id` correlation crosses the two platforms) belongs to the ADR and
+its adapter stage, not to this page.
+
+## What this doc is not
+
+- Not an integration design. The ADR in `agent-substrate` owns the decision, the interfaces and the
+  migration sequencing; this page only points at it.
+- Not a change to [04-integration-plan.md](../04-integration-plan.md). That document's substrate table
+  stays authoritative for what flows where; §2.1 there links back here.
+- Not a dependency. Governance of gates, verdicts and autonomy ceilings stays with the swarm
+  ([02-message-protocol.md](../02-message-protocol.md) autonomy levels L0–L4); substrate never raises a
+  ceiling.