ehoandClaude Sonnet 5
dd11eafe50
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>
165 lines
8.3 KiB
Markdown
165 lines
8.3 KiB
Markdown
# 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.
|