refactor: strip WP-/RB- ticket refs from apps and libs (RD-18)
204 WP-NN/RB-NN comments named a closed ticket instead of the code they sit next to. git blame already records history and stays correct when code moves; the comment does not. This sweep removes the reference and keeps the sentence, across 95 files in apps/ and libs/ plus the behaviour-spec generator's header text. Eleven references stay: five story files justify an a11y disable per the README's rule, and one line in a11y.mdx documents that convention. Two sentences needed a rewrite, not a deletion, so the reference's meaning survives its removal. behaviour-spec.mdx is regenerated, not hand-edited. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 5
@@ -0,0 +1,164 @@
|
||||
# RD-18 — Strip the `WP-`/`RB-` ticket references from `apps/` and `libs/`
|
||||
|
||||
Status: done
|
||||
Source: PLAN.md Phase 2, item 4
|
||||
|
||||
## Why
|
||||
|
||||
204 `WP-NN`/`RB-NN` references sit in comments across 104 files in `apps/` and `libs/`. They
|
||||
record which ticket introduced a line. `git blame` already records that, and it stays correct
|
||||
when the code moves. The comment does not: it names a closed ticket, and the reader who chases
|
||||
it learns nothing the surrounding sentence did not already say.
|
||||
|
||||
The sweep removes the reference and keeps the sentence. It changes no behaviour.
|
||||
|
||||
## Read first
|
||||
|
||||
- `libs/shared/docs/a11y.mdx` lines 14, 20, 28 and 68 — three references to strip and one to
|
||||
keep, in one file. It is the clearest example of the rule in decision 2.
|
||||
- `libs/shared/src/ui/task-list/task-list.stories.ts:17` — an exempt reference, and why.
|
||||
- `scripts/gen-behaviour-spec.mjs:183` — the generated document's header text.
|
||||
- The README's rule: "No ticket leaves a check disabled without an inline reason **and** a
|
||||
reference to the ticket that removes it."
|
||||
|
||||
## Decisions (pre-made, don't relitigate)
|
||||
|
||||
1. **Strip `WP-NN` and `RB-NN`. Keep every `ADR-000x`.** ADR references point at documents
|
||||
that exist and that the reader must read. There are 50 of them in scope; the count must not
|
||||
move. `CD-` does not appear anywhere in this repo — do not go looking for it.
|
||||
|
||||
2. **Eleven references are exempt, in six files.** A reference survives when it names an
|
||||
obligation that is not yet discharged, rather than recording history:
|
||||
|
||||
| File | Refs | Why exempt |
|
||||
| ----------------------------------------------------------------- | ---- | ----------------------------------- |
|
||||
| `registratie/ui/aanvraag-block/aanvraag-block.stories.ts` | 2 | justifies `a11y: { disable: true }` |
|
||||
| `registratie/ui/dashboard/wat-moet-ik-regelen.section.stories.ts` | 2 | justifies `a11y: { disable: true }` |
|
||||
| `libs/shared/src/ui/choice-link/choice-link.stories.ts` | 2 | justifies `a11y: { disable: true }` |
|
||||
| `libs/shared/src/ui/choice-list/choice-list.stories.ts` | 2 | justifies `a11y: { disable: true }` |
|
||||
| `libs/shared/src/ui/task-list/task-list.stories.ts` | 2 | justifies `a11y: { disable: true }` |
|
||||
| `libs/shared/docs/a11y.mdx` line 68 only | 1 | points at WP-13's marker convention |
|
||||
|
||||
The five story files each disable an accessibility check. The README forbids leaving a check
|
||||
disabled without naming the ticket that removes it, so stripping WP-11 there would break a
|
||||
rule this arc enforces. **Do not edit those five files at all.**
|
||||
|
||||
`a11y.mdx` is edited: lines 14, 20 and 28 are provenance and go; line 68 stays.
|
||||
|
||||
3. **Thirteen references live in `describe`/`it` titles.** Strip them there too. A spec title
|
||||
is documentation the generator publishes, so the reference reaches
|
||||
`libs/shared/docs/behaviour-spec.mdx` and shows up in the rendered behaviour spec.
|
||||
|
||||
4. **Never hand-edit `behaviour-spec.mdx`.** It is generated. Fix the spec titles, then run
|
||||
`npm run gen:behaviour-spec`. Its 14 references disappear on their own — except one.
|
||||
|
||||
5. **The exception in decision 4 is the generated file's header.**
|
||||
`behaviour-spec.mdx:4` says "the compile-time guarantees WP-70 bought". That sentence comes
|
||||
from `scripts/gen-behaviour-spec.mjs:183`, not from a spec. Edit the generator. Fix the
|
||||
duplicate of the same sentence in that file's own header comment at line 4 while you are
|
||||
there. This is the one file outside `apps/`+`libs/` that this ticket touches.
|
||||
|
||||
6. **Two sentences need a rewrite, not a deletion.** Deleting the reference alone leaves them
|
||||
meaningless:
|
||||
- `subject.interceptor.spec.ts:45` — the title ends "(WP-33-style stickiness)". The
|
||||
reference _is_ the adjective. Rewrite the parenthetical as "(sticky per tab)".
|
||||
- `apps/ssp/src/index.html:14` — "(WP-25 inlines this same file)". The subject is the
|
||||
backend renderer. Rewrite as "(the backend inlines this same file)".
|
||||
|
||||
7. **Keep the sentence readable, not merely shorter.** `passage-picker.component.ts:13-14`
|
||||
reads "Superseded by `besluit-panel` (WP-27's guided drafting)" and "no consumer left …
|
||||
(WP-28 audit)". Strip to "Superseded by `besluit-panel`'s guided drafting" and "no consumer
|
||||
left … outside its own story". A stripped line must not leave an empty `()`, a stranded
|
||||
"see", or a doubled space.
|
||||
|
||||
## Files
|
||||
|
||||
`apps/` and `libs/`, minus the five exempt story files, plus
|
||||
`scripts/gen-behaviour-spec.mjs`. About 99 files change.
|
||||
|
||||
This is the one ticket type where an acceptance command **should** address a whole directory
|
||||
rather than a file list: the sweep's contract is "no reference survives in `apps` or `libs`
|
||||
except the listed eleven". Enumerating 99 files would restate the sweep, not check it.
|
||||
|
||||
## Steps
|
||||
|
||||
1. Strip the references outside the six files in decision 2. Work directory by directory so
|
||||
the diff stays reviewable.
|
||||
2. Apply the rewrites in decisions 6 and 7.
|
||||
3. Edit `scripts/gen-behaviour-spec.mjs` per decision 5.
|
||||
4. Run `npm run gen:behaviour-spec`.
|
||||
5. `git add -A`, then run the acceptance commands.
|
||||
6. Update this ticket's `Status:` to `done` and the README's RD-18 row to `done`.
|
||||
7. Commit all of it together.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
Measured against the tree before handover. `git grep -o … | wc -l` counts **occurrences**;
|
||||
`git grep -c` would count lines and give a different, wrong number.
|
||||
|
||||
```bash
|
||||
git grep -oE "\b(WP|RB)-[0-9]+" -- apps libs | wc -l # is 204 -> MUST be 11
|
||||
```
|
||||
|
||||
Those eleven are exactly the exempt ones, all inside the six files of decision 2:
|
||||
|
||||
```bash
|
||||
git grep -hoE "\b(WP|RB)-[0-9]+" -- \
|
||||
apps/ssp/src/app/registratie/ui/aanvraag-block/aanvraag-block.stories.ts \
|
||||
apps/ssp/src/app/registratie/ui/dashboard/wat-moet-ik-regelen.section.stories.ts \
|
||||
libs/shared/src/ui/choice-link/choice-link.stories.ts \
|
||||
libs/shared/src/ui/choice-list/choice-list.stories.ts \
|
||||
libs/shared/src/ui/task-list/task-list.stories.ts \
|
||||
libs/shared/docs/a11y.mdx | wc -l # is 14 -> MUST be 11
|
||||
```
|
||||
|
||||
The five story files are untouched, so their disables keep their justification:
|
||||
|
||||
```bash
|
||||
git diff --name-only HEAD -- '*.stories.ts' | grep -cE "aanvraag-block|wat-moet-ik-regelen|choice-link|choice-list|task-list" # MUST be 0
|
||||
```
|
||||
|
||||
The ADR references all survive, and the sweep leaves no damaged prose:
|
||||
|
||||
```bash
|
||||
git grep -oE "ADR-[0-9]+" -- apps libs | wc -l # unchanged: 50
|
||||
git grep -nE "^\s*(//|\*|1\.|\|).*\s\(\)" -- apps libs | wc -l # unchanged: 0
|
||||
git grep -nE "^\s*(//|\*).*[a-z] [a-z]" -- apps libs | wc -l # unchanged: 0
|
||||
```
|
||||
|
||||
```bash
|
||||
npm run ci --full # exits 0
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
**`--full` is required, although the README's Order table leaves that column blank for this
|
||||
ticket.** The table is wrong here: the sweep edits four `.mdx` files (`a11y.mdx`,
|
||||
`cibg-gaps.mdx`, `layers.mdx`, and the generated `behaviour-spec.mdx`), and the README's own
|
||||
rule says an `.mdx` edit needs `--full`. Fix the column to `yes` in the same commit.
|
||||
|
||||
The behaviour-spec drift check inside `npm run ci` is what proves step 4 was run. If it fails,
|
||||
you edited `behaviour-spec.mdx` by hand or skipped the regeneration.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- `backend/` — 370 references across 86 files. RD-19 owns them.
|
||||
- `docs/`, `.claude/`, `e2e/`, `scripts/` — except the one generator file in decision 5.
|
||||
- The five exempt story files (decision 2). Fixing the markup that makes their a11y disables
|
||||
necessary is WP-11's job, not this ticket's.
|
||||
- Rewording a comment beyond what removing the reference requires. This ticket is a sweep, not
|
||||
a documentation pass.
|
||||
|
||||
## Risks
|
||||
|
||||
- **`git grep`, never `grep -r`.** `grep -r` reaches gitignored build output and inflates every
|
||||
count.
|
||||
- **A reference inside a spec title changes a generated document.** Strip the title, then
|
||||
regenerate. Editing the `.mdx` directly leaves the spec title unchanged, and the next
|
||||
regeneration silently puts the reference back.
|
||||
- **The generator's header is not a spec title** (decision 5). It is the one reference that
|
||||
regeneration cannot remove, because it comes from `scripts/`.
|
||||
- **Do not open the five exempt story files.** An edit there is the one way this ticket can
|
||||
break a rule the README enforces.
|
||||
- **204, not the 181 that PLAN records.** The arc's own commits added references since PLAN was
|
||||
measured. Trust the command, not the prose.
|
||||
@@ -112,7 +112,7 @@ two. Note that RD-15 exists because 22 abandoned agent worktrees are still on di
|
||||
| RD-15 | Remove 22 abandoned agent worktrees (4.7 GB) | 01 | | done |
|
||||
| RD-16 | ~~`parseDashboardView` returns `BigProfile`~~ — DROPPED, see PLAN.md 2.2 | 01 | | n/a |
|
||||
| RD-17 | `successOf`/`successOr` sweep — 10 sites, 8 files | 01 | | done |
|
||||
| RD-18 | Ticket-reference sweep, frontend — 181 refs, 100 files | 01 | | todo |
|
||||
| RD-18 | Ticket-reference sweep, frontend — 181 refs, 100 files | 01 | yes | done |
|
||||
| RD-19 | Ticket-reference sweep, backend — 370 refs, 86 files | 01 | | todo |
|
||||
| RD-20 | `wizard-errors.ts` + spec, adopted by all 3 wizards | 02 | | todo |
|
||||
| RD-21 | `rich-text-dom.ts` helpers + spec cases | 02 | yes | todo |
|
||||
|
||||
Reference in New Issue
Block a user