A Repository Is Not a Software System

Repositories are excellent containers for versioned source. They are poor proxies for the full software system.

The difference matters most when a machine is expected to act rather than merely search.

Readability is not consequence

Two files can be equally readable and operationally unequal. One may support a demo. Another may govern billing, compliance, or a customer-facing contract. Syntax and local imports do not always reveal that difference.

A repository index can answer useful questions:

• Where is this symbol defined?
• Which file imports this module?
• What does this function appear to do?

But safe system change needs additional answers:

• Who owns the behavior?
• Which contract is public?
• What is the blast radius?
• Which policy applies?
• Which evidence must be refreshed before release?

Those facts often live across repositories, CI, deployment configuration, policy files, generated artifacts, and human operational knowledge.

Bigger context does not create a system model

Increasing the context window can expose more text. Retrieval can select more relevant text. Neither guarantees stable identities, typed relationships, freshness, or authority.

More files != more meaning
Relevant chunks != governed truth
Long memory != current evidence

The missing step is model construction: observations become entities and relationships; evidence remains attached; uncertainty remains visible; changes invalidate affected facts.

The workspace as an operating boundary

A workspace is useful when it represents the system being operated on, even when that system spans multiple repositories and runtimes.

It can connect:

• projects and repositories;
• services and runtime boundaries;
• contracts and consumers;
• owners and policies;
• changes and affected verification;
• commands and durable evidence.

This does not make the repository obsolete. It restores the repository to its proper role: a primary source inside a larger system model.

A better test for AI tooling

Do not ask only whether an agent can read the codebase. Ask whether it can show:

1. which system entities it believes exist;
2. which evidence supports each important relationship;
3. what is unknown or stale;
4. how a proposed change affects the model;
5. which verification closes the loop.

An agent that cannot answer those questions may still generate good code. It does not yet understand the software system it is changing.