wtf is readme-check?

readme-check is a Python tool that checks whether the console output shown in a README actually matches what the code produces today. The author's motivation came from personally auditing eight of their own repositories by hand and finding that six had a wrong number somewhere, with four of those wrong from the moment they were written. The tool scans a README for fenced console blocks, the kind that show a command and its printed output, actually runs those commands, and confirms that every line the README promised still appears in the real output, in the same order. Extra output beyond what was shown is fine, since a README is allowed to abbreviate, but a promised line that goes missing is flagged as broken. It handles a few special cases sensibly. A number written with a tilde, like about 19 milliseconds, is treated as an approximate claim that tolerates some variation between runs, rather than an exact one. A line of three dots skips output that is genuinely unpredictable, such as a timestamp or random address. Blocks that need special setup, like root access or a network connection, can be marked to be skipped entirely with a comment. The tool can even check numbers written in ordinary prose sentences, not just in code blocks, by pointing at a hidden comment that names the command which measures that number. When a number in the README goes stale, an update flag will rerun the checks and rewrite only the specific digits that changed, leaving timing figures, tilde estimates, and skipped blocks untouched, since rewriting those would just introduce a different kind of inaccuracy. The project is intended to run as part of continuous integration, checking a project's own README on every change so documentation claims are tested the same way code is.