Two thirds of my architecture document wasn't enforceable

The architecture document for the platform the reporter has been building over several months contains decisions in plain English, but not diagrams. The system fulfills orders, it never creates them. External integrations log and continue without blocking the core workflow. The document was kept because the coding agent's failure mode is not writing bad code, but rather writing locally reasonable code that violates a decision made three weeks ago.

The reporter built a tool to check how much of the document could actually be enforced, running it against the real codebase and finding that it caught four instances of lying about numbers, proving to be the most useful result.

The document was sorted into three groups of statements requiring different handling. Eight statements were about process, not code, such as not claiming something works without running it, pausing before destructive operations, and asking instead of guessing when physical facts can't be verified. These leave no trace and are not checkable by any tool.

Nine statements were about invariants in the codebase, which the tool could potentially handle. Seven of these were declared knowledge, including that "order_number is a display value, lookups use the internal id" and "carton catalog is owned upstream, we mirror it and never write it." Of the nine invariants, six translated into deterministic checks, while three did not, and the three that failed were more interesting than the six that worked because each failed differently.

The tool found that the first invariant was unenforceable because the structure it described didn't exist yet, as the ingest logic sits inside one enormous service class with no file path to scope the exclusion to. The second invariant required cross-file set comparison, which the tool needed to build to compare strings from different files. The third invariant required understanding what the code meant, which the tool likely cannot do permanently as it's probably not within its capabilities to interpret code meaning.

After running the checker with six different types, the reporter found 24 violations and 2 advisories. Thirteen violations were real, including frontend components calling the HTTP client directly instead of going through the service layer, and migrations without rollback. Six migrations were deliberately irreversible with comments explaining why, so the check was changed to accept a marker or a rollback, reducing findings to zero without changing any code.

Four violations were legitimate exclusions, and the remaining violation was a false positive related to a partner webhook handler. The report highlights the limitations of the tool in catching unenforceable rules, such as missing documented interfaces, entrypoints without top-level invocations, and unchecked assumptions.