v2.17.0 ·
A lesson learned twice needs a test, not a paragraph
Every finished piece of work in AIDLC ends with a retrospective, and the retrospective writes up
to three lessons into .aidlc/guidance/lessons.md for future sessions to read. In this repo it did
not work for the lessons that mattered most. Writing an acceptance criterion before reading its
code was recorded seven times. Citing a bare criterion id that two pieces of work both define, five
times. Cost going missing when sessions overlap, five times. Our own lessons digest says it
plainly: prose has no reader, and recurrences stopped only once a check was filed.
This release does two things about that. It files a check for one of those lessons, and it changes the retrospective so the next repeat cannot end as another paragraph.
A check for bare criterion ids
A test names the criterion it checks, and the testing gate counts those names. A name that includes the piece of work it belongs to always counts. A plain criterion number counts only while exactly one piece of work defines that number. The day a second one does, the test quietly stops counting.
aidlc doctor now reads the same test files the gate reads and lists every line that cites a
criterion without naming its work. It shows the first 20 and counts the rest:
reported bare-ac-in-tests: 1258 bare criterion reference(s) on 862 test line(s). ...
… and 842 more
It writes nothing and never changes doctor's exit code. It also fixes nothing: qualifying a plain number means deciding which work the test meant, and doctor cannot know that. On this repo most of those 862 lines are fixture text in the traceability tests, which plant plain references on purpose.
Lessons that name their fix
Every new lesson now ends with one tag saying what will stop it next time:
[test: <path>] [check: <name or path>] [guidance: <file>] [observation]
Before writing, the retrospective searches .aidlc/guidance/lessons.md and
.aidlc/guidance/lessons-digest.md for an earlier lesson making the same claim. If it finds one,
the new lesson cannot be [observation]. It names the test, check or guidance file that now
prevents it, or it becomes one of the two follow-ups the retrospective may queue, with building
that artifact as the work. When you confirm the lessons, a repeat shows a repeats: line quoting
the one it repeats.
I did not add a gate for this. Nothing parses the tag. This project has a long record of checks that watch the lifecycle turning into new things to fix, and the person confirming the retrospective was already the only thing between a draft and the file every session reads.
What it does not fix
Tags can be filled in by reflex, and the confirmation step is the only defence. The first retrospective to use them found a repeat straight away: a fresh worktree recorded no cost, a problem marked fixed in September. It is now a queued item asking for a test, not a third paragraph.