The Development Framework

How an idea becomes assured code: the meta-harness that wraps agent work in verification, and why each part of it exists

Agents removed the bottleneck on writing code. They did not remove the bottleneck on knowing whether the code is right — they moved it, and made it sharper, because output now arrives faster than a human can read it.

So this framework is not about producing quality. It is about producing warranted confidence, continuously and cheaply enough that nobody is tempted to skip it. Every mechanism below exists to answer one question: what do we actually know, and how do we know it?

The agent harness coordinates who does the work. This meta-harness decides whether the work is allowed to count.

The path from an idea to shipped code

An idea you say out loud survives seven translations before it runs in production. Each one loses something. The job here is to make each translation lossless enough to trust, and to make the loss visible when it happens.

Idea to requirement. You say what you want, in whatever form it arrives — mid-sentence, as an aside, as a complaint about something on screen. It is captured as a requirement immediately, because the alternative is that it lives in a conversation that scrolls away. Requirements get recorded before they are understood. Clarifying first is how things get dropped.

Requirement to task. Requirements become ordered tasks with owners. Ordering is not bureaucracy, it is what makes the system answerable: you should be able to ask where a feature stands and get “third in line” or “implemented, deploying now” rather than a shrug. A task with no owner is unclaimed, and two agents will both correctly conclude it is free.

Task to test. Behaviour is written before implementation. Not as ceremony — as specification. A test written first says what the thing must do. A test written afterward says what the code happens to do, which is a different and much less useful document.

Test to code. The agent writes the implementation. Everyone thinks this is the work. It is the cheapest step in the chain.

Code to gate. Nothing lands that regresses a standard. The gate measures the commit — not the working tree, not the intention.

Gate to deploy. Green means push and deploy. One action. A commit that passes and sits undeployed is not finished work, it is a claim about the future.

Deploy to verification. The deployed artifact is checked against reality: is the new build actually serving, does the page actually render. Not against the deploy tool’s exit code. Tools report their own success. Reality does not care.

Verification to audit to report. Scheduled audits measure the running system on dimensions a test suite cannot see, and write findings where a human will read them.

The five properties that make it hold

Most quality processes are a list of good practices. What makes this one load-bearing is that every stage is required to be falsifiable.

Every claim must be able to fail

A check that cannot fail is decoration. Before trusting a new verification, break it on purpose and confirm it notices. A test that passes the first time it runs has told you nothing — you have not watched it fail, so you do not know it is connected to anything.

This bites hardest on checks you write about your own work. The expensive defects are rarely broken code. They are confident reports about code nobody looked at.

Unmeasured is not failed, and it is not passed

Three states, not two. A check that could not run — network refused, page never loaded, credential rejected — produced no information. Recording that as a failure creates false alarms that get ignored. Recording it as a pass is worse: it manufactures confidence out of nothing.

Carry unmeasured all the way through: into the numbers, the reports, the dashboard. A score with unmeasurable inputs says so rather than quietly averaging them away.

Refuse, do not warn

A warning printed on every run and never actioned is indistinguishable from noise, and it trains everyone to stop reading the place where the next real failure will appear. If a condition matters, the tool refuses and says what to do instead. If it does not matter enough to refuse, do not print it.

Every guard needs a documented escape hatch. A guard with no override teaches people to disable guards, and then you lose the guard and the habit together.

Measure the artifact, not the intention

Verification reads the thing that shipped. Not the branch, not the working tree, not a tool’s summary of itself.

This sounds obvious and is violated constantly, because the wrong thing is usually nearer to hand: a checkout that silently fell behind, a field nested one level deeper than you looked, a status line printed before the step it describes. When an instrument disagrees with reality, suspect the instrument first — including your own.

The instruments are code, and code has bugs

Auditors, gates and probes are software. Software written to check other software is not exempt from being wrong. It needs tests. It needs controls: a known-good case that must pass, a count with an expected magnitude, something in the output that reveals the measurement itself is broken.

A probe that reports a defect at every input is describing itself. A sweep that reports everything clean may never have looked. Build each measurement so it can expose its own failure, and re-run anything that matters under different conditions before believing it.

The shape of the code

Assurance is cheaper on code that is small and honestly named. These are not style preferences — they are what stops the cost of verification growing faster than the codebase.

Minimal files, correct abstraction. Extract when the same idea appears a third time, and extract the idea, not the lines. Moving duplicated text into a shared file without finding what it means produces a worse structure than the duplication did. Per-file size limits exist so that crossing one prompts the question of what the file has become.

Refactor continuously, never as a project. Deferred cleanup is cleanup that never happens. It rides along with the change that revealed the need.

Names that do not lie. A name that misdescribes its subject is a defect to fix, not a note to leave. Misinformation compounds — the next reader builds on it, and the correction costs more every week it waits.

Delete completely. Removing a thing is half the change. Whatever watched it — the health check, the file list, the docs, the test — has to learn it is gone. A watcher left pointing at something deleted reports a fault forever, and the fault is in the report.

Two audiences, two kinds of documentation

Documentation fails when it serves both at once. Separate them by who reads them and what they cost.

Agent-facing: minimise tokens to context. Every file an agent must read to understand a change taxes every session that touches it. One to three lines at the top of each code file: purpose, key dependencies, anything non-obvious. Never restate what the code already says. One terse README per directory explaining why the directory exists — and a directory needing no explanation needs no README. Target a fresh session understanding the project in a few hundred tokens of reading.

Comments earn their place by explaining why, especially why something is not the obvious thing. A comment describing what a line does is dead weight. A comment recording the reasoning behind a non-obvious choice stops the next person re-deriving it or, worse, “fixing” it.

Human-facing: the reference manual (TRM). A person needs the opposite of a token budget — orientation, worked examples, the reasoning behind decisions, what was tried and rejected. Written for someone new, or for you in six months. Different document, different economics. Collapsing it into code comments ruins both.

Tests run in a real browser, with a real session

If a thing cannot be tested, it cannot be assured. That sounds like a truism until you notice how much of a web application is untestable by the means most suites use.

Unit tests verify functions. They cannot see a component pointed at the wrong host, a handler that never binds, a stylesheet that no longer exists, or a control that renders perfectly and does nothing. Fetching HTML is barely better: on a page whose per-user data is loaded by client JavaScript, the server returns the same markup whether or not you are signed in — so a fetch-based check reads a shell and reports it clean.

So end-to-end and behaviour tests run in a real browser, with a real session, against a deployed target. Not a mock, not a fetch, not a logged-out page.

What that buys, concretely — every one of these is a defect class that no unit test can reach:

• Console errors fail the run. A component that throws during hydration takes every handler after it with it. The page looks right and nothing works.
• Network connections are asserted, not assumed. A WebSocket pointed at the wrong host fails only when something actually tries to open it.
• Interactive controls are clicked. Rendering a button proves nothing about whether it responds.
• The signed-in surfaces are covered at all. They are usually the most complex part of an application and the least tested, because testing them requires exactly the setup this rule mandates.

The session has to be real for the same reason. A credential the page never verifies is not a session — it is a cookie, and it produces a page that looks authenticated while containing none of the data a user would see. Assert something that can only appear when genuinely signed in, and let the absence of it fail the run.

The cost is real: a browser is slower than a function call, and a deployed target is slower than a local one. Both are cheaper than shipping a page where the tabs do not respond.

Scheduled audits

Tests answer did this change break something. Audits answer what is true about the running system today. Different questions, different clocks.

Two rules make the schedule worth keeping.

Establish the noise floor before believing a difference. A performance number measured on a loaded machine measures the machine. Run it twice under different conditions. A diff without a control is a number without a unit.

Audits produce reports, not just numbers. A finding needs a location, a cause, and what changes if it is fixed. The report goes where a human reads it, attached to the project it concerns — not into a log, and not into a channel that scrolls.

The gate as a ratchet

The gate does not demand perfection. It demands that nothing gets worse than the recorded baseline. That is what makes it survivable on a codebase with existing problems, and a gate that gets switched off protects nothing.

One subtlety decides whether the ratchet stays honest. When an auditor improves and starts seeing a class of problem it was blind to, the finding count rises without the code getting worse. Treating that as a regression punishes better measurement, which is backwards. So an auditor declares what it can see, the baseline records which version produced its number, and a change in coverage forces the question to be answered explicitly rather than silently blocking or silently passing.

Accepting a new baseline is a decision with a written reason, not a way past a red light. If the reason is that the fix looked like work, the ratchet has stopped meaning anything.

The project API

None of the above is enforceable unless the project is addressable. Requirements, tasks, documents, quality state, deploy state and blockers are readable and writable over an API. That is what lets agents and humans work the same system on equal terms.

It is what makes “where is that feature in the queue” a question with a real answer. It is what lets an agent file a report where you will find it, rather than in a terminal you closed. It is what makes a kanban view possible without a second source of truth, and what lets several agents share one backlog without colliding — the board is shared state; messages between agents are not.

One rule keeps it trustworthy: state is written through the API, never by reaching around it. Direct writes to storage skip the validation, the ownership checks and the audit trail. That is how a dashboard starts disagreeing with reality.

How this composes with the agent harness

The agent harness decides who does what. The meta-harness decides what counts as done.

They meet at three points. The board is shared state — ownership is claimed there, not announced in a message, because a message can cross with the work it describes. The gate is identical for everyone, so nothing ships by being persuasive. The reports are written to the project, so what an agent learns outlives the session that learned it.

The framework assumes agents are fast, capable, and occasionally confidently wrong — which is also true of people, at a different speed. Nothing here depends on any participant being reliable. It depends on claims being checkable, and on the system preferring “I could not determine this” over a comfortable answer.

That preference is the whole thing. The rest is mechanism.