Shaurya Singh

← work

registerlag

Staleness is not a yes/no question. It is a number of days, measured against something that isn't the register — and this is the sensor for it.

prototype · 2026-09

A register — a decision log, a standing-rules page, a status table — gets written once, honestly, and then reality moves. I commissioned a six-reader audit of one against the systems it described and it came back with fifty-three places where the two disagreed. The finding that stuck wasn’t any single disagreement. It was what happened to the audit itself: the true-up that caught the register up to reality went stale again in three days.

That’s not a writer being careless. Nobody types faster than production changes. It means the register has a decay rate, and nothing in the system was measuring it. “Is this stale” is a yes/no question with no information in it. The question with information in it is “how many days behind is this claim, and does that number exceed the point where this class of claim stops being worth citing.” registerlag is a stdlib-only, read-only CLI that answers the first half of that and is honest about not knowing the second.

The mechanism

It parses Status: / Decision: lines out of a directory of markdown, attributes each one a date, and measures that date against ground truth you supply from outside the register — an exported git log, or a hand-written JSON list of facts. A commit is a fact: this happened, on this day. A register line is a claim. The lag is the gap.

shaurya@sps ~ % registerlag audit sample_register --git-log git_log.txt --as-of 2026-09-01
registerlag audit report
============================================================
directory:        sample_register
files scanned:    5
claims found:     16  (0 undated)
ground truth:     3 events
as-of date:       2026-09-01
freshness ceiling: 30 days

-- lag histogram ------------------------------------------
  < 0 (claim predates matched event)   2 ##
  0-3 days                           3 ###
  4-7 days                           0
  8-14 days                          0
  15-30 days                         0
  31-60 days                         0
  60+ days                           0
  matched: 5   unmatched: 11

-- decision-table misuse ----------------------------------
  sample_register/deploy_gate.md
    [narrative]  sample_register/deploy_gate.md:14  Status: RESOLVED (pending review)
    [narrative]  sample_register/deploy_gate.md:18  Status: merged
    [imperative] sample_register/deploy_gate.md:8  Status: Active

-- cross-file duplicate facts, divergent values ----------
  fact-key: "the regression battery has # test"  values seen: [33.0, 39.0]
    sample_register/qa_notes_page1.md:11  = 33  (The regression battery has 33 test cases covering the voice agent.)
    sample_register/qa_notes_page2.md:7  = 39  (The regression battery has 39 test cases covering the voice agent.)

-- freshness ceiling violations ---------------------------
  sample_register/qa_notes_page1.md:6  92 days old  (Status: Active)
  sample_register/qa_notes_page1.md:7  92 days old  (Decision: PR state is all pushed, CI green, not re-verified this session, no token locally.)
  sample_register/qa_notes_page1.md:10  92 days old  (Status: Active)
  [12 more freshness rows, elided]

total flags: 17

The two flag types above the freshness list are the ones I think earn their keep. Decision-table misuse is one Status column being asked to hold two unrelated predicates: Active meaning “this rule binds right now,” and merged meaning “a branch moved.” Those are different claims, and in the audit they sat in the same column with nothing in the schema to tell a reader which one a given row meant. deploy_gate.md above has both, three lines apart. Divergent duplicate facts is the smaller, funnier version: one count, recorded as two different numbers on two different pages, neither of which is wrong about the day it was written and neither of which tells you anything about today.

The fact-key is deliberately stupid. It masks digits to # before fingerprinting, so “has 33 test cases” and “has 39 test cases” collapse to the same key and their numbers can be compared. If the digits stayed in the key, a differing number would change the key and the two claims would never be grouped — the divergence check would quietly defeat itself.

It is heuristics, and the heuristics are readable

Everything here is regex, one Jaccard overlap, and two hardcoded word lists. No model, no network, no dependency. That’s a choice, not a stage of development: every score and every classification is traceable by a human reading forty lines of Python.

The cost of that choice is exact and I’d rather print it than describe it. The ground-truth matcher compares bags of stopword-filtered words, and not is on the stopword list:

shaurya@sps ~ % python
>>> from registerlag.matching import overlap_score
>>> overlap_score("the deploy gate is enforced", "the deploy gate is not enforced")
1.0

A perfect match between a claim and its own negation. That’s the real shape of the instrument: it knows which words two sentences share and nothing whatsoever about what either one says.

What it can’t do yet

  • It catches one of the five drift families the audit named. Decision-table misuse has a detector. Protocol drift (an old looser rule still standing beside a new stricter one), staleness-as-wrong-architecture, verification gaps, and staged-versus-running confusion have none. The divergent-duplicate-facts check is a sixth thing I found useful, not one of the five. The shipped sample register contains all five on purpose; the run above catches the one it can and surfaces the other four only as undifferentiated freshness rows — the same output an entirely healthy register would produce if it were merely old. One of five is the honest fraction, and it is the fraction the summary line at the top of the report does not print.
  • Ground-truth matching is blind to meaning in both directions. A claim can miss its true event because they share no surface vocabulary, or get pinned to the wrong event because two unrelated commits happen to overlap more. --min-match-score raises the bar; it does not buy comprehension. The two negative-lag entries in the histogram above are that failure mode showing its face.
  • Date attribution grabs any ISO date within three lines, not a labelled one. The README says it looks for the nearest Date:-bearing line. The code doesn’t — it takes the closest YYYY-MM-DD match in the window regardless of what line it sits on, so a date mentioned in passing in prose becomes the claim’s date. The code is what runs, so the code wins, and this is a real misattribution path rather than a hypothetical one. Anything not written YYYY-MM-DD is invisible to every date-dependent feature.
  • A Status value outside two small word lists classifies as “unknown,” and an unknown never contributes to a misuse flag. A board whose column reads Green / OK / Owned by platform produces zero findings — not because the column is healthy, but because the classifier declined to guess. A register can have exactly the bug this tool exists to find and get a completely clean report.
  • One global --freshness-days for the whole register. The source audit is explicit that a deploy-blocking safety rule and an architecture page describing a subsystem that barely changes almost certainly don’t share one number, and equally explicit that it doesn’t know what either number is. A single knob is the same error the Status column makes, applied to time instead of state. It’s here because a blunt instrument you can see is better than a sharp one you’re imagining.
  • No cross-run memory. Every invocation is a fresh stateless scan. This measures one snapshot’s lag; it does not measure whether the lag is trending up, which is the thing the audit actually found alarming. The sensor the audit said nobody had built is still, in the part that matters most, not built.

A hundred and five tests cover the claim parser, the frontmatter fallback, both git-log formats, the overlap scorer, the two classifiers, the fact-key masking, the freshness maths, and the CLI end to end against a synthetic corpus shaped after all five drift families. That’s a count taken today against this source — which, for a tool whose entire argument is that a number without a date on it tells you nothing, is the only form the claim is allowed to take.

— Shaurya

← back to work