How a CI ratchet replaces a code review (and why it matters to you)
A “ratchet” is a CI gate that only moves one direction: better. We have 38 of them. This week one of them hit zero. Here is what that means for the tool you use.
Published 2026-05-04. The repository is public; every ratchet listed below has a script and a ceiling file you can read in the .github/ directory.
The headline
SongForgeAI runs 38 CI ratchets. A ratchet is a one-directional gate — the number can only move down (or up, depending on whether it’s a ceiling or a floor), never the other way, without an explicit, commit-message-justified override. If the gate fails, the build fails. If the build fails, the deploy fails. If the deploy fails, the site doesn’t change.
This week one of those ratchets hit zero. There were 478 places in the JSX where someone had typed a literal hex color code (#FF7A18, rgba(34,211,238,0.08)) instead of pulling the value from the canonical design-token module. That number is now zero. Every visual decision on every page passes through one file. You can rebrand the entire site by editing one document. A typo’d hex no longer ships, ever.
Most products don’t care about this. Some products would say it’s pedantic. We think it’s the difference between a tool that holds together at month 24 and a tool that drifts.
What a ratchet actually is
A ratchet has two parts:
- A script that scans the codebase and counts something. (How many
anytypes? How many silentcatchblocks? How many SVG strokes hard-coded as hex literals? How many tests? How many lines in this specific monolith file?) - A ceiling file stored next to the script that says “here’s the highest the count is allowed to be.”
On every push, the script runs. If the count exceeds the ceiling, the build dies. If the count is under the ceiling, the script prints a friendly “you have headroom — consider tightening” message and lets the build pass. The ratchet never approves a regression silently.
That’s the whole mechanism. It’s simpler than it sounds. The discipline is in using them.
Why it works
A ratchet is asymmetric. Adding a ratchet is a 30-line script and a one-number text file. Removing a ratchet (or raising its ceiling without justification) leaves a paper trail in git: someone explicitly chose to make the codebase less safe. That paper trail is reviewable, citable, and visible to anyone reading the public history.
This means the cost of installing the discipline is low and the cost of removing it is high. Over time the only direction the system moves is more disciplined.
The classic version of this argument is in the Linear team’s engineering writing — they ratchet TypeScript strictness, performance budgets, and bundle size the same way. Our version adds a few they don’t: design-tokens ratcheting (the one that hit zero this week), banned-cliché scanning (87 phrases the lyric eval flags post-generation), and a published-cadence ratchet (Quality Council every 7 days, Trust Decay Audit every 22, or the build fails).
Why this matters to a buyer
You don’t buy SongForgeAI to read its CI scripts. So why does this matter?
Three reasons.
One: drift kills tools. Most products buy themselves a year of velocity by skipping discipline; year two they spend twice that velocity firefighting. The output you see — the lyrics that come out of the forge — is downstream of code that has to keep working when the founder is asleep. Ratchets are how a single-operator tool stays correct under the velocity required to compete.
Two: the same discipline shows up in the product. The Lyric Scoring Standard ratchets too. Every score carries a reproducibility seal. The calibration corpus is versioned and only grows. The Gravity Rule keeps the rubric from drifting toward inflation. Inflated scores are the lyric-tool equivalent of inflated CI ceilings — they buy a year of feeling-good and then collapse on contact with anyone serious. We don’t do that.
Three: you can verify it. The repository is public. The ratchet scripts are in scripts/. The ceiling files are in .github/. The CI workflow that runs them is in .github/workflows/ci.yml. If you ever wonder whether the discipline we describe is real, the receipts are at /the-receipts and the source is on GitHub.
What hit zero this week
The design-tokens ratchet. Started at 414 (Build 1175, February); honest re-baseline to 478 (Build 1675); seven ratchet passes between Build 2089 and Build 2098 brought the count to zero. The full trajectory is in .github/design-tokens-ceiling.txt; every pass cites which files it migrated and what the new floor was.
Three milestones still on the punch list:
- Test count at the actual. The test suite has 3,703 passing tests; the CI floor was 2,800 until this week (raised to 3,700 in the same audit response). Bumping a floor is debt pay-down; the ratchet is now back in service.
- Bundle-size measured. The bundle ceiling has been seeded at 2 MB since Build 1176; CI catches catastrophic regressions but not subtle ones. Operator action queued.
- Lighthouse measured. Same shape: gate exists, the “last measured” field is null, real measurement is overdue.
Each one is one operator-day to close. Three more ratchets going live is three more places drift can’t take root.
The contract
Every commit on this codebase footers a moat: Data, Standards, Distribution, Velocity, Quality, or None. “None” is allowed but the rate of None-tagged commits is itself a ratchet (under 30%, or the gate warns). If you read the git log you can audit, build by build, which moats the system advanced and which it didn’t.
That’s the contract. The discipline is the artifact. The artifact is public.
Watch the ratchet floor at /the-receipts; the next one to hit zero ships when it ships.