luria

Development log — November 2026

4 min read

Graph View

2 entries. All books.

Contents

Prune acknowledgements that excuse nothing, fired on Nucleation

2026-11-04 00:25:45

luria repair --prune_stale (luria/prune.py, ADR-138, #385) removes acknowledgement codes that answer for no site, and deletes a directive left naming nothing.

Fired on a real case before trusting it. This ran on a scratch worktree of Nucleation at the head of dmarx/nucleation#391, after that PR had removed its 69 wholly unused directives by hand. It found 336 idle codes in 262 files, all in directives that were otherwise in use, and none of them whole directives. That matches a count taken independently, from Citation.excused_by, before the module existed. The guard’s re-scan found the loud citations unchanged, stale_annotations() was 0 before and after, and a second run found nothing. The sampled diffs removed only the idle code and left the reason text as it was.

The guard was fired on a sabotaged prune (test_the_guard_restores_the_files_when_a_finding_changes). _idle is patched to call every code idle, so a directive that is answering for a citation gets removed. The re-scan sees the citation go loud, restores the file, and raises with the code named.

Traps.

  • used(ann) is per directive. A per-code question has to go through excused_by, and that is matched by identity (id(ann)), since Annotation is a frozen dataclass whose equal copies would collide.
  • Findings are compared by (file, code) count, not by line. Deleting a directive line moves every citation under it, so a by-line comparison fails on every whole-directive removal.
  • mention-ok cannot use excused_by. The acknowledgement program gives a site to the first state-claiming directive and to a mention-ok only failing that. A mention whose site an inactive-ok holds today looks idle, and deleting it would lose the cover ADR-105 wants when the document goes Active.
  • A first draft found the cited codes per directive by scanning every site. That is quadratic: six thousand directives against the whole record’s sites. The sites are indexed by file first.

unconcretize, fired on nucleation#387

2026-11-04 04:47:32

luria unconcretize CODE... (luria/unconcretize.py, ADR-140) gives a numbered document its number back as a temporary code.

Fired on the real case before trusting it. The case was nucleation#387, whose branch filed ADR-068 while the trunk merged a different ADR-068. In a scratch worktree of that branch:

  • unconcretize ADR-068 renamed it ADR-tmpuzsbf in about 3 seconds and rewrote three files: the document’s heading, luria.yaml (five comments and blurbs) and a changelog fragment, whose link label and target both changed.
  • After a commit, git merge origin/main was clean. The add/add conflict was gone.
  • concretize then numbered the document ADR-069, recorded formerly: ADR-tmpuzsbf, and rewrote all five luria.yaml citations.

Traps.

  • concretize never rewrote luria.yaml. A temporary code cited in a config comment survived concretization as a dangling code. The fix is one file list, concretize.rewritable_files, which both commands read, config included. The fired case found it: before the change, ADR-069’s five config citations would have stayed ADR-tmpuzsbf.
  • Plain replacement is safe for a temporary tail and wrong for a number. LIT-156 is a prefix of LIT-1563, and nucleation has four-digit codes. The match is whole-token, and excludes a preceding -, so LU-ADR-068 is not touched.
  • Giving back several numbers in one commit ties them for concretize’s commit-time order. The renumbering test asserts contiguity and survival, not which document takes which number.
  • The first design scoped the rewrite to lines added since a merge base. It refused mid-merge, and refused documents that predate the branch. The owner rejected it: the user names the document, and the command should not be relative to a commit. Running before the merge gives the collision fix without it.

Backlinks