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
- 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, runpython3 .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, thengh 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 localmain. - 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.
- 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 closedwontfix. 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 thatnext-id.py --check-prrefuses, so every later entry would have to renumber (the lead’s decision on BUG-299, 2026-11-02). - 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. - 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 hygienefails 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. - 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. - Database migrations (
forge-et-be,src/main/resources/db/migration/V<n>__*.sql) take the highest version onmainplus one at merge time, never a number above one that an open PR holds: Flyway runs without-of-orderoff, 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.mdhas the steps. - 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 treatsBUG-000as 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. - 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.pyfails 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 hygieneruns it on each PR’s merge result, and/forge-doctorreports it.python3 .claude/lib/check-unique-ids.py --gapslists 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 hygieneprints 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 fromorigin/main, the open PRs and the pushed branches with no PR, and prints nothing when a read fails;bash .claude/lib/next-bug-id.shis 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 numbermain, 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 hygieneruns 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.