Software Factories Need Building Codes

In the last post I wrote that a rule without an enforcing check is an opinion. That came from six months of watching an autonomous software factory politely route around every expectation that existed only as prose. Better prompts did not make the system trustworthy. Gates, evidence, independent review, and mechanically enforced decisions did.

That left me with another question: once the harness can enforce rules, what rules should it enforce?

I initially thought the answer was some combination of engineering standards, reference architectures, and the accumulated craft knowledge senior engineers carry from project to project. Then I noticed HydraFlow had already started answering the question for itself. It had grown a docs/standards tree covering ADR enforcement, testing, branch protection, factory autonomy, factory operation, ports and loops, parametrised guards, and vitals conformance.

I had built the mechanism before I had a useful name for what it was becoming.

The name I keep coming back to is software building codes.

By that I mean a set of continuously enforced properties the software must satisfy, independent of which agent or engineer built it.

Not because software needs another pile of standards documents. We have plenty of those already. The interesting part is what happens when the standards sit inside a system capable of detecting a violation, manufacturing the repair, verifying the result, and sometimes tightening the standard afterward.

One distinction matters here. The harness does not decide what standards a product must satisfy. It governs how a worker operates: context, skills, tools, permissions, sandboxes, retries, budgets, and review. The factory owns the longer control loop. It knows what is being built, which standards apply, turns violations into work, runs that work through harnessed agents, and keeps the product within those standards over time. The harness governs a run. The factory governs the product lifecycle.

That is the layer that becomes important once the harness is doing its job.

This is not policy-as-code with a new name

There is obvious prior art here, and pretending otherwise would make the idea weaker.

Open Policy Agent already lets us express policy as code and evaluate structured data against it. Conftest applies that model to configuration and can fail CI when a configuration violates policy. Sentinel can proactively prevent disallowed changes from being deployed. Backstage and similar platform tooling have made scorecards and conformance checks a familiar way to expose whether software meets an organization's expectations.

So the interesting claim cannot be that software standards become executable. We already know how to make policies executable.

What changed for me while building HydraFlow was the actuator. In control-system terms, the actuator is the part that changes the system in response to a decision: it turns a detected violation into concrete corrective action.

Most conformance systems answer some version of: does this thing satisfy the rule? Depending on where the policy is enforced, the answer may block a merge, stop a deployment, create an alert, or show up as a red scorecard.

An autonomous factory can continue the loop. It can ask why the rule failed, create bounded work to repair the violation, dispatch a builder, verify the resulting change against the same rule, and merge the remediation if it passes.

The useful shape is closer to this:

That is where the building-code analogy starts earning its keep. The code is not only inspected. The structure is continuously brought back toward conformance.

HydraFlow already contains examples of this, which is more interesting than the analogy on its own.

It helps to separate the layers here. The harness does not decide what standards a product must satisfy. It governs how an individual worker run happens: the context it receives, the skills and tools available to it, its permissions and sandbox, retry and budget limits, and the review around its work.

The factory owns the larger control loop. It knows what is being built and which standards apply, turns those obligations and violations into work, runs that work through harnessed agents, verifies the result, and keeps the product within those standards as it evolves.

The harness governs a run. The factory governs the product lifecycle.

The standards define the required properties. The factory closes the loop around them. The harness equips and constrains the worker that performs each change. The worker doing the work can be human or machine. Both operate under the same rules.

One standard that became real

HydraFlow uses Architecture Decision Records heavily. That created an obvious failure mode: an ADR could say something important, everybody could agree with it, and the code could quietly stop obeying it six months later.

I originally treated the presence of the decision as useful institutional memory. Eventually that stopped being enough.

HydraFlow's ADR Enforcement standard now classifies accepted ADRs into three states: REAL, where the decision points to an actual resolving and asserting machine check; WEAK, where something is named as enforcement but is not a meaningful mechanical check; and MISSING, where no enforcing check exists at all. WEAK and MISSING together become unenforced-decision debt.

The rule is deliberately uncomfortable. If an ADR claims to be mechanically enforced, the referenced enforcement has to be real. A manual or process-only decision is allowed, but it has to earn an explicit justified exemption rather than masquerading as an executable invariant.

When that standard landed, HydraFlow already had twelve accepted decisions that did not satisfy the new bar. Blocking every change until all twelve were repaired would have been a terrible migration strategy, so those decisions were grandfathered into a baseline.

But the baseline had a property that matters: it could never grow.

A new ADR could not join the debt. Existing debt could leave the baseline only by gaining real enforcement or by being honestly classified as something that could not reasonably be checked mechanically. The standard itself is enforced by a merge gate, and the live tally is generated as part of the architecture documentation.

That is already more useful to me than a standards document. The standard has a rule, a sensor, evidence, and a governor.

It is still not the whole idea, though, because that mechanism primarily prevents new drift and forces existing debt downward. The more interesting step is when the factory becomes responsible for doing the repair.

From red scorecard to manufactured remediation

HydraFlow's disturbance dampener came from a much more mundane problem: suppressions and other small quality exceptions accumulate.

A # noqa here or an untyped mock there is rarely catastrophic. The problem is that these things are cheap to add and expensive to clean up later, so a codebase gradually drifts away from whatever engineering standard the team thought it had.

A conventional hard gate creates an adoption problem. If a repository already has hundreds of violations, turning the gate on can freeze unrelated development until somebody cleans up the entire backlog. Leaving the gate advisory avoids that disruption, but then nothing forces the debt downward.

HydraFlow took a third path.

The first half is a ratchet. Existing violations are baselined. A pull request cannot add new ones, and the baseline is not allowed to silently absorb growth. In the original suppressions dimension, the starting backlog was 782 findings across 300 signatures.

The second half is the actuator. DisturbanceDampenerLoop selects bounded units from that backlog and dispatches a coding agent to fix the underlying violation and prune the corresponding baseline entry in the same change. The resulting PR then has to pass the same ratchet gate that defined the violation in the first place. If the agent prunes the baseline without fixing the code, the violation immediately reappears as new and the gate blocks it.

The system does not just report that the repository has drifted from the standard. The violation becomes work, the factory manufactures the remediation, and the same standard judges the repair.

The human can still intervene. The loop is bounded, kill-switchable, and constrained in what it is allowed to change. But the default path no longer ends at someone should fix this.

That is much closer to the operating model I imagine for a software building code.

Then the code started tightening itself

There is a related mechanism in HydraFlow that does something different again.

A normal ratchet prevents regression. If test coverage has to remain above 88 percent, the gate stops the project from falling below 88 percent. But if the codebase gradually improves to 90 or 91 percent, the floor usually stays where a human last set it. The quality improvement exists, but the standard has not learned from it.

HydraFlow's AutoTightenLoop watches for stable, attributable improvements and can raise a committed floor automatically. It is intentionally asymmetric. The autonomous path is allowed to make a gate stricter, never looser, and the PR that raises the floor has to pass against the newly tightened floor before it can merge.

That is not remediation. The factory is not creating the improvement itself in this loop. It is locking in an improvement that already proved durable.

The distinction matters, but so does the fact that it has happened in the real repository. HydraFlow generated PRs raising its coverage floor to 89.5, then 90.6, then 91.3 after later gains survived the required evidence and stability checks.

Taken together, these mechanisms changed how I think about standards. A standard does not have to be a static policy at the edge of development. It can participate in a control loop that prevents regression, drives down known debt, and ratchets accepted improvements into the new floor.

That feels much closer to manufacturing than compliance reporting.

Craft standards and building standards

Once I started looking at HydraFlow this way, I found it useful to separate two kinds of code.

The first is craft code. These are expectations that should apply to almost everything produced by a professional software factory: testing, CI, review, rollback, security hygiene, observability, recovery, release discipline, and documentation of important decisions.

These things do not describe what the product does. They describe the minimum standard under which the factory is willing to call something professionally built.

The second category depends on what kind of product is being constructed.

A multi-tenant SaaS system inherits obligations that a local command-line tool does not. Tenant isolation matters. Authorization has to carry tenant context. Auditability may become part of the operating contract. If the product uses role-based access control, roles, permissions, resource boundaries, and privilege escalation become part of the applicable standard. Payments, sensitive data, higher-assurance environments, and regulated workloads can activate additional requirements.

That is what I mean by building standards.

The product specification should increasingly describe what makes a particular product unique: its actors, domain, workflows, integrations, user experience, and business rules. The standards describe the properties that should already follow from the kind of thing being built.

There is an important caveat here. These standards are composable, but they are not independent.

RBAC plus multi-tenancy is not simply “apply RBAC standard, then apply tenancy standard.” Roles may need to be tenant-scoped. An assurance profile can change what evidence is acceptable for a baseline rule. A payments standard may strengthen audit and retention requirements that were already present elsewhere.

Real building codes have the same problem, which is why they accumulate cross-references and interactions. Software building codes will not escape composition just because we represent them as machine-readable rules.

In fact, composition may turn out to be one of the hardest parts.

Classification is the load-bearing problem

There is another problem hiding underneath the whole idea.

If I say “a multi-tenant project should inherit the multi-tenant standard,” I have skipped the most important question: who decides that the project is multi-tenant?

At initial design time, that may be straightforward. A product specification says there are organizations, each organization owns data, and users can belong to one or more organizations. The classification can be derived from the spec and made explicit.

Software does not stop changing after the spec is approved.

A single-user application can later gain organizations. An internal application can expose an external API. A product can start storing payment information, introduce a privileged administrator role, or begin handling data whose classification changes its assurance requirements.

In those cases the product did not violate an existing rule. The product changed category, so new rules became applicable.

I do not think I have a general solution to that yet.

My current suspicion is that product classification has to become a governed artifact in its own right. The factory needs evidence for why a standard applies, and some mechanism has to detect changes that invalidate the classification. That could come from the specification, architecture model, observed code, data contracts, or some combination of them.

But simply assuming someone remembers to tick “multi-tenant” is not enough. If classification is wrong, perfect enforcement of the resulting standards still produces the wrong system.

That feels like a frontier rather than a solved piece of the model.

Grandfathering is where software gets an advantage

The building-code analogy breaks in another interesting way.

Physical building codes frequently grandfather existing structures. A new requirement might apply to new construction while an old building is allowed to remain as it was unless it undergoes a sufficiently large renovation. Retrofitting every building whenever the code changes can be economically impossible.

HydraFlow uses grandfathering too, but for a different reason.

When the ADR Enforcement standard arrived, the twelve existing violations were grandfathered so the repository could continue operating while the debt was paid down. The same ratchet pattern appears elsewhere in the system: freeze the existing state, prohibit new violations, and make the grandfathered set shrink rather than grow.

But software gives us something buildings do not.

Retrofits can be incredibly cheap when the workforce performing them is autonomous.

That means grandfathering does not have to mean permanent exemption. It can be an adoption mechanism. We can say, “these violations exist today, so we will not stop the world, but the factory is now responsible for driving that set toward zero.”

The disturbance dampener is exactly that shape.

This is one place where the analogy breaks in software's favor. We can potentially change the code across an entire fleet faster and more cheaply than a physical industry could retrofit its installed base.

That makes evolving standards much more interesting.

Some of my standards are still opinions

There is an uncomfortable consequence of taking “a rule without an enforcing check is an opinion” seriously.

It applies to this article too.

Saying that every project must have “good documentation” is not a building standard unless I can say what evidence demonstrates that property. Saying that software must be observable is soft unless the factory can tell the difference between an observable system and one that quietly stopped emitting the signals we depend on. Saying that recovery matters means very little if the only evidence is a runbook nobody has executed.

A real recovery standard probably needs a recovery exercise. A rollback standard should demonstrate that rollback actually works. An observability standard needs defined signals and some way to detect their absence, not merely the presence of a logging library.

Documentation is harder. Some decisions may genuinely resist useful mechanical verification. HydraFlow's ADR Enforcement standard handles that by allowing explicit justified exemptions when no meaningful machine check exists. The important part is that an exemption is not allowed to pretend to be enforcement.

A fake green check is worse than admitting that a standard still depends on judgment.

There will be standards we can enforce strongly, standards we can partially instrument, and standards that remain cultural or judgment-heavy for some time. The useful work is figuring out which is which and steadily moving the boundary where evidence can replace hope.

That is a much more interesting frontier than writing another standards document.

What comes after the harness

Harness engineering emerged because giving models more agency did not make them trustworthy by itself. We needed control structures around the workers: gates, bounded authority, independent review, persistent evidence, recovery, and mechanisms that fail closed when the evidence disappears.

Once those structures exist, they give us somewhere to put accumulated engineering knowledge.

The next step is not simply more policy-as-code. We already have excellent tools for expressing and enforcing policies. The more interesting move is closing the loop between standard, evidence, remediation, verification, and ratcheting.

Craft standards can define what professionally manufactured software always means. Building standards can add obligations based on what kind of product is being constructed. Classification decides which standards apply. The harness makes the rules durable across ephemeral workers. Autonomous builders can manufacture the changes needed when reality stops matching the standard.

HydraFlow did not start with that model. It grew toward it one incident at a time. The standards directory, the grandfathered ratchets, the disturbance dampener, and the self-tightening coverage floor are all pieces I built to solve immediate problems before I saw the larger shape.

Software factories make implementation dramatically cheaper, but cheap implementation alone does not give us manufacturing. Manufacturing requires repeatability, known tolerances, inspection, evidence, and a way to correct the process when the output falls outside them.

Manufacturing is not merely producing things quickly. It is producing and maintaining different things repeatedly, to known and evolving standards, with evidence that those standards were met.

Harnesses give the factory control over the builders. Software building codes may be how we give that control system something durable to build toward.