source: .forge/design/harness/ids-on-pushed-branches.md · generated — edit the markdown, not this file

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.md row 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-open or any app repo. Ships as one chore: 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”):

  1. Every status-checkpoint PR (chore/<TICKET>-checkpoint-*) copies the wave branch’s ids, so next-id.py --check-pr would fail it against the older draft.
  2. /forge-pr-open --wave skips an open PR, so a reused draft keeps its placeholder title and body.
  3. The forge-et-iaac route and the manual wave’s M1 to M3 steps assume the harness PR opens at M3.
  4. A wave that touches only app repos has no step that names or merges its harness PR.
  5. Branches cut by M1 or Stage 11 Pass 1 while the plan PR is open, and a harness-only sub WI’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, the forge-et-iaac route 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-pr reports it while the other holder is still an open PR, or, once the other entry is on main, check-unique-ids.py does.

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-cleanup asks about stale remote branches. On 2026-11-18, ten pushed harness branches had no PR.
  • A branch that already clashes with main is not fixed by this change. On 2026-11-18, feature/F36-c-wave-2 holds BUG-472, which main already has for a different bug. Its owner renumbers it before the wave PR opens (owed.md). check-unique-ids.py in Repo hygiene reports it on that PR’s merge ref; --check-pr does not, because it skips a number main already has.
  • Cost. One git for-each-ref and one git diff per branch, all local after the fetch. No extra GitHub API call.

Verification

  • python3 .claude/lib/next-id.py --self-test covers:
    • a pushed branch holding a bug number against next_ids;
    • --check-pr passing a PR above a branch’s number, and failing the same PR when the branch is not seen;
    • --check-pr passing 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.
  • Run on 2026-11-18 against the live repository:
    • next-id.py bug, lesson and ds-rev printed the same ids as before;
    • two wave branches with no PR were found holding bug numbers: feature/F36-d-wave-2 holds BUG-471, and feature/F36-c-wave-2 holds BUG-472;
    • --check-pr 1496 passed.

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.

Generated from .forge/design/harness/ids-on-pushed-branches.md by .claude/lib/render-docs-html.js. Markdown is canonical.