hyperpolymath · hyperpolymath · May 26, 2026 · May 26, 2026
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,22 @@
+# Build artefacts (lead-dot AND no-dot variants both seen in zig)
+**/zig-cache/
+**/.zig-cache/
+**/zig-out/
+**/.zig-out/
+**/node_modules/
+**/.cache/
+**/_build/
+**/target/
+**/dist/
+
+# OS junk
+.DS_Store
+*.swp
+*~
+
+# Local env
+.env.local
+*.local.json
+
+# Cartridge-side runtime
+**/*.log
diff --git a/README.md b/README.md
@@ -1,2 +1,81 @@
+<!-- SPDX-License-Identifier: MPL-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) -->
+
 # boj-server-cartridges
-Canonical home of BoJ cartridges. Hosts (boj-server, panll) fetch from here on demand.
+
+Canonical home of **BoJ cartridges**. Hosts (`boj-server`, `panll`, others) fetch cartridges from here on demand into a host-local cache; this repository ships the source tree.
+
+## Status
+
+🟢 **v0.1 — populated from boj-server 2026-05-26.** Initial migration of 125 cartridges out of `boj-server/cartridges/` into this dedicated repository. Boj-server's catalog refactor to fetch from here is tracked separately.
+
+## What is a cartridge?
+
+See the canonical spec: [standards/cartridges/CARTRIDGE-FORMAT.adoc](https://github.com/hyperpolymath/standards/blob/main/cartridges/CARTRIDGE-FORMAT.adoc) and JSON schema: [cartridge-v1.json](https://github.com/hyperpolymath/standards/blob/main/cartridges/cartridge-v1.json).
+
+A cartridge is a self-contained server unit consumed by a host to extend its tool surface (MCP), language-server reach (LSP), debug-adapter capabilities (DAP), build-tool integration (BSP), or other server-role mode. Cartridges are process-isolated (each backend listens on its own loopback port) and content-addressable.
+
+## Taxonomy
+
+Hybrid layout ratified in [docs/decisions/ADR-001-taxonomy.adoc](docs/decisions/ADR-001-taxonomy.adoc):
+
+```
+cartridges/
+├── domains/                  ← cartridges grouped by functional domain
+│   ├── cloud/                ← 10 cartridges (umbrella + 9 providers)
+│   ├── database/             ← 12 cartridges (umbrella + 11 providers)
+│   ├── ci-cd/, languages/, security/, research/, …  (30 domains total)
+├── cross-cutting/            ← cartridges not bound to a single domain
+│   ├── agentic/              ← agent-mcp, claude-ai-mcp, model-router-mcp, …
+│   ├── nesy/                 ← nesy-mcp, ml-mcp
+│   ├── build/                ← bsp-mcp (generic BSP server)
+│   ├── debug/                ← dap-mcp (generic DAP server)
+│   ├── fleet/                ← fleet-mcp (orchestration)
+│   └── health/               ← boj-health
+└── templates/                ← canonical scaffolds for new cartridges
+    └── gossamer-mcp/         ← reference template
+```
+
+## Cartridge roles
+
+A cartridge name ends in a canonical role suffix:
+
+| Suffix | Role |
+|---|---|
+| `-mcp` | Model Context Protocol |
+| `-lsp` | Language Server Protocol |
+| `-dap` | Debug Adapter Protocol |
+| `-bsp` | Build Server Protocol |
+| `-debug` | Debugger (when not strictly DAP) |
+| `-format` | Code formatter |
+| `-lint` | Linter / static analyser |
+| `-build` | Build orchestration |
+| `-nesy` | Neurosymbolic reasoning |
+| `-agentic` | Agent harness |
+| `-fleet` | Fleet orchestrator |
+
+A single domain may have multiple cartridges across roles, e.g. `database-mcp` + `database-lsp` + `database-format`.
+
+## Schema
+
+`schemas/cartridge-v1.json` mirrors the canonical spec at [hyperpolymath/standards](https://github.com/hyperpolymath/standards/blob/main/cartridges/cartridge-v1.json). The mirror is SHA-pinned via [schemas/SCHEMA-MIRROR.md](schemas/SCHEMA-MIRROR.md).
+
+## Versioning + on-demand fetch
+
+Each cartridge directory contains its own `cartridge.json` with `version` (semver). Hosts fetch cartridges by name + version; the tray UI (`hyperpolymath/boj-server`) exposes "Add cartridge source" to point at this registry (the canonical default) or any other GitHub URL.
+
+## Inventory (this initial commit)
+
+- **125 cartridges** copied from `boj-server/cartridges/` (snapshot 2026-05-26).
+- **30 functional domains** + **6 cross-cutting categories** + **1 template**.
+- All cartridges retain their original `cartridge.json` manifests. A separate follow-up PR will add the new required `category` field to each manifest.
+
+## Contributing
+
+1. Use the **gossamer-mcp** template as your starting point: `cp -r cartridges/templates/gossamer-mcp cartridges/domains/<your-domain>/<your-cartridge-name>` (or use the minter tool once landed).
+2. Update the manifest to reflect your cartridge's name (role-suffixed), domain, protocols, tools.
+3. Open a PR; auto-merge is enabled by default for this repo.
+
+## License
+
+[MPL-2.0](LICENSE). Cartridges retain their individual SPDX identifiers per `cartridge.json`.
diff --git a/cartridges/cross-cutting/agentic/agent-mcp/AGENT-MCP-REPORT.adoc b/cartridges/cross-cutting/agentic/agent-mcp/AGENT-MCP-REPORT.adoc
@@ -0,0 +1,277 @@
+// SPDX-License-Identifier: MPL-2.0
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+= Agent-MCP Cartridge — Technical Report
+Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+:toc: left
+:toclevels: 3
+:icons: font
+:source-highlighter: rouge
+
+== Executive Summary
+
+Agent-MCP is a formally verified agentic orchestration cartridge for the BoJ (Bundle of Joy) server. It enforces Boyd's OODA loop (Observe → Orient → Decide → Act) as a dependent-type state machine, making it *impossible* for an AI agent to act without first observing, orienting, and deciding. This prevents the "shoot first, think later" anti-pattern that plagues autonomous AI systems.
+
+The cartridge is accessible via *9 protocol transports*: REST, gRPC, GraphQL, WebSocket, JSON-RPC 2.0, MQTT, tRPC, SOAP, and Cap'n Proto — supporting everything from web dashboards to multi-agent swarms.
+
+== Architecture
+
+=== The ABI-FFI-Adapter Triple
+
+[source]
+----
+   Idris2 ABI (SafeOODA.idr, Protocol.idr)
+        │  ValidOODA proof: impossible to skip stages
+        │  Dependent types enforce state machine correctness
+        ▼
+   Zig FFI (agent_ffi.zig)
+        │  32 concurrent sessions, mutex-protected
+        │  30+ tests, C-ABI exports
+        ▼
+   zig Adapters (9 protocol servers)
+        │  REST, gRPC, GraphQL, WebSocket, JSON-RPC,
+        │  MQTT, tRPC, SOAP, Cap'n Proto
+        ▼
+   AI Agents (Claude, Gemini, custom agents, bot fleets)
+----
+
+=== Why This Architecture Matters
+
+* The *Idris2 layer* makes invalid state transitions a compile-time error. There is no `ValidOODA Observe Act` constructor — the type system physically prevents it.
+* The *Zig layer* manages 32 concurrent agent sessions with mutex-protected state, ensuring thread safety under load.
+* The *zig layer* exposes session management through every protocol pattern, from request/response to pub/sub to binary RPC.
+
+== Core Logic
+
+=== The OODA State Machine
+
+Every AI agent session follows a strict cycle:
+
+[source]
+----
+    ┌──────────┐
+    │ OBSERVE  │ ◄─── Gather data, read context
+    └────┬─────┘
+         │ (only valid transition)
+    ┌────▼─────┐
+    │  ORIENT  │ ◄─── Analyse, interpret, contextualise
+    └────┬─────┘
+         │ (only valid transition)
+    ┌────▼─────┐
+    │  DECIDE  │ ◄─── Choose action, plan execution
+    └────┬─────┘
+         │ (only valid transition)
+    ┌────▼─────┐
+    │   ACT    │ ◄─── Execute the decision
+    └────┬─────┘
+         │ (loops back)
+         └──────────► OBSERVE (new loop, loopCount++)
+
+    Any state ──► HALTED (emergency stop)
+    HALTED ──► OBSERVE (resume)
+----
+
+=== Valid Transitions (Idris2 Proof)
+
+[cols="1,1,1", options="header"]
+|===
+| From | To | Allowed?
+
+| Observe | Orient | *Yes* — must analyse before deciding
+| Observe | Decide | *No* — cannot skip analysis
+| Observe | Act | *No* — cannot skip analysis AND decision
+| Orient | Decide | *Yes* — must decide before acting
+| Orient | Act | *No* — cannot skip decision
+| Decide | Act | *Yes* — execute the decision
+| Act | Observe | *Yes* — new loop begins
+| Any | Halted | *Yes* — emergency stop always available
+| Halted | Observe | *Yes* — resume with fresh observation
+|===
+
+The `ValidOODA` dependent type in Idris2 has exactly 9 constructors — one for each valid transition. Any other transition is a *type error at compile time*.
+
+=== Tool Call Safety
+
+Not all agent actions are equal. Agent-MCP classifies tool calls by risk:
+
+[cols="1,1,1", options="header"]
+|===
+| Tool Call Type | Has Side Effects? | Requires Safety Check?
+
+| Execute | Yes | *Yes*
+| Query | No | No
+| Transform | No | No
+| Communicate | Yes | No
+| Delegate | Yes | *Yes*
+| Escalate | Yes | *Yes*
+|===
+
+=== Safety Gate
+
+Before execution, a safety check determines whether to proceed:
+
+[cols="1,1,1", options="header"]
+|===
+| Safety Outcome | Allows Execution? | Needs Human?
+
+| Approved | *Yes* | No
+| Denied | No | No
+| Escalated | No | *Yes*
+| Timeout | No | No
+| Sandboxed | *Yes* (isolated) | No
+| Human Required | No | *Yes*
+|===
+
+=== Multi-Agent Coordination
+
+[cols="1,1", options="header"]
+|===
+| Strategy | Description
+
+| Solo | Single agent, no coordination
+| Collaborative | Agents share information and goals
+| Competitive | Agents compete for best solution
+| Hierarchical | Manager agent delegates to workers
+| Swarm | Emergent behaviour from simple rules
+| Consensus | Agents vote before acting
+|===
+
+=== Agent Memory Types
+
+[cols="1,1,1", options="header"]
+|===
+| Memory Type | Persistent? | Scope
+
+| Working | No | Current session only
+| Episodic | Yes | Event history
+| Semantic | Yes | Knowledge base
+| Procedural | Yes | Skills and procedures
+| Shared | Yes | Across all agents
+|===
+
+== Protocol Transports
+
+=== 9 Protocols Available
+
+[cols="1,1,2", options="header"]
+|===
+| Protocol | Adapter File | Best For
+
+| *REST* | `agent_adapter.v` | Standard web APIs, Claude MCP bridge
+| *gRPC* | `agent_grpc.v` | Microservice agent orchestration
+| *GraphQL* | `agent_graphql.v` | Agent dashboards, flexible session queries
+| *WebSocket* | `agent_websocket.v` | Real-time OODA state streaming, live monitoring
+| *JSON-RPC 2.0* | `agent_jsonrpc.v` | MCP native protocol, batch operations
+| *MQTT* | `agent_mqtt.v` | Distributed agent swarms, edge agents
+| *tRPC* | `agent_trpc.v` | Type-safe frontend agent controls
+| *SOAP* | `agent_soap.v` | Enterprise workflow integration
+| *Cap'n Proto* | `agent_capnproto.v` | High-performance multi-agent coordination
+|===
+
+=== Protocol Selection Guide
+
+* *Building an agent dashboard?* → GraphQL or WebSocket
+* *Orchestrating a bot fleet?* → gRPC or MQTT
+* *Connecting from an MCP client?* → JSON-RPC (native MCP protocol)
+* *Running agents on edge devices?* → MQTT
+* *Enterprise workflow integration?* → SOAP
+* *Maximum throughput agent swarm?* → Cap'n Proto or gRPC
+* *Simple single-agent integration?* → REST
+
+== Specific Agentic Server Types
+
+=== 1. OODA Compliance Gateway
+
+The most common deployment: every AI agent in an organisation must register a session with Agent-MCP before it can act. The gateway enforces that no agent skips the Observe → Orient → Decide sequence.
+
+*Example flow*: Claude Code starts a task → creates OODA session → Observes (reads code) → Orients (analyses patterns) → Decides (plans changes) → Acts (writes code) → loops back to Observe.
+
+=== 2. Multi-Agent Swarm Controller
+
+Uses MQTT to coordinate dozens of agents working on the same problem. Each agent has its own OODA session; the controller uses the `Consensus` coordination strategy to aggregate decisions before any agent acts.
+
+*Example*: 6 bots in the gitbot-fleet (Rhodibot, Echidnabot, Sustainabot, Panicbot, Glambot, Seambot) each run independent OODA loops, but coordinate via Agent-MCP before making changes to shared repositories.
+
+=== 3. Safety-Critical Agent Sandbox
+
+For high-risk agent actions (code deployment, database migrations, financial transactions), Agent-MCP gates every `Execute` tool call through the safety check. Only `Approved` or `Sandboxed` outcomes allow execution.
+
+*Example*: AI-assisted database migration — agent Observes schema, Orients by checking foreign keys, Decides on migration plan, but Act is blocked until safety check returns `Approved` (human reviews the plan).
+
+=== 4. Hierarchical Agent Orchestrator
+
+Uses gRPC for high-throughput manager → worker delegation. The manager agent runs its own OODA loop, and in the `Act` phase, delegates sub-tasks to worker agents, each with their own enforced OODA sessions.
+
+*Example*: Project manager agent decomposes a feature request → delegates sub-tasks to coding agent, testing agent, documentation agent → each worker follows its own OODA cycle → results flow back to manager's next Observe phase.
+
+=== 5. Agent Audit Trail
+
+Every OODA transition is a logged event. Using WebSocket streaming, a compliance dashboard shows real-time agent activity: which agents are in which OODA phase, how many loops they've completed, whether any have been halted.
+
+*Example*: Regulatory compliance — financial institution must prove that every AI decision followed a structured process. Agent-MCP's OODA log provides a formal audit trail with cryptographic attestation.
+
+=== 6. Adaptive Agent Learning
+
+Uses the `Episodic` and `Procedural` memory types to build agent skills over time. After each OODA loop, the agent stores what worked (episodic memory) and extracts reusable procedures (procedural memory).
+
+*Example*: DevOps agent learns from incident response — each incident is an OODA loop, the agent builds procedural memory of "when X alert fires, check Y then Z", getting faster with each iteration.
+
+== Value Beyond Current Implementation
+
+=== What We Have Now
+
+* Dependent-type proof that OODA stages cannot be skipped
+* 32 concurrent agent sessions with thread-safe management
+* 9 protocol transports for universal accessibility
+* Tool call classification with safety gates
+* Multi-agent coordination strategies
+* Cognitive memory type system
+
+=== What This Enables That Nothing Else Does
+
+1. *Provably Safe Agents*: No other agent framework mathematically guarantees that agents follow a structured decision loop. Agent-MCP's `ValidOODA` proof type makes "act without thinking" a *type error*, not a runtime bug.
+
+2. *Universal Agent Protocol*: The same OODA enforcement works over MQTT (for a Raspberry Pi agent), WebSocket (for a browser-based agent), gRPC (for a Kubernetes agent), and SOAP (for a bank's agent system) — all with the same formal guarantees.
+
+3. *Safety as Architecture*: Tool call classification and safety gates are not config — they are type-level properties. The system knows that `Execute` has side effects and `Query` doesn't, and enforces safety checks accordingly.
+
+4. *Coordination Without Chaos*: The 6 coordination strategies are not just labels — they prescribe how agents interact. `Consensus` means agents vote before acting; `Hierarchical` means only the manager can delegate. The protocol enforces this.
+
+5. *Memory as a Type System*: The 5 memory types aren't just storage categories — `Working` memory is explicitly non-persistent (disappears with the session), while `Shared` memory is explicitly cross-agent. This prevents accidental state leakage.
+
+== Roadmap
+
+=== Short-Term (v0.3.0)
+
+* [ ] *Session persistence*: Save/restore agent sessions across restarts (currently in-memory only)
+* [ ] *OODA metrics*: Track average time per phase, loop completion rate, halt frequency
+* [ ] *WebSocket state streaming*: Subscribe to specific session IDs for targeted monitoring
+* [ ] *Tool call logging*: Record every tool invocation with timestamp, inputs, outputs, safety check result
+* [ ] *MQTT retained messages*: Last-known state available to new subscribers
+
+=== Medium-Term (v0.4.0)
+
+* [ ] *Plan execution engine*: The 7 `PlanStep` types (Action, Condition, Loop, Branch, Parallel, Checkpoint, Rollback) become executable — agents submit plans, Agent-MCP validates and executes them step by step
+* [ ] *Agent capability model*: Define what tools each agent is allowed to use (per-session capability sets)
+* [ ] *Cross-session coordination*: Agents in different sessions can coordinate without sharing state (message-passing only)
+* [ ] *Rollback support*: If an `Act` fails, automatically roll back to the last `Checkpoint` in the plan
+* [ ] *GraphQL subscriptions*: Real-time OODA state changes via GraphQL subscription
+* [ ] *Cap'n Proto streaming*: Bidirectional streaming for high-throughput swarm coordination
+
+=== Long-Term (v1.0)
+
+* [ ] *Formal verification of coordination*: Prove that `Consensus` coordination never deadlocks and always terminates (using Idris2 totality checker)
+* [ ] *Agent identity and attestation*: Each agent cryptographically signs its OODA transitions, creating a tamper-proof audit trail
+* [ ] *OODA composition*: Nest OODA loops — an `Act` phase can contain a sub-OODA cycle for fine-grained decision-making
+* [ ] *Temporal logic properties*: Prove liveness (agents always eventually act) and safety (agents never act without deciding) using CTL model checking
+* [ ] *Agent marketplace*: Community-contributed agent templates with pre-defined OODA patterns, tool call sets, and coordination strategies
+* [ ] *Cross-cartridge agent workflows*: Agent-MCP orchestrates multi-cartridge workflows (e.g., agent uses NeSy-MCP for decision verification, Database-MCP for data access, Git-MCP for code changes — all within a single OODA loop)
+* [ ] *Self-improving agents*: Agents analyse their own OODA loop performance and suggest optimisations to their observation and orientation strategies
+
+=== Protocol Evolution
+
+* [ ] *HTTP/2 native gRPC*: Upgrade from JSON-over-HTTP to full Protobuf transport via Zig FFI
+* [ ] *QUIC transport*: UDP-based low-latency transport for swarm gossip
+* [ ] *NATS/JetStream*: Cloud-native messaging for distributed agent coordination
+* [ ] *OpenTelemetry integration*: Emit OODA transitions as OTel spans with distributed trace context
+* [ ] *MCP native transport*: Direct MCP stdio bridge without HTTP intermediary
+* [ ] *Agent-to-Agent protocol*: Purpose-built binary protocol for direct agent communication without broker overhead