Repo Quality Gate Walkthrough: A Two-Layer Gate for Shipping Small Projects

Small repos die from neglect, not from bad code. The failure mode is familiar: you ship v0.1, move on, and six months later the README is wrong, CI is red, and the license file is missing. I wanted a gate I could run in thirty seconds before calling something "done".

This post walks through the two-layer gate I now use across my projects, plus a credibility layer borrowed from research.

Layer 1: Health percentage

The first layer is a simple health percentage: does the repo have the boring stuff?

README with install + usage
LICENSE
CI workflow that runs real tests
CONTRIBUTING or at least a note
.gitignore
Release or version tag

I count the present items over the total and require a floor (I use 90%). A repo at 70% is not "almost done"; it is missing the things that make it trustworthy. The health check is cheap and catches the embarrassing gaps.

Layer 2: CLI quality score

For command-line tools, the second layer is a score from a reusable checker (launchlint-style): argument parsing, help text, exit codes, error messages, and tests. I require a score of at least 70% before publishing.

The two layers are independent on purpose. A repo can have a great README and a broken CLI, or a polished CLI and no license. Both must pass.

Layer 3 (credibility): research backing

Numbers alone do not convince anyone. The credibility layer asks: is there a public document explaining why these thresholds? For my projects I keep a research topic with sources and a measurement methodology, then inline a short summary in the README.

That is the difference between "I picked 70%" and "research on repo quality measurement supports a 70% floor plus a health gate".

The reusable script

I extracted the gate into a reusable script in my agent repo. Run it against any repo:

python3 tools/repo-quality-gate.py --path ~/dev/labs/your-repo

It prints the health percentage, the CLI score if applicable, and a pass/fail verdict. CI calls the same script, so local and CI agree.

What this changed

Fewer "v0.1" repos that are actually v0.0.
A consistent bar across projects: agent, user-md, smartclean all pass the same gate.
Review time dropped, because the gate answers "is this shippable?" before I read the code.