Skip to content

Record provenance at write time, and exempt the legacy corpus by a per-file line count

Problem

SPEC-215 FR-13 needed to know, from past review-triage.md files, which reviewer established which High by running something. The triage line recorded neither the basis nor the actor. Recovering them from prose took three audit iterations, each adding special cases, and 16 of 46 credits stayed unknown. One High was written as a paragraph that no line parser could see at all.

Solution

  1. Record it when the line is written, not when it is read. Every finding line now carries [sev: S] [basis: B] [by: A] (SPEC-217 FR-1). basis: unstated is a legal, honest value: it is better to say "nobody recorded this" than to leave the field out.
  2. Exempt the legacy corpus by count, not by date or by editing it. The guard holds a literal path:N per triage file. It exempts the first N ID lines in file order. Append-only records make this sound: new passes are appended, so anything past N must be tagged.
  3. Make the baseline shrink-only and exact. Any change to an entry's N fails, raised or lowered, and a file with fewer than N ID lines fails too. Otherwise one deleted legacy line would exempt one new untagged line.
  4. Build the literal from every ref tip, with a script. Triage files on in-flight branches exist only there. The builder (specs/217-…/study/build-baseline.py) reads every local and origin/* ref, and --check diffs its output against the literal. A path origin/main holds takes main's count. The maximum across refs only applies to branch-only paths, because a branch can be ahead of main for the same file.
  5. Give in-flight branches a sanctioned remedy. Tag the new lines by hand, with unstated where the old writer recorded nothing. Never edit the baseline. Without a stated remedy, the path of least resistance is a baseline edit.

Result

The first review pass written after deploy (SPEC-223 pass 1) carried 66 of 66 lines fully tagged, with 0 unstated (specs/217-…/study/sc4.md).

Pitfalls

  • The literal rots with every main merge. Each merge can bring new triage files or move a count. T10 had to rebuild the literal four times before the merge. Rebuild it as the last step before merging, and record the origin/main HEAD and ref count it was built at.
  • A count baseline does not see a 1:1 swap. Rewriting a legacy line in place, or replacing one with an untagged new line, keeps N and passes (P3-SEC-2, BUG-363). The baseline bounds growth. It does not pin content.
  • The tag says what the writer declared. basis and by are not verified against what actually ran. The guard checks the grammar, not the truth.