A Development Brain, Folded Into A Live Production Product
The scarce asset in a long-lived codebase isn't the code — it's the decisions: why a boundary was drawn here, why an approach was rejected, what a subsystem is actually for. HESUS makes that reasoning durable and queryable. This is the story of folding it into a real shipping product, upgrading it across a generational engine rename, and measuring what actually held — including the experiments that didn't.
AI-assisted development has a quiet structural failure: decisions aren't tracked. An architectural choice made in session one is forgotten by session five. The same utility gets reinvented across sessions. Code quality starts to depend on whether the assistant happens to "remember" an earlier design choice — and it doesn't. The reasoning lives scattered across commit messages, docstrings, runbooks, and wikis that drift out of sync with the code, and it evaporates between people and between sessions.
Omniscient is a real product with this exact shape: a substantial PowerShell engine and, at the start, 81 documented architectural decisions scattered across decision logs, docstrings, and comments. Cold-start, an assistant reads the codebase with no decision context. Warm-start, it reads the entire decision history and burns a large fraction of its working context just orienting. Neither is good. That's the problem HESUS was folded in to solve.
The difference between a project that evolves and one that accumulates technical debt is not velocity or test coverage — it is whether the reasoning-state is versioned. A project that accumulates carries every past decision as undifferentiated sediment: live constraints and dead ones look identical in the code, superseded approaches leave residue no one dares remove, and each change is made against an architecture nobody can fully reconstruct. Architectural-drift is the widening gap between a system's intent and its current state, and it widens silently precisely because intent was never recorded as state. A project that evolves keeps that intent as versioned, decoupled-reasoning: decisions are typed, supersession is explicit, and a rejected path stays legible as rejected. The codebase still changes constantly — but every change is made against a known architectural position, not a guess. HESUS doesn't slow accumulation down; it changes the substrate, so growth compounds reasoning instead of debt.
HESUS treats decisions as first-class objects. Each lives as a structured record — in the cortex a record carries a Title, Context, Decision, Rationale, Consequence, Status, Supersedes and a version Bundle marker — and the engine loads them all into a small in-memory graph, enforcing unique keys and resolving cross-references on load. Records are typed by a Kind field: a fact the operator stated, an observation the brain inferred, or a ratified decision. Only an unconfirmed observation surfaces a loud trust-tag; confirmed records read clean. The default Kind is decision, so an existing cortex stays backward-compatible the moment the typing was introduced — that exact reasoning is itself recorded as decision HD-001 in HESUS's own brain.
The load-bearing design choice is that the engine and the data are strictly separated. Every organ reads project-specifics through one seam — a descriptor file (hesus.toml) — so no organ hardcodes a path, marker, id-scheme, or threshold. The brain is project-blind: it names only its own organs and verbs, never a project fact. That separation is why the same ~6,200 lines of engine run unmodified against any project, and why the engine can be swapped underneath a project without touching accumulated knowledge. The descriptor even ships a tiny pure-Python TOML parser as a fallback, so the brain needs zero pip installs and runs on Python 3.8+ — "a brain that needed pip install would be friction at exactly the moment you want zero friction."
Day to day, the benefit is context-efficient briefing. The waste a brief targets isn't orientation or finding one decision — it's the four or five exploratory round-trips at the start of a task (query, then debt, then hunt for files, then read the anti-patterns) just to assemble context before the assistant can think. A brief collapses that into one call: the decisions that may govern the task, the files to read in full, and the constraints in play. Because a brief stays near-constant in size while the decision memory grows, the saving compounds — the bigger the cortex, the more a brief saves over loading it all.
HESUS is a set of small, single-purpose organs behind one entry point. The ones an operator touches daily: brief (task-relevant retrieval that points, never summarizes), gestate (extract an existing project's decisions on first contact), query (pull one record and expand it), and a set of gates that keep the brain honest.
These gates verify what they're built to verify — version integrity, execution, project-blindness — not correctness. That distinction is stated plainly rather than oversold.
The brain Omniscient runs is a prior generation of the engine — a different entry-point and a different configuration name, from before a generational rename. The real test wasn't “does it work on a fresh project” but “can the engine be swapped underneath an accumulated cortex without losing anything.” Auditing that real production fold surfaced the cost of leaving the seam implicit: a leftover configuration file from a rename never retired, a stale comment naming the old seam, and runtime caches stale against the new engine. None were the project's bugs — each was a place the fold couldn't be mechanical.
That drove codifying upgrade as a first-class operation. The engine ships a machine-readable capability manifest, and an upgrade diffs the installed manifest against the incoming one, classifying every capability into exactly what it will cost: drop-in (works on the existing cortex immediately), seam-migration (a rename/move — migrate and retire the old, no orphan), new-gate (verification that may legitimately go red on first run), needs-data (present but inert until the cortex is armed — the dormant trap, surfaced loudly), and unknown (never assumed safe). The operation is thought-gated: the instant the two versions match it no-ops, so an up-to-date project pays nothing.
In AI-assisted engineering the engine — the specific model, version, and prompt regime that generated a system — is the most perishable component you own. It is replaced on a vendor's release cadence, not yours. A codebase whose architectural reasoning lives only in the chat history of a deprecated model is already orphaned; it just hasn't been told yet. The reasoning that justified every boundary evaporated the moment that session closed.
HESUS treats this as a structural fact and decouples accordingly. The Cortex — the versioned-state of decisions and the architectural reasoning behind them — is held as durable, project-owned data. The Engine — the retrieval-and-verification machinery, and by extension whatever model drives it — is project-blind and replaceable. The two are joined at a single descriptor seam. This is not a convenience; it is the load-bearing invariant. It is why, on the live production fold, the engine was swapped across a generational rename while the Cortex was driven at zero errors, record count unchanged — decoupled-reasoning surviving an engine it was never written against.
HESUS inverts the thing you preserve. You stop versioning the disposable output and start versioning the irreplaceable reasoning — which is the only asset in the system whose value compounds instead of decaying with the model that produced it.
Six months after a security boundary is drawn, the question is rarely what the boundary is — the code shows that. The question an auditor, an incident responder, or a new lead actually asks is why it was set there, who ratified it, and what was rejected in its favor. In a conventional workflow that answer lives in a closed chat window, a chat thread, or nobody's memory. Forensically, it is gone.
The HESUS Cortex is a queryable Decision Graph in which each record is a forensic decision log: a typed entry carrying the decision, its rationale, its consequence, its status, and its provenance — pinned to the source file and line it governs. Three properties make it audit-grade rather than documentation:
- Provenance is typed and non-fungible. Every record declares whether it is a fact the operator stated, an observation the engine inferred, or a ratified decision. An unconfirmed inference cannot masquerade as established fact — it surfaces with a loud trust-tag until a human ratifies it. An audit can distinguish what was decided from what was merely assumed.
- Rejection is first-class. A boundary's justification is incomplete without the alternative it beat. HESUS records killed approaches as durable entries with their own reasoning, so "why not the other way" is answerable on demand rather than reconstructed defensively under questioning.
- Supersession is a chain, not a deletion. When a decision is replaced, the old record is marked superseded and linked to its successor — never silently overwritten. The graph preserves the full lineage of a boundary's evolution, so an auditor sees the versioned-state history that produced the current state, not just the current state.
Even the gate that ships the system carries this discipline: a finding that's been reviewed and waived isn't deleted from the code, it's entered in a triage registry with a written reason. The accountability trail is mechanical, not cultural — it does not depend on anyone remembering to document.
One honest boundary on this claim: HESUS makes the reasoning auditable — the decision, its provenance, its lineage. It is not a tamper-evident ledger and makes no cryptographic chain-of-custody guarantee about the records themselves. It answers "why was this decided, and what was rejected," with provenance; it does not, on its own, prove a record was never altered after the fact. Framed as a decision-accountability layer, it delivers exactly that.
A project doesn't have one kind of memory — it has three, and they must not mix. Decisions about the product are not decisions about the engine that remembers the product, and neither is an experiment that might be refuted next week. HESUS keeps them in three separate cortexes with separate id schemes, and one verb tells the assistant which one it's standing in.
ED-282, PAY-002. This is the brain a developer's brief reads. It ships inside the product folder and is the thing being protected.HD-001 through HD-152. Why retrieval scores a title above a caveat, why a summary is refused. Brain A's engine improvements fold up into B; nothing ever flows back down, so B's dev reasoning never contaminates a customer's project.ES-001 through ES-032, plus RD- research decisions. Deliberately outside the A↔B sync: a lab, not a synced peer. A refuted hypothesis stays legible as refuted rather than propagating.Retrieval is the whole product. A decision that exists but isn't surfaced at the moment it governs is worth nothing — worse than nothing, because the operator believes it's covered. So the retrieval path was rebuilt, measured, and rebuilt again across thirty-two studies.
The naive approach flattens every record into one bag of words and counts overlap. That fails in a specific way: a term buried in a Caveat counts exactly as much as the same term in the Title, so a record that merely mentions "payment" outranks the credential-exposure record that exists to stop you. The fix was to score per field, then to add a channel that isn't a coincidence of wording at all.
The scorer described above runs in the browser against a worked sample project: eleven decisions, five studies, real field weights, real trigger terms, the ×1.3 load-bearing boost and the 28% relevance floor. Type a task and watch it rank the cortex — then type something the project has no opinion about and watch it say so.
Open the live dashboard demo →Two structural failures were found in that pipeline and are worth naming, because both are the kind that pass every test suite. The first: retrieval was non-deterministic. Two sorts truncated on a hash-randomised tie-break, so the same query returned a different near-list on each run. The top hit stayed correct, which is exactly why twenty-five studies never caught it. The second is worse — found, ranked, and thrown away. A load-bearing credential-exposure record scored 3.25 and ranked seventeenth of sixty, behind sixteen generic competitors that matched one more query token; the eight-slot window discarded it. And the guard meant to catch that built its candidate list from the records already in the results, so a record crowded out was invisible to the mechanism designed to rescue it. Meanwhile the brief printed "read the GOVERNS section above" — while that section held only the competitors. A warning pointing at a record it has declined to show reads as reassurance.
The clean result is the one below: same project, same three hundred decisions, same eight development tasks. The only variable is how the constraints reach the model.
| What was measured | Before | After | How it was found |
|---|---|---|---|
| Cortex parse, 10,000 decisions | 10.2s | 0.30s | Two stacked quadratics — a tail-slice copy per token, and 64,040,000 str.lower() calls in the duplicate-key check |
| Retrieval, 850-record cortex | 33.9s | 5.3s | 699 tokenizations for one search collapsed to 81 by sharing one index across the brief's sub-searches |
| Brief length | 570 words | 324 words | Ceremony cut — per-decision expand hints, section explainers, headers. Zero retrieval regression |
| Concurrent cortex writes | 11 of 12 | 20 of 20 | Unlocked read-modify-write. No corruption, but a silently dropped decision breaks the one promise the tool makes |
| Verb coverage in smoke | 24 of 48 | 48 of 48 | Smoke reported "24/24 clean" while ship crashed on every invocation — it was never in the list. Omission is silent |
| Determinism across processes | 2 answers | 1 answer | 25 fresh processes, one query. Hash-randomised tie-break in two truncating sorts |
| False-quiet rate | 61% | 0% | Novelty-gated confidence — the brief said nothing while a safety decision sat uncovered |
| Composite score | 20% | 86% | Across the full study suite, from the earliest measured baseline |
Everything below is drawn from the research brain that ships with the engine — thirty-two studies, each with a pre-registered hypothesis, a stated method, raw per-pass measurements, and a verdict that was allowed to be no. The charts are rendered directly from those payloads. Where a study refuted the thing it was testing, that is what the chart shows.
The cause was isolated rather than argued away. Same cortex, same queries, only the trigger vocabulary stripped: recall@1 fell 95% → 25%, recall@k 100% → 45%. The gap was never synthetic-versus-real; it was with-triggers versus without — and the real brain carried triggers on nine of two hundred and twenty-two records. Drawing candidate vocabulary from each record's own source file took real-brain recall@k from 0% to 48%. 48% is not 100%, and coverage is 13%. Both numbers are in the shipped record.
Two more results are worth stating without a chart, because they are single comparisons rather than curves. ES-002: on a cortex dense with code identifiers, the identifier-aware tokenizer took recall from 0.00 to 1.00 — a compound name like SaveWTSettings is now emitted whole and split, so a natural-language task can reach a decision written in code. ES-003: on a small project measured with and without the brain across three passes, cross-pass regressions fell from three to one and recorded rationale went from nothing to twenty of twenty — while context cost went up, because at that size re-reading the source was cheaper. That result is why the compact brief exists, and it is why the crossover chart above starts where it does.
Both front-ends are deliberately thin over the same tested command line, so there is no second implementation to drift. They exist because two different people need the brain: the operator standing at a machine, and the operator handing a link to somebody else.
A bound workstation tool. It remembers the brain it is tied to by lease id and reopens straight into its health on launch. Opening any other folder is a peek — it finds the nearest brain, however deep the folder schema buries it, and shows you that without moving the binding.
It is where the code and the reasoning become one navigable thing. The source browser renders Python through the standard-library tokenizer for real syntax colouring, and selecting a symbol re-scopes a panel to the decisions that govern it. The reverse works too: click a decision, jump to the file it names.
It also carries the parts nothing else does — a development timesheet with an accruing stopwatch and value-per-day graphs, and a capability catalogue that derives the project's public surface statically and caches it against a source fingerprint, so it recomputes only when code actually changes.
This one started as a twenty-endpoint HTTP server and was deleted. Every tab had a loading state; every read was a round trip; a slow endpoint queued behind another. It was replaced by a generator: the command loads the project once, bakes every brain's records, every study payload and every chart into one HTML file, and opens it.
There are no fetch calls for reads. Switching brains re-renders the cortex instantly from data already in the page. A tiny background thread survives for exactly one endpoint — running a live brief — because that genuinely needs the engine.
It is also the multi-project view: it scans for every project carrying a brain, deduplicates by real path, and shows each one's record count, engine version and full bundle timeline. Output runs 34–132KB depending on cortex size.
A memory tool that loses a record, or reports a pass it did not observe, is worse than no tool — it converts an absence of information into false confidence. Most of the engineering here is defence against exactly that. These are the failures that mattered, in the shape they were actually found.
There is a pattern in these. Every one was a mechanism that reported success while failing — a smoke suite reporting 24/24 clean while a verb crashed on every invocation because it was never in the list; a self-check reporting a file verified when its version stamp format meant the matcher skipped it entirely; a dashboard passing every syntax check and shipping an inert page. The engineering answer, applied repeatedly, is that a guard which can silently not-run is not a guard. Each fix is now paired with a check that asserts the guard itself is reachable — every dispatchable verb is either exercised or explicitly excused, and a new verb cannot go uncovered by accident.
Twenty pre-registered studies across 154 build passes. Three arenas: synthetic testbeds where ground truth is controllable, a hand-rolled binary-protocol codec the engine was never tuned for, and Omniscient — a real shipping Windows fleet-hardening tool carrying 326 live architectural decisions.
| Context efficiency ratio (6 passes, 70-decision project) | 0.112 — briefs cost 11.2% of source reading |
| Cumulative context over 6 passes: briefs vs. naive re-reading | 863 words vs. 7,695 words |
| Retrieval at 1,000 decisions (in-vocabulary / paraphrase) | 100% / 90% — unchanged from 40 records |
| Brief latency at 1,000 decisions | 114ms (from 88ms at 40 — still interactive) |
| Adversarial safety recall, binary-protocol codec (30 tasks) | 88% — 29 of 33 constraints |
| Six-step cascading build — the first mistake | Caught; all 5 downstream violations prevented |
| Naive violations prevented on the real 326-decision project | 9–11 of 20 |
| Head-to-head A/B: cross-pass contradictions | 3 → 1 |
| Head-to-head A/B: decision rationale preserved | 0/20 → 20/20 |
| Silent misses (a thin answer that still looked confident) | 61% → 0% |
| Frozen 45-probe retrieval baseline across the research arc | 22/45 → 43/45 |
Two results deserve to be read together. The context win is automatic — it arrives on pass one and widens as the project grows, because a brief stays near-constant in size while the codebase does not. The safety win is conditional — it is bounded by retrieval, and retrieval is bounded by vocabulary. A recorded constraint only helps if the brief surfaces it for the tempting task. That distinction is the honest core of the whole system, and the studies below are mostly the story of pushing on the second one.
Retrieval — deciding which decisions a brief surfaces — is the whole ballgame. A brain that holds the right constraint but fails to show it when you're about to violate it is worthless. So it was built as a chain of pre-registered experiments against a frozen set of 45 labeled probes, split into three difficulty tiers, with tier assignment verified mechanically rather than by eye.
The arc, in one line: the frozen baseline went from 22/45 to 43/45 — and every step of it is a study you can read, including the ones that went the wrong way.
The most useful study wasn't about recall percentages. It simulated how damage actually happens in AI-assisted work: a six-step build where each step's mistake feeds the next. Step one adds a "lenient mode" flag. Step two relaxes a check because lenient mode exists. Step three trusts the relaxed check. By step six you have shipped a security hole, and no single step looked wrong.
HESUS caught the first domino — the brief surfaced the strict-by-default decision the moment the lenient flag was proposed, and flagged caution. Catching that one step prevented all five downstream violations. Five of six steps surfaced their governing constraint; step six slipped (caching a parsed chain shares no vocabulary with zero key material from memory), and it is written down as a miss.
That is the shape of the value. Not "the AI never makes a mistake" — but the expensive mistake, the one that compounds, gets caught at the top of the chain where it is still cheap.
Three studies argued against the product. They are the reason to trust the other seventeen.
HESUS does not autonomously write code or make decisions. It makes an operator's judgment durable, queryable, and provenance-preserved — and it tells you how much it might be missing. Sold as exactly that, the measured results above are what it delivers.
Lease HESUS for your project
$300 per project — folded in once, yours to keep in that codebase for life. Pure Python, standard library only, nothing added to your runtime.
Figures were measured on live production artifacts on 2026-06-24 and are reproducible from the shipped bundles. Where a number is projected rather than measured, it is labeled as such.