DEV Community: Aming

The agent industry made stack overflow billable—but who owns the return?

Aming — Thu, 23 Jul 2026 15:25:01 +0000

The model chooses the next call. The runtime counts the calls. The customer
pays for the calls. Nobody owns the return.

The agent industry took one of the oldest programming bugs and turned it into
a product category.

It shipped recursion without a base case.

ReAct standardized think, act, observe, repeat. Reflection adds another lap.
Re-planning adds another plan. Graph frameworks make the back-edge explicit.
Then, when the system cannot establish that the job is semantically finished,
the harness offers a maximum-turn setting, a timeout, a token budget, or
something literally named recursion_limit.

That is not a semantic completion model.

It is a kill switch attached to a meter.

A resource ceiling does guarantee that the run will eventually die. That is
not the disputed point. It proves death, not completion.

In an ordinary code review, a self-call without a trusted base-case guard or
termination argument is a bug. Nobody proposes a larger stack as the fix. In
agent engineering, we made the back-edge ergonomic, let a probabilistic model
assert its own postcondition, wrapped the recursion in tracing, and priced the
fallback.

The defense is predictable: useful agents need loops.

Of course they do. Search, retries, and probabilistic refinement need
iteration. The charge is narrower — and worse. When the body can manufacture
the reason for its next lap, when a state the policy calls terminal remains
executable, and when the only generic external boundary is numerical, the
lifecycle carries the same termination debt as recursion without a trusted
base case.

Maximum turns can cap the damage. They cannot prove the goal was reached. A
timeout can kill the process. It cannot make the answer correct. A token
budget can bound the invoice. It cannot make recursion return.

The agent industry did not solve termination.

It made stack overflow billable.

Mine ran for three days, generated 102 work items, and spent roughly two
thirds of its activity working on itself while every aggregate gauge stayed
green.

It also exposed exactly one legal action at every step. The entrance problem
was solved.

The position problem was not.

I have the stack trace

I know this failure because I built it into a governance runtime designed
specifically to prevent AI drift.

The system gives coding agents bounded contracts, frozen acceptance criteria,
append-only evidence, independent QA, verified position, merge authority, and
one legal action at each step. Evidence is stamped with the commit,
generation, and authority that warranted it. This was not a toy prompt loop
running blind. It was the anti-drift harness with every gauge attached.

For close to three days, it looked healthy.

Repairs merged. Tests passed. Backlog items closed. Red no-PASS verdicts were
visible on the ledger. The system was not concealing failure. It was
converting each failure, promptly and legally, into another apparently useful
piece of work.

What I felt was only that development had become strangely slow.

Eventually I asked my AI co-developer a lazy-sounding question: after an
audited bypass, do we return to the old item and keep trying to close it?

Six pieces of code evidence came back.

Yes.

The recovery path said:

close(item) → blocked → repair() → repair returns → close(item)

The second close could reveal the next blocker. That blocker created the next
repair. The next repair returned to the same item again.

This was not a workflow template being applied to fresh work. It was the same
semantic instance calling its own lifecycle again after the generation had
already crossed what was supposed to be a terminal barrier.

The ledger showed the depth. During the three-day window, 102 work items were
created. Sixty-eight percent were repair, diagnostic, or recovery items.
Thirty-six items closed; 67 percent were governance-family work. Roughly two
thirds of all work-item activity was the system working on the machinery that
decided whether the system could stop working.

Every frame looked responsible. Every call had evidence. Every repair fixed
something real.

And every aggregate gauge celebrated the stack getting deeper.

I had one legal entrance. I was in the wrong generation.

My earlier drift
theory
reduced one agent step to two probabilities:

P(correct step) = P(correct position) × P(correct entrance | position)

next_legal attacks the second term. Once the runtime knows the state, it
computes the authorized transition and pushes one entrance instead of asking a
probabilistic model to choose among several. Remove the choice; remove the
routing tax.

My runtime did that. Every actor received one legal next action.

It still orbited.

The equation was not wrong. My definition of position was incomplete.
next_legal is conditional: it can produce the correct entrance only for the
position it was given. A perfect router from an expired coordinate is a
deterministic mistake. One entrance cannot save you when the room number is
wrong.

Verified position is not a stage label. It has three parts:

coordinate = item × stage × generation × invocation × authority × terminal
status

datum = goal/scope epoch × acceptance criteria × world/baseline epoch

verified position = coordinate × datum × live warranty

The coordinate says where the work is. The datum says which goal, scope, and
baseline define “progress.” The warranty says whether that coordinate and
datum still have authority in the current world.

Remove any factor and “position” becomes a plausible story about the wrong
place.

My earlier position guide answered “where?” This incident added two questions:
“relative to what?” and “is that frame still authorized here?”

This article does not replace the position theory. It supplies the
control-flow mechanism underneath one class of position failure. A missing
base case makes the journey self-extending. Warranty expiry invalidates old
coordinates. Position aliasing hides the invalidity. The probability law
measures the result.

The model continues. The runtime counts. Nobody returns.

The field's consensus definition — an LLM using tools “in a loop” — standardized
the next call and outsourced the return. After crowdsourcing more than two
hundred definitions, Simon Willison landed on
"An LLM agent runs tools in a loop to achieve a
goal". Anthropic's definition
is almost identical: agents are
"typically just LLMs using tools based on environmental feedback in a
loop".

ReAct gives the model a Finish[answer] action; the harness gives the operator
maximum turns, timeouts, and token ceilings. One is a model-generated return
instruction, not a trusted success predicate. The other is forced execution.
Neither is external proof that the obligation was satisfied.

The model owns continuation. The runtime owns containment. Semantic return
sits between them, unimplemented.

If your agent stops only when the harness kills it, it did not finish. It
hit the billing condition.

We moved the stack somewhere too expensive to overflow

These backlog rows were not literal in-memory stack frames. There was no LIFO
call stack waiting for the operating system to kill it.

That made the bug worse, not better.

The operational stack had been distributed across:

context holding the conclusions of earlier calls;
backlog rows holding suspended obligations;
recovery tasks holding the promise to return;
QA histories holding prior verdicts;
graph edges holding the route back in; and
token and time budgets paying for every additional frame.

Ordinary recursion fails loudly because memory is finite and the runtime knows
what a frame is. Agent recursion can externalize its frames into durable
storage, reload them tomorrow, and invoice each return trip separately. The
stack becomes deep enough that it never needs to overflow. It can simply
become the organization.

That is the perverse achievement:

we built a stack overflow that sends an invoice instead of a crash report.

The ledger was the stack trace. We had not named it as depth because each row
used a respectable business noun: repair, review, recovery, follow-up. Once
recursion escapes RAM, it does not look like recursion. It looks like a
backlog.

“A loop is not recursion” is true — and not a defense

Iteration is not recursion. A for loop over a finite collection is not a
recursive function. A stochastic search can revisit a stage. A long-lived
service may accept new work forever while every individual case terminates.

The charge is not about syntax. It is about semantic self-reentry. A “loop”
carries the termination debt of recursion when its body can manufacture the
guard for its next invocation, a state the policy calls terminal remains
executable, and only a numerical resource boundary can force return.

A reusable workflow template is ordinary iteration:

dispatch(item 1) → close(item 1) → dispatch(item 2)

Each pass binds fresh data. Completed instances remain completed. My failure
was different:

close(item X) → repair() → close(item X)

The same instance returned after its generation had terminalized. “Closed”
was spelled like a base case and wired like a recursive branch. That topology
may be implemented with a while loop, a message queue, a graph edge, or a
database row. Syntax does not pay its termination debt.

GraphRecursionError is the euphemism briefly failing

The graph-orchestration wave made agent control flow inspectable. It made the
back-edge visible, then left its authority untyped.

The early LangGraph README was admirably direct:
"The main use is for adding cycles to your LLM application. Crucially,
this is NOT a DAG
framework."

The framework also exposes a
recursion_limit,
RemainingSteps, and GraphRecursionError. LangGraph exposes END and
conditional routing too. The abstraction failure is not that exits are
impossible to draw. It is that a justified retry and the resurrection of a
terminal generation are both typed as merely an edge. Continuation is
first-class. Its proof obligation is application homework.

GraphRecursionError is the framework briefly dropping the euphemism.

The OpenAI Agents SDK has
MaxTurnsExceeded.
Anthropic recommends stopping conditions such as a maximum number of
iterations. Responsible runtimes need these circuit breakers. The scandal is
that they are asked to carry a proof obligation the application never
defined.

A base case defines a non-recursive return. A termination argument shows that
recursive calls reach it. A postcondition says whether the return is valid.
An agent needs all three: a trusted success guard, a justification for
continued execution, and a bounded failure path. A recursion limit supplies
only the last. It guarantees that the run will die after N steps. It cannot
guarantee that the obligation was satisfied.

Raising the limit may be appropriate when a valid bounded process genuinely
needs more steps. Without a termination argument, it only expands the blast
radius.

A budget is not a base case. It is a price ceiling on a bug.

Policy text wrote the recursive call

Nobody intentionally drew this topology.

I wrote it in prose.

My operating principles said “continue the original lane” and “the source row
remains OPEN.” Each phrase was locally reasonable in the situation I had in
mind: persist inside a live run; do not discard an unfinished obligation.

My AI co-developer compiled those sentences literally into a control
back-edge. Then it added a test asserting that back-edge, so the wrong
topology was not merely present. It was defended.

Policy text is code now. Ambiguity compiles.

A missing base case in source code attracts a familiar review comment. A
missing base case in operating prose has no syntax error. It can pass tests
that faithfully encode the mistake and arrive days later as a vague feeling
that the organization is slow.

This is what “AI writes the implementation” changes about management. Your
verbs become control flow. “Continue,” “resume,” “return,” and “keep open” are
not motivational language. They are candidate edges in an executable graph.

If you do not state the negative edge — never return after this barrier —
the compiler is free to invent it.

Every successful call manufactured the next call

A missing base case explains the shape. It does not explain why the recursion
kept discovering legitimate work.

The fuel was warranty expiry.

Every conclusion produced by an agent — a plan, diagnosis, review verdict, or
claim of completion — is warranted by the world and belief state in which it
was minted. Every lap can change one or both. Writes alter files and APIs;
reads reveal facts. Either transition can invalidate conclusions minted under
the previous (world, belief) state.

The invalidation is selective. History remains true as history. Acceptance
criteria deliberately pinned by contract remain pinned. The casualties are
current-state claims whose ground has moved.

Ordinary agent context barely represents that distinction. Attention has an
order column. It does not have a validity column.

Now replay the recursive call.

The original item accumulated evidence in world V0. Its repair changed the
runtime and created world V1. Returning to the old item resumed a logical
invocation whose premises were now partly stale. Re-running QA could expose an
incompatibility that did not exist — or was not visible — in V0. Fixing that
blocker created world V2, making the next return still less congruent with the
original evidence.

Every successful repair could manufacture or expose the premise for the next
recursive call.

The recursion brought its own arguments.

Not every blocker in my three-day window was caused by stale premises. Some
were ordinary defects that repeated verification surfaced. The topology did
not care. Both kinds became fresh reasons to call the same lifecycle again.

This is why retry budgets attack the wrong variable. They limit how many
times the system may consume possibly expired premises. They do not tell the
system which premises remain authorized. Longer context can enlarge the stale
surface. Better retrieval can retrieve the wrong conclusion more accurately.

Relevance is not validity. Recency is not authority. More memory is not a
return statement.

The judge moved. Then it refused to die.

An earlier incident produced nine QA rejections in 27 hours while every test
stayed green. Each finding was locally real. The reviewer knew the candidate
and the stage. What moved was the measuring standard: every lap widened scope
and rewrote the pass predicate.

The position in memory was correct. The reference frame drifted.

The fix was to freeze the verdict baseline to the goal, scope, and acceptance
criteria that existed at dispatch. Findings beyond that line became new work
instead of new reasons to fail the current candidate.

The three-day recursion failed in the opposite direction. This time the judge
stayed while the world moved. Repair changed the runtime from V0 to V1, but
the old generation, evidence, and evaluation authority were reopened as
though their warranty had survived. Invocation one and invocation nine both
rendered as “in review.”

Call that position aliasing: different generation, invocation, world, and
warranty coordinates collapse into the same stage label.

One loop mutated its base case. The other resurrected an expired one.

The position law is the same in both:

The success predicate must be immutable within an invocation and
non-transferable across invocations.

Freeze the judge within a generation. Retire the judge when the goal or world
epoch changes. Search may loop. Evaluation authority may not drift.

My watchdogs missed both failures. One looked for rejection streaks; every
recursive call eventually succeeded. Another looked for flat progress; real
repairs merged. Both thermometers measured scalar activity. The pathology
lived in reference frame, direction, and depth.

A dashboard that prints only “in review” is showing an instruction pointer,
not a position. A perfect next_legal function fed that coordinate will serve
one confidently wrong entrance.

The public failures already have recursion-shaped names

AutoGPT's first wave produced the canonical report:
"It loops the same queries although it successfully got the google
results".

The intention “search for X” should have reached a base case when the answer
arrived. The tool call changed the agent's epistemic state: the answer was now
available. The intention survived as though nothing had changed. The same
logical obligation scheduled itself again.

Research on intrinsic self-correction reached a similarly uncomfortable
result:
"LLMs struggle to self-correct their responses without external feedback,
and at times, their performance even degrades after
self-correction."

A reflection loop without fresh authority can repeatedly call a
transformation over conclusions minted by the same process. It spends more
tokens without necessarily moving closer to a semantic return condition.
Confidence accumulates. Ground does not.

The MAST taxonomy,
1,642 annotated traces across seven
frameworks, reported step repetition as
its most frequent failure mode at 15.7 percent and unawareness of termination
conditions third at 12.4 percent. A
July 2026 scan of 6,549 agent
repositories reported 68 confirmed infinite-loop failures across 47 projects.

Those studies report symptoms, not one proven mechanism. The recursion model
offers a falsifiable engineering question that cuts across them:

What input permits a successful return, and what termination argument — a
ranking function, probabilistic bound, or bounded-failure contract — justifies
another invocation?

If neither answer exists, the agent does not have a stopping condition.

It has an allowance.

Fix the first probability term

next_legal collapses entrance uncertainty only after position is valid.
These rules repair the first term.

1. Type position completely. Bind every position claim to item, stage,
generation, invocation, goal/scope epoch, world/baseline epoch, authority, and
terminal status. “In review” is not a position. It is one field.

2. Freeze the datum within a generation. Goal, scope, acceptance criteria,
and verdict baseline do not float per lap. Findings outside the frozen line
become new work. The loop may explore; it may not move its own finish line.

3. Expire the warranty across generations. If a goal or world change
invalidates the frame, the current invocation returns. New reality creates a
new generation with a freshly derived datum. Old evidence remains history,
never current authority. A fresh UUID is not enough unless the root obligation
is retired or reduced.

4. Compute one entrance from that warranted position. Only then should the
runtime push next_legal. Maximum turns, timeouts, and token ceilings remain
circuit breakers: bounded failure, never completion.

The architecture is simple to state:

dynamic search inside an externally bounded generation, followed by an
irreversible terminal barrier.

The outer service may run forever. The individual case must return.

Freeze within the generation. Regenerate across it.

Position first. Then one entrance.

The detector is structural. The boundary is honest.

My scalar watchdogs slept through three days of recursion because every call
did useful work. Real terminal semantics create a structural detector:

Any control edge that re-enters a generation after its terminal barrier is
an alarm on first occurrence.

No threshold and no anomaly model. Provenance may connect a new repair to old
work; history is supposed to remain connected. The alarm is for control flow
that makes the terminal generation executable again. A second detector can
watch user-facing work versus repair, diagnostic, and recovery rows. Structure
catches the illegal call. Work mix shows the invoice.

This is not new theory. Workflow
soundness property requires,
among other things, that every case can terminate cleanly. A 2026 paper on
agent execution graphs names
"review loops that cycle indefinitely".

My narrower contribution is the receipt: ambiguous policy compiled into a
defended back-edge, successful repairs loaded the next call, template
coordinates hid the depth, and the cost rendered as progress.

The offending orbit is fixed. Bypassed generations now become terminal WAIVED
after their audited barrier and remain available as history, never as a
destination. The detector is not yet running.

Its falsifiable test is a replay of the three-day ledger: fire on the first
illegal re-entry and expose the work-mix ratio within hours. If it cannot, this
article documents a diagnosis rather than a cure.

Stop selling the missing return statement

The field keeps asking how to make agents continue for longer.

More context. More memory. More reflection. More retries. More graph steps.
Larger recursion limits.

That entire list assumes continuation is the scarce capability.

It is not.

Continuation is the part we standardized. Return is the missing half.

Reliable control requires both terms of the earlier equation: serve a
versioned, warranted position, then compute one legal entrance from it.
next_legal without position authority makes the wrong turn deterministic.
Verified position without entrance collapse leaves a known transition to
model sampling.

Before you add another turn, name the input that permits a successful return.
Before you raise a limit, state the ranking argument, probabilistic convergence
bound, or bounded-failure contract that makes continued execution legal.
Before you call a graph “controlled,” inspect whether a state the policy calls
terminal remains executable.

If you cannot answer those questions, tracing will only document the
recursion. Memory will only preserve its arguments. Reflection will only add
frames. A larger context window will only make the stack more comfortable.

The model chooses the next call.

The runtime counts the calls.

The customer pays for the calls.

Nobody owns the return.

That is not autonomy. It is a missing base case with better marketing.

It does not return. It bills.

The runtime described here is built in the open:
github.com/amingclawdev/aming-claw.
The internal numbers come from its governance ledger and git history. Earlier
in this series:
Fixing AI drift is a simple probability
problem
and
Push, not
pull.

Fixing AI drift is a simple probability problem - Your human-in-the-loop is a very expensive GPS

Aming — Tue, 21 Jul 2026 13:44:24 +0000

Your human-in-the-loop is a very expensive GPS.

Fixing AI drift is not an AI problem. It is a small probability problem —
two variables and one multiplication — and it has an engineering solution
that works at any model tier.

Here is the entire theory:

P(correct step) = P(I know where I am) × 
                  P(I pick the right door | position)

Every step an agent takes is the product of two estimates: whether it
knows where it is, and whether it takes the right entrance from there. In
most agent systems both factors sit quietly below 1.0. Multiply them
across a long task and you get the failure everyone has watched: steps
one through ten crisp, correct, fast; somewhere past the twentieth step
the agent is still busy, still confident, still producing plausible work
— and no longer doing the task you gave it.

The field has a taxonomy for this (goal drift, role drift, plan decay,
hallucination cascades) and a modern reliability stack against it: ReAct
loops inside supervisor–worker hierarchies, goal re-anchoring,
checkpointed state, and the four levers of context engineering — write,
select, compress, isolate. I run that stack. One of my agents still
drifted for 27 hours in the middle of it — nine locally correct decisions
in a row while the project died underneath them. The stack failed for a
structural reason, not a tuning one: every piece of it improves the
agent's own account of the two variables. None of it makes either
variable true.

What follows: the two variables, the 27-hour case that shows loops and
memory don't cure them, and the system design that does.

Which door? — the entrance variable

Start with the entrance variable, because it is the easier one. When a
system offers several entrances — three ways to register, two documents
that both claim authority, "you could do it either way" — the agent must
reason about which to take, and reasoning is sampling: a deterministic
event becomes a probabilistic one. Chain twenty such choices at P = 0.95
each and the flow completes correctly 36% of the time. Nobody's model got
dumber in step fourteen; the luck budget ran out. (I watched a frontier
model, minutes after writing "index-first discovery" discipline into
another agent's contract, ignore that discipline itself and go guessing
with find — the repo offered five entrances, including a queryable code
graph, and its training prior picked. You cannot configure the sampling
distribution. You can only remove the choice.)

The arithmetic itself is by now folk wisdom — Utkarsh Kanwat's widely
shared 2025 essay ran the same numbers to bet against agents outright,
and the industry's standard responses are to shorten the chain and add
human checkpoints. Both just lower N. The doors stay open.

But the choice tax is roughly constant per step. It explains failure; it
does not explain why failure accelerates with task length. That is the
position variable's job.

Where am I? — the position variable

An agent's belief about where it is — which phase, which obligations are
met, what has actually happened — comes, by default, from one source: its
own context. Its memory of its own trajectory. In navigation terms, that
is dead reckoning: estimating position by accumulating your own
movement log. And dead reckoning has a famous property — the error only
grows. Nothing in the log ever removes accumulated uncertainty.

This is why drift is a long-task disease. Entrance multiplicity taxes
each step equally; position uncertainty compounds across steps. Short
tasks end before the estimate degrades. Long tasks are precisely the ones
that outlive their own position estimate.

A week of instrumented agent operation caught the mechanism three ways:

Position amnesia. One session went through 105 context compactions in a day; after every compaction the agent re-derived the same solutions and re-hit the same errors. It hadn't lost skill. It had lost place.
False position beliefs. A bounded worker wrote a status file claiming it had started up, implemented, and committed — while the server showed its startup rejected and no such commit existing. Not strategic deception: its self-narrative had diverged from reality, and self-narrative was its only position source.
Position forks. Two subsystems each held an authoritative opinion of where one piece of work stood — "merged, done" versus "evidence missing, unclosable." Same work, two positions, and every agent that touched it inherited the fork.

There is a fourth variant — subtler than all three, able to hide inside
a healthy-looking loop for a full day. It deserves the whole case study.

The case: every finding real, the project dying anyway

My governance system (aming-claw)
runs AI coding agents under enforced contracts: every change needs a work
item with acceptance criteria, evidence lands on an append-only timeline,
and merges require independent QA from a separate agent identity. In
early July it needed a bounded new capability: a CLI agent service to
drive multiple vendors' models — Codex, Claude, local Ollama — from one
machine without mixing up accounts.

The implementer (a frontier coding model running as a governed worker)
shipped a clean 997-line foundation in a morning. My adversarial QA agent
— separate identity, explicit mandate to attack the work — found real
gaps. Three fix rounds before lunch. Working exactly as designed. The
next slice — a host-private registry for the profiles — was dispatched
that evening.

The next day, the registry hit review.

Round one: FAIL — genuine privacy and path-isolation gaps. Fair.
Rework. Round two: FAIL — a real hole in crash-cleanup logic. Also
fair. Rework. Round three is where you should slow down and admire the
findings: the reviewer proved the schema validation accepted behaviorally
incompatible database objects, and demonstrated — by writing a SQLite
trigger that silently inserted a shadow row — that registration reported
success without rolling back the exact mutation set. Genuinely brilliant.
FAIL.

By end of day: nine rejections, zero approvals. All 818 tests green
in every round. Not one finding wrong. Not one fix that made the system
worse. Meanwhile the product package had not moved in 27 hours,
review-driven work items outgrew product work 19 to 3, and the codebase
was on its way from one thousand lines to a ten-thousand-line fortress
guarding a feature that didn't exist yet. There was no round N where this
converged: "find problems" is an objective with no finish line, and the
pass bar silently rose to meet whatever the implementation survived — a
ratchet with no release lever.

The intervention that broke the loop was one message: freeze the verdict
baseline to the acceptance criteria that existed at dispatch; findings
beyond that bar become new work items instead of failing the candidate;
go back to the feature. Within 24 hours the same agents under the same
governance shipped the daemon, the supervisor, the scheduler, and
local-model certification. The capacity had been there the whole time.

Now read the case through the theory. It is not a dumb agent, a bad
reviewer, a missing memory, or a broken loop. The reviewer ran a textbook
ReAct loop — observe, reason, act — under a supervisor, with externalized
state on an evidence timeline. Every component of the modern reliability
stack was present and functioning. What failed is the fourth position
variant: reference-frame drift. The reviewer always knew which
candidate it was reviewing — its position in memory was fine. What
drifted was its measuring standard: the pass bar had no fixed datum, so
its coordinate system moved a little every round, and every measurement
remained internally consistent while the whole frame slid off the goal.

Why the modern stack doesn't touch either variable

Translate the current reliability stack into navigation terms:

Industry fix	What it is, navigationally
Longer context / memory	A thicker logbook
Context engineering: write / select / compress	Better-organized logbook, better retrieval, cleaner entries
Isolate / subagents	Shorter voyages (smaller error surface — real help)
Goal re-anchoring	Re-reading the destination's name aloud
Checkpointed state / scratchpads	A logbook the agent writes to disk
Supervisor–worker hierarchy	Splitting the voyage among navigators

Every one of these improves dead reckoning quality. Not one provides
a verified position. Two properties are missing across the board, and
each has a live counterexample above:

Externalized state is still self-authored state. The worker with the
false position beliefs had a persisted status file — checkpointing par
excellence. Externalization without verification just persists the
delusion. A position claim is worth nothing unless something other than
its author can reject it.

The reference frame itself can drift. The QA loop was locally correct
nine times in a row and still captured the project, because no fix in
that table anchors the standard the loop measures against. A loop does
not fix position; a loop compounds per-iteration bias.

A lost navigator does not need a thicker logbook, a tidier logbook, or a
committee of navigators comparing logbooks. He needs a position fix from
outside the boat, against a datum that does not move.

The human in the loop was the position guide all along

Which raises the obvious question: if the missing instrument is this
fundamental, why hasn't a whole industry noticed? Because the standard
mitigation hides it. Put a human in the loop and drift disappears — and
everyone concluded the human was supplying intelligence. Decompose
what the human actually does at each check-in: "you're off track" — a
position fix. "Not that one, this one" — an entrance collapse. And,
rarely, "this framing is wrong, stop" — actual judgment. The first two
are not intelligence work. They are manual position service: a human
GPS, polled at human frequency, priced at engineer salary, degrading
with boredom. Human-in-the-loop works precisely because it is a
hand-operated position guide — which is also why it cannot scale, and
why it taught the industry the wrong lesson about what it was providing.

The agent never needed the human's intellect at those check-ins; my
drifted reviewer was doing genuinely brilliant work — inventing trigger
attacks — while lost. It needed the human's coordinates. And two of
the three services the human provides are mechanical: a runtime can
serve position and entrance at every step, instantly, identically at
step 3 and step 3,000, without fatigue and without a salary. That is
the real argument for systematizing the loop — not that the machine is
smarter than the human, but that most of what the human does there was
never a judgment task to begin with.

The third service is the one that must stay human — and concentrating
the human there is the point. My 27-hour ratchet was broken by a human
sentence no guide could have pre-written, because the pathology was
being encountered for the first time. But watch what happened next: the
judgment was encoded — baseline freeze — and the runtime now enforces it
forever. The human never makes that call again. That is the one ratchet
you actually want: every repeated human intervention is a system defect;
every judgment call becomes a rule; the human's mechanical workload
falls toward zero while their attention concentrates on the calls no
system can pre-write. A bored human rubber-stamping fifty checkpoints is
not safety — it is a position guide running at 0.1 Hz with an attention
problem. One focused human making three genuine judgment calls a week,
on top of a runtime that handles the other two variables per step, is
both faster and safer.

The solution: a role-bound position guide

The system I run converged on a cure I can now name properly: give
every agent, at every step, an external, verified, role-bound answer to
"where are you" — measured against a frozen datum, and pushed to the
agent rather than waiting to be fetched. Five properties, each earned
from a live failure:

External. Position comes from the runtime's contract authority — a first-missing-line service that answers "given everything actually accepted so far, here is where you stand and the one legal next action." The agent's context is commentary; the runtime's answer is position. When an agent dies mid-task, its successor does not need the predecessor's memories — it re-fixes position from the timeline and continues. We have resurrected agents twice this way. Recovery is re-fixing, not remembering.
Verified. Positions are earned, not declared. You are not "past startup" because you say so; you are past startup because the gate accepted your startup evidence. Every gate is a landmark fix that resets accumulated estimation error to zero. A gate, seen this way, is not a wall — it is an odometer reset.
Role-bound. "Where am I" has no role-free answer. The worker's position is the next contract line; the reviewer's position is the candidate commit it is bound to; the orchestrator's position is the lane phase. Serving one undifferentiated state dump forces each agent to reason out its own slice — reintroducing the choice tax through the back door.
Datum-frozen. The standards an agent is measured against are pinned at dispatch time and hashed. Discovery of new concerns is welcome — as new work items, never as silent movement of the current bar. This is what fixed the ratchet: adversarial review kept its teeth, but its intensity became a controlled parameter (full battery on round one; rounds two and up re-verify only prior failures against the frozen baseline) instead of an unbounded objective.
Pushed, not pulled. This one the theory itself forces. Consulting the map is one more door, and the probability an agent walks through it collapses exactly when it matters most: pulling requires the agent to know it is lost and to know what to fetch — precisely the judgment drift has already corroded. The evidence is brutal. Handed a code dependency graph as a tool and left to pull from it, agents in one benchmark made zero calls to it in 58% of trials (CodeCompass, arXiv 2602.20048); the frontier model from my entrance anecdote had exactly that instrument available and went guessing anyway. Position is not a tool the agent may call. It is what the runtime serves with every step, before the agent acts. I have argued this delivery half separately as "push, not pull" — the two-variable theory is why it is not a style preference.

Put together, a guided step becomes a navigation loop older than
software: fix your position → take the one indicated heading → confirm
at the checkpoint → new fix. The agent supplies intelligence inside
each leg; the system supplies certainty about the map.

Who guards the guide

One instrument remains, and my case earned it the hard way: the ratchet
happened inside a guided runtime — every round procedurally legal, the
guide correctly serving position within a frame that was itself sick. A
guide cannot see its own frame drift from inside. But every drift
pathology I have logged, whatever its mechanism, shares one
machine-readable symptom: activity without progress. Sailors
distinguish speed through water from speed over ground — my reviewer had
enormous speed through water (nine brilliant rounds, thousands of new
test lines) and zero speed over ground for 27 hours. You cannot
pre-write a detector for a disease you have not met; you can pre-write
the fever thermometer, because the fever is generic even when the
pathogen is novel.

So the mechanism now being encoded from this case: when rounds
accumulate and progress toward the dispatched objective stays flat, the
runtime pushes the aggregate view into the loop — round count, product
movement, the frozen baseline — and demands a self-audit anchored
against it. Not "are you drifting?" (a drifted agent answers "every
finding is real," and it's true); instead, the panorama the agent
structurally cannot see from inside, with the burden of justifying
another round against the dispatch baseline. If the stall survives,
escalate to the human. Note what this automates: the glance that saved
my project. Noticing the flat line was the mechanical half of my
intervention — only the reframe was judgment.

The boundary that keeps this from becoming a cage

Some choices are mechanical: the right branch is knowable in advance, and
leaving it open is pure probability tax. Collapse those without mercy.
But some choices are the work: which frame fits a novel failure, what
is worth building, when a rule itself is sick. Collapse those and you
have built a workflow engine that confidently does the wrong thing. Spend
judgment only where judgment is irreplaceable — and the test is whether
you could have written the correct choice down before the agent arrived.

Old wisdom, new constraints

Manufacturing calls the entrance half poka-yoke — design the fixture so
the part only fits the right way. Robotics calls the position half SLAM —
nobody trusts odometry alone; everybody fuses in landmark fixes. Type
systems call it "make illegal states unrepresentable." We did not invent
the idea that reliability lives in the environment's topology rather than
the operator's skill.

Three things are new when the operator is an LLM agent. First, the
operator is a probabilistic reasoner you cannot configure — an agent's
choice among entrances is sampled from a training-shaped distribution;
the entrance anecdote above is this in miniature. Environment topology is
the only reliability lever you actually hold. Second, the single entrance
can be dynamic — a guided runtime recomputes the one legal next action per
step, per role, per state; rails that move with the work, which is what
separates this from the static workflow engines the 2000s buried. Third,
it is finally measurable: entrance counts per flow, position-loss
incidents per compaction, divergence between claimed and verified
position, preventable gate rejections. Drift stops being a vibe and
becomes a dashboard.

The conclusion, restated

The agent field has spent two years making dead reckoning excellent:
smarter loops, richer memory, disciplined context, hierarchical crews.
And long tasks keep drifting, because none of it was ever the missing
instrument. (Princeton's recent agent-reliability study measured the
decoupling directly: across 24 months of frontier releases, capability
climbed while reliability plateaued — for every vendor.) My drifted
reviewer ran the full modern stack and failed in a way invisible from
inside the loop, because every fix on that list shares one assumption:
that the agent's account of where it is can be trusted. It can't —
not because agents lie, but because self-estimated position compounds
error by construction, at any intelligence level.

Drift is compounding position uncertainty multiplied by per-step choice
sampling. Both variables live in your system's topology, not in the
model's weights, and neither yields to a better model or a better loop.

Don't give your agents a longer logbook or a faster loop. Give them a
map with a verified you-are-here dot — pushed into their hands at every
step, because a lost agent never asks for directions — and make sure the
map has only one door per room.

The runtime described here is being built in the open:
github.com/amingclawdev/aming-claw.
Every number in this article — the nine rejections, the 27-hour freeze,
the 818 green tests — comes from its governance timeline and git
history. The system is iterating from pull to push; a stable version
will follow. If you run agents on long tasks and want the two variables
on a dashboard instead of in a postmortem, watch the repo.

Push, not pull: your AI agent shouldn't fetch its own context

Aming — Wed, 01 Jul 2026 16:04:20 +0000

The guided runtime — push, not pull.

Status: public draft for Dev.to. Public-safe. A thesis with early, observational
evidence — not a validated result. The controlled experiment is at the end, and
the number will follow.

I watched my agent slowly lose the thread

I'm building a system that got complex. Many entry points. Interfaces that call
interfaces. Docs, contracts, and conventions scattered across the repo. The kind of
codebase where you need a minute to remember how a piece fits.

So I'd hand an agent a task and watch. It would start fine. Then, a dozen steps in,
it would begin to slip — re-deriving where it was, missing an interface it had
already seen, grepping for a doc it had read an hour ago, patching a symptom,
hitting the same wall, patching again. It never stopped to ask whether its whole
approach was wrong. It just kept grinding, locally, until it ran out of road.

I did the obvious thing. I improved the context: better indexing, embeddings,
retrieval, a repo map, a search tool. Give the agent more ways to find what it
needs.

It barely helped. And that's when I realized I was solving the wrong problem.

Everyone's solving the wrong problem

Grep, RAG, repo-maps, semantic search — they're useful. I still use them. But
they mainly make more information available. And the dominant assumption is
that the agent fails because it doesn't know enough about the system.

But watch a capable model fail on a long task and that's not what you see. Given
the right frame, the same model executes long, correct, disciplined chains without
complaint. It doesn't lack intelligence, and on my codebase it didn't lack
information — it had a search tool pointed at everything.

It gets lost because it cannot hold its place in a complex system across a long
horizon. That's an attention problem, not just an information problem.
Retrieval helps the fact layer; it does not, by itself, control attention. Worse:
pull asks an already-drifting model to do the exact thing drift has corroded —
navigate the system, decide what's relevant, and assemble its own context. Hand
agents a precise structural tool and leave it optional, and they often don't even
reach for it. They're lost. Being lost is what makes you unable to know what to
fetch.

We've been answering the wrong question.

The flip: push, not pull

If the agent can't be trusted to find its context, stop making it. Have the
runtime compute the next step and push it — into the loop, before the agent
acts.

That's the whole move: push, not pull. I stopped building a better library for
the agent to search and started building a thing that tells the agent where it is
and what's legal next, every step. I call it a guided runtime.

It's defined by what it is not:

Not retrieval as the control loop. Search still exists, but it becomes a fact-layer tool. The agent shouldn't have to decide, while drifting, what context to assemble before every action.
Not error-feedback (post-hoc). Not "you ran the tests, they failed, fix it." It fires before the action, to keep the trajectory on the rails rather than drag it back after it leaves them.
Not a one-shot plan. It's recomputed every step from current state, not read off a plan written once at the start.

The mechanism — Facts + Rules → Guide

A guided runtime factors into three layers. Only the outer two are
domain-specific; the middle engine is reusable.

Facts — a fresh, queryable model of ground truth. For code, a commit-bound dependency/symbol graph. Generally: a projection over an append-only event log (event sourcing). Current state is the fold of events pinned to an explicit watermark. If the world has moved beyond that watermark, the runtime can say so instead of pretending its snapshot is omniscient.
Rules — the plan, compiled into something checkable. This is the load-bearing idea: a contract is a plan made verifiable. Where a plan says "implement the feature and add tests," a contract says: these files are the fence, these acceptance predicates must hold, these actions are allowed and these forbidden, this evidence must exist before done.
Guide — guide = rules ∘ facts. Evaluate the rules against the facts and emit the steering signal: the next legal action, the missing piece, a drift alert, a blocked action. The guide tells; gates enforce. Evidence still has to be written by the right actor, and authoritative gates decide what can close.

If this smells familiar, good: it's the classic facts + rules → inference
architecture — production rule engines, policy-as-code (evaluate policy over
input facts → a decision), event sourcing / CQRS. The engine rests on decades of
battle-tested ground. The novelty isn't the engine.

What does the runtime actually push? Not just a paragraph of advice. A usable
guide looks like an envelope: current contract id, actor role, allowed and
blocked actions, next legal action, required evidence, a payload skeleton, the
state watermark it was computed from, and the gate that will verify it. The
important thing is that the agent no longer has to re-infer "where am I and what
is legal now?" from scratch.

The part I didn't expect: this isn't about code

The guide engine — rules ∘ facts — is domain-independent. Code is just the
instance where the fact layer is easy (a commit and its dependency graph are free).

To stand a guided runtime up in any complex agent-workflow domain — an ops
runbook, an insurance-claims pipeline, a multi-step business process — you supply
exactly two things:

A fact-layer tool that extracts ground truth as an event-sourced projection (most business state is lower-churn than code — it changes at discrete, modelable transition points, which makes the fact layer cheaper than for code, not harder).
The rules — the domain's plans compiled into checkable contracts.

Then the same guided runtime steers the agent: it pushes the right next step, the
right gate verifies the result, and the system escalates only when the contract
can't resolve it. The hard part — and the only per-domain cost — is the
modeling: choosing the events and writing the checkable rules. Everything else
is reused. The machine is general; the modeling is where human judgment goes.

That's the bet that makes this more than a coding trick: a guided runtime is a
general way to keep an agent on-trajectory through any complex business you can
model as facts + rules.

Let me be honest about novelty

Every ingredient is prior art. Continuous, structure-derived steering of the next
action is old (grounded decoding, value-guided action selection in robotics).
State-machine-driven context injection into an LLM is old. The facts+rules engine
is older. Event sourcing is decades old.

The bet is the synthesis: push (not pull) + structure-derived from a contract
over a freshness-pinned, event-projected fact model + as the primary anti-drift
control for an autonomous agent. As far as I can find, no one has fused exactly
that — and several lines of work are converging on it right now, which I take as a
sign the frame is right.

Does it work?

Here's where I keep myself honest, because the internet is full of "new paradigm
solves everything" posts and I don't want to write one.

I built this as a governance layer for coding agents — Aming Claw (public; it's dogfooding on itself, so expect churn) — and dogfooded it hard. The
observational signal is genuinely encouraging: as the runtime stabilized, the
pathological stuck-loops became visible earlier, and several paths that used to
die in a thrash of repeated blockers started converging cleanly. Some
multi-worker paths that had been painful began to run through the contract
instead of through operator memory.

I will not call that validated. It's observational, not controlled. The work
was longitudinal: the architecture, the bug fixes, and my own guidance all changed
at once, so I cannot yet cleanly separate the runtime's effect from the
operator's. Encouraging trajectory, unproven causality. If anyone shows you a
trend like this and calls their paradigm "validated," they're selling.

Where it actually is today: mid-migration from pull to push. The guide does not
yet compute every legal step. Where a contract hasn't modeled the situation, the
agent still falls back to pulling context and reasoning its way through — and that's
by design during the build. Push doesn't abolish pull; it aims it, and right now a
lot of the space still isn't aimed. Each iteration moves more of it from
agent-pulls to runtime-pushes as more gets modeled into facts and rules. I'm
publishing the thesis now, mid-iteration and openly unstable. Once the push path
converges and the pull fallback shrinks to the genuinely-novel edge, I'll cut a
stable release — and run the experiment below against that, not against
today's moving target.

So here's the experiment I'm running next, and the number I'll publish:

Operator-free, logged as such — so the runtime's effect is isolated from mine.
Same model, guided runtime on vs off, plus a strong baseline scaffold — a fixed-model ablation, so the delta is attributable to the harness, not the model.
An external, objective benchmark with a third-party metric and verified trajectories — not my own success gate.
Drift/completion delta, stratified by task length — because the thesis is that the overhead loses on short tasks and the anti-drift wins on long ones. The crossover is the claim.

If it shows what I think it shows, I'll post the number. If it doesn't, that's
worth knowing too.

The frame, in one line

Your agent isn't lost because it lacks context. It's lost because it can't hold its
place. So stop making search the control loop — push, not pull: build a guided
runtime that computes the next step as rules ∘ facts and hands it to the agent
before it acts. It works for code today; the same shape should work for any
complex workflow you can model as facts and rules.

Tell me where it's wrong.

Route Context: How I Built Right Context for Agents

Aming — Sat, 30 May 2026 12:28:20 +0000

We already knew agents needed the right context. Dogfood taught us the harder problem: making that context live, visible, auditable, and enforceable inside a multi-agent workflow.

The failure looked like success.

A worker changed one file. The focused test passed. The patch was small, readable, and locally correct. If you only looked at the worker's report, the job was done.

But the overall job was still wrong.

The change touched a permission-sensitive path. It needed evidence that the right role had acted, that the project map still matched the code, that the audit trail could explain why the edit was allowed, and that the final close check had not been skipped. Instead, the system had solved the nearest local problem. A lane that should have preserved the shape of the work had drifted into implementation. The worker had completed its tiny job, while the whole route had lost its meaning.

Nobody had to make a dramatic mistake for this to happen. That was the unsettling part. The worker was not lazy. The test was not fake. The prompt was not empty. The system had plenty of context. It just did not have route context.

Route context is the per-task, per-lane runtime packet that tells an agent what job it is in, what role it has, what it saw, what it cannot do, and what evidence must pass before the work is done.

That is the positioning of this article. I am not trying to convince technical readers that right context matters. Most people building with agents have already learned that, usually the hard way. The point is how we made right context operational for agent development: route context, a live artifact that turns the principle into prompt-visible, hashable, auditable, gate-checkable workflow state.

We started with a different hope. We wanted agent development to feel zero-orchestration-ish: the user says what they want, the system understands the work, the right agents handle the right pieces, and nobody has to manually conduct a meeting of subagents. The observer would keep things coherent. Workers would implement. Review lanes would check evidence. Validation would catch bad finishes.

Then we used it on ourselves.

Again and again, the same failure appeared in different clothes. The observer would begin correctly, then collapse into a nearby code edit. A worker would pass a test, but not satisfy the larger obligation. A reviewer would evaluate plausible reasoning, but not the same evidence the worker actually produced. A prompt would contain lots of useful system knowledge, but not the specific promises this worker had to satisfy.

That is when the thesis became operational: AI agent development needs right context, not more context, and route context is how we made that sentence executable.

The Words We Needed

We had to translate our internal language into something simple enough to survive a live task.

Topology means what kind of job this really is. Is this a tiny deterministic bug fix, a permission change, a runtime change, a graph update, a public decision, or a mixed task that needs independent lanes?

A contract is the set of promises a worker must satisfy: target files, acceptance criteria, out-of-scope areas, allowed actions, blocked actions, and evidence to return.

A gate is a check that prevents a false finish. A test can be a gate, but it is not the only one. A close gate may reject a change because the audit evidence is missing, the runtime was not redeployed, the project map is stale, or the wrong role acted.

Graph, backlog, timeline, and contract are the governance layers that preserve project state, user intent, execution evidence, and allowed action. The graph is the project map. The backlog records the work and acceptance criteria. The timeline records what happened. The contract says what this lane may do.

Once those words were clear, the bug was easier to see. Our static skill text explained the system, but the live task needed route context: the current path through the work, with the role, lane, injected context, and checks bound to the action about to happen.

Static skill text is only a bootloader. It can teach the agent that observers, workers, review lanes, graphs, and gates exist. It cannot reliably decide what matters for this task, this lane, this file, this permission boundary, and this moment. Route context is the runtime packet assembled for that decision.

The Route Context Artifact

The useful fix was not a bigger prompt. It was a route context alert: a small implementation artifact generated before lane dispatch, during topology classification and prompt-contract assembly. It describes what the lane is allowed to do, what was injected into its prompt, and what evidence will be checked later.

A simplified route context alert looks like this:

route_context_alert:
  task_intent: "fix permission handling without changing audit policy"
  role_boundary: "implementation worker; no merge, close, or graph mutation"
  topology: "permission-sensitive bug; requires independent review"
  contract: "edit accepted target file; run focused test; report evidence"
  blocked_actions: ["change route policy", "close backlog", "redeploy runtime"]
  visible_injection_manifest: ["route_doc@sha256:...", "contract@sha256:..."]
  evidence_gates: ["focused_test", "independent_validation", "close_gate"]

This is not magic model control. The model can still misunderstand things. The point is that the important context is visible in the prompt, listed in an audit manifest, and tied to workflow checks that can reject a false finish.

The visible injection manifest was especially important. If a document, decision summary, expert note, or implementation contract influences a lane, it should appear in the manifest with an id, kind, source reference, and hash. The hash proves the identity of the injected artifact. Gates and evidence decide whether the lane satisfied the contract. Without the manifest, nobody can reconstruct what the agent actually saw.

Route context gave us a way to keep orchestration minimal without making it invisible. The system still feels close to zero-orchestration from the user's side, but the route carries enough explicit structure that lanes do not silently blend together.

The Implementation Pattern In Aming Claw

This is not only language we use around the system. Aming Claw implements the pattern as code-level contracts, local gates, audited queries, and append-only evidence.

The route prompt contract is source-controlled in the mf_workflow_runtime.v1.json template. That contract makes route-owned prompt context explicit: the injected artifacts are listed in a visible manifest, observer and review lanes are blocked from drifting into implementation, and the worker has to carry matching route_context_hash, prompt_contract_id, and prompt_contract_hash values. In other words, the prompt is no longer just a bag of helpful text. It has identity.

Before a bounded worker is handed the job, Aming Claw runs a local dispatch gate in mf_subagent_contract.py. The gate checks the worker's branch, worktree, base commit, target head, merge queue, fence token, route hash, prompt hash, and owned files. Same-worktree dispatch is blocked by default because "please stay in this directory" is not a boundary. The boundary has to be represented in durable facts the system can re-check.

When the worker returns, the finish gate in the same module treats the response as a claim, not as truth. The finish validation requires the fence token to match, tests to pass, blockers to be absent, a checkpoint id to exist, and the worker identity to still match the handoff. This is the difference between "the agent says it is done" and "the route can safely advance."

The audit trail follows the same idea. The task_timeline.py module is append-only execution evidence. Its close gate expects the route to have the right event kinds: implementation, verification, and close_ready. The later close verification checks those facts before a backlog item can be honestly closed.

Even project knowledge is handled this way. Graph context is not dumped wholesale into the prompt. It is queried through an audited graph-query trace and exposed through the MCP graph_query surface, so later review can ask what the agent looked up instead of guessing. The public manual-fix SOP names the same workflow: route, contract, timeline, and close gates are required evidence, and dispatch has to prove the worker's fenced identity before handoff (timeline and contract gates, dispatch requirements).

That is the implementation pattern: right context becomes a chain of small, checkable facts. The agent can reason with them, but it does not get to be the only witness.

Before And After

Before, the agent confidently finished the wrong local job.

It saw a failing test and fixed the code. It saw a nearby file and edited it. It saw a plausible completion story and wrote one. The observer forgot what kind of job this really was. The worker optimized inside its local patch. The review or validation step, if present, evaluated the local result instead of the global obligation.

After, route context requires the observer to start by preserving global state. It names the topology: tiny fix, permission-sensitive change, runtime change, graph-impacting change, major decision, or something else. It dispatches lanes accordingly. The worker acts inside a contract. The architecture review lane checks whether the route makes sense. Validation checks evidence, not just confidence. Later validation and close gates check the route context alert, manifest, and returned evidence before accepting the result.

That rejection matters. A good system must be allowed to say, "The test passed, but the work is not done."

For example: the focused test passed, but the route context hash did not match the worker contract. Or the code changed the right file, but the audit evidence did not prove the right role acted. Or the patch was correct, but the graph, meaning the project map, was now stale. Or runtime needed redeploy before anyone could claim the fix was live. Route context makes those checks explicit instead of hoping a model remembers them.

What The Observer Is For

The observer's advantage is not that it manages subagents. That framing makes it sound like a tiny project manager.

The observer's real advantage is global-state custody. Route context gives it something concrete to preserve: route identity, dirty scope, graph/current state, runtime status, backlog state, tests, close gate requirements, and follow-up work.

Workers should be local. That is their strength. A bounded worker should know its target files, acceptance criteria, blocked actions, focused tests, and required evidence. It should not need to carry the whole project in its head. When every worker receives the whole world, prompts get heavier and guarantees get weaker.

The observer keeps the larger surfaces connected through route context. Did this lane have permission to edit? Did it stay inside its file fence? Did the test prove the actual promise or just a nearby behavior? Did an independent reviewer inspect the same packet the worker produced? Did the runtime or graph need an update? Is there follow-up work outside the worker's scope?

These checks are not glamorous. They are what stop a green test from becoming a false finish.

Efficiency Without The Theater

The biggest improvement was not raw wall-clock speed.

Parallel lanes can help. Architecture review, implementation, and validation lanes expose different gaps earlier than one linear worker. But the real win was effective efficiency and quality: fewer locally correct patches that could not be honestly closed, less rework after review, and earlier discovery of missing evidence.

The system became calmer because it stopped treating "done locally" as "done globally." Some gates remain serial on purpose. Commit, runtime redeploy, graph reconcile, and backlog close mutate shared state or claim shared state is current. Those steps should not be casually parallelized just because multiple agents are available.

This is the correction to zero-orchestration-ish design. The goal is not to hide all orchestration. Hidden orchestration is unreliable because nobody can audit what happened. Route context keeps orchestration visible and minimal at the points where role, evidence, and shared state matter.

The Rule We Use Now

A tiny deterministic edit can be one agent plus a focused test. If route context says the blast radius is clear, the file ownership is obvious, and there is no permission, audit, graph, or runtime implication, keep it simple. Give the worker a tight contract and verify the behavior.

P1 and P0 work is different. So are routing, permission, audit, graph, and runtime tasks. Those need an observer, an architecture review lane, an implementation worker, and independent validation. Major decisions need adversarial lanes: separate expert packets, an independent review lane comparing evidence, and an observer final decision. Not because important work deserves ceremony, but because important work has more ways to be locally successful and globally wrong.

The checklist is compact:

Name the topology: what kind of job this really is.
Bind the worker contract: target files, acceptance criteria, and evidence.
List blocked actions: what this lane must not do.
Expose injected context: manifest the artifacts and hashes the lane saw.
Make gates reject false finishes: tests, validation, and close checks must be able to say no.

That is the practical lesson we got from dogfood. More context made agents sound more informed. Route context made right context safer to act on.

For us, right context stopped being a prompt-writing aspiration when it became route context: a route that knows what matters now, a contract that bounds the worker, a manifest that shows what was injected, and gates that refuse to confuse a passing test with a finished job.

AI's tech debt is invisible — even to AI. I solved it at the architecture layer.

Aming — Sat, 23 May 2026 03:58:23 +0000

TL;DR — AI repeats your patterns badly, ignores existing services, and forgets every cross-session lesson you taught it. This isn't laziness — it's a new kind of tech debt: invisible, systemic, and architectural. Project memory hints don't scale. Bigger context windows don't help. The fix is structural: pin a graph projection of your codebase to every commit, let AI read it before writing, surface "graph stale" prompts when source drifts. Real commit receipts from my own OSS project aming-claw inline. Architects, change my mind in the comments.

What is AI tech debt?

Let me define this precisely, because it's a different beast from the tech debt you already know.

Dimension	Traditional tech debt	AI tech debt
Who creates it	Engineers (knowingly)	AI (unknowingly)
Awareness	Conscious tradeoff	AI doesn't know it's accruing
Fix lifecycle	Fix once, done	Every new session repeats it
Visibility	`git log` shows it	Invisible across sessions
Scale	Team-bounded	Systemic, AI-generated

The core asymmetry: the more your team uses AI for coding, the more invisible debt accrues — and you have no tool that sees it.

5 symptoms (diagnose yourself)

Run this checklist against your team:

❌ AI re-implemented a service that already exists
❌ AI shipped code using a pattern completely inconsistent with everything around it
❌ AI didn't see the implementation sitting in the next file over
❌ Every new session repeats the same mistakes you corrected last time
❌ AI treats a familiar codebase as if it were brand new

Three or more? You're accruing AI tech debt. The bigger your team and the more AI you use, the faster it compounds.

A real case study: my toolboxclient stateService

I'm the maintainer of toolboxclient (open-source cross-platform AI agent runtime, 274+ stars). I asked AI to add a stateService.

The directory server/services/ already contained, in clear sight:

TOOLBOXCLIENT/server/services/
├── fingerPrintService.js
├── memoryService.js
├── providerModelService.js
├── proxyService.js
├── taskService.js
├── toolServiceManager.js
├── walletService.js
└── webSocketService.js

Roughly a dozen services, all sharing the same HTTP pattern.

What AI shipped (commit 68487cc, 2026-03-19):

// AI's version: WebSocket-based StateClient with Proxy
class StateClient {
  constructor(agentName) {
    // 🚨 WebSocket, not HTTP — inconsistent with every other service in the folder
    this.ws = new WebSocket(...)
    this._data = {}
    this.state = this._createProxy()
  }

  _createProxy() {
    // Proxy traps to broadcast via WebSocket
    return new Proxy(this._data, { ... })
  }
}

It used WebSocket instead of HTTP. It used a Proxy-based intercept-and-broadcast pattern unlike anything else in the codebase. It built a parallel architecture next to an established one.

This wasn't a code bug. It was a pattern bug. AI literally couldn't see the existing services.

The first fix: project memory

My first instinct: add a hint to project memory.

use existing HTTP services, don't add WebSocket

AI refactored cleanly (commit bbdf82c, 2026-03-21):

feat: stateService Phase A+B — HTTP CRUD + SSE broadcast

Phase A: /api/state/* routes (read, write, session CRUD, language pref)
Phase B: SSE subscribe endpoint with topic filtering + EventBus broadcast

74/74 tests pass. No breaking changes — additive only.

WebSocket gone. HTTP CRUD + SSE matching the existing pattern. Clean fix.

For about ten seconds, I thought I'd solved it.

Why project memory hints don't scale

Then I realized something uncomfortable:

This catch only worked because I noticed.

The next AI session would start with zero memory of this lesson.
Every context window starts as a blank slate.

This is the systemic nature of AI tech debt:

AI can't see existing patterns when it writes
I see it → I fix it once → the fix doesn't propagate to future sessions
Manual project memory maintenance puts the work back on me, not AI
This doesn't scale — and the failure mode is silent

The first insight

I stopped trying to fix prompts and started looking at the structural problem:

AI agents don't need bigger context windows.

They need a persistent structural record of the project that survives across sessions.

Context windows are short-term memory. What's missing is long-term, project-level memory — something any AI session can read before writing.

This is the insight that turned into aming-claw.

Building aming-claw (and falling into the next trap)

The idea: give every AI session a queryable graph of the project. Files, modules, functions, patterns — all of it, machine-readable, persistent.

Scan the codebase → build a graph of all entities and relations
Expose it through an MCP server that any agent can query
AI reads the graph before writing
Graph persists across sessions

I built it. It worked. Then it broke — at a higher layer.

I had implemented the graph with:

Mutable nodes — agents could edit graph state directly
A patch pipeline — 5-stage mutation flow (propose → validate → review → apply → snapshot)
A graph editor UI — humans could also edit the graph

Within a few weeks, the graph drifted from the actual code.

Why? Because I had created a second source of truth:

The real source of truth was source code
But I also let the graph be directly mutated
The two sources inevitably diverged

Same trap. Higher layer.

The real architectural insight

After hitting the same trap twice, the answer crystallized:

~~The graph is something you edit.~~

The graph is a projection of the commit.

In concrete terms:

Every commit can correspond to one graph

git commit (modifies source / hints / config)
     ↓
system detects: HEAD ≠ graph's bound commit
     ↓ ⚠️ "graph stale" prompt
user decides when to reconcile
     ↓ user-triggered
fixed_algorithm(source + hints + config)
     ↓
new graph snapshot ←→ new commit hash

4 key invariants

#	Invariant	What it guarantees
1	Fixed algorithm	Same input → same graph (deterministic, no randomness)
2	1:1 binding	Every commit hash maps to exactly one graph snapshot
3	User-triggered	Reconciliation is explicit, not a background git hook
4	Stale prompt	System surfaces drift in dashboard / CLI; user triggers when ready

Why not a git hook?

A reasonable question: why not auto-rebuild the graph on every commit via a git hook?

Three reasons I deliberately didn't:

Reconciliation is expensive (full codebase scan + algorithm)
Surprise auto-builds destabilize state — user should control when state changes
Batching commits before a single reconcile is often what users want

The system shows a graph stale indicator in dashboard and CLI. Users reconcile when they're ready. This is a deliberate design choice, not a limitation.

How modification and rollback work

Operation	Implementation
Modify the graph	Modify source / hints / config → trigger reconcile
Roll back the graph	`git revert` → trigger reconcile
Verify consistency	Same commit → same graph (replayable)

Logic lives in code. The graph is a read-only projection.

How this solves AI tech debt

Returning to the original problem: AI repeats patterns badly because it can't see the codebase.

The architectural fix:

Every AI session starts by querying the graph (via MCP)
The graph records the full structure — files, functions, modules, patterns
AI sees, for example, existing HTTP service pattern in server/services/
AI reuses the pattern instead of shipping a parallel WebSocket implementation
After AI makes changes → user commits → system flags graph as stale → user reconciles → next session sees updated patterns

Cross-session knowledge transfer happens through the graph, not the prompt.

This is what "solved at the architecture layer" means: it's not a smarter prompt, it's a different topology of state.

Coming up: the algorithm itself

This post covered why the projection model works. The next post covers how the algorithm builds the graph:

in-degree=0 entry detection
DFS 3-color marking
Tarjan SCC for cyclic clusters
6-signal layer scoring
Cross-language fact pipeline (Python + TypeScript)

Follow me here to catch the next one.

Change my mind

I claim this architectural pattern solves AI tech debt: every commit corresponds to one graph + user-triggered reconcile + stale-state prompt.

Your turn. Two architectural choices:

Treat project state as a single source of truth, commit-bound
Or maintain a separate memory store that AI writes to

Which is more robust? Which scales better? Where would you attack my approach?

Calibrated invitation: I want senior engineers and AI infra people to push back with specifics. "What about X?" or "Have you considered Y?" lands better than "this won't work." If you've shipped something adjacent, tell me — I want to compare designs.

AI proposed 5 components for my parallel system. After walking one scenario, only 3 were real.

Aming — Mon, 18 May 2026 04:18:53 +0000

TL;DR — AI loves to design "enterprise-grade" systems for you: message queue, distributed lock, state machine service, scheduler, monitoring bus. Half of them aren't real. The cheapest filter I know: before letting AI design anything, walk one concrete scenario through the system. Whatever shows up in the scenario is real. Whatever doesn't — delete. This week it took me from a 5-component design down to 3 — and surfaced one critical component AI had missed entirely.

What I was building

This week I was extending aming-claw (an open-source AI code governance tool I'm building) to support parallel multi-agent development: multiple AI agents working on the same project simultaneously, each on its own branch, all of it merging back into trunk.

I asked AI to help me design it.

It came back fast. Confident. Five components:

- Message queue        (so tasks can line up)
- Distributed lock     (so agents don't step on each other)
- State machine service (so we track progress)
- Task scheduler       (so we know what runs when)
- Monitoring bus       (so we see what's happening)

Each component had a paragraph of justification. The diagram looked impressive. The names sounded right.

I almost just said "ok, build it."

Why I didn't

A thing I've learned working with AI on architecture: AI doesn't filter for necessity. It filters for plausibility. The components it lists are real things real systems have — they're just not necessarily things your system needs.

So instead of letting it design the system, I did one thing:

I walked a concrete scenario through the system before agreeing to anything.

Here's an honest framing: nobody can look at a 5-component design and immediately tell you which 2 are load-bearing. AI can't. Most engineers reading this can't, not on inspection.

The good news:

You don't need to know what to design. You just need to walk one scenario.

The scenario does the filtering for you.

Scenario 1: five tasks with dependencies

I started with the most boring scenario I could think of:

Five AI agents working in parallel. Each one on its own branch. The tasks have a dependency chain: 1 → 2 → 3 → 4 → 5. Task 2 needs what task 1 built. Task 5 needs everything before it.

I walked through what the system has to do:

Five tasks running in parallel — they need to queue for merging. OK, "message queue" was real.
BUT — they have to merge in dependency order. Not first-come-first-served. So a plain FIFO message queue isn't enough. It has to be an ordered queue.

Already, one component refined. "Message queue" → "ordered merge queue."

Nothing has been deleted yet. Keep going.

Scenario 2: the machine reboots mid-batch

Now the machine reboots. When it comes back up: task 1 already merged. Task 2 tried to merge and failed. Task 3 hadn't started yet. Task 4 was waiting in queue. Task 5 was halfway through executing when the power cut.

I walked it again:

For the system to even know what state each task is in after a reboot, task state has to be on disk, not just in memory. Not a "state machine service" with its own server — just durable per-task state. (task_id → status → checkpoint.) That's a column in a database, not a service.
Task 2 failed, but tasks 3-5 are downstream of it. The system has to recognize "upstream failed, downstream blocked" automatically. That's not a separate component — it's a query against the durable state.
Task 5 was mid-execution when the power cut. When the machine restarts, what stops a second copy from picking it up and racing the half-finished one? Each execution attempt needs a unique token — whoever has the newest token is the live runner, everyone else gets fenced off.

Now two more things have surfaced:

Durable per-task state (which AI called "state machine service" — but it's not a service, it's a table)
Fence tokens to prevent zombie reruns

And here's the first thing that got deleted: distributed lock.

A distributed lock is "this resource is held by exactly one agent right now." Fence tokens solve the same problem in a much weaker, much cheaper way: "the latest token wins, all stale tokens are ignored." For agent merge work, that's sufficient. Distributed locks would be massive overkill for the actual scenario.

1 component deleted, 0 lines of code written.

Scenario 3: the ordering itself was wrong

This one wasn't in my original head-list. It only surfaced when I kept walking:

Five tasks ran. Three merged. Then it turns out the dependency order I gave the system was wrong — it should have been 1 → 3 → 2 → 4 → 5, not 1 → 2 → 3 → 4 → 5. The three already-merged tasks need to be rolled back as a batch and replayed in the correct order.

This is a scenario most systems never plan for. Per-task rollback is common — undo one merge. Batch rollback with replay is rarer.

Plain per-task revert doesn't work — you can't revert task 2 while leaving task 3 (which depends on task 2's wrong order) intact.
The whole batch has to roll back atomically.
Then the system has to replay them in the new order, with all the graph artifacts (snapshots, indices, semantic projection, test results) re-derived per merge.

This is the component AI had not mentioned at all. It only surfaced because I walked a scenario nobody told me to walk.

Call it BatchMergeRuntime. It's the rarest kind of architectural decision: not "should we have it" but "do we even know we need it?" — and the answer, for most teams, is not until production.

What the architecture actually became

After walking three scenarios:

Scenario	What it surfaced
5 tasks with dependencies	Ordered merge queue
Machine reboots mid-batch	Durable task state + fence tokens
Dependency order was wrong	Batch rollback + replay runtime
All of the above untested	Test scenario matrix as P0.0 (highest priority)

Three real components. The fourth — the test scenario matrix itself — is a meta-component: the dry-run scenarios I just walked became the first acceptance bar for every subsequent PR. Anything that ships has to survive these scenarios before merge.

AI's first design vs what scenarios required

AI's first list	Reality after scenario walk
Message queue	✅ Needed — but ordered, not FIFO
Distributed lock	❌ Deleted — fence tokens are sufficient
State machine service	✅ Needed — but as a table, not a service
Task scheduler	❌ Deleted — the ordered queue is the scheduler
Monitoring bus	❌ Deleted — each component emits its own events
(AI did not propose)	✅ Batch rollback runtime — surfaced only by scenario 3

Net: 5 → 3 components, plus the one critical piece AI had missed entirely.

The win is not "I deleted 2 components." The win is I now know why each remaining component exists, which means I can explain it, scope it, and reject scope creep on it. That's the difference between a system you built and a system you understand.

The method, in 3 steps

❌ Don't:   "Hey AI, design me a system that does X."
           → AI returns a plausible-looking inventory of components.
           → Half of them aren't real for your specific case.

✅ Do:      Step 1.  Write one concrete scenario yourself.
                    (Or: have AI write the scenario, you evaluate it.
                     Real numbers, real steps, with crashes,
                     failures, and orderings going wrong.)

           Step 2.  Walk the scenario through your design.
                    At each step, ask: "What does the system need here?"

           Step 3.  Aggregate "what's needed."
                    That's your minimal architecture.
                    Anything not in that list — delete.

That's it. Three steps. No architecture-pattern library required. The scenario does the work for you.

Why this works (and why it's hard to skip)

Three reasons:

1. AI optimizes for plausibility, not necessity. It lists components that sound right for this kind of system, drawing from its training data. It can't know which components are necessary for your specific scenario, because it doesn't see your scenario unless you walk it through.

2. Scenarios surface the negative space. A happy-path design is the union of every component someone might need. A scenario walk is the intersection of components someone definitely needs for that scenario. The intersection is always smaller — and more honest.

3. Scenarios surface what AI missed. The batch-rollback runtime wasn't on AI's list. It surfaced because scenario 3 was a state AI's training data didn't lean on. Whatever your system's weird state is — only your scenarios will find it.

The reason this method is hard to skip is that the pressure to just accept AI's design is enormous. The design looks complete. It uses real words. You feel productive saying "yes, build it." Walking a scenario feels like slowing down. It is. That's the whole point.

What's next in this series

This is part 2 of the AI Collaboration Survival Guide. The previous post was about making AI's claims about completed work auditable via a backlog database. The next ones, lining up:

Pain	Coming up
AI edits one function, breaks 10 callers	Code graph + impact analysis
AI modifies code it shouldn't touch	Governance hints as the only authoring surface
What did AI even change this week?	Event ledger
Every session starts from zero	Project memory layer

One pain per article. All built around the same open-source project, aming-claw.

About aming-claw

GitHub: amingclawdev/aming-claw
What it is: A shared workspace where you and your AI agent see the same dashboard. Backlog database, code graph, event ledger, governance hints — all queryable by AI through MCP.
Why I'm writing this series: I keep running into the same kind of AI-collaboration pain. Each post fixes one of them. The fixes generalize beyond aming-claw — the scenario-walk method in this post is a 5-minute habit you can adopt in any project.

If the parallel-agent scenario sounded familiar, drop a comment with the architecture decision AI most recently tried to oversell you on — I'll work through it the same way in the comments. Free architectural review, basically. The repo also takes stars and they're free for you to give. 🌟

Part 2 of "AI Collaboration Survival Guide" — practical patterns for the messy reality of shipping with AI agents.

I told my AI to build a feature. Did it? I had no idea.

Aming — Sat, 16 May 2026 18:43:34 +0000

TL;DR — I tried to "manage" AI by having it write decisions, todos, and constraints into markdown docs. After 56 files, I realized AI doesn't maintain document state. So I built aming-claw — a backlog database AI can actually read and write through MCP.

A bug I kept running into

I thought I was doing AI collaboration the right way.

This is the docs/dev/ folder of my aming-claw project — 56 markdown files, all produced through AI collaboration:

proposal-* — new feature specs
review-* — design review records
handoff-* — state passed between sessions
Plus plan-, optimization-, interface-, manual-fix-...

Every file dated. Two months in, over a thousand pages of markdown. I figured the next AI session would read these. I figured I'd be able to search them too.

But there's one problem I can't engineer my way out of:

AI doesn't maintain document state.

proposal-graph-state-reconcile-and-chain-governance-modes.md — did this proposal ship? Which commit? Is it still valid?
handoff-2026-05-10-dashboard-semantic-hash-queue.md — did the next session actually pick up where this left off?
18 proposals on file. Which are done, which got rejected, which are still alive? Grep through git log line by line?

I don't manually maintain the docs, so the docs rot. AI doesn't maintain them either — its context window only sees a tiny slice of the workspace. The other 56 files are invisible.

The more we talk, the more we write — and the further docs drift from code. Eventually you don't trust the docs, and you don't have time to read the code.

Why this happens

This isn't AI being lazy. It's a structural problem:

Markdown is dead text. No state machine. "TODO" doesn't become "DONE" on its own. "Decision: use Redis" doesn't auto-expire when you flip back to in-memory three weeks later.
AI context has a boundary. Each session sees ~200 lines of working code. Old docs never enter the window. Not in the window → can't be maintained.
No traceable link between docs and code. Which TODO maps to which function? Once it's done, which commit landed it? Humans can't remember. AI doesn't look it up.

GitHub Issues, Notion, Linear — none of these help. AI can't see them, so they don't exist.

The core mismatch is this: humans want global state. AI sees only local present. Between them you need a living, traceable, AI-readable/writable state layer. Markdown isn't that layer.

How aming-claw solves it

I gave aming-claw a dedicated backlog database — a peer-level system to the code graph and event ledger, with its own schema, state machine, and query interface. Not stored in markdown. Not buried in code comments. Not dependent on an external issue tracker.

Each backlog entry is a structured record (todo / decision / constraint) with status, priority, source session, and a code reference (function name or file path). AI reads and writes it through MCP.

The flow:

1. You speak → it goes to the database, not a dead doc

In chat:

"Add a retry-after to the rate limiter on UserService.login"

Or: "Decision — use Redis instead of in-memory for caching"

aming-claw's MCP server intercepts those statements and writes directly into the backlog:

target:    UserService.login   # function or file path
type:      todo | decision | constraint
status:    proposed
priority:  P1
source:    session-id-xyz
timestamp: 2026-05-16T10:23:45Z

Markdown is dead text. The backlog database is live state — schema, indexed, state-machined, AI-accessible. That's the difference.

2. Dashboard shows it instantly

Open the aming-claw dashboard — the left panel shows the new backlog entry. Click it — the right panel jumps to the function via the vscode:// protocol. Status chips are editable inline.

The backlog view — every entry has priority, status, code reference, and update timestamp. AI and you query the same source of truth.

3. State machine, automatic

proposed → in_progress → done(commit hash) → verified

in_progress — AI started working on it
done — commit landed, hash automatically bound
verified — you reviewed it

Every state change is appended to an event ledger: which day, which session proposed it, which commit implemented it, who verified it — all queryable, all replayable.

4. AI reads the backlog itself, next time

Days later, in chat:

"Did we ever fix that Codex plugin Windows install bug?"

AI queries the backlog through MCP and returns:

status:     FIXED, P0
commit:     0ad8c7e
fixed at:   2 days ago
file:       agent/plugin_installer.py (line 455)
change:     replaced regex pattern with callable replacement

No grepping git log. No asking a teammate. No "I think we did?"

The key thing to notice: AI didn't "remember" this from conversation history. It queried the backlog database in real time through MCP. Even if this bug was raised three months ago, in a session that's long gone — AI still gets the current status + full commit trace.

That's the difference between dead markdown and a live state layer: the database is the memory, not the conversation.

This is just the start

Look back at the docs/dev/ screenshot — 56 markdown files, nobody knows which are alive.
Look at the dashboard screenshot — every backlog entry has status, commit, location.

The difference isn't the tool. It's whether information has state.

The backlog solves "did the AI build the feature I asked for?" — but AI collaboration has plenty of other holes I'm planning to fill in this series:

Pain	Next article
AI edits one function, breaks 10 callers	Code graph + impact analysis
AI modifies code it shouldn't touch	Governance hints
What did AI even change this week?	Event ledger
Every session starts from zero	Project memory layer

One article per pain point.

About aming-claw

GitHub: amingclawdev/aming-claw — open source
Next post: "AI breaks 10 callers when it edits one function" — coming this week
Hit me with issues if you've felt this pain

If "did the AI actually do that thing I asked?" sounds familiar, give the repo a star — it costs you nothing and tells me I'm not the only one.

This is part 1 of an "AI Collaboration Survival Guide" series — practical tools for the messy reality of building with AI agents.