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

[SomeRandmGuyy]

Companion [S0] to SPE-5051: a thin mirror cross-link in agent-swarm recording that Agent Substrate is the shared platform the swarm runs on. The primary ADR lands in agent-substrate (docs/adr/*-swarm-substrate-integration.md); this PR only points at it.

Docs only — no runtime behaviour change.

What changed

• docs/substrate-integration.md (new) — the mirror pointer. States the platform relationship (the swarm is a tenant, not the owner), links the forthcoming ADR path and Linear SPE-5050 / SPE-5051, and carries a vocabulary map:

  Substrate	AgentSwarm concept
  Events over substrate-mcp	Message bus, swarm.v1 envelope, evt./req./offer./ctl./esc. subjects
  Governed memory	Memory plane (vector + KV), memory.write
  Leases / handoffs	task.offer → claim → task.assign, single-writer ownership, A01-only transitions
  Graph ID	the id a correlation_id maps onto
  Telemetry (not claimed by substrate here)	OTel telemetry plane, trace_id correlation, A13 operates

  It references the existing 01 §2.2 / 02 / 04 §2 rather than restating them, and notes explicitly that it is not an integration design, not a change to 04, and not a dependency (autonomy ceilings stay with the swarm).

• 04-integration-plan.md — new short §2.1 "Platform substrate" under the existing data-sharing substrate table. The table stays authoritative for what flows where; the subsection names the platform and links out. Not rewritten wholesale.

• README.md — document-map row 9 for the new doc, plus a short "Platform" section above the agent roster.

Scope of the platform claim

Substrate is credited with four of the substrates in 04 §2 — events, governed memory, leases/handoffs and the Graph ID. The artifact registry (Git + OCI) and secrets (Vault/KMS) stay externally provisioned, and the telemetry plane stays OTel; the doc says so explicitly and warns against reading the page as a provisioning list.

The Graph ID row is a correspondence, not string equality: one swarm run corresponds to one substrate graph, but the swarm mints correlation_id as str(uuid.uuid4()) (scripts/orch_plan.py:152, swarm/envelope.py:57), so joining substrate-side audit to the run log needs an explicit correlation_id ↔ Graph ID mapping. Defining it, and how trace_id correlation crosses the two platforms, is left to the ADR and its adapter stage.

Review

Greptile raised three findings on the first commit (4bff972) — all genuine over-claims in the new doc rather than problems in the spec it references — fixed in 6dfc4de:

#	Finding	Fix
P1	Graph IDs may differ	Dropped the "no translation table" claim; restated as a correspondence needing an explicit mapping, citing the uuid4 mint sites.
P2	Platform scope unclear	Narrowed "provides them" from all six 01 §2.2 services to the four in the map; registry and secrets called out as externally provisioned; telemetry row added, marked as not claimed by substrate here.
P2	Local implementation reference misleads	Repointed the .swarm/ sentence at the runnable-swarm sections of CLAUDE.md / README; 05-deployment-guide.md now cited for the containerized NATS/Postgres/etcd/Vault model it actually covers.

The scope over-claim had leaked into the 04 §2.1 and README wordings too; both were corrected.

One deliberate non-change: Greptile cited SPE-5051 as requiring the mapping to cover OTel. The telemetry plane is now in the map, but documented as-is and explicitly not claimed for substrate, since that attribution isn't in the material available to this session. If SPE-5051 does assign the telemetry plane to substrate, that row needs a follow-up edit.

Verification

• python3 scripts/build_agents.py --check and python3 scripts/build_trae_agents.py --check → both up-to-date (no generated agents/skills affected).
• Relative markdown links in all three touched files resolve to existing paths (checked programmatically).
• bun test tests/ts green.
• The push-triggered test job passed on 4bff972, confirming the full pytest + TS suites are green on this branch; 7 failures seen locally were container-environment only (a broken cryptography rust binding raising pyo3_runtime.PanicException, no omp binary, and one CPU-timing-sensitive perf assertion).

Definition of done

• Short docs/ + README section points to Substrate as the platform and to SPE-5050 / SPE-5051
• No runtime behaviour change
• Draft PR opened

Grok-Run: 20260930T104345Z-c08ca4fe

🤖 Generated with Claude Code

https://claude.ai/code/session_01BRBehxvVTgfHY4VEaXT89U

Confidence Score: 5/5

The documentation-only PR appears safe to merge.

Summary

Adds a documentation-only pointer from AgentSwarm to Agent Substrate.

• Maps swarm concepts to substrate capabilities and distinguishes externally provisioned services and OTel.
• Cross-links the pointer from the README and integration plan, while leaving identifier mapping to the future ADR.
  Greptile automatically discovered a related ticket that helped explain the purpose of this PR: provide an S0 ADR mapping and a mirror pointer without production-code changes.

_{Reviews (2) · Last reviewed commit: "docs: narrow substrate scope claims and ..."}

---

Note

Low Risk
Markdown-only cross-links and scope clarifications; no code, config, or runtime paths are modified.

Overview
This PR adds documentation-only cross-links so AgentSwarm records that it runs on Agent Substrate, with the real integration ADR staying in that repo (Linear SPE-5050 / SPE-5051). No runtime or swarm/ behaviour changes.

A new docs/substrate-integration.md is the mirror pointer: swarm-as-tenant (not platform owner), a vocabulary map from four substrate capabilities (events, governed memory, leases/handoffs, Graph ID) to existing spec concepts, and explicit exclusions (artifact registry, secrets, OTel stay as documented elsewhere). It states that correlation_id ↔ Graph ID is a correspondence requiring an ADR-defined mapping, not identical strings, citing UUID minting in orch_plan.py / envelope.py.

04-integration-plan.md gains §2.1 under the substrate table (table unchanged as authority), and README.md adds document-map row 9 plus a short Platform section with the same scoped claims.

^{Reviewed by Cursor Bugbot for commit 6dfc4de. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_a5719e9b-439b-4b15-9296-14e44b03f985)