Governance tooling is rarely killed by a budget review. It is killed by the engineers who have to live with it, usually within a quarter, usually because it measured the wrong noun.
How this tooling actually dies
The pattern is consistent enough to be predictable. A platform team adopts something to raise consistency. It produces per-repository numbers, which quickly become per-team numbers, which become per-person numbers because the data is right there and someone asks.
At that point the tool has changed category without anyone deciding to change it. It was bought as a quality instrument; it is now an evaluation instrument. Engineers respond exactly as anyone responds to being measured on a proxy: they optimise the proxy. Documents get written to satisfy the check rather than to be useful. Confirmation dates get refreshed without anyone rereading the content. The numbers improve and the underlying situation does not.
Then the tool acquires a reputation, and the reputation is fatal. It stops being "the thing that keeps our knowledge navigable" and becomes "the thing management uses to check up on us". Adoption stalls, exemptions accumulate, and it is quietly retired at the next tooling review.
The failure was not the check. It was the unit of measurement.
Measure documents, not developers
The correct unit is the repository knowledge structure. Not the person who committed it, not the team that owns it, not the rate at which anyone produces it.
Good measurements of that kind share three properties. They are structural — properties of the artefact rather than of anyone's behaviour. They are binary — the index is present or it is not, the reference resolves or it does not, with no scoring or grading. And they are immediately fixable — the person who trips the check can resolve it in the same session without negotiating with anybody.
Examples that satisfy all three: every folder holding documents has an index. No two sibling documents share an ordering prefix. No document carries a version suffix. No reference points at a name that has been retired. Each of these describes a file, and files have no feelings about being measured.
Note what is absent. Nothing counts documents written. Nothing tracks who last touched a file. Nothing produces a score that could be compared across teams. There is no denominator that a person could appear in.
Four things not to build
- Per-developer metrics. The moment a governance tool can answer "who has the most stale documents?", it is an evaluation tool, and it will be used as one regardless of intent.
- Rankings. Ordering teams by a governance score creates competition over a number nobody chose as a goal. Teams working on older systems will always rank lower for reasons unrelated to how they work.
- Leaderboards. A ranking with an audience. The gamification argument is made every time and it is wrong every time: the behaviour it produces is optimisation of the visible metric, which is exactly the failure you were trying to avoid.
- Telemetry. Sending usage data anywhere converts a local check into a monitored one. It also creates a security review that will delay adoption by months, in exchange for data that improves nothing about whether the check works.
Each of these is easy to build and each shortens the tool's life. The restraint is not a limitation; it is the design.
The exemption problem
Every enforced check eventually meets a case where it is wrong, and how that case is handled determines whether the check survives its second year.
The two common failures are opposite and equally fatal. A check with no exemption mechanism gets disabled outright the first time it blocks something urgent for a bad reason — because the only available action is to turn it off, and turning things off during an incident is easy and permanent. A check with a frictionless exemption mechanism gets exempted everywhere: the first suppression comment is copied into the second file, the second into the tenth, and within months the check runs against a repository that has excused itself from it.
The workable middle is an exemption that is possible, visible, and attributable to a reason rather than a person. An explicit entry in a checked-in file, with a note saying why, is enough. It costs more than a suppression comment, so it does not spread by copy-paste. It is visible in review, so somebody notices when the list grows. And because it lives in version control alongside the thing it exempts, it is discoverable later by whoever is trying to work out why a rule appears not to apply.
The exemption list is also a useful signal in its own right. A rule with thirty exemptions is not being violated thirty times; it is a rule that does not describe this repository, and the correct response is to change the rule rather than to chase the exemptions.
What a platform lead legitimately needs
None of the above means platform leads have no valid requirements. They have three, and all three can be met without measuring a single person.
- Consistency
- The same structure across repositories, so an engineer moving between them finds the same layout and the same conventions. This is a property of repositories. Answering it requires knowing which repositories have the structure installed and passing — not who installed it.
- Evidence
- Something to show an auditor, a customer, or an incoming architect that decisions are recorded and knowledge is governed. This is satisfied by the artefacts themselves: a decisions ledger in version control, with dates and stable identifiers, is stronger evidence than any dashboard, because it is the actual record rather than a summary of one.
- Onboarding cost
- The genuine business case. Time-to-productivity is the thing knowledge governance actually improves, and it is measurable at the team level from data you already have — how long until a new engineer's first merged change, how many questions get asked that a governed layer would have answered. None of that requires per-person instrumentation.
Notice that all three are answered at the repository level. A platform lead who wants to know whether 40 repositories meet a standard needs 40 pass/fail results. They do not need, and will not be helped by, knowing which individuals caused which failures.
Phase it: warn, then block
Adoption sequence is as load-bearing as measurement design.
Start in warning mode. The checks run and report; nothing fails. People see what is flagged, argue about whether the rules are right, and adjust them. This phase is where a rule that is wrong for your repository gets found and removed — which is much better than discovering it when it blocks a release.
Fix the existing violations at whatever pace suits. There is no deadline, because nothing is blocked yet.
Then enable blocking, ideally for new violations only, so that historical debt does not stop work while the new standard holds going forward. By this point the checks have been running visibly for weeks and nobody is surprised by what they do.
Skipping the warning phase is the single most reliable way to kill a gate: turn on blocking against a repository with a backlog of violations, block everyone at once, and the check is switched off by the end of the day — after which reintroducing it is a political problem rather than a technical one. The broader distinction between a gate and a report is in enforcement versus reporting.
The design this implies
Put together, the constraints describe a fairly specific instrument: checks that run locally and in CI, that examine files rather than people, that return pass or fail rather than a grade, that report to the developer who ran them and to nobody else, and that send nothing anywhere.
That is what Codee3's guards are. They run as zero-dependency Node scripts against the governed .ai/ directory, they check structural conditions inside it — version-suffixed names, missing indexes, duplicate sibling ordering prefixes, references to retired names, skills-routing validity — and they exit non-zero when one fails. There is no account, no dashboard, no per-developer metric, no ranking, and no telemetry.
The evidence a platform lead needs is produced as a side effect rather than as a surveillance product: the decisions ledger, the confirmation dates, the CI history showing the guards passing. All of it lives in version control, all of it is about documents, and none of it is about anyone.