atomic-design-poc/docs/project/readable-codebase/RD-18-ticket-refs-frontend.md

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.

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:

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:

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:

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

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.