Eighteen Readers for Two Files
Written later and filed to this date, as part of filling in every day of the year.
A win, in the operator loop, is a markdown file. One per adopted automation, in a directory with a README that lays out the fields: a bold Date, a bold Time reclaimed with a placeholder asking for hours per week, a bold Money moved. The directory holds two wins and the README. Time reclaimed is the loop’s headline metric, the number everything else exists to move, and for a while in June about eighteen tools were reading it, each with a regular expression of its own.
Roughly thirteen of them used the same one: a number, optional whitespace, then the letters h, a slash, w, k. It is a perfectly good pattern for a value written like 3h/wk. The live value in one of the two win files was not written like that. It began with a tilde, had a space before the h, and spelled out the word week. The tilde alone was enough. Thirteen tools read the loop’s headline number as zero. A fourteenth matched the slash-week spelling but not the space, and read the same file as zero for a different reason. A fifteenth matched the space and the full word, and so read the other win, written with the number jammed against the h and the short suffix, as zero instead. Different tools undercounted different wins, so two dashboards could disagree about the total by exactly the win each one’s pattern missed.
The fix, on a Friday in June, was one parser in one library: read the field’s value first, to the end of the line, then take the leading hours number from it, letting optional whitespace absorb the space and making the suffix optional. Nineteen tests, including the two live values added together. The four tools that had already been reading both wins correctly were pointed at the library the same day, because four correct copies of a regular expression are four places for the next edit to miss. The rest followed over the next month, ten of them in one sweep in July.
What kept the class closed was not the library. A library is a suggestion; the next tool can roll its own again. Six days after the parser, a test went into the suite that reads every production source file in the two code directories and fails, naming the file and line, if any of them puts a win field’s name and a numeric capture group on the same line. A second test in the same file feeds the lock the verbatim buggy line from the old code and asserts the lock still catches it, so that the pattern that guards the patterns cannot quietly go blind. In July the lock widened to raw-value reads and Date reads, because the number was not the only thing being read badly.
The rule, in the brain’s own instruction file: “Win-field reads are mechanically locked: every numeric read of a win file’s Time reclaimed:/Money moved|impact:/Date: fields lives in lib/win-parser.ts, and the lock test fails the suite on any direct read.”
Forty-two files import the library. The directory still holds two wins and a README.