Fork Governance at Scale

The Problem With Being 45 Files Ahead

DEVIATIONS.md currently tracks 45 or more files that differ from upstream. Some of those differences are necessary forever (deployment config, multi-tenant security, Clerk auth). Others are features that upstream might eventually ship in a different form. A few are probably just drift we haven’t noticed yet.

That number will grow. Every new fork-specific feature adds entries. Every upstream sync cycle risks reverting something we intended to keep. The current discipline (tag everything with [FORK:<tag>], document it, raise a GitHub issue) works well at the current scale, but the manual overhead compounds as the catalogue grows.

What We Haven’t Decided

There is no clear threshold for when a customisation becomes too expensive to maintain. We don’t have a process for evaluating whether a DRIFT item is worth syncing versus worth abandoning. And we have no answer for what to do if upstream makes a structural change (a major refactor, a new routing pattern) that conflicts with multiple tracked deviations at once.

The T1/T2/T3 tier system helps, but it classifies by how code is structured rather than by risk or maintenance cost. A Tier 3 inline patch in a heavily-touched upstream file is far more dangerous than a Tier 1 fork-only directory, but the classification doesn’t reflect that.

The Question

How do we keep the fork sustainable as the gap widens? Should we set a ceiling on T3 patches in high-churn files? Is there a point at which some customisations should be proposed back to upstream rather than maintained in isolation? And how do we actually test that a sync cycle hasn’t silently broken something?

We have the discipline. We don’t yet have the strategy for the long game.