ARC-ADR-071 — File-First Fleet Static Registry (Topology + Ontology vs MCP)¶
| Field | Value |
|---|---|
| ID | ARC-ADR-071 |
| Status | Proposed |
| Date | 2026-06-04 |
| Deciders | Hub owner |
| Supersedes | — |
| Superseded by | — |
| Tags | fleet, agents, mcp, repo-map, ontology, lexicon, hub-spoke, offline, untool-self, coordination |
| Related | ARC-ADR-061-fleet-coordination-plane, ARC-ADR-047-hub-contract-mirror, ARC-ADR-044-untool-ontology-orchestrated-swarm-intelligence |
One line: the fleet’s identity and vocabulary live as hub-authored, spoke-synced files in every repo; the local-fleet MCP is the live coordination plane — not the only place the fleet is defined. Agents must be able to orient when MCP is down.
Context¶
Coding agents (Claude Code, Codex, Copilot, Grok, cloud routines) need two different kinds of truth:
- Static fleet facts — which GitHub repos exist, which is the foundry (
untool-self), legacy synonyms (AgentArmy→untool-self), which repos are archived, local vs cloud MCP/Docker rules, and the platform system ontology lexicon (capabilities, surfaces, components). - Operational fleet state — roster, memos, handoffs, path claims, kill-switch, board queries — served by the untool local-fleet MCP (ARC-ADR-061).
ARC-ADR-061 correctly makes the MCP the canonical write path for coordination (serialized memos, claims, audit). It also demotes the on-disk coordination ledger to a cache, not the semantic source of truth.
A failure mode appears if agents treat MCP as the only registry: loopback unreachable (MCP not running, token missing, Docker pegged, cloud agent without CF Access), sandbox without network, or a spoke microVM that cannot reach 127.0.0.1:8765. In those cases the agent still must resolve repo names, avoid archived repos, and speak platform vocabulary — without calling fleet_start_here.
PR #514 introduced .agent/repo-map.json and synced it to every dressed spoke via spoke-sync. The split between topology (repo-map.json) and ontology vocabulary (ontology/platform-self-model/generated/lexicon.yaml) is intentional, not accidental duplication.
This ADR records that split as a first-class architectural rule.
Decision Drivers¶
| # | Driver |
|---|---|
| D1 | MCP-down survivability. Agents must orient from the repo checkout alone — Read, cat, editor — with zero live MCP or GitHub calls for static facts. |
| D2 | MECE artifact boundaries. “Where is the repo?” and “what does forge mean?” change on different cadences and have different authors (hand-edited map vs generated lexicon). |
| D3 | Selective context load. Repo-scoped work should not require loading the full ontology lexicon; platform naming work should not require the archived-repo list. |
| D4 | Hub authority, spoke read-only copies. Same pattern as agent packs and ARC-ADR-047: hub edits; spokes receive one-way sync; no spoke-local drift. |
| D5 | Graduate into untool. Static files are the bridge until ARC-ADR-044 exposes the same facts through holons/APIs; files remain the offline contract either way. |
Decision¶
1. Two file classes — do not merge into one mega-registry¶
| Artifact | Path (hub + synced spokes) | Answers | Authorship |
|---|---|---|---|
| Fleet topology | .agent/repo-map.json |
Which repos, hub vs spoke, synonyms, archived_repos, MCP endpoints, agent_rules (local CLI vs cloud fleet_*) |
Hand-edited in hub |
| System ontology lexicon | ontology/platform-self-model/generated/lexicon.yaml |
Capabilities, surfaces, components — agent-facing vocabulary | Generated (python tools/selfmodel/emit.py) |
| Spoke hub pointer | .agent/hub.json |
How this repo relates to the foundry; includes "repo_map": ".agent/repo-map.json" |
Hand-edited in hub, synced |
Rationale: ~6 KB topology + ~11 KB lexicon today — combining saves negligible tokens but couples ontology regeneration to every repo-map edit and forces full reads for trivial gh routing tasks.
2. MCP owns operations; files own definitions¶
| Concern | Canonical when MCP is up | Canonical when MCP is down |
|---|---|---|
Roster, memos, handoffs, claims, fleet_control |
local-fleet MCP (coordination/ prefix) |
No substitute — coordination pauses; agents do not invent ledger files |
| Repo IDs, GitHub slugs, archived list, synonyms | .agent/repo-map.json |
Same file |
| Platform vocabulary | fleet_lexicon tool or lexicon.yaml |
lexicon.yaml |
| Foundry URLs, board, ADR/contract links | .agent/hub.json + repo-map.json hub block |
Same files |
Rule: MCP reflects and acts on the fleet; it must not be the sole store of “what repos exist” or “what words mean.” fleet_start_here orients tools and backends; it does not replace reading repo-map.json for topology.
3. Agent read order (documented, not hook-enforced)¶
At session start (or before any cross-repo gh / handoff):
.agent/repo-map.json.agent/hub.jsonontology/platform-self-model/generated/lexicon.yaml— when work involves platform naming, ADRs, or cross-layer contracts
Human-facing summary: docs/repo-map.md. Fleet-wide agent rule: AGENTS.md (“Fleet topology — read first”). Spoke sync includes all three paths in scripts/spoke_sync.config.json.
4. Distribution mechanism¶
- Hub is source of truth;
scripts/sync_helpers_to_spokes.pydresses spokes (see spoke-sync.md). - Trigger: hub push to
mainon synced paths (mirrored in.github/workflows/sync-helpers-to-spokes.yml). - Spokes must not edit synced copies; changes flow hub → PR on spoke → merge.
Considered Options¶
Option A — Single fleet-canonical.json (topology + ontology embedded)¶
Rejected. Couples hand-edited and generated content; increases blast radius on lexicon regen; no meaningful win for MCP-down bootstrap (agents can read two small files).
Option B — MCP-only registry (no repo-map file)¶
Rejected. Fails D1: cloud/sandbox/offline agents lose fleet topology; contradicts file-first agent packs already synced to spokes.
Option C — Files only, no MCP coordination plane¶
Rejected. Fails operational needs in ARC-ADR-061 (serialized writes, claims, kill-switch, audit).
Option D — Two files + thin pointers (chosen)¶
Matches D1–D5. Optional future: a manifest stub listing paths only — not required while hub.json already points at repo-map.json.
Consequences¶
Positive¶
- Agents survive MCP outage for routing and vocabulary — the common “where do I push?” and “don’t target archived repos” failures.
- Clear MECE: edit repo-map when the fleet topology changes; regen lexicon when the self-model changes.
- Aligns with hub contract mirror thinking (ARC-ADR-047): local bytes, hub authority, spoke copies.
- Complements ARC-ADR-061: MCP ledger demoted to cache for coordination; repo-map promoted to canonical for static topology.
Negative / costs¶
- Two files to keep in sync instructions (mitigated by AGENTS.md + repo-map.md).
- Stale spoke copy if sync PR not merged — same class of problem as any dressed helper; fleet-heartbeat can detect drift over time.
fleet_start_heredoes not yet echo repo-map contents — agents still rely on reading the file or AGENTS.md in context.
Neutral¶
- Renaming GitHub slugs (e.g.
AgentArmy→untool-self) updatesrepo-map.jsonsynonymsandhub.github.repo; canonical id staysuntool-self. - Live coordination state remains MCP-only; no return to a shared mutable
coordination_ledger.jsonas source of truth.
Compliance¶
| Check | How |
|---|---|
Hub has repo-map.json |
Present under .agent/ |
| Spokes dressed | repo-map.json on spoke main via sync workflow |
| Docs | repo-map.md, agent-onboarding.md |
| Ontology path synced | lexicon.yaml in spoke_sync.config.json paths |
| MCP ADR cross-link | repo-map.json → coordination.adr (061) + static_registry_adr (071) |