Atlas: Accountable Agentic Engineering

In August I published the story of how Atlas was born, the system I engineered and built to keep LLM agents from wrecking a multi-package stack. That post ended with a wish list. Context injection at the point of work. A staleness engine. An auto write-back for public surfaces. A review bot.

I tend to not keep calm with things, the things that passion me. Atlas did passion me. A little.

Two months later, the receipts are in. Every item on that list exists now. Most shipped exactly as imagined. One grew into something better.

But the wish list is the small story. The big one: Atlas grew senses, judgment, and memory. It went from "a linter with a map attached" to the layer where the team's boundaries, traps, and decisions live. With a full-time auditor making sure none of it rots.

Before the tour, though, the scoreboard. Growth deserves numbers.

The scoreboard

Seven+ months ago, Atlas was a folder of notes on my machine. Today it is 250+ documents of living architecture, and every one of them is linted, written in controlled English, and resolvable against real code.

The breakdown:

• 50+ package maps. One per package in the stack: every public surface declared, every internal marked off-limits.
• 20+ quirks, the stack's recorded traps. 20 of them carry a verified guard: a test in Warden, our QA suite, or a convention the linter enforces.
• 10+ immutable decision records. Settled questions stay settled.
• 20+ conventions, transaction flows and plans in flight.

And the number I'm watching the closest now is the newest: plans that ship get their delivered PR stamped into the archive, dated and permanent. The receipt happens at merge time, not audit time. The map grows because the work grows. Everything below exists to keep it honest.

Un manjarsh...

The receipts

Promised in August. Shipped since:

• Context at the point of work became atlas context. You point it at the files you're about to touch, and it returns the contracts, collisions, quirks, and conventions that apply to exactly those files. Nothing else. Prompts shrink by up to 90% while the constraints get sharper.
• The staleness engine became atlas review staleness. Each package document carries an updated date, and the CLI compares it against release tags and git history. Docs lagging behind code become a named finding instead of a slow surprise.
• The auto write-back became atlas review release-surface. It reads the git diff, extracts every new public interface, and flags the undeclared ones. With --fix, it writes the code annotations for you.
• The review bot evolved. It doesn't comment on diffs. For any plan it assembles a self-contained review packet: contracts with file:line anchors, per-repo diff stats, a coverage grid. Two validation gates then prove the reviewer evaluated every row and resolved every finding before merge.
• The living map arrived as two pieces: atlas map, one filterable line per document, and JSON manifests compiled from the docs, which CI checks for drift.

Five for five. The fine print: the review bot came back upgraded.

The impostor who lives on my shoulder read my own wish list back to me and waited for the part where I stopped delivering. He's still waiting. He says "hi!".

From tool to system

Four systems grew around the original core of map plus lint.

Senses: brief, context, map, check. The agent stopped needing to read Atlas, because Atlas pushes the exact slice at the moment of work.

Judgment: delegation tiers. A written answer to "how much may this agent do without asking?"

Memory: quirks, investigations, immutable decision records. The team's scar tissue, queryable.

Proof: falsifiable contracts, AST resolution, two verdict grades. Every claim checkable, deterministically.

What follows is what that buys in practice. One section per wound.

It prevents building on sand

Every package in the stack gets a one-file map: its role, its dependencies, its public surfaces, its protected paths, its internals. Both humans and agents now know exactly what is in bounds before the first line of code.

The pain it kills is old. Nothing marked the line between public API and internal detail, so code called another plugin's private class, a refactor broke it, and the fix crossed 3 repositories. Now that line is declared, and the linter proves the declared surfaces still exist in live code, with real AST parsing. A documented symbol that disappears fails the build. That is a strictly stronger promise than "we have docs".

On top of the maps sit contracts. A contract is a written promise about a piece of code: its name, what it does, who may depend on it. Status makes it operational: stable means build away, unstable means moving soon, ask first, editing means somebody is in there right now.

Contracts come in several kinds, because a WordPress stack lives on strings as much as classes: PHP symbols, hooks, REST routes, block names, JS exports, DB models, template globs. A hooks-and-REST system can't be mapped with class names alone.

And my favorite bit of stubbornness in the whole design: every stable contract carries a wrong_if. A concrete statement of what change would break the promise. A contract you cannot falsify is a wish. Wishes don't pass review.

It prevents relearning the same lesson

Every incident has 2 costs: the outage and the relearning. This part of Atlas deletes the second cost.

Verified incidents become quirks. Each quirk carries mandatory sections, symptom, cause, resolution, anchored to the exact files involved, plus a guard field proving the fix stays fixed. The guard is either a test in Warden, our QA suite, or a convention the linter checks.

The magic is injection. Touch a file listed in a quirk's sources, and atlas context inserts the guardrail into your session automatically. You don't have to know the trap exists. The trap costs one write-up, then it defends itself.

Hard, multi-package bugs get investigations: structured records with reproduction steps, a fail-first test, root cause, blast radius, resolution evidence. When a finding repeats across investigations, it promotes into a quirk. Knowledge compounds instead of evaporating in Slack threads.

Decisions get the same treatment. An accepted architecture decision is immutable. A change of direction means a new decision that supersedes the old one, dated and archived. The seniors can stop re-litigating settled questions, because the ledger answers with a link. So do the agents, who used to re-argue everything with fresh confidence on every run.

Just like my...

It prevents agents from wandering

Session boot starts with atlas brief. Active plans near your packages, debt counts, whether your clone of the knowledge base is stale. And one line I'm proud of: the delegation tier. T0 through T3, how much autonomy this task allows. T0 is read-only. T3 is full send, with review. A number for how much rope the agent gets, written down before the work starts.

Before editing anything: atlas check on your paths. It intersects them with every active plan's contracts and the protected paths from the package maps. Crossing something somebody is editing right now? The CLI emits a structured stop block and the agent halts, instead of writing code on contested ground. Humans run it too. It answers the oldest question in parallel development: is anyone else in here right now?

Discovery runs through atlas map. One line per document, filterable by type, package, tag, status. Map first, read only what matches. A corpus of hundreds of documents is useless without discovery; people re-ask answered questions and re-write conventions that already exist. Agents do both, faster.

It prevents lying maps

Documentation you cannot verify is a rumor with nice formatting.

So the engine never calls a model. The whole thing is a Go binary. Every check is AST parsing, YAML schemas, git inspection, or set intersections. Same input, same verdict on your laptop and in CI. Determinism is the point: an agent cannot charm an AST resolver.

Findings carry exactly 2 grades: FORCED and ADVISORY. FORCED exits 1: broken contract, active collision, protected path. ADVISORY exits 0: context and style. Linters that cry wolf get ignored by humans and halt agents on trivia. Warning fatigue is dead, and CI fails only on the real ones. The stopping rule is mechanical: halt on FORCED, read and proceed on ADVISORY.

The review packet closes the human side of that loop. Reviewers with partial context approve partial work, so the packet assembles everything a fresh reviewer needs and the validation gates prove nothing was skipped. A fresh-context agent can run the same gate. Review became a reproducible procedure instead of an act of faith.

And the corpus itself is written in ASD-STE100, the aerospace controlled-English standard. Short sentences, active voice, closed vocabulary, hard size caps per document. It reads identically to a human and to a model, and no document grows into an encyclopedia nobody maintains. Yes, NASA-grade English for a CRUD stack. Two articles in a row, and it still works.

Mic-drop.

One feature's week

Here's the loop on a real task.

Morning: brief. The tier says T2. Two active plans run near my target files. One quirk anchors to code I'm about to touch, guardrail loaded before I knew I needed it.

The plan gets written first, contracts declared, statuses set. And you actually read the plan. And polish it. Get grilled on it. Amend it. And go back and read it all. And actually understand it. That part no agent can do for you. No osmosis for us humans.

check runs against my paths: green. context assembles the slice: the contracts on those surfaces, the quirk, the convention for this kind of work.

Now code and tests. Warden builds the stack from scratch and runs the suites, so nothing ships on a machine that happens to work.

Once the work is ready, comes the pull request. review release-surface --diff proves every new public interface is declared. The review packet assembles itself for whoever reviews, human or fresh-context agent.

Merge: the archive command stamps the PR into the plan, the plan's rationale becomes an immutable decision, and the plan itself moves to the archive, when everything actually shipped.

Nothing wrote to the map unchecked at any point in that week. That's the whole trick.

What it adds up to

For the tech-curious, the bill of materials: a Go binary (you can also do Rust if you want, nerd), 25+ commands, PHP and JavaScript (and any language) AST traversal, SARIF output that GitHub renders as inline annotations, a pre-commit lint under 2 seconds, a dozen zones of documented knowledge, determinism everywhere. A stack that knows itself, in a language a machine can read without guessing.

Determinism. This is the key. To fight stochastic madness of LLMs.

The interesting problems are no longer "write the feature". They look a lot more like "make 10 moving pieces and a fleet of agents provably coherent". I ended up building the system that answers that. I'm open to chat on Fridays.

Agents do the typing. Atlas decides where the typing is allowed to land. Humans engineer and envision how the system should work, review everything and stay the authors of the grand design. For a fistful of tokens.