atomic-design-poc/docs/project/readable-codebase/RD-19-ticket-refs-backend.md

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.mds 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.

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:

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:

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):

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

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.