Context Is the Architecture

Every project I’ve built inside Hekton gets a service architecture reviewed before it ships. None of them, until recently, got the same scrutiny for the thing that actually determines whether anyone can pick the work back up next week: the record of why it’s built the way it is.

The actual problem

Code architecture gets budget, review, and design time, because everyone agrees a bad schema is expensive to unwind later. Context, the accumulated reasoning behind why the code looks the way it does, usually gets none of that, because the cost of skipping it doesn’t show up until someone, an engineer or an agent, needs to resume the work and finds nothing but the diff.

Agent-assisted engineering doesn’t create this problem. It multiplies how often you hit it. A human picking up their own three-week-old work still has some residual memory to lean on. An agent starting a new session has none. Every session is a cold start unless something durable was written down at the moment the reasoning actually happened.

What I tried, and what got weird

Hekton’s answer is an append-only decision log (docs/decisions.md, in every project, this one included): every material choice recorded with its reasoning, at the moment it’s made, never edited afterward, only added to. A session log alongside it (docs/session-log.md), capturing what changed, why, what’s still a risk, and what’s next, every time a session closes, per the rule written down in ~/hekton/CLAUDE.md’s Documentation Contract. Together they’re supposed to be the thing a cold-start agent reads before touching anything.

It worked, mostly, until a second copy of it showed up. Hekton keeps a separate vault for cross-project search, and for a while the vault mirrored the same code-coupled files the repo already owned: decisions, next actions, session history, all duplicated into a second location nobody had designated as the source of truth. Two places claiming to hold the real record is worse than one place slightly behind, because a reader has no way to know which copy to trust without diffing them by hand.

The fix was a boundary, not a bigger sync job: the vault holds only a project card and the session log, the semantic index a cold-start search actually needs. Decisions, next actions, and everything else stay owned by the repo, linked from the card, never duplicated. One thing, one home, one way to find out it’s stale.

That’s the part that made the architecture framing click for me. A schema migration that nobody reviews is a known kind of risk. A context system with two unreconciled copies of the same record is exactly the same category of risk, wearing a documentation label instead of a database one, which is precisely why it gets budgeted for less.

What actually held

The pattern that holds, in daily use across most of Hekton’s projects now, is three simple rules kept honest rather than one clever system. Append, don’t edit, so the log stays a record of what was actually decided in the moment, not a reconstruction. Capture the session’s what, why, risks, and next actions every time, so a cold start has somewhere real to begin. And keep an explicit boundary on what’s allowed to mutate where, so a second copy can’t quietly become a second, unreconciled source of truth.

A decision log nobody prunes or checks for drift is architecture debt in the same way an unreviewed schema migration is.

Even a boundary needs checking, not just declaring. This site’s own repo-local mirror of its history drifted over two weeks behind its source, caught automatically by a pre-push hook that diffs the mirror against the source on every push, not by anyone remembering to look. The boundary rule fixed the structural risk. It didn’t make drift-checking optional, which is exactly why the check runs on every push instead of living in someone’s memory.

The record you didn’t check for drift is the record you’re actually trusting on faith.

The artefact

I built a small audit CLI to make the checking part mechanical instead of occasional: github.com/dermdunc/context-audit. Point it at any docs or context folder and it reports, per file, an approximate token cost, a staleness signal against git history, and a redundancy score between file pairs, each explicitly labeled as a heuristic, never presented as more precise than it is.

$ git clone https://github.com/dermdunc/context-audit.git
$ node context-audit/bin/context-audit.mjs /path/to/your/docs
Scanned /path/to/your/docs
23 file(s), ~38,453 tokens total (approx, chars/4 heuristic)

Biggest (top 5):
  ~10,112 tokens   session-log.md
  ~8,590 tokens    decisions.md
  ~4,537 tokens    post-backlog.md
  ...

Most redundant pairs (top 1, word-shingle heuristic, not semantic):
  17%  reproducibility.md  <->  setup.md

That’s a real run against this site’s own docs/ folder, invoked with an explicit path on purpose: point the command at the checkout it clones instead of the folder you happen to be standing in, or it will happily audit its own docs instead and print a plausible-looking report about the wrong repo (numbers above will differ if you run it yourself; docs grow). It correctly flagged session-log.md and decisions.md as the two biggest files in the tree, exactly the growth pattern this essay’s thesis predicts once a project has been running for a while. The one redundant pair it found is a good demonstration of the tool being honest about its own limits rather than a case of real drift: reproducibility.md and setup.md share a templated bash block from the same scaffold script, not duplicated reasoning, and the tool’s own README names this exact shape as a pattern that scores higher than its actual content overlap warrants. A redundancy signal that flags boilerplate as boilerplate, and says so, is worth more than one that quietly overclaims semantic overlap it never actually measured.

What next

If you’ve invested in code architecture and treated your project’s context as whatever happened to get written down, the concrete first step is small: add an append-only decision log to one project that doesn’t have one, and check it for drift the same way you’d check a schema for an unreviewed migration.

Next time: what four incidents across three different systems taught about governance that holds even when the agent grading its own work is completely sure it’s fine.