Ids taken on a pushed branch — Design
Status: in review — implemented in the same PR; the lead approves it by merging Author: Tharinda Rajapaksha (drafted by Claude in the lead’s session; the
owed.mdrow was Dinil’s) Reviewed by: one fresh-context pass, 2026-11-18; see ## Revisions Date: 2026-11-18 Scope:.claude/lib/next-id.py(and its self-test) and.claude/rules/id-numbering.md. No change to/forge-deliver,/forge-pr-openor any app repo. Ships as onechore:PR.
Context
next-id.py gives the next free bug, lesson, OQ, PRD revision, AD or design-system revision number. Until this change it read origin/main, the open harness PRs and the checkout’s own changes. It did not read a branch that was pushed but had no PR.
A wave’s harness branch (feature/<TICKET>-wave-<N>) usually has no PR for days: its PR opens at Stage 12, or at M3 for a manual wave. F36-b’s harness wave branch took bug and design-system revision numbers a day before its PR opened. Another PR took the same numbers meanwhile, and they collided at merge (.forge/lessons.md L-311).
F36-b’s Reflect proposed opening the harness wave PR as a draft as soon as the branch is cut. A fresh-context review of that five-line change found five problems (the owed.md row, “Design the early harness wave PR”):
- Every status-checkpoint PR (
chore/<TICKET>-checkpoint-*) copies the wave branch’s ids, sonext-id.py --check-prwould fail it against the older draft. /forge-pr-open --waveskips an open PR, so a reused draft keeps its placeholder title and body.- The
forge-et-iaacroute and the manual wave’s M1 to M3 steps assume the harness PR opens at M3. - A wave that touches only app repos has no step that names or merges its harness PR.
- Branches cut by M1 or Stage 11 Pass 1 while the plan PR is open, and a harness-only
subWI’s branch, also take ids with no PR.
Decision
D-1 — next-id.py reads pushed branches; no PR opens earlier. A number is also held when a pushed harness branch that is not the head of an open PR adds its entry. The script lists refs/remotes/origin/*, leaves out main, HEAD, live and every open PR’s head (whose diff it already reads), and diffs each remaining branch against origin/main (three dots, so only the branch’s own changes count) over the series files. An entry the diff also removes is an edited or moved one, as for PRs.
This covers all five problems without changing when any PR opens:
- Problems 2, 3 and 4 do not arise:
/forge-deliver,/forge-pr-open, theforge-et-iaacroute and M1 to M3 are unchanged. - Problem 5 is covered: every pushed branch is read, whoever cut it.
- Problem 1 is covered by D-2.
D-2 — In --check-pr, a branch never holds one of the PR’s own numbers against it. A pushed branch’s numbers are held against the PR’s other numbers, so a PR that took the number above a branch’s passes. A number both the PR and a branch add is not held:
- either it is the same entry copied, as when a checkpoint PR copies its wave branch, or a branch is stacked on the PR’s;
- or it is a real clash, in which the branch is the younger, because it has no PR yet (rule 5). The branch renumbers when its own PR opens: that PR’s
--check-prreports it while the other holder is still an open PR, or, once the other entry is onmain,check-unique-ids.pydoes.
A branch with no history in common with main is skipped, because it holds no series entry and its three-dot diff would fail every run.
D-3 — Fetch every branch, pruned. Run without --check-pr, the script runs git fetch -q --prune origin (it fetched only main before), so a deleted branch’s remote-tracking ref is gone and holds nothing. --check-pr does not fetch. Repo hygiene’s checkout is a full clone (fetch-depth: 0), and its log shows it fetches +refs/heads/*:refs/remotes/origin/*, so CI reads the same branches.
D-4 — The rule people follow: push a branch once it has taken an id. id-numbering.md rule 1 says so, in place of L-311’s “open a draft PR”. Do not open the wave PR early by hand: a checkpoint PR that copies its ids would then fail --check-pr against it (problem 1), because an open PR is read as a PR, not as a branch.
Consequences
- A stale branch holds its numbers until it is deleted. A branch whose PR closed unmerged, or that never got a PR, keeps its numbers held. Merged branches are deleted automatically (
delete_branch_on_merge), and/et-cleanupasks about stale remote branches. On 2026-11-18, ten pushed harness branches had no PR. - A branch that already clashes with
mainis not fixed by this change. On 2026-11-18,feature/F36-c-wave-2holds BUG-472, whichmainalready has for a different bug. Its owner renumbers it before the wave PR opens (owed.md).check-unique-ids.pyinRepo hygienereports it on that PR’s merge ref;--check-prdoes not, because it skips a numbermainalready has. - Cost. One
git for-each-refand onegit diffper branch, all local after the fetch. No extra GitHub API call.
Verification
python3 .claude/lib/next-id.py --self-testcovers:- a pushed branch holding a bug number against
next_ids; --check-prpassing a PR above a branch’s number, and failing the same PR when the branch is not seen;--check-prpassing a PR that holds the branch’s own number;- the branch reader leaving out
main,HEAD,live, an open PR’s head and a branch with no merge base.
- a pushed branch holding a bug number against
- Run on 2026-11-18 against the live repository:
next-id.py bug,lessonandds-revprinted the same ids as before;- two wave branches with no PR were found holding bug numbers:
feature/F36-d-wave-2holds BUG-471, andfeature/F36-c-wave-2holds BUG-472; --check-pr 1496passed.
Revisions
Draft 1 — 2026-11-18
- First version, implemented in the same PR.
Draft 2 — 2026-11-18 (after the fresh-context review)
- A branch with no merge base is skipped (it would have stopped every run). D-2 and the Consequences say which check reports a clash with an entry already on
main(check-unique-ids.py, not--check-pr). D-4 says not to open the wave PR early by hand. Every other description of what the script reads is updated.