A repository guide points to a retired API. The page still loads, search still finds it, and an agent can follow it exactly while producing the wrong change. Who notices the failure, who owns the correction, and which future runs receive it? Those operational questions are what this chapter means by context infrastructure.
Context needs architecture
An agent working on a service may need organization policy, domain rules, team conventions, repository instructions, architecture decisions, and task-specific intent. Providing everything creates noise. Providing too little creates unsupported assumptions.
Hierarchical context solves the scoping problem by letting broad guidance flow downward while local guidance refines it.
Operational repositories create an address
Knowledge is easier to use when it has a stable location, clear ownership, and version history. An operational repository can hold standards, architecture, runbooks, decisions, specifications, evaluations, and agent instructions.
The repository is not valuable because Git is fashionable. It is valuable because changes become reviewable and consumers can reference an exact version.
Freshness is an operational property
A document with no owner or review trigger decays silently. Context infrastructure needs freshness signals: last verified date, accountable owner, affected systems, and conditions that require review. Incident follow-ups, architecture changes, and policy updates should feed the same maintenance loop.
Stale context is more dangerous than missing context because it looks authoritative.
Retrieval must be testable
A context system is working when the right consumer can retrieve the right guidance for a concrete task. Teams can evaluate representative queries, measure missing sources, inspect conflicting instructions, and record when humans had to repair agent context.
The goal is not a larger knowledge base. It is reliable context resolution.
Operate a bundle, not just a repository
Hierarchical Context defines authority and scope. This chapter defines the maintenance work. In the fictional Northstar case, CTX-42 is a run-specific manifest pointing to approved sources. It is not a new permanent copy of every source.
| Manifest field | Why it exists |
|---|---|
| Source identifier and exact revision | Reconstruct what the run actually received. |
| Owner and scope | Know who can resolve a conflict. |
| Authority state | Separate accepted policy from proposals and historical evidence. |
| Last verified date and invalidation trigger | Detect when apparently current guidance needs review. |
| Sensitivity and permitted consumers | Preserve access boundaries through retrieval and summarization. |
| Exceptions and supersession | Show why a local instruction differs from its parent. |
Use revisions for reproducibility and review triggers for freshness. A recently edited document can still be wrong. A stable constraint can remain valid for years. Age alone is a poor authority signal.
Define a small retrieval evaluation
The owner of Orders writes representative questions: which retry semantics govern ORD-42, who may approve a migration, and may a sandbox agent inspect production reports? For each, record the required sources, prohibited sources, and the expected handling of uncertainty.
Run these checks after a relevant policy change, retrieval change, or ownership transfer. A result that cites an obsolete record is a failure even if its answer happens to sound correct. A correct refusal to retrieve restricted information is a successful permission check.
Track misses and conflicts separately. A missing source needs discovery or documentation. Two authoritative-looking contradictory sources need an owner decision. More retrieval cannot solve that disagreement.
Budget maintenance
Assign time for triage, ownership transfer, stale-source review, and deletion. Northstar begins with one service and a small weekly review allocation agreed by its team. That is an experiment, not a staffing formula.
If maintenance exceeds the value of the retrieved context, shrink the collection or the task boundary. Do not solve a decaying knowledge base by requiring everyone to write more.
Retained bundles inherit sensitivity from their contents. Deleting access to the source while leaving an unrestricted summary defeats the control. Decide retention and deletion propagation before capturing sensitive material.
Make expiry change behavior
When ADR-17 is superseded, CTX-42 remains an honest historical record. It should no longer be assembled for a fresh implementation without an explicit exception. A running task pauses at a material invalidation event and asks its owner what to do.
Your first operating artifact is a manifest for one real task and three retrieval checks. Have someone reproduce the source selection without asking the original author. Missing ownership or inaccessible evidence is a useful failure to discover before delegation.