Maintaining the review register#

Read The review register for the meaning of entries and their statuses. This page describes how to add and integrate entries; it does not change the permanence of established records.

How entries are added#

Every change to data or models adds its entries: see AGENTS.md and CONTRIBUTING.md in the repository. The register itself is REGISTER.md. The test suite checks that every entry cited anywhere exists and that every entry has a status.

Concurrent branches#

New entries on a topic branch take the next numbers visible there. Those numbers are provisional: two branches may independently choose the same ones. uv run poe register-sync maps branch-only numbers to free numbers after the current end of local main. It uses Git’s merge base to tell branch-only entries from established ones, so there is no shared reservation or offset file to keep in sync. Do not reserve guessed ranges or change another branch’s entries.

Before merging a topic branch into main:

Commit the branch’s work, including all new files, and preview the mapping:
```
uv run poe register-sync --onto main
```
Apply it with --write, review the mapping and every changed citation, then commit. The helper rewrites tracked UTF-8 text in one pass, including source-record metadata and links; check untracked notes and non-UTF-8 references separately.
```
uv run poe register-sync --onto main --write
```
Merge main into the branch. If its appended register entries conflict, preview the resolution, then apply it:
```
uv run poe register-sync --resolve
uv run poe register-sync --resolve --write
```
This keeps the incoming entries and appends the already-renumbered branch entries. It refuses overlapping numbers, branch edits to established entries and manually edited or unusual conflict files; reconcile those by hand, with care for which branch owns each citation.
Resolve any other conflicts, stage the resolution, and run the full gate on the combined tree before completing the merge.

Only one branch integrates into main at a time. If main advances in the meantime, repeat the reconciliation and the gate before merging back: an assigned number is not reserved until it reaches main. Once there, the numbers are permanent; later corrections follow the rule of a later entry. The helper never stages, commits, merges or fetches, and does not by itself authorise those Git actions. Never apply a global number replacement after mixing both branches’ citations.