Episode 8: The Polyrepo Context Wall

Correct code in the wrong system. Here’s how we solved boundary blindness across 20+ repos using a Global Architect agent, System Header Maps, and an SDK-First gate.

This is Episode 8 of the Autonomous Dev Org series — an honest account of building a development organization where AI handles implementation and humans handle direction.

---

Correct Code in the Wrong System

Episode 7 solved the inner loop. Hook Shields catch violations at write time — before compilation, before review, before the mistake can compound. Within a single repository, the agent now operates within hard physical constraints. Standards hold.

Then we asked the loop to implement a cross-service feature.

The CRM repository got a new SharedContract type. All 847 tests passed. The agent opened the PR with a clean diff and a confident summary. We merged it.

Twenty minutes later, the API Gateway started returning 422 errors on subscription queries. Not because the CRM implementation was wrong — it was correct, by every check we had. But the API Gateway was a different repository, with a different agent context, holding a cached understanding of the SharedContract schema that no longer matched what the CRM was sending.

The fix took four hours. The root cause was five lines. The gap between them was a month of accumulated interface drift across twelve repositories that nobody — no agent, no human — had been systematically watching.

This is Boundary Blindness: the agent’s context ends at the repository boundary, but the system’s dependencies don’t.

---

What We Built

We built a Global Architectural Loop — a separate agent process that holds all twenty-plus repository interfaces simultaneously, using a high-context model, and acts as the system-wide verifier before any cross-repo change begins.

The key shift: this agent doesn’t implement anything. It reads contracts and identifies drift. Every domain repository has a context boundary. The Global Architect has none — or rather, its context is the entire estate’s public surface.

We also enforced a hard sequencing rule: no domain implementation begins until the SDK contract is updated and verified. We called it SDK-First. It sounds obvious in retrospect. We ignored it for six months before the 422 incident forced our hand.

---

The War Room

Director: We’ve solved the inner loop with Hook Shields, but now we’re hitting a different wall. The agents are developing Boundary Blindness.

Architect: I saw that this morning. The agent implemented SharedContract in the CRM repo perfectly — passed all tests — and completely broke the API Gateway. The shared schema was out of sync. Clean diff, catastrophic runtime.

Builder: From my perspective inside the CRM repo, the world looks great. I don’t have context on the other nineteen repositories. I’m building in a silo because that’s the context I’m given.

Director: That’s the Context Wall. We split the monolith into twenty-plus repos to keep things manageable — and inadvertently blinded every agent to the interface drift it causes across boundaries.

Architect: So what’s the plan? Feed all twenty repositories into one prompt? You’ll hit the token limit before you even get to the business logic.

Director: Not if I use a high-context model not to code, but to read. I’m running a Global Architect agent with a one-million-token context window. It doesn’t read every line of logic — it reads every repository’s public interface. The System Header Map.

Builder: So it sees the Core SDK, the READMEs, the OpenAPI specs for the whole estate?

Director: Exactly. It treats twenty-plus repos as a single specification. It identifies drift before a single domain repo is touched.

Architect: And when it finds drift?

Director: It produces a Sync Plan — a structured diff of what needs to change, in what order, for the system to be consistent again. Domain agents work from the Sync Plan. They don’t discover the problem mid-implementation.

Architect: I’ll believe it when the 422s stop.

---

The Context Wall, Precisely

Here’s why this fails without the Global Architect.

A monolith is easy for an agent. One context. One set of boundaries. Change a function signature, run the compiler, fix every call site that breaks. The tooling enforces consistency mechanically.

A polyrepo removes that mechanical enforcement. Each repository compiles independently. A breaking change in a shared type doesn’t cause compilation errors in consumers — it causes runtime failures, sometimes weeks later, after the change has propagated through deployment cycles.

An agent working in one repository has, by definition, only that repository’s context. It can’t see that the API Gateway holds a different version of the type. It can’t see that the billing service depends on a field it’s about to rename. It can’t see that three other teams wrote adapters against the old interface that will silently produce wrong output when the schema changes.

This isn’t an agent failing at its job. It’s an agent doing its job correctly within an incomplete view of the system. The incompleteness is structural.

The solution has to be structural too.

---

The System Header Map

The Global Architect doesn’t read implementation code. It reads interfaces.

For each repository, we extract:

• The Core SDK: shared types, traits, error enums
• OpenAPI / Protobuf specs: for service boundaries
• Public function signatures: the exported API surface
• README contract sections: documented behavioral guarantees
• Integration test fixtures: the expected shape of cross-repo communication

Together, this is the System Header Map — a compressed but complete view of what each service promises to every other service. For twenty-plus repositories, the full map is large but not overwhelming. An SDK definition doesn’t need the full implementation; it needs the types and the contracts.

---

The SDK-First Rule

Once the Global Architect identifies what needs to change, a hard gate applies: no domain implementation begins until the SDK contract is updated and all consumer impact is mapped.

1. Contract Proposal

   The Global Architect proposes SDK changes based on the system-wide requirement. It defines the interface — the bridge — before any domain agent touches an implementation. The contract is what the system agrees to, not what one service already does.

2. Consumer Impact Scan

   The agent scans all downstream consumer repositories against the proposed contract change. It lists every call site, adapter, and fixture that will break. This happens before any implementation change is made — not discovered during it.

3. Synchronized Execution

   Domain agents work from the Sync Plan in dependency order: SDK first, then consumers, then services. Each step is verified before the next begins. No domain repository can merge until its contract with the SDK is valid.

The SDK-First rule sounds obvious. We ignored it for six months. Here’s why it’s easy to skip: when a requirement touches only one repository, the SDK doesn’t seem relevant. But requirements that appear local often have boundary effects that aren’t visible until you look at the full interface map. We were wrong about scope more often than we were right.

---

The 422 Incident, Root Caused

Going back to the CRM incident: here’s what the Global Architect would have caught.

The SharedContract type in the Core SDK had a field primary_field: Vec<String>. The CRM requirement needed to add extended_metadata: HashMap<String, MetaValue>. From inside the CRM repository, that looked like a pure addition — backwards compatible, no existing callers affected.

What the CRM agent couldn’t see: the API Gateway had an adapter that pattern-matched on the SharedContract struct using serde’s deny_unknown_fields attribute. Adding a new field wasn’t backwards compatible from the Gateway’s perspective — it was a deserialization failure.

The System Header Map would have shown the Gateway’s adapter on the first scan. The Consumer Impact step would have flagged it immediately. The Sync Plan would have included “update Gateway adapter to accept new field or remove deny_unknown_fields” before any implementation began.

Instead, we found it at runtime, in staging, four hours and two on-call pages later.

// What the Global Architect scans from the Gateway:
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]   // <-- This is the problem
struct SharedContractAdapter {
    primary_field: Vec<String>,
    // No extended_metadata field — will reject incoming payloads
}

One attribute. Visible if you look at the right repository. Invisible if you don’t have the context to know it exists.

---

What Didn’t Work

Running the Global Architect on every task. The high-context model is slower and more expensive than a domain agent. Running it on every task regardless of scope introduced latency without proportional benefit. Isolated tasks — bug fixes in a single service, documentation updates — don’t need the full system view. We added a task classifier that routes cross-repo tasks to the Global Architect and keeps isolated tasks local.

Using the System Header Map as implementation context. Early on, we tried feeding the Header Map to domain agents as additional context — “here’s the full interface picture, now implement in the CRM.” It didn’t work. Domain agents with too much context about other repositories started making unsolicited changes to adjacent service logic. They needed to know the contract, not the full picture. The Global Architect holds the map. Domain agents hold their own context. Those are different roles.

Manual SDK updates. Before the Global Architect, SDK updates happened when someone remembered to do them — usually after an integration failure. The Global Architect doesn’t eliminate human judgment on what the contract should be, but it ensures that when the contract changes, the impact is mapped before implementation begins, not discovered during it.

---

AI Collaboration in This Episode

The Global Architect approach required choosing a model capable of holding a million-token context while reasoning about cross-repository dependencies. That’s a real capability constraint, not a prompt engineering question.

We used Claude for this role specifically. For domain implementation, cheaper and faster models are appropriate — the task is bounded, the context is local, the verification is mechanical. For the system-wide architectural view, model quality directly affects whether the drift detection is correct.

The human role: reviewing the Sync Plan before execution begins. The Global Architect produces a structured diff of what needs to change. We read it. If the scope looks wrong, we push back before any domain agent writes a line of code. This is the highest-leverage human intervention point in the entire cycle: one review, before implementation, prevents hours of downstream debugging.

---

What’s Next

The inner loop has Hook Shields. The outer loop has a Global Architect and SDK-First gates. But these two loops aren’t integrated — they’re running independently, with a human manually deciding when to invoke each.

At low task volume, that’s manageable. At the volume we were approaching, it wasn’t. The coordination overhead was becoming its own full-time job. We needed an Intelligence Router: a system that automatically classifies tasks, routes them to the right verification tier, and orchestrates the correction cycle when something fails.

That’s Episode 9 — and it’s where the loop stops being well-monitored and starts being genuinely self-healing.

Episode 9: The Self-Healing Correction Cycle

Orchestrating trust between local and global intelligence.

Series Overview

The full arc from loop to organization.

---

Earlier in the Series

• Episode 1: The Orchestration Problem — building the autonomous loop from scratch
• Episode 2: Memory — the bead format that gave the loop persistent memory
• Episode 3: Blast Radius — Tree-sitter + KuzuDB impact graph for safe refactoring
• Episode 5: Process Gates — the hard gates that stopped the loop from working against a moving target

---

All content represents personal learning from personal and side projects. Code examples are sanitized and generalized. No proprietary information is shared. Opinions are my own and do not reflect my employer’s views.