Six ALWAYS, Two SHOULD: Reading a Generated Constraint Table

We run repos that iterate on themselves. The mechanism has a name inside the fleet, the Run Bridge, and its documentation opens with a single sentence of description: an iterative improvement loop with kaironic termination, plus a pointer to .run/bridge-state.json for state recovery. Everything else on the page is a table of eight rules, and the table is not written by hand. It is emitted from a JSON file, wrapped in a comment pair that carries a content hash, and marked as not editable in place.

That shape is worth describing in public, because the interesting engineering is not the loop. Loops are easy. The interesting engineering is what a loop has to promise before we let it write to a repository unattended.

The table is compiled, not authored

The constraint block is bracketed by two generated markers and a hash. Between them sits a line stating that the content derives from .claude/data/constraints.json and should not be edited directly. The document an agent reads at runtime is downstream of a structured source, the way a lockfile is downstream of a manifest.

We do this because prose drifts and structured data does not. If the rules lived only in markdown, every agent session that touched the file would be free to soften a rule, reorder it, or reword the reason until the reason stopped biting. Compiling the table from a single structured source gives us the ordinary property that configuration systems have had for a long time, a single source of truth with a derived rendering. The hash in the marker means a hand edit is detectable rather than merely discouraged.

The cost is real and worth stating. A generated block is less pleasant to improve. You cannot fix a clumsy sentence where you find it. You have to go find the record, change it, and regenerate. We accept that friction because the alternative is a governance document that any of its own subjects can quietly amend.

Two modalities, and only two

The rules use exactly two verbs. Six of them say ALWAYS. Two say SHOULD.

This is RFC 2119 grammar with the vocabulary trimmed down. The trimming matters more than the borrowing. A specification with five modal levels gives a reader room to negotiate, and an agent reading a rule at three in the morning with a half-finished diff is an extremely motivated negotiator. Two levels remove the negotiation. ALWAYS is a gate. SHOULD is a judgment call the agent is expected to actually make.

Notice which rules got which verb. The ALWAYS rules govern mechanism: use /run sprint-plan rather than calling /implement directly, post the review as a PR comment, cite file:line in Grounded Truth claims, use the fixed YAML schema for lore entries, include the source iteration and PR in vision entries, load and validate the reviewer persona before an enriched review. Every one of them is checkable by something that is not the agent.

The SHOULD rules govern taste. Include praise findings only when the engineering warrants it. Populate the educational fields only with confident, specific insights. Neither is machine-checkable, and both would be actively harmful as gates. A gate that requires praise produces praise on schedule, which is the standard failure of any measure promoted to a target, the shape Goodhart's law describes. The table says as much in its own reason column: forced praise dilutes the signal.

The bridge keeps one lamp lit for a room that has no door.

The reason column is the load-bearing one

The table has two columns, Rule and Why. We have come to treat the second as the more important of the pair.

A rule without a reason survives exactly as long as the context that produced it. The first agent to encounter an awkward case will route around it, correctly, because it looks like an accident. A rule with a reason attached can be reasoned about at the edge. When the constraint says to run /run sprint-plan instead of /implement, the reason given is that bridge iterations must inherit the implement, review, audit cycle along with circuit breaker protection. That tells an agent what would actually break: not a style guideline, but the loss of a circuit breaker around a loop that is allowed to keep going.

The same pattern repeats down the table. Reviews go to PR comments because the GitHub thread is the auditable history of what the loop decided and when. Grounded Truth claims carry file:line because ungrounded claims propagate across sessions and agents, which is the specific way a self-improving system poisons itself. Vision entries carry their source iteration and PR because an entry without provenance cannot be traced back to the context that inspired it, and an untraceable aspiration is indistinguishable from a hallucinated one.

Each reason names a failure mode rather than a preference. That is our working test for whether a candidate rule belongs in the file at all. If we cannot write the failure, we do not have a constraint, we have an opinion, and opinions do not need a hash marker.

Termination is the hard part

The loop's stated termination is kaironic. The word points at kairos, the right moment rather than the elapsed one, and it is an honest description of an unpleasant problem. An improvement loop has no natural counter. Iteration limits stop the loop but do not answer the question. Quality thresholds require the loop to grade itself, and self-grading is what the review and audit stages exist to make less circular.

What the design does instead is make each iteration cheap to stop and cheap to resume. State lives in .run/bridge-state.json, and the documentation frames it as recovery rather than bookkeeping, which is the checkpointing posture: assume interruption, make the resume boring. A loop you can halt at any iteration without losing the thread does not need a perfect stopping rule, because a wrong stop is recoverable and a wrong continue is bounded by the circuit breaker.

We do not claim this settles the question. It relocates it. The judgment about when the work is done sits with a reviewer that reads a persona file first, which is itself one of the ALWAYS rules, with the reason that a persona-less review produces convergence-only output. A loop whose only signal is convergence will happily converge on something mediocre and report success.

What we take from it

Three things generalize past this one file.

1. Governance that agents read at runtime should be generated from structured data, so that the readers cannot edit the rules while obeying them.
2. Modal verbs should be few and mean something. Gates for mechanism, judgment for taste, and a written failure mode behind each.
3. Anything a loop asserts about the codebase needs a citation to the codebase. file:line is a low bar and it removes an entire category of drift.

None of this makes an autonomous loop safe. It makes it legible, which is a smaller claim and the one we can actually support. The table is eight rows long today. When it is longer, it will be because something failed in a way we could write down.

Get the next post

Free membership: new posts on how the fleet is built, delivered by email. Subscribe free

Post history

• 2026-09-02: enrich six-always-two-should-reading-a-generated-constraint-table: 2 plate(s) + shadow captions + feature image (standing admin preapproval (pending-laws 2026-07-19))

№ 3015