docs(test): make Given/When/Then the default BDD structure (WP-71)

bdd.mdx previously banned "Given/When/Then ceremony" outright, which
directly contradicted WP-70's own acceptance tests (Acceptance/
BesluitLifecycleTests.cs already used // Given/When/Then comments) and
the backend's organically-evolved PascalCase_snake_sentence convention,
which the doc gave zero guidance for. Reverses that rule: every test is
now structured Given -> When -> Then, with a genuinely empty phase
omitted rather than faked; present-tense declarative naming and the
one-behaviour-per-test rule are unchanged. ADR-0006 gets a cross-reference
so both documents agree everywhere, not just in acceptance tests.

Also closes out the doc's other named-but-unenforced rules found by the
audit: fixes the 5 files asserting rendered $localize copy instead of
the underlying tag/message-id (the compliant pattern already existed in
werkvoorraad-item-view.spec.ts), splits the multi-behaviour titles the
doc itself calls a smell (";", "and", "/"), and fixes bdd.mdx's own false
citation of registratie-wizard.machine.spec.ts as "one transition per
test" by actually splitting that test into one-transition-per-test.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

apps/ssp/src/app/brief/application/brief.store.spec.ts

@@ -4,7 +4,7 @@ import { Result } from '@shared/kernel/fp';
 import { Brief, BriefDecisions, CaseContext, LetterBlock } from '@brief/domain/brief';
 import { OrgTemplate } from '@brief/domain/org-template';
 import { BriefAdapter, BriefView } from '@brief/infrastructure/brief.adapter';
-import { LetterPreviewAdapter } from '@brief/infrastructure/letter-preview.adapter';
+import { LetterPreviewAdapter, PREVIEW_FAILED } from '@brief/infrastructure/letter-preview.adapter';
 import { RevealBigNummerAdapter } from '@brief/infrastructure/reveal-bignummer.adapter';
 import { BriefStore } from './brief.store';
 
@@ -164,25 +164,64 @@ async function loadedStore(over: Partial<BriefAdapter> = {}): Promise<BriefStore
 }
 
 describe('BriefStore undo/redo history', () => {
-  it('records an edit, undoes and redoes it; buttons mirror; a no-op edit is not recorded', async () => {
+  it('starts with nothing to undo', async () => {
+    // Given a freshly loaded brief.
+    // When no edit has happened yet...
     const store = await loadedStore();
-    expect(store.canUndo()).toBe(false);
 
+    // Then there is nothing to undo.
+    expect(store.canUndo()).toBe(false);
+  });
+
+  it('records an edit and makes it undoable', async () => {
+    // Given a loaded brief with one block.
+    const store = await loadedStore();
+
+    // When a block is removed...
     store.edit({ tag: 'BlockRemoved', blockId: 'local-1' });
+
+    // Then the block is gone and the edit becomes undoable.
     expect(loadedBrief(store).sections[0].blocks.length).toBe(0);
     expect(store.canUndo()).toBe(true);
+  });
 
+  it('undo reverts the edit and enables redo', async () => {
+    // Given a brief with one recorded edit (a removed block).
+    const store = await loadedStore();
+    store.edit({ tag: 'BlockRemoved', blockId: 'local-1' });
+
+    // When the edit is undone...
     store.undo();
+
+    // Then the block is back, and redo becomes available.
     expect(loadedBrief(store).sections[0].blocks.length).toBe(1);
     expect(store.canRedo()).toBe(true);
+  });
 
+  it('redo reapplies the undone edit', async () => {
+    // Given an edit that was undone.
+    const store = await loadedStore();
+    store.edit({ tag: 'BlockRemoved', blockId: 'local-1' });
+    store.undo();
+
+    // When it is redone...
     store.redo();
-    expect(loadedBrief(store).sections[0].blocks.length).toBe(0);
 
-    // A no-op edit (unknown block) changes nothing → leaves no dead history step.
+    // Then the edit is reapplied.
+    expect(loadedBrief(store).sections[0].blocks.length).toBe(0);
+  });
+
+  it('a no-op edit does not clear the redo future', async () => {
+    // Given an undone edit, with redo available.
+    const store = await loadedStore();
+    store.edit({ tag: 'BlockRemoved', blockId: 'local-1' });
     store.undo(); // back to 1 block, redo available
+
+    // When an edit that changes nothing (an unknown block) is applied...
     store.edit({ tag: 'BlockRemoved', blockId: 'does-not-exist' });
-    expect(store.canRedo()).toBe(true); // future NOT cleared by a no-op
+
+    // Then the no-op leaves no dead history step — redo is still available.
+    expect(store.canRedo()).toBe(true);
   });
 
   it('a new edit clears the redo future', async () => {
@@ -268,12 +307,12 @@ describe('BriefStore.previewLetter', () => {
     const open = vi.spyOn(window, 'open').mockImplementation(() => null);
     vi.spyOn(TestBed.inject(LetterPreviewAdapter), 'preview').mockResolvedValue({
       ok: false,
-      error: 'De voorvertoning kon niet worden geopend.',
+      error: PREVIEW_FAILED,
     });
 
     await store.previewLetter();
     expect(open).not.toHaveBeenCalled();
-    expect(store.lastError()).toBe('De voorvertoning kon niet worden geopend.');
+    expect(store.lastError()).toBe(PREVIEW_FAILED);
   });
 });
 

apps/ssp/src/app/brief/infrastructure/letter-preview.adapter.ts

@@ -4,7 +4,9 @@ import { currentRole } from '@shared/infrastructure/role';
 import { problemDetail } from '@shared/infrastructure/api-error';
 import { environment } from '@shared/environments/environment';
 
-const PREVIEW_FAILED = $localize`:@@brief.preview.failed:De voorvertoning kon niet worden geopend.`;
+/** Exported so specs can assert against the same message id instead of retyping the
+    Dutch sentence (see `brief.store.spec.ts`'s `previewLetter` failure test). */
+export const PREVIEW_FAILED = $localize`:@@brief.preview.failed:De voorvertoning kon niet worden geopend.`;
 
 /**
  * `/brief/preview` returns `text/html`, not JSON, and is `.ExcludeFromDescription()`'d

apps/ssp/src/app/herregistratie/domain/intake.acceptance.spec.ts

@@ -77,15 +77,20 @@ describe('intake acceptance journeys', () => {
     });
   });
 
-  it('buitenland gewerkt requires land + hours abroad, and gaNaarStap corrects an earlier answer', () => {
+  it('buitenland gewerkt requires land and hours abroad before advancing', () => {
+    // Given a user who says they worked abroad.
+    // When they try to advance without a country...
     const blocked = givenIntake(
       { tag: 'SetAnswer', key: 'buitenlandGewerkt', value: 'ja' },
       { tag: 'Next' },
     );
+
+    // Then they stay on the same step, blocked by a missing 'land' answer.
     expect(blocked.tag).toBe('Answering');
     expect(blocked.tag === 'Answering' && blocked.cursor).toBe(0);
     expect(blocked.tag === 'Answering' && blocked.errors.land).toBeTruthy();
 
+    // When land and hours abroad are supplied, and the rest of the journey answered...
     const reviewing = given(reduce, blocked)(
       { tag: 'SetAnswer', key: 'land', value: 'Duitsland' },
       { tag: 'SetAnswer', key: 'buitenlandseUren', value: '300' },
@@ -93,16 +98,34 @@ describe('intake acceptance journeys', () => {
       { tag: 'SetAnswer', key: 'uren', value: '1200' },
       { tag: 'Next' }, // werk step valid, uren high enough to skip scholing -> review
     );
+
+    // Then the journey advances all the way to review.
     expect(reviewing.tag).toBe('Answering');
     expect(reviewing.tag === 'Answering' && reviewing.cursor).toBe(2); // review
+  });
 
-    // Jump back from review to correct the country, without losing later answers.
+  it('gaNaarStap corrects an earlier answer without losing later ones', () => {
+    // Given a journey that reached review with a foreign-work answer.
+    const reviewing = givenIntake(
+      { tag: 'SetAnswer', key: 'buitenlandGewerkt', value: 'ja' },
+      { tag: 'Next' },
+      { tag: 'SetAnswer', key: 'land', value: 'Duitsland' },
+      { tag: 'SetAnswer', key: 'buitenlandseUren', value: '300' },
+      { tag: 'Next' },
+      { tag: 'SetAnswer', key: 'uren', value: '1200' },
+      { tag: 'Next' },
+    );
+
+    // When gaNaarStap jumps back to correct the country...
     const corrected: IntakeState = given(reduce, reviewing)(
       { tag: 'GaNaarStap', cursor: 0 },
       { tag: 'SetAnswer', key: 'land', value: 'België' },
       { tag: 'Next' }, // buitenland step re-validated
       { tag: 'Next' }, // werk step re-validated (earlier 'uren' answer preserved)
     );
+
+    // Then the correction lands back on review with the new answer, and the later
+    // 'uren' answer is preserved rather than lost.
     expect(corrected.tag).toBe('Answering');
     expect(corrected.tag === 'Answering' && corrected.cursor).toBe(2);
     expect(corrected.tag === 'Answering' && corrected.answers.land).toBe('België');
@@ -111,6 +134,7 @@ describe('intake acceptance journeys', () => {
     const noForwardJump = reduce(corrected, { tag: 'GaNaarStap', cursor: 2 });
     expect(noForwardJump).toBe(corrected);
 
+    // And the corrected journey still submits successfully with the corrected data.
     const done = given(reduce, corrected)({ tag: 'Submit' }, { tag: 'SubmitConfirmed' });
     expect(done.tag).toBe('Submitted');
     expect(done.tag === 'Submitted' && done.data).toEqual({

apps/ssp/src/app/registratie/domain/tasks.spec.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest';
+import { formatDatumNl } from '@shared/kernel/datum';
 import { tasksFromProfile } from './tasks';
 import { Registration } from './registration';
 
@@ -13,34 +14,56 @@ const base: Registration = {
 
 describe('tasksFromProfile', () => {
   it('offers herregistratie when the server says eligible, with the formatted deadline', () => {
+    // Given a registration whose deadline is 2026-12-31.
+    // When the server says the professional is eligible for herregistratie...
     const tasks = tasksFromProfile(base, true);
+
+    // Then one task is offered, routed to herregistratie, whose copy carries the
+    // deadline through the same date formatter the rest of the app uses (this test's
+    // point IS the date formatting, so the expectation is derived from `formatDatumNl`
+    // rather than a hardcoded Dutch date literal).
     expect(tasks).toHaveLength(1);
     expect(tasks[0].to).toBe('/herregistratie');
-    expect(tasks[0].description).toContain('31 december 2026');
+    expect(tasks[0].description).toContain(formatDatumNl('2026-12-31'));
   });
 
   it('offers nothing when the server says not eligible', () => {
+    // Given the same registration.
+    // When the server says the professional is not eligible for herregistratie...
+    // Then no task is offered.
     expect(tasksFromProfile(base, false)).toHaveLength(0);
   });
 
   it('surfaces a notice for a suspended registration (independent of eligibility)', () => {
+    // Given a suspended ("Geschorst") registration, ineligible for herregistratie.
     const reg: Registration = {
       ...base,
       status: { tag: 'Geschorst', geschorstTot: '2027-01-01', reden: 'Onderzoek' },
     };
+
+    // When the tasks are derived...
     const tasks = tasksFromProfile(reg, false);
+
+    // Then exactly one notice is surfaced, routed to the registration page, carrying
+    // the raw suspension reason through unchanged (not translated copy — `reden` is
+    // domain data, passed through as-is).
     expect(tasks).toHaveLength(1);
-    expect(tasks[0].title).toContain('geschorst');
+    expect(tasks[0].to).toBe('/registratie');
     expect(tasks[0].description).toBe('Onderzoek');
   });
 
   it('surfaces a notice for a struck-off registration', () => {
+    // Given a struck-off ("Doorgehaald") registration.
     const reg: Registration = {
       ...base,
       status: { tag: 'Doorgehaald', doorgehaaldOp: '2025-01-01', reden: 'Op eigen verzoek' },
     };
+
+    // When the tasks are derived...
     const tasks = tasksFromProfile(reg, false);
+
+    // Then exactly one notice is surfaced, routed to the registration page.
     expect(tasks).toHaveLength(1);
-    expect(tasks[0].title).toContain('doorgehaald');
+    expect(tasks[0].to).toBe('/registratie');
   });
 });