Matthew Gradient · Reference architecture & research pilot

A reference architecture.
A pilot in software.

Matthew Gradient’s approach to judgment under AI amplification, expressed as a control architecture and explored through the SolventAgent software pilot.

This page explains the reference design. The pilot’s scope and limitations are identified separately from the wider controls the architecture describes.

01 · The lineage

Higher abstraction needs better instruments.

When compilers arrived, assembly programmers warned that developers would lose touch with the machine. When garbage collection arrived, the manual-memory camp warned of memory blindness. When object orientation arrived, engineers pointed out that you could no longer trace execution top to bottom by reading.

Those shifts changed what developers could see directly. Instruments — the symbolic debugger, the type checker, the heap profiler, source maps — helped restore visibility at the higher layer. Inspection of the layer beneath remained available where the problem warranted it; it did not have to carry the whole burden of control.

SolventAgent explores the role of a debugger for generated work: making changes to accepted boundaries visible.

The complaint that delegation breeds distance and de-skilling is as old as the compiler. But this time the differences are structural, and the loss of control is not a feeling about the work. It is the state of the work.

When the generator is non-deterministic and the input is informal, recovering intent from a four-hundred-line diff can consume the attention delegation was meant to save. Review needs a clearer reference for what the change was supposed to preserve and accomplish. The boundaries have to be pinned by instrument: preservation checked against what you HAVE, progress checked against what you have PLANNED.

Which is what the instrument is for. As generation takes over more of the implementation, the human task shifts toward vigilance. Without useful instruments, attention can drift to whatever is cheap to check while the intent behind the work slips out of view. Protecting that intent is the job the instrument supports.

That sets the standard the tool has to meet, and the standard is not determinism. The reference is a ratified boundary — something a person has accepted on the available evidence — together with an instrument that reports honestly against it. Ratification records responsibility; it does not turn incomplete evidence into certainty. Determinism is welcome wherever it is available, and it often is not: reflection, dynamic wiring and queries assembled at runtime put large parts of any legacy system beyond static reading.

The extractor's job is to put the right things in front of a person. Measured that way, a guess is not the failure — a guess rendered as a clean verdict is.

Which leaves the question vigilance always comes down to: what gets looked at first. Aviation provides a long-established priority order for competing demands: aviate, navigate, communicate — hold control, maintain the course, and communicate without allowing that demand to displace either. That ordering decides what the instrument puts in front of you, and in what order.

02 · The two representations

HAVE is what you vouched for. PLANNED is what you have not built yet.

Every reading the instrument takes is a comparison between two artifacts, and keeping them apart is what makes either one mean anything.

Two artifacts because there are two questions, and they come apart in both directions. A change can hold every guarantee and leave the work undone. It can deliver the work and take a guarantee with it. Preservation of what you have already established is judged against HAVE, progress against PLANNED, so that intent past and future is protected.

Intent has never had a home in the system. It lived in the author's head, thinly echoed in naming, folder structure, tests and comments — a lossy record that worked only because a human was around to reconstruct the context when something broke.

Generation breaks that arrangement. A model is given an instruction once, writes the code, and retains nothing; the engineer who held the mental model never existed. Intent can no longer be an implicit byproduct of having written the thing. It has to become an explicit artifact held outside the code — which is what HAVE is, and why it is ratified rather than inferred.

Strip a program to its essentials and little survives. Something enters, something is done to it, something leaves — and then it happens again. For each file, HAVE holds those terms:

The single pass is the tidy drawing and the wrong one. Nothing runs once and nothing is written once: every pass leaves state the next one reads, and every change is judged against a boundary the last change moved. Drawn flat, effects look like a leak out of the side of the shape. Across time they are the mechanism, which is why they need governing separately from either edge.

Delegating the interior is only safe once intent has stopped living inside it.

Three rules fall out of that, and they are the entire design.

None of the structure is new. Hexagonal architecture said most of it decades ago, as an aesthetic preference for testability — back when a human held the intent. With a model writing the implementation, the boundary is the only place intent can survive at all.

03 · The ladder

Every rung has a governed edge and a delegated interior.

A single code change is legible at more than one altitude. The lower rungs answer what changed; the higher rungs answer whether it matters. A change enters at syntax and ripples upward.

The reference architecture uses the same comparison at each rung: what changed at the governed boundary, and what does the evidence support? The proposed contract card is layer-agnostic, so broader architecture and purpose contracts can use the same presentation. Coverage at each rung must be implemented and evaluated; the design is not a claim that the pilot already supports every rung.

Human effort does not vanish under this arrangement, it relocates — onto the boundary, which is what a person controls, and onto the intent, which is what the transform is for. Implementation can be regenerated within the accepted boundary. The instrument reports its observable footprint: whether it performs IO, whether it is transactional, whether it writes to a store. It must also show where that reading is incomplete. Its verdict concerns the checked boundary; it does not certify the implementation itself or remove the need for targeted code review.

Ratification is where intent re-attaches to output — a person saying yes, this is what I meant, about work a model produced.

04 · The envelope

Left ungoverned, widening is an attractor state.

If every added capability is a benign amber asking someone to take a look, then over enough changes everything trends widened, the signal decays into noise, and the reviewer habituates and rubber-stamps. That is precisely the failure this exists to prevent, arrived at by a sequence of individually reasonable steps.

A permissionless widened also flattens two unlike events into one light. A utility gaining a pure transform and an auth file gaining the ability to render UI both surface as the same amber. One is noise. The other is a category error.

An added capability is not a verdict. It is a question — and the envelope is what lets the tool answer it instead of forwarding it to a human until the human stops looking.

Both violations read red at a glance, meaning do not proceed casually. The reason differentiates on reading and decides which actions are offered; it does not earn a fourth color.

The envelope lives at the architecture rung, not the file rung. Auth may not render UI is not a fact about one file's history, it is a rule about the system's structure. A file can only observe that a capability was added; only the layer above knows whether it is legitimate for that role. So the objection that everything drifts to widened is not a flaw to be patched. It is the argument for the ladder.

How hard any of this binds is a separate decision, and the architecture has two failure modes rather than one. Too little control produces rubber-stamping, unnoticed drift and unowned decisions. Too much produces fixation — queues, ceremony and attention spent on governance artifacts instead of consequential work. Then people route around the tool, and drift moves into the bypass lane.

A control earns its place only if its result can allow, deny, pause, escalate, narrow or materially inform a decision. Anything that repeatedly consumes attention without changing an outcome is removed, sampled or automated. So ceremony scales with consequence:

For consequential work, Aviate findings require a stop decision, Navigate items gather at checkpoints, and routine Communicate activity can be automated. The pilot’s scope is advisory: findings inform the required decision, and the named owner controls whether work proceeds. An operational integration can enforce an authorised gate at the action boundary. Automatic checks never promote a candidate state into HAVE. Planning is not ceremony at any tier — decomposing the intent changes what gets executed, so it earns its place on its own. What scales with the tier is the decisions, not the plan.

05 · Aviate, Navigate, Communicate

Current interfaces invert the hierarchy.

The doctrine survived because the ordering is cheap to hold and expensive to lose. Mapped onto work done with a model, each class wants different handling:

Communicate is not the prose layer, and its two parts must not be confused. Its activity is automated and inspected only when exceptional. Its content — what the project is for and how decisions get made — is deliberate, versioned, and shared by the people and the models doing the work.

Assistants built on models invert that order. They make Communicate exceptionally polished, produce a strong impression of successful Navigation, and offer almost no instrumentation showing whether anyone is still Aviating.

Which is why vigilance cannot be left as a personal virtue. The ordering is not hard to understand; it is hard to hold against an interface actively inverting it.

That inversion is the mechanism of judgment insolvency. Fluent communication consumes attention and delivers psychological closure while the structural decisions underneath may never have been examined at all. The polish is not incidental to the failure. It is the failure, because it satisfies the reviewer's sense of having reviewed.

So the classes must not be collapsible by fluency. A Communicate-class artifact may never look like a resolved Aviate-class one, which is why the verdict palette is reserved and semantic, why an unanalysed file must never render as Respected, and why a nearly empty attention display is a legitimate result rather than a gap to be filled. Those are all the same rule: polish must not manufacture closure.

An instrument that tells you where not to look is doing as much work as one that tells you where to.

It is tempting to map the ladder onto this doctrine — the File rung as Aviate, Architecture and Purpose as Navigate — and it is wrong. A purpose rule that prevents duplicate charges is Aviate-critical; a cosmetic change at the file rung is Communicate. Priority is assigned per clause and per finding: the rung says where a fact lives, the priority determines the response it requires. Enforcement depends on the operating mode. The opposite failure is easier to mistake for diligence: a crew that spends an approach diagnosing a burnt-out indicator lamp is not being careful, it is fixating, and the aircraft descends while everyone stays busy. Treating every generated line as equally deserving of attention can reproduce that failure in software. Targeted code review remains necessary where the consequences or evidence warrant it.

06 · Sprints and snapshots

The spatial god-file has a temporal twin.

Crossing from HAVE to PLANNED is never executed as one task. Hand a model an entire planned entry and you get the god project: a sprawling change nobody can re-anchor, where stochastic per-step deviation compounds over an uncorrected sequence. Add subscription billing, organizations, role-based permissions and reporting is one sentence and several hundred undeclared design decisions — whether an organization owns a subscription or the reverse, whether permissions are checked at the edge or in the domain. Every one is a boundary decision, and none of them was put to anyone.

So the model's job at this point is decomposition rather than construction: given the parsed reality, the target entry, and the project's own design documents as retrieval context, propose an ordered sequence of small increments that walks from one to the other. Each increment is scoped to a section, individually extractable so the pipeline can return a verdict on it, and small enough to ratify honestly — because too large and the human rubber-stamps, which is drift under another name. That bound is reviewability, not a score.

Planned entries are scoped per section for the same reason. A sprint that has to touch every section at once is a god project by definition. And a planned entry is a dormant rule, checked against what exists but not yet enforced, so the gap between sections is a roadmap the tool computes rather than one anyone types. Promoting it arms the rule, which is a governance act: a rule the current code violates cannot be armed quietly.

For consequential work, the decomposition is a proposal. So is a plan a person writes by hand — both are candidate artifacts and both require explicit acceptance, because authoring is not the same act as vouching for the result. Private Tier 0 exploration remains outside that acceptance process.

The source of a plan never confers authority. Only ratification does.

Each accepted increment ends in a ratified, frozen state, which makes it a snapshot worth being able to return to. Snapshots form a tree rather than a line. Discovering three increments in that the plan was wrong should not require unwinding through territory nobody anchored: return to the last state a person vouched for and fork from there, keeping the abandoned branch, because a rejected direction is itself a governance record. That snapshot provides a concrete reference for the next increment. Ratification can miss a problem, but its evidence and decisions remain inspectable — an anchor has to be a place you can stand, not a moment that has passed.

07 · Scope

Code gives boundary checks a mechanical foothold.

Source code exposes formal structure that an instrument can inspect repeatedly: declared imports and exports, types, and some effects. Within a supported language and analysis scope, those readings can be mechanical. Reflection, dynamic wiring, runtime state and external systems leave gaps that need other evidence. Automation reduces the repeated cost of inspection; it does not make coverage complete or review free.

An underwriting memo, a clinical summary, a claims decision, a client deliverable — each has a boundary just as real: valid inputs, conditions that must hold, outcomes that must never ship. A model can read a candidate boundary out of those documents and cite the span it read each obligation from. What no extractor supplies is authority: which guarantees actually matter here, which failures are survivable, what each role may do. Until someone who holds those answers ratifies it, an extracted boundary is a description of current practice rather than a standard anything can be judged against.

The instrument must distinguish mechanically checked facts, model-inferred findings and unknowns in either domain. Comparing two extracted records can be deterministic while both records remain incomplete. A finding must retain its evidence and coverage limits all the way to the decision.

Uncertain evidence can still justify pausing a consequential action until someone verifies it. A gate can mean “do not proceed until this is resolved”; it does not have to mean “the extractor has proved a violation.” The consequence and the agreed decision rule determine the required response. The advisory pilot is intended to flag that response; enforcement belongs to a separately implemented operational integration.

The pilot makes selected parts of the reference architecture available for examination in software. Its behaviour and coverage must be assessed on their own evidence. Matthew Gradient’s preliminary diagnostic applies the underlying questions in the client’s context through a guided questionnaire.

The pilot’s limits, stated plainly

• It does not tell you the code is correct. A reported boundary result is limited to the clauses checked and the evidence available; an unknown remains unknown. Correctness still requires the appropriate engineering checks.
• The pilot is scoped to advisory review and does not block commits. Enforced action gates and higher governance tiers belong to the wider reference architecture and require their own implementation and verification.
• It does not certify the interior, and it will never present a boundary check as verification of the full implementation.
• It does not replace tests, or reading the code in the places that actually warrant it.
• It is not a claim that nothing needs review. A quiet display is meaningful only when analysis completed and coverage is visible. It means no material issue was found within that coverage; it does not establish that the code works.
• It is not a claim that every workflow can be automated this way. Software is the exception that made the mechanism visible.
• A reading is only as good as what the extractor actually looked at, and static reading runs out early in a large or legacy system. What the instrument owes you is not certainty but an account of its own coverage: what it checked, what it could not, and which findings rest on a model's reading rather than a rule.

The generator’s fluency establishes no proof of correctness. Acceptance needs an explicit boundary, evidence about what was checked, and an honest record of each ratified change to that boundary.