ADR-0008 — Preserve Armory capability composition and consolidate MCP transport on ContextForge

Status: Accepted; corrected 2026-07-16 after auditing ContextForge v1.0.5 and the complete Armory skill and Suit contracts.

Current pinned implementation guidance: ContextForge 1.0.5.

Context

Armory and ContextForge overlap only in the MCP transport slice. ContextForge natively owns gateways, MCP servers, tools, prompts, resources, Virtual Servers, A2A agents, authentication, team/RBAC bindings, routing, and telemetry. The legacy armory Kubernetes stack duplicates that plane with another ContextForge instance, SQLite PVC, custom registrar, route catalog, and admin-token proxy.

Armory’s remaining contract is broader than a Virtual Server. It resolves Team Contract and profile intent into MCP references, executable agent-skill bundles, policies, schemas, runtime attachments, client capability requirements, credential modes, isolation scopes, launch phases, and execution modes. ContextForge’s A2A Agent Card skills field is descriptive capability metadata; it does not distribute SKILL.md, scripts, assets, executable bits, versions, or workspace materialization instructions. ContextForge plugins are gateway hooks, not agent skills.

Suit is also not a Virtual Server definition. It is project-scoped test-actor state: account and credential references, entry state, role keys, lifecycle, procedures, permissions, and mutable memos. The suit MCP server exposes that domain safely; ContextForge brokers and authorizes the call but does not own Suit state.

Decision

Keep Armory as a pure capability compiler. Armory deterministically compiles a versioned capability manifest from Team Contract plus ProjectAgentProfile. The manifest covers agent skills, policies, MCP references, runtime attachments, client capability negotiation, schemas, and execution mode. Armory is not an MCP gateway and does not own transport credentials or a second catalog database.
Keep profile intent with Agent Execution. The profile stores desired capability intent and the immutable resolved-manifest digest. This preserves identity across a Codex-to-Claude takeover. Armory compiles the manifest; it is not a mutable identity system of record.
Use ContextForge as the only MCP/A2A control plane. A FractalOps-owned deployment uses the official release and chart, CNPG, native APIs, Virtual Servers, scoped identities, RBAC, routing, and telemetry. Delete the custom SQLite gateway, recurring registrar, route proxy, and admin-token fallback after canary proof. One bounded Argo PostSync registration adapter may remain while the pinned native catalog cannot express required passthrough headers, direct_proxy, secret-backed bearer auth, and Virtual Server tool associations. It runs once per rollout, fails on any missing required registration, and owns no runtime routing or refresh loop.
Project only the MCP subset. Armory projects selected MCP server, tool, prompt, and resource references into a ContextForge Virtual Server. Profiles with the same MCP projection digest may share that Virtual Server while retaining distinct subjects, scoped tokens, audit records, leases, worktrees, and continuity state.
Keep agent-skill supply native. Skill bundles are immutable OCI/Nexus artifacts addressed by digest and materialized inside the owned workspace. ContextForge may expose discovery metadata or resources, but it is not the package authority and may not silently substitute missing skill content.
Keep Suit in Access. Suit definitions and memos remain project-scoped business state. Credential values remain in OpenBao; Suit stores references and lease state. Armory may attach the role-test-suit bundle and suit MCP reference. ContextForge enforces the transport boundary for the real profile subject.
Fail closed. Launch admission verifies every required skill artifact, runtime attachment, and ContextForge reference. SpiceDB checks mcp_server:use; ContextForge receives a subject-scoped credential. Agent traffic never falls back to an admin token.

Migration

Deploy the FractalOps-owned ContextForge release beside the legacy gateway using CNPG, native APIs, and the bounded PostSync adapter for fields missing from the native catalog schema.
Compile a canary profile manifest and project only its MCP subset into a Virtual Server. Keep skill and Suit fields in the Armory manifest.
Prove authorized routing, unauthorized HTTP 403, subject-level audit identity, skill artifact digest/materialization, Suit project isolation, and zero admin-token fallback.
Move AgentSquad, DevPod, API, and worker consumers to the native ContextForge endpoint.
Delete only the duplicated Armory operational plane: the second gateway, SQLite PVC, recurring registrar, ingress proxy, MCP route catalog, and admin-token path. Retain the bounded rollout adapter until its documented deletion trigger is met, plus the Armory compiler, manifest contract, skill projection, and Suit integration.

Implementation evidence

ContextForge runs on shared CNPG with no application SQLite PVC.
Agent gateway traffic uses subject-scoped identities; SpiceDB denies unauthorized mcp_server:use with HTTP 403 and no agent-path admin fallback.
Armory renders no registrar CronJob. Argo executes one strict PostSync Job per rollout and deletes it after success. Any failed required server fails the hook.
Seven required MCP servers are registered through ContextForge, including official Astro Docs and GlitchTip MCP endpoints. ContextForge owns runtime health and refresh.
Exact native gaps and adapter deletion trigger remain pinned in ContextForge 1.0.5.

Consequences

One maintained ContextForge plane replaces duplicate MCP infrastructure.
Armory keeps the behavior ContextForge does not provide: identity-aware composition of skills, policies, runtime constraints, and execution semantics.
Suit remains evolvable project business state while gaining ContextForge transport authentication, authorization, and telemetry.
The cutover stays reversible until capability parity, deny behavior, and rollback are proven against immutable revisions.