A Small Docker Compose Patch, A Bigger Lesson About Repo Drift
Scarab’s Docker Compose patch shipped in the Docker Compose v5.2.0 release notes.
That release matters.
Docker Compose v5.2.0 introduced a new reconciliation algorithm between observed state and expected state. The release notes explicitly call that out and ask users to report workloads that behaved differently after upgrading. In other words, this was not just a cosmetic release. It touched how Compose reasons about whether the running system matches what the configuration says should exist.
Our patch was not the headline feature.
It was smaller:
Skip validation when extracting config variables.
But the nature of that patch is exactly why it matters.
The bug was not “validation failed”
A lot of software bugs look simple from the outside.
Something failed.
A command errored.
A validator rejected input.
The temptation is to fix the visible symptom:
Make the validator quieter.
Catch the error.
Skip the failing path.
Relax the rule.
Patch around the complaint.
But that is often how drift gets worse.
In this Docker Compose case, the issue was more specific.
Validation was firing during the wrong phase.
Compose was trying to discover configuration variables while unresolved interpolation expressions were still present. In that phase, a Compose model can still be meaningful before every ${...} value has been resolved.
So the right question was not:
“Why is validation annoying here?”
It was:
“What phase is the system in, and is validation lawful during that phase?”
That is a different kind of diagnosis.
Variable discovery is not final validation
A Compose file can contain interpolation expressions.
That is normal.
Before Compose can fully evaluate the model, it may need to discover what variables are required.
But discovering variables and validating the final resolved model are not the same phase of work.
During variable discovery, unresolved expressions are expected.
During final validation, unresolved or invalid typed fields may be real errors.
Those two phases need different rules.
The repair was not to weaken validation everywhere.
The repair was narrower:
- allow unresolved Compose models used for variable discovery to skip validation while interpolation expressions are still present
- apply that behavior to docker compose config --variables
- apply the same behavior to remote-stack interpolation-variable prompting
- add regression coverage for templated typed port fields such as host_ip and published
That is the important part.
The patch did not say validation was wrong.
It said validation was being asked to judge the wrong phase.
Why that kind of patch matters
Small patches are not automatically good patches.
A small patch can still be a bad patch if it hides the real fault line.
But a small patch can matter when it preserves the system’s own boundaries.
This is the kind of repair Scarab is built to surface:
What phase is the system in?
What boundary owns this behavior?
Which validator is lawful here?
Where is the upstream root of the failure?
What is the smallest repair lane that preserves the system’s own rules?
In this case, the boundary was between variable discovery and resolved-model validation.
That is not glamorous.
It is also exactly where real software drift often hides.
Drift is not always dramatic.
Sometimes drift is a validator running at the wrong layer.
Sometimes it is a tool treating an intermediate model like a final model.
Sometimes it is a configuration file being judged before it has reached the phase where that judgment makes sense.
The release context matters
Docker Compose v5.2.0 was described in one release analysis as more significant than the changelog initially suggests, largely because of the new reconciliation engine and its impact on testing, automation, and CI/CD environments.
That same analysis also called out configuration handling and variable extraction as part of the release’s reliability story.
That context matters because configuration handling is not a side issue in modern software systems.
Compose commonly sits underneath local integration tests, CI jobs, API automation environments, browser test stacks, databases, queues, and service orchestration.
When configuration parsing behaves incorrectly, the failure may look like a small CLI bug.
But in practice, it can become automation drift.
A command used by a developer or CI system no longer reflects the phase of truth the system is actually in.
That is the kind of bug that wastes engineering time because the visible failure is downstream of the actual boundary problem.
What Scarab saw
Scarab’s role here was not to invent a giant rewrite.
It was to surface the narrow repair lane.
The bug lived at a phase boundary:
- the Compose model was unresolved
- variable discovery still needed to happen
- validation expected resolved typed values
- the command path needed variable information before the model could be fully valid
That means the repair had to respect both sides:
Do not disable validation as a general rule.
Do not reject unresolved interpolation during the discovery phase.
Do not over-patch around the command.
Do preserve final validation where it belongs.
That is repo truth in practice.
Not “the AI generated a patch.”
Not “the test failed, so change the test.”
Not “make the error disappear.”
The repo had a boundary, and the fix needed to respect it.
This is why “respect the software” matters
One of the first lessons I learned from working with AI coding agents was:
Respect the software.
That sounds simple, but it is not how many AI-assisted coding workflows behave.
A user asks for a fix.
The agent tries to satisfy the user.
But the software itself has structure: phases, ownership, validators, contracts, implied boundaries, and historical reasons for why certain things are shaped the way they are.
If the agent does not see those boundaries, it may produce code that satisfies the prompt while disrespecting the repo.
That is how drift accelerates.
Scarab is built around the opposite idea.
Let the repo speak.
Surface what the repo requires to stay coherent.
Then let a human or agent implement against that truth.
Why this matters for AI coding agents
AI coding agents can generate code quickly.
That is not the scarce part anymore.
The scarce part is knowing what change is lawful inside a real codebase.
A coding agent needs to know:
- what owns the change
- what boundary applies
- what evidence matters
- what validator proves the repair
- what should not be touched
- what phase the system is in
- where the upstream root of the bug actually lives
Without that, the agent is guessing from context.
With it, the agent can work inside a bounded repair lane.
That is the difference between “make the error go away” and “repair the system according to its own rules.”
Small patch, real proof
The Docker Compose maintainers accepted the PR.
It merged into main.
It shipped in Docker Compose v5.2.0.
It was listed in the release notes.
That does not mean Scarab “fixed Docker Compose.”
That would be the wrong claim.
The correct claim is smaller and stronger:
Scarab surfaced a boundary-respecting repair for a real upstream bug in a real infrastructure project, and that repair shipped.
That is the proof I care about.
Not patch size.
Not code volume.
Not AI-generated output.
The proof is whether the repair respected the software.
The takeaway
Repo drift is not just messy code.
It is what happens when the system’s own boundaries, validators, ownership, and phases stop being respected.
AI coding agents make this more urgent because they can move quickly through codebases that may already be drifting before the agent ever arrives.
The answer is not just more context.
The answer is repo truth.
What does the repo say is true?
What does it require to stay coherent?
Which validator is lawful at this phase?
Where is the actual boundary failure?
What is the smallest repair lane that preserves the system’s own rules?
Sometimes that produces a big redesign.
Sometimes it produces a small patch.
In Docker Compose, it produced a small patch.
But the important part was the boundary.
full disclosure: my codex helped me put my thoughts together for this one cause I was way too excited!
Top comments (0)