ehoandClaude Opus 5
a196a380ce
RD-18 established that a ticket reference inside a path to a document that still exists is a pointer, not provenance, and exempted one. RD-19 did not re-run that check against `backend/`, and asserted a target of 0. Two such paths existed, so the agent described the two documents in prose instead. The path no longer resolves and the reader must search. Restore both paths, correct the ticket's decision 1 and acceptance target to 2, and record the miss as the eighth in the README's list. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
169 lines
8.1 KiB
Markdown
169 lines
8.1 KiB
Markdown
# 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.
|