# RD-19 — Strip the `WP-`/`RB-` ticket references from `backend/`

Status: done
Source: PLAN.md Phase 2, item 4

## Why

The backend half of the sweep RD-18 did for the front end. 370 `WP-NN`/`RB-NN` references sit
in comments across 86 files under `backend/` — 70 `.cs` files plus the Dockerfile, four shell
scripts, four compose files, two `README.md`s and a handful of config files. `git blame` holds
the provenance and stays correct when the code moves; the comment names a closed ticket and
tells the reader nothing the sentence around it does not.

Strip the reference, keep the sentence. No behaviour changes.

## Read first

- `backend/tests/BigRegister.Tests/LetterHtmlTests.cs:8-13` — the golden-file test, and the
  reason decision 2 exists.
- `public/letter.css` lines 1 and 4 — three references, mirrored byte for byte inside the
  golden file.
- `backend/src/BigRegister.Api/appsettings.json:9` — the `_Zgw` key, a documentation string
  rather than a comment.
- `RD-18`'s decisions block, for the sentence-quality rule this ticket repeats.

## Decisions (pre-made, don't relitigate)

1. **Strip all 370 except two.** No backend file disables a check by naming the ticket that
   removes it — verified against `pragma warning disable`, `Skip =`, `NoWarn` and
   `SuppressMessage`, none of which carries a reference. Keep all 40 `ADR-000x` references; that
   count must not move.

   **Corrected after the ticket ran.** The original text said "nothing is exempt", and it was
   wrong. Two references are part of a path to a document that still exists:

   | Site                               | Reference                                           |
   | ---------------------------------- | --------------------------------------------------- |
   | `backend/README.md:18`             | `docs/project/backlog/WP-22-durable-persistence.md` |
   | `Domain/Letters/LetterHtml.cs:153` | `docs/project/backlog/WP-25-letter-preview-html.md` |

   RD-18 exempted this same class of reference (`a11y.mdx:68`). A path that resolves is a
   pointer, not provenance. Stripping the number breaks the path, and describing the file in
   prose instead makes the reader search for it.

2. **`public/letter.css` and `LetterHtml.golden.html` change together, or the build goes red.**
   `LetterHtml.cs:161` finds `public/letter.css` at run time and **inlines it** into the
   rendered letter. `LetterHtml.golden.html` is a snapshot of that output, so it embeds the
   same CSS comment verbatim. Both hold the same three references (WP-24, WP-25 on line 1;
   WP-25 on line 4).

   - Edit `public/letter.css`.
   - Apply the identical edit to the copy inside `LetterHtml.golden.html`.
   - Editing either one alone fails `Renders_the_golden_brief`.

   `public/letter.css` is the one file outside `backend/` that this ticket touches, exactly as
   `scripts/gen-behaviour-spec.mjs` was for RD-18.

3. **No spec regeneration is needed, and that is a fact about C#, not an oversight.**
   `scripts/gen-behaviour-spec.mjs:124` extracts backend `[Fact]`/`[Theory]` **method names**
   into `behaviour-spec.mdx`. A C# method name cannot contain a hyphen, so no backend test name
   can carry a `WP-NN`. Verified: zero `WP_NN`/`RB_NN` underscore variants exist either. Do not
   run `gen:behaviour-spec`. If the drift check fires, you changed something this ticket did not
   intend.

4. **Three kinds of reference live in a string, not a comment. All three are display-only and
   all three get stripped:**

   | Site                                                                                     | What it is                                   |
   | ---------------------------------------------------------------------------------------- | -------------------------------------------- |
   | `appsettings.json:9`, the `_Zgw` key                                                     | a documentation string; no code binds `_Zgw` |
   | `setup_configuration/data.yaml:15,29` + `.template`                                      | the OpenZaak harness's `name:` / `label:`    |
   | `bootstrap-notificaties.sh:44`, `verify-notificatie.sh:32`, `bootstrap-catalogus.sh:171` | a `label=` value and two `echo` lines        |

   Verified: nothing in the repository greps for these labels, so renaming them breaks no
   script. They are read by humans looking at an OpenZaak admin page.

5. **Keep the sentence readable, not merely shorter** — the same rule as RD-18. Several `.cs`
   XML doc comments read "… (WP-53) is the acting citizen" or "— WP-73: a freshly submitted
   aanvraag …", where the reference sits mid-sentence. Rewrite the clause. A stripped line must
   not leave an empty `()`, a stranded "see", a dangling dash, or a doubled space.

6. **Leave `<paramref>`, `<see cref=…>` and every other XML doc tag intact.** They are compiled
   references; breaking one is a build warning at best and a silent documentation hole at worst.
   Only the ticket number inside the prose goes.

## Files

Everything under `backend/`, plus `public/letter.css`. About 87 files change.

As in RD-18, this ticket's acceptance commands address the directory rather than a file list,
because the sweep's contract is "no reference survives".

## Steps

1. Strip the references in `backend/`, working directory by directory so the diff stays
   reviewable.
2. Apply decision 2: edit `public/letter.css`, then make the golden file's embedded copy match
   it exactly.
3. Run `cd backend && dotnet test` on its own before the full gate. It is the fastest proof
   that step 2 landed correctly.
4. `git add -A`, then run the acceptance commands.
5. Update this ticket's `Status:` to `done` and the README's RD-19 row to `done`.
6. Commit all of it together.

## Acceptance criteria

Measured against the tree before handover. `git grep -o … | wc -l` counts **occurrences**;
`git grep -c` counts lines and would give a different, wrong number.

```bash
git grep -oE "\b(WP|RB)-[0-9]+" -- backend public/letter.css | wc -l   # is 373 -> MUST be 2
```

The two survivors are the document paths in decision 1:

```bash
git grep -oE "\b(WP|RB)-[0-9]+" -- backend/README.md \
  backend/src/BigRegister.Api/Domain/Letters/LetterHtml.cs | wc -l    # MUST be 2
```

The ADR references survive, and the sweep leaves no damaged prose:

```bash
git grep -oE "ADR-[0-9]+" -- backend | wc -l                                  # unchanged: 40
git grep -nE "^\s*(//|\*|#).*\s\(\)" -- backend public/letter.css | wc -l      # unchanged: 0
git grep -nE "^\s*(//|\*|#).*[a-z]  [a-z]" -- backend public/letter.css | wc -l # unchanged: 0
```

The golden file still matches the renderer (decision 2):

```bash
cd backend && dotnet test --filter FullyQualifiedName~LetterHtmlTests   # exits 0
```

```bash
npm run ci   # exits 0
```

## Verification

`npm run ci` is enough. `--full` is **not** required: this ticket touches no story, no `.mdx`,
and nothing under `libs/shared/src/ui/`. The README's Order table already leaves that column
blank for RD-19, and it is right this time.

If `dotnet test` fails with `SQLite Error 1: 'no such table: …'`, that is the stale-database
trap, not your change. See this README's Troubleshooting section.

## Out of scope

- `apps/`, `libs/`, `docs/`, `.claude/`, `e2e/` — RD-18 did the first two; the rest keep their
  references.
- `public/` beyond `letter.css`.
- Rewording a comment beyond what removing the reference requires.
- The `Case`/`Zaak` vocabulary rename (PLAN, "Deliberately out of scope").

## Risks

- **The golden file is the trap in this ticket.** Three references in `public/letter.css` are
  mirrored inside `LetterHtml.golden.html`. Change one without the other and the golden test
  fails. Change neither and the acceptance count cannot reach 0.
- **A reference inside a string is still a reference.** Decision 4 lists all three kinds. They
  do not look like comments, so a comment-only regular expression misses them and the count
  stops short of 0.
- **Do not touch `<see cref=…>` or `<paramref name=…>`** (decision 6).
- **`git grep`, never `grep -r`.** `grep -r` reaches `backend/bin`, `backend/obj` and the
  gitignored SQLite files.
- **370 is measured today.** If your first count differs, re-measure before assuming the ticket
  is stale.