docs(local-coord-mcp): envelope schema v1 + design rationale

Declares the full message envelope for local-coord multi-agent comms.
Replaces raw-string messages with typed, routed, auditable envelopes.

Design choices:
- Op-kind taxonomy: 18 typed message kinds with default risk tiers.
- Risk ladder 0-4: proportional gating from free (status/query) through
  forbidden for supervised role (force-push, always-private-repo touch).
- BFT-inspired safety (5 layers): hash chain per sender, M-of-N
  attestation for Tier 2+ from supervised, watchdog TTLs on claims,
  content sanity gate with auto-promote patterns, tamper-evident audit
  log to VeriSimDB.
- Self-assessment 4 layers: static affinity + per-claim confidence +
  server-computed track record + drift detector (catches "Gemini
  confidently wrong" case).
- Adaptive awareness: context_fetch_id required for Tier 2+, forcing
  every risky action to be preceded by a context read. Summary vs raw
  context gated by role to prevent supervised peers hallucinating from
  raw state.
- User-interaction routing: fyi (log-only) / clarify (batched through
  supervisor) / blocker (inline interrupt). Supervised peers cannot set
  urgent_direct — they never reach the user directly.

No code changes yet — schema is forward-declaration. Wiring into the
FFI coord_send path comes after Task #5 (supervision tier model) +
Task #7 (VeriSimDB sidecar).

Companion memory: project_coord_supervision_architecture.md.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

cartridges/local-coord-mcp/docs/envelope-design.adoc

@@ -0,0 +1,220 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+
+= local-coord-mcp message envelope — design rationale
+:author: Jonathan D.A. Jewell
+:date: 2026-04-20
+:toc: macro
+:version: v1
+
+Companion document to `schemas/coord-messages.ncl`.
+Architectural memory: `project_coord_supervision_architecture.md`.
+
+toc::[]
+
+== Motivation
+
+The first version of local-coord-mcp treated messages as opaque strings.
+That worked for a toy two-peer ping but doesn't survive a real multi-agent
+workspace with mixed-trust peers (Claude + vibe + codex + gemini), where
+one agent is prone to confabulation ("Gemini is often nuts") and the user
+needs a firewall between runaway outputs and the system.
+
+The envelope defined here:
+
+* Makes every message typed, routable, and auditable.
+* Carries enough metadata for the server to gate risky ops without
+  interrupting free ones.
+* Uses Byzantine-style cross-verification to catch the specifically
+  dangerous failure modes of a low-trust peer.
+* Keeps the supervisor (Opus + user) as the single locus of attention
+  while the other agents work in parallel.
+
+== Design principles
+
+. *Proportional gating.* Tier 0/1 flow free, Tier 2 light auto-approve,
+  Tier 3 hard gate, Tier 4 schema-level reject. Coordination overhead
+  should never be the rate-determining step for routine work.
+. *Awareness scales with blast radius.* Drone behaviour on small ops,
+  strategic awareness on big ones. Enforced by requiring
+  `context_fetch_id` on Tier 2+.
+. *Never trust self-assessment alone.* Self-declared confidence is a
+  signal, never a decision. Server cross-checks against track record
+  and, for Tier 2+ from supervised peers, requires an independent
+  attester.
+. *Supervision without bottleneck.* Auto-approve where safe, batch
+  where feasible, preserve Opus attention for genuine judgement calls.
+. *Single user locus.* All agent-to-user traffic filters through the
+  supervisor terminal. Supervised peers never reach the user directly.
+
+== Trust tiers
+
+|===
+| Role | Assigned to | Default for client_kind
+
+| `supervisor` | Opus | (explicit only)
+| `executor` | Claude Sonnet / Haiku | `claude`
+| `supervised` | vibe, codex, gemini | `gemini`, `copilot`, `custom`
+|===
+
+`supervisor` must be requested explicitly on register; the server
+SHOULD restrict the role to Opus-tier Claude clients.
+
+== Risk ladder
+
+|===
+| Tier | Examples | Gate
+
+| 0 | status, query, read, peer discovery, context_query | none
+| 1 | single-file edit (non-critical), test, lint, fyi, release | logged
+| 2 | multi-file edit, dep bump, new file, claim (local/repo) | auto-approve 60s
+| 3 | commit, push, mirror, secret-adjacent, deletion, schema migration | supervisor approval, no timeout
+| 4 | force-push, branch delete, public-repo create, license change, always-private-repo touch | schema-level reject for `supervised`
+|===
+
+== Byzantine safety mechanisms
+
+Five layers, each catching a specific failure mode:
+
+=== 1. Hash chain per sender — catches retroactive rewriting
+
+Each envelope's `prev_msg_hash` is the SHA-256 of the sender's previous
+envelope. First-ever message uses 64 zeros. Server tracks chain head per
+peer; any break is an instant reject. Cost: 32 bytes per message.
+
+=== 2. M-of-N attestation — catches unilateral bad Tier 2+ ops
+
+Before a Tier 2+ envelope from `role=supervised` executes, server routes
+`attest_req` in parallel to a second executor (Sonnet or Codex). That
+executor independently reads the payload, HMAC-signs the envelope with
+its session token, and returns `attest_resp`. Opus sees both the
+supervise_req and the attestation when deciding.
+
+This is PBFT-lite for *f=1* byzantine tolerance.
+
+=== 3. Watchdog claims — catches claim-squatting
+
+Every `claim` op has a TTL. Claimant must emit `progress` or `release`
+before expiry or server auto-releases the claim.
+
+* `supervised`: 30s TTL
+* `executor`: 5min TTL
+* `supervisor`: unlimited
+
+=== 4. Content sanity gate — catches confabulation + tier underclaiming
+
+Server runs heuristics over payload content:
+
+* File references validated against recent-FS-state cache — nonexistent
+  path = reject.
+* Self-contradiction detector (simple heuristic within payload).
+* Risk-tier escalator — content matching `sanity_auto_promote` patterns
+  forces the minimum tier regardless of declared value.
+
+=== 5. Tamper-evident audit log — forensic recovery
+
+Every envelope + every supervision decision logged to VeriSimDB with
+hash-chain continuity. Even when a bad message slips through, post-hoc
+audit reconstructs exactly what happened and who signed what.
+
+== Self-assessment — four layers
+
+.Ranked by strength of evidence
+|===
+| Layer | Source | Catches
+
+| A. Static affinity | Peer declares on register | Coarse mismatch
+| B. Per-claim confidence | Peer self-reports on `claim` | Laziness / overreach
+| C. Track record | Server-computed from outcomes | Pattern miscalibration
+| D. Drift detector | Server alerts on confidence vs track-record gap | Specific overclaim ("Gemini is nuts" case)
+|===
+
+Tie-break on concurrent claims = `max(sender_confidence * effective_affinity)`.
+The second factor is server-attached and cannot be forged.
+
+== Adaptive awareness
+
+`context_fetch_id` is the load-bearing field here. Required for Tier 2+
+envelopes. Obtained via `context_query` + `context_reply`. Forces every
+high-risk action to be preceded by a context read.
+
+Context summary depth scales with requester role:
+
+* `supervised` → summary only (never raw state — prevents hallucinated
+  connections).
+* `executor` → summary by default, raw on request.
+* `supervisor` → full raw on request, always.
+
+== User-interaction routing
+
+Three op_kinds for agent-to-user communication:
+
+[cols="1,2,2",options="header"]
+|===
+| op_kind | Behaviour | Allowed setters
+
+| `fyi` | Log-only. Never interrupts. | any role
+| `clarify` | Batch through supervisor terminal. `urgent_direct` breakout allowed for executor/supervisor. | any role (supervised can't set urgent_direct)
+| `blocker` | Inline interrupt on supervisor terminal. Stops the task. | any role
+|===
+
+The supervisor (Opus) deduplicates near-identical questions from multiple
+peers, synthesises with context, and relays to the user in natural
+language. Rejected confabulated questions from supervised peers never
+reach the user.
+
+== op_kind quick reference
+
+[cols="1,1,3",options="header"]
+|===
+| op_kind | Default tier | Purpose
+
+| status | 0 | Current work status, visible via list_peers
+| query | 0 | Read-only Q&A between peers
+| context_query | 0 | Request big-picture context (required for Tier 2+)
+| context_reply | 0 | Response to context_query
+| supervise_req | 0 | Supervised peer requests gated-op approval
+| supervise_resp | 0 | Supervisor decides approve/reject
+| attest_req | 0 | Server requests independent attestation (BFT)
+| attest_resp | 0 | Executor attests/rejects
+| fyi | 1 | Log-only observation
+| progress | 1 | Task percent + note
+| warn_drift | 1 | Rule / invariant / expected-state drift
+| release | 1 | Release claim with outcome
+| claim | 2 | Claim task, affinity-routed (3 when scope=estate)
+| handoff | 2 | Transfer task to peer (3 when scope=estate)
+| clarify | 2 | Question for user, batched
+| blocker | 3 | Peer cannot proceed without user
+| gated_op | 3 | Wrapper for arbitrary high-risk action
+|===
+
+== What this does NOT cover
+
+* *Cross-machine transport* — this envelope is localhost-only. Umoja
+  federation (separate design) handles multi-host.
+* *Model attestation* — peer identity is `(client_kind, session token,
+  suffix)`. No proof the peer is actually the model it claims.
+  Out-of-scope until we have hardware attestation.
+* *Privacy between peers* — all messages are server-visible. Encrypted
+  peer-to-peer is a later addition (not needed for local use).
+
+== Implementation sequence
+
+. Schema + design doc (this commit).
+. Supervision tier + role field in FFI (Task #5).
+. Supervisor tools: coord_review / coord_approve / coord_reject (Task #6).
+. VeriSimDB sidecar for durable state + track record (Task #7).
+. E2E test: 2-instance with supervisor gate + durability (Task #8).
+
+Only after those land do we wire the full envelope into the FFI's
+coord_send path. Today's coord_send accepts raw strings; in the
+transition period, strings without the envelope shape are treated as
+implicit `{op_kind: "query", risk_tier: 0}` for backward compatibility.
+
+== References
+
+* Nickel source: `../schemas/coord-messages.ncl`
+* JSON export: `../schemas/coord-messages.json`
+* Supervision architecture memory: `memory/project_coord_supervision_architecture.md`
+* Cartridge manifest: `../cartridge.ncl`
+* ADR-0006 (five-symbol cartridge ABI): `boj-server/docs/adr/ADR-0006.adoc`