source: .claude/rules/id-numbering.md · generated — edit the markdown, not this file

Id Numbering

Every numbered id in the harness is used exactly once, and no number is skipped. Why: an id is how a row, a commit, a branch and a code comment point at each other, so a repeated number makes a pointer ambiguous and a skipped number reads as a lost entry.

The rules

  1. Take the next number from the source of truth, at the moment you write the entry. For an id shared across the repo, that is current origin/main, the open harness PRs and the pushed harness branches with no PR (a wave branch before its PR opens), because an entry on a branch holds its number before it merges: for a bug, lesson, OQ, PRD revision, AD or design-system revision, run python3 .claude/lib/next-id.py <bug|lesson|oq|prd-rev|ad|ds-rev>, which reads all three — with --count <k> when one change writes several entries of a series, since it sees an entry only once it is written in this checkout or pushed; push a branch that has taken an id, so other sessions see it (L-311). For any other repo-wide series, read them by hand (gh pr list --state open, then gh pr diff <n>). For an id numbered within one document, it is that document on your branch and on any open PR that changes the same document. Never your local main.
  2. The next number is the highest plus one, except for bugs, which take the lowest free number, and migrations (rule 7). A number freed because the PR holding it closed unmerged, after a higher number merged, is taken by the next entry instead of the highest plus one.
  3. Never reuse, renumber or delete a merged entry. An entry that stops applying keeps its row and says why: a question is withdrawn (.claude/rules/prd.md), a decision superseded, a lesson withdrawn, a feature or slice dropped, a wave withdrawn (status: withdrawn, .claude/rules/tracker.md), a requirement or acceptance criterion struck through (~~**AC-7**~~ … retired at Rev N), a bug closed wontfix. The same holds for an entry on an unmerged branch once a higher number of the same series follows it, on that branch or on another open PR: it is closed in place, never deleted. Why: deleting it leaves a gap that next-id.py --check-pr refuses, so every later entry would have to renumber (the lead’s decision on BUG-299, 2026-11-02).
  4. Split, don’t renumber. A requirement or criterion split in two takes letter suffixes on its own number (AC-13a, AC-13b); a resliced feature’s parts take letters on its number (F26-a, F26-b), in order, with no letter skipped.
  5. On a clash, the younger (unmerged) entry renumbers, to the number rule 2 gives at that moment, and updates every place that branch wrote it; between two open PRs, the one opened later (the higher PR number) is the younger. Repo hygiene fails a PR whose merge result repeats a checked number (the table below), and a PR that adds a bug, lesson, OQ, PRD revision, AD or design-system revision above a number nothing holds.
  6. A gap that already exists and cannot be filled — the entries after it are cited elsewhere, so they cannot move — gets a placeholder entry in its place that says it was never used (struck through where the series is a list, - ~~**Q-7**~~ Not used: …; a heading where it is a log, ### Rev 2 — not used), so the series reads complete.
  7. Database migrations (forge-et-be, src/main/resources/db/migration/V<n>__*.sql) take the highest version on main plus one at merge time, never a number above one that an open PR holds: Flyway runs with out-of-order off, so a version lower than one already applied can never be added later, and skipping past an open PR’s number would leave a permanent gap. Two PRs with the same version: the second to merge renumbers. forge-et-be/docs/migrations.md has the steps.
  8. An example id that must not point at a real entry uses number 0 (BUG-000, OQ-0, L-000, AD #0), which no series reaches; no tool treats BUG-000 as a bug. An example that cites a real entry on purpose (F2, FS-3, a past bug that shows a pattern) keeps its real id. A test fixture that needs several distinct made-up ids uses numbers already used by real entries, never a free number below the highest, which a new entry would take.
  9. Point-in-time records keep their numbers as written — audits, the engagement log, weekly updates, meeting notes, finished plans’ quotations of a spec’s numbers. They are history; this rule governs the documents that define ids.

Every numbered series

Series Defined in Scope Next number Duplicate check
BUG-NNN .forge/tracker.yaml bugs: and its .forge/bugs.md section repo lowest free (next-id.py bug) yes
OQ-N .forge/project-prd-signals.md, then .forge/project-prd-history.md repo highest + 1 across both files (next-id.py oq) yes
PRD Rev N .forge/project-prd-history.md repo highest + 1 (next-id.py prd-rev) yes
AD #N .claude/CLAUDE.md § Architecture Decisions repo highest + 1 (next-id.py ad) yes
AD-O-N .forge/design/architecture.md open decisions repo highest + 1 yes
L-NNN .forge/lessons.md repo highest + 1 (next-id.py lesson) yes
FS-N .forge/tracker.yaml setup.foundation.slices repo highest + 1 yes
F<n>, F<n>-<letter> .forge/tracker.yaml features and .forge/features.md repo highest + 1; letters in order yes
R-<area>-NNN, SP-<area>-NNN .forge/tracker.yaml setup.* risks and spikes; R-FND-NNN in .forge/engagement-gate-runs.md § Gate 3 precondition (the foundation seal), which also restates earlier gates’ risks; a later run that carries an R-FND row forward does not define it again repo, per area highest + 1 yes
Gate N Run M .forge/engagement-gate-runs.md headings per gate highest + 1 yes
R-NN, P-NN .forge/project-prd.md § Risks, § Reference-System Classification repo highest + 1 yes
UAT-NNN .forge/tracker.yaml uat_issues, and its section in .forge/release/<id>/uat-issues.md repo highest + 1 yes
RC-N, UC-N .forge/tracker.yaml releases[].cycles repo (across every release, not restarted per release) highest + 1 yes
FLOW-NNN, R-REL-N a release cycle’s plan and report (.forge/release/), and the cycle’s flows in tracker.yaml per cycle highest + 1 yes (repeats only for FLOW: a cycle may run a subset of the release’s flows, as .forge/release/README.md’s UC-1/FLOW-003 shows)
Design-system Rev N .forge/design/ui/design-system.md ## Revisions repo highest + 1 (next-id.py ds-rev) yes
Entity-map Rev N .forge/design/data/entity-map.md ## Revisions repo highest + 1 (read origin/main and the open PRs that change the file, rule 1) yes
A-N, C-N .forge/cloud-gated-validation.md §A rows, §C sections repo highest + 1 yes
Client questions QN .forge/client/open-questions.md repo highest + 1 yes
FR-…, NFR-N, AC-N, Q-N each spec’s Requirements, Acceptance Criteria, Open Questions; a requirement is defined by its bold or struck-through id, and a plain-text FR-N there (a parent spec’s, say) only cites one per spec highest + 1; split with letters yes
Spec or plan Rev N that spec’s or plan’s ## Revisions per document highest + 1 yes
F-NNN each *-findings.md per file highest + 1 yes
W-N each spec’s gap-check warnings (forge-gap-check), - **W-N** items in its Open Questions per spec highest + 1 yes
Any other numbered list in a spec, plan, wave contract, WI record or harness design record (D-N, Q-N, R-N, C-N, N-N, OI-N, …) that document per document highest + 1 — (these documents restate an entry in the same shape that defines it, so no check can tell a repeat from a restatement; the author and the reviewer check them)
WI-<wave>.<index>, waves .forge/tracker.yaml and the Decomposition Plan (/forge-wave-decompose) per feature next in order yes (tracker; each id is <feature>-WI-<its wave>.<n>, and no wave or work-item number is skipped)
V<n> migrations forge-et-be db/migration backend repo rule 7 Flyway validation

.forge/owed.md and the engagement log are not numbered. A list that starts numbering its entries joins this table in the same change.

The checks

  • python3 .claude/lib/check-unique-ids.py fails on a repeated number in every series marked “yes” above, on a work item whose id is not <feature>-WI-<its wave>.<n> or a wave without a number, and on a skipped wave or work-item number in a feature’s tracker entry: those are numbered in one decomposition, never taken by two open PRs at once, so a gap there is a deleted row, not a number an open PR holds (rule 3 — a wave that will not run is withdrawn, and a work item is withdrawn only with its wave, .claude/rules/tracker.md). It reads an id only where it is defined, in the shape the table names, never where it is cited. Repo hygiene runs it on each PR’s merge result, and /forge-doctor reports it.
  • python3 .claude/lib/check-unique-ids.py --gaps lists every skipped number in those series, without failing: outside waves and work items, a gap can be momentary while an open PR holds the number below yours. Repo hygiene prints the list as warnings; a gap that no open PR holds is fixed by rule 2 or rule 6.
  • python3 .claude/lib/next-id.py <series> prints the next id of a bug, lesson, OQ, PRD revision, AD or design-system revision from origin/main, the open PRs and the pushed branches with no PR, and prints nothing when a read fails; bash .claude/lib/next-bug-id.sh is the same for bugs.
  • python3 .claude/lib/next-id.py --check-pr <n> fails when PR <n> adds an entry of one of those six series that is not the lowest number main, the other open PRs and the pushed branches leave free, and prints the ids to renumber to. A pushed branch never holds one of the PR’s own numbers against it: that is the same entry copied (a checkpoint PR), or a clash the branch’s own PR fixes later, as the younger (rule 5). Repo hygiene runs it on every PR, so a number taken by hand cannot skip a free one; run it yourself before pushing. The other series in the table are not checked this way: their gaps show only in --gaps.

See .forge/lessons.md L-057 for the collision this guards against.

Generated from .claude/rules/id-numbering.md by .claude/lib/render-docs-html.js. Markdown is canonical.