docs(architecture): ADR-0004 — Reqnroll as BDD framework (refs #5)

Record the choice of Reqnroll.xUnit for the acceptance layer introduced in
S-04, and register the previously-unlisted ADR-0002/0003 in the MkDocs nav.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.gitignore

@@ -5,6 +5,9 @@ obj/
 [Rr]elease/
 *.user
 
+# Reqnroll-generated test code (regenerated from *.feature on build)
+*.feature.cs
+
 # Test results / coverage
 [Tt]est[Rr]esults/
 *.trx

Makefile

@@ -5,7 +5,7 @@
 # `make ci` locally runs exactly what the pipeline runs — no drift. Until a
 # self-hosted runner is registered, `make ci` is the gate (see docs/runbooks/ci.md).
 
-SLN        := services/bff/Bff.slnx
+SLN        := register-referentie.slnx
 COMPOSE    := infra/docker-compose.yml
 HEALTH_URL := http://localhost:8080/health
 OZ_COMPOSE  := infra/openzaak/docker-compose.yml
@@ -14,6 +14,8 @@ NRC_COMPOSE := infra/opennotificaties/docker-compose.yml
 NRC_BASE    := http://localhost:8001
 KC_COMPOSE  := infra/keycloak/docker-compose.yml
 KC_BASE     := http://localhost:8180
+FL_COMPOSE  := infra/flowable/docker-compose.yml
+FL_BASE     := http://localhost:8090/flowable-rest/service
 STACK_FILES := -f $(OZ_COMPOSE) -f $(NRC_COMPOSE)
 
 # On a rootless Podman dev box, point Docker CLI/Compose at the Podman socket —
@@ -26,7 +28,7 @@ export DOCKER_HOST := unix://$(PODMAN_SOCK)
 endif
 endif
 
-.PHONY: ci lint build unit smoke down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down help
+.PHONY: ci lint build unit smoke down changelog openzaak-up openzaak-smoke openzaak-seed openzaak-down stack-up stack-smoke stack-down keycloak-up keycloak-smoke keycloak-down flowable-up flowable-smoke flowable-down help
 
 ## ci: run the full pipeline — lint, build, unit, smoke (mirrors Gitea Actions)
 ci: lint build unit smoke
@@ -124,6 +126,21 @@ keycloak-smoke: keycloak-up
 keycloak-down:
 	docker compose -f $(KC_COMPOSE) down --volumes
 
+## flowable-up: start Flowable (deploys registratie.bpmn on boot)
+flowable-up:
+	docker compose -f $(FL_COMPOSE) up -d
+
+## flowable-smoke: start Flowable, then verify a started instance waits on the external task
+flowable-smoke: flowable-up
+	@bash -c 'for i in $$(seq 1 80); do \
+	    c=$$(curl -s -o /dev/null -w "%{http_code}" -u rest-admin:test $(FL_BASE)/repository/process-definitions?key=registratie || true); \
+	    [ "$$c" = "200" ] && break; sleep 3; done; echo "Flowable ready ($$c)"'
+	python3 infra/flowable/verify.py
+
+## flowable-down: stop and remove Flowable
+flowable-down:
+	docker compose -f $(FL_COMPOSE) down --volumes
+
 ## help: list available targets
 help:
 	@grep -E '^## ' $(MAKEFILE_LIST) | sed 's/^## //'

docs/architecture/adr-0003-default-fill.md

@@ -0,0 +1,44 @@
+# ADR-0003: ACL default-fill strategy
+
+- **Status:** Accepted
+- **Date:** 2026-06-04
+- **Deciders:** Respellion engineering
+- **Relates to:** S-04 (#5); builds on ADR-0001 (loose coupling)
+
+## Context
+
+The ACL is the only code that talks to ZGW APIs (ADR-0001 / CLAUDE.md §8.1). When the
+domain asks it to "open a zaak", the domain payload is intentionally free of ZGW
+specifics — it carries domain facts (e.g. the registrant's BSN), not OpenZaak fields. But
+OpenZaak's `POST /zaken` requires ZGW-mandatory fields: `bronorganisatie`,
+`verantwoordelijkeOrganisatie`, `startdatum`, `vertrouwelijkheidaanduiding`, and a
+`zaaktype` URL. Something has to supply those, and it must not leak into the domain.
+
+## Decision
+
+**The ACL default-fills the ZGW-mandatory zaak fields; the domain never sees them.**
+
+- `bronorganisatie`, `verantwoordelijkeOrganisatie`, `vertrouwelijkheidaanduiding`, and the
+  `zaaktype` URL come from **ACL configuration** (`AclDefaults` options) — not hardcoded,
+  not from the domain. This keeps them operationally manageable (the beheer portal will
+  edit them in S-15) and environment-specific (the seeded BIG zaaktype URL differs per env).
+- `startdatum` is derived from an injected **clock** (today's date), so it is
+  deterministic in tests.
+- The mapping from domain payload → ZGW `ZaakRequest` lives entirely inside the ACL
+  (`Application` builds the request from payload + defaults; `Infrastructure` serialises and
+  POSTs it). No other service constructs ZGW payloads or URLs.
+
+## Consequences
+
+- **Positive:** the domain stays ZGW-agnostic; ZGW knowledge is in one named place; defaults
+  are config (testable, env-specific, later editable via the beheer portal).
+- **Cost:** the ACL must be configured per environment (the seeded zaaktype URL, the
+  organisation RSINs). Missing/invalid config fails fast at the ACL boundary.
+- **Follow-ups:** mapping the BSN onto the zaak (eigenschap/rol), status transitions, and
+  documents are explicitly out of scope for S-04 and get their own slices.
+
+## Alternatives considered
+
+- **Defaults in the domain payload** — rejected: leaks ZGW concerns into the domain,
+  violating ADR-0001.
+- **Hardcoded defaults in code** — rejected: not env-specific, not operationally editable.

docs/architecture/adr-0004-bdd-framework.md

@@ -0,0 +1,52 @@
+# ADR-0004: Reqnroll as the BDD acceptance framework
+
+- **Status:** Accepted
+- **Date:** 2026-06-04
+- **Deciders:** Respellion engineering
+- **Relates to:** S-04 (#5); supports CLAUDE.md §3 (BDD at the use-case level) and §11 (tests pyramid)
+
+## Context
+
+CLAUDE.md §11 mandates that each user-visible flow is driven by a Gherkin acceptance
+scenario living in `tests/acceptance/`, and §3 names "BDD at the use-case level" as a core
+engineering principle. The foundational slices (S-00…S-03) added no acceptance layer; S-04
+is the first slice with real domain behaviour to drive, so it is where the BDD framework is
+introduced. We need a .NET tool that:
+
+- parses Gherkin `.feature` files and binds steps to C#,
+- integrates with the existing xUnit test runner (the repo standardises on xUnit), so
+  acceptance tests run under the same `dotnet test` / `make ci` gate as everything else,
+- is actively maintained on modern .NET (we target net10.0).
+
+## Decision
+
+**Use [Reqnroll](https://reqnroll.net/) (`Reqnroll.xUnit`) for acceptance tests.**
+
+- Reqnroll is the actively-maintained, open-source successor to SpecFlow (which is no longer
+  maintained). It keeps the same Gherkin + `[Binding]` model, so the knowledge transfers.
+- `Reqnroll.xUnit` generates one xUnit test per scenario, so acceptance tests are discovered
+  and run by the same runner as the unit tests — no second test framework, no extra CI step.
+- Acceptance projects live under `tests/acceptance/` per the PRD §9 layout. Generated
+  `*.feature.cs` files are build artefacts and are git-ignored.
+
+## Consequences
+
+- **Positive:** one assertion/runner stack (xUnit) across unit and acceptance tests; scenarios
+  are written in business language (Dutch domain terms inline) and reviewed as the slice's
+  contract; maintained tooling on net10.0.
+- **Cost:** a new dependency (`Reqnroll.xUnit`) and its xUnit v2 transitive graph. Reqnroll
+  pulls `xunit.core` but not the assertion library, so the `xunit` metapackage is referenced
+  explicitly to get `Assert`.
+- **Replaceable by:** hand-written xUnit "scenario" tests with a Given/When/Then helper, at
+  the cost of losing Gherkin as the shared, readable contract — which is the whole point of §3.
+- **Follow-ups:** the real-OpenZaak integration test (Testcontainers) and the Stryker mutation
+  baseline for S-04 are tracked as their own issues split off #5.
+
+## Alternatives considered
+
+- **SpecFlow** — rejected: unmaintained and without an official net10.0 story; Reqnroll is its
+  drop-in successor.
+- **Plain xUnit Given/When/Then helpers** — rejected for user-visible flows: loses the
+  business-readable Gherkin contract that §3/§11 require. Still fine for unit-level tests.
+- **Xunit.Gherkin.Quick** — rejected: lighter but less featureful (no hooks/scoped contexts,
+  smaller community) than Reqnroll.

docs/runbooks/flowable.md

@@ -0,0 +1,40 @@
+# Flowable runbook
+
+Flowable (`infra/flowable/docker-compose.yml`) runs the **flowable-rest** engine on
+Postgres. The `workflows/registratie.bpmn` model is deployed via the REST API at boot by
+the `flowable-init` container. Host port **:8090**; REST API under
+`http://localhost:8090/flowable-rest/service/` (basic auth **rest-admin / test**, dev only).
+
+## The model — `registratie`
+
+A minimal "Registratie ontvangen" process: **start → external-worker task
+`OpenZaakAanmaken` → end**. The external task is where the Workflow Client / ACL will
+later create the zaak in OpenZaak (S-04/S-05); for now a started instance parks there.
+
+## Quick test (`make`)
+
+```bash
+make flowable-up      # start engine + deploy registratie.bpmn on boot
+make flowable-smoke   # start + verify a new instance waits on the external task
+make flowable-down    # stop + wipe
+```
+
+`make flowable-smoke` runs `infra/flowable/verify.py`, which:
+1. waits for the `registratie` process definition to be deployed,
+2. starts an instance and asserts it did **not** end immediately,
+3. asserts an execution is parked at activity **`OpenZaakAanmaken`**,
+4. deletes the test instance.
+
+## Notes
+
+- **Deploy on boot** is idempotent: `flowable-init` skips if a deployment named
+  `registratie` already exists (so restarts on the same volume don't pile up versions).
+- **Dev creds:** `rest-admin` / `test`. Override via the flowable-rest app config for
+  anything beyond local dev.
+- **Image** `flowable/flowable-rest:latest` — pin a tag when stabilising.
+- Start an instance by hand:
+  ```bash
+  curl -s -u rest-admin:test -H 'Content-Type: application/json' \
+    -d '{"processDefinitionKey":"registratie"}' \
+    http://localhost:8090/flowable-rest/service/runtime/process-instances
+  ```

infra/flowable/docker-compose.yml

@@ -0,0 +1,65 @@
+# Flowable (S-03): the flowable-rest engine on Postgres.
+# The registratie.bpmn model is deployed via the REST API on startup by flowable-init.
+#
+#   docker compose -f infra/flowable/docker-compose.yml up -d
+#   # REST API (basic auth) under http://localhost:8090/flowable-rest/service/
+#
+# Host port 8090 (8000/8001/8080/8180 are taken by OpenZaak/NRC/BFF/Keycloak).
+services:
+  flowable-db:
+    image: docker.io/library/postgres:16
+    environment:
+      POSTGRES_USER: flowable
+      POSTGRES_PASSWORD: flowable
+      POSTGRES_DB: flowable
+    volumes:
+      - flowable-db:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U flowable -d flowable"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+    networks: [cg]
+
+  flowable-rest:
+    image: docker.io/flowable/flowable-rest:latest
+    environment:
+      SPRING_DATASOURCE_DRIVER-CLASS-NAME: org.postgresql.Driver
+      SPRING_DATASOURCE_URL: jdbc:postgresql://flowable-db:5432/flowable
+      SPRING_DATASOURCE_USERNAME: flowable
+      SPRING_DATASOURCE_PASSWORD: flowable
+    ports:
+      - "8090:8080"
+    depends_on:
+      flowable-db:
+        condition: service_healthy
+    networks: [cg]
+
+  # Deploys workflows/registratie.bpmn via the REST API once flowable-rest is up.
+  # Idempotent: skips if a deployment named "registratie" already exists.
+  flowable-init:
+    image: docker.io/curlimages/curl:latest
+    restart: "no"
+    volumes:
+      - ../../workflows/registratie.bpmn:/work/registratie.bpmn:ro,z
+    command:
+      - sh
+      - -c
+      - |
+        base=http://flowable-rest:8080/flowable-rest/service/repository/deployments
+        until curl -sf -u rest-admin:test "$$base" >/dev/null 2>&1; do echo "waiting for flowable-rest..."; sleep 3; done
+        if curl -s -u rest-admin:test "$$base?name=registratie" | grep -q '"name":"registratie"'; then
+          echo "registratie already deployed; skip"
+        else
+          curl -sf -u rest-admin:test -F 'file=@/work/registratie.bpmn;filename=registratie.bpmn' "$$base" >/dev/null && echo "deployed registratie"
+        fi
+    depends_on:
+      flowable-rest:
+        condition: service_started
+    networks: [cg]
+
+volumes:
+  flowable-db:
+
+networks:
+  cg:

infra/flowable/verify.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""Smoke-check Flowable: the registratie process is deployed, and starting an
+instance parks it on the OpenZaakAanmaken external task. Stdlib only.
+"""
+import base64, json, sys, time, urllib.error, urllib.request
+
+BASE = "http://localhost:8090/flowable-rest/service"
+AUTH = "Basic " + base64.b64encode(b"rest-admin:test").decode()
+
+
+def call(method, path, payload=None):
+    data = json.dumps(payload).encode() if payload is not None else None
+    req = urllib.request.Request(BASE + path, data=data, method=method, headers={
+        "Authorization": AUTH, "Content-Type": "application/json", "Accept": "application/json"})
+    with urllib.request.urlopen(req, timeout=30) as r:
+        return r.status, json.loads(r.read() or "null")
+
+
+def main():
+    # 1. process definition deployed? (wait for the async init-container deploy)
+    defs = {"total": 0}
+    for _ in range(40):
+        _, defs = call("GET", "/repository/process-definitions?key=registratie")
+        if defs["total"] >= 1:
+            break
+        time.sleep(3)
+    assert defs["total"] >= 1, "registratie process definition not deployed"
+    print(f"process definition 'registratie' deployed (total={defs['total']})")
+
+    # 2. start an instance
+    st, pi = call("POST", "/runtime/process-instances", {"processDefinitionKey": "registratie"})
+    assert st == 201, f"start failed: {st} {pi}"
+    pid = pi["id"]
+    assert pi.get("ended") is False, "instance ended immediately — external task not reached"
+    print(f"started instance {pid} (ended={pi.get('ended')})")
+
+    # 3. waiting on the external task?
+    _, ex = call("GET", f"/runtime/executions?processInstanceId={pid}")
+    activities = [e.get("activityId") for e in ex["data"]]
+    assert "OpenZaakAanmaken" in activities, f"not waiting at OpenZaakAanmaken: {activities}"
+    print(f"instance is waiting at the external task: {activities}")
+
+    # 4. cleanup
+    try:
+        call("DELETE", f"/runtime/process-instances/{pid}")
+        print("cleaned up instance")
+    except urllib.error.HTTPError:
+        pass
+
+    print("flowable smoke OK")
+
+
+if __name__ == "__main__":
+    main()

mkdocs.yml

@@ -23,6 +23,9 @@ nav:
   - Product Requirements: PRD.md
   - Architecture:
       - "ADR-0001: Loose coupling": architecture/adr-0001-loose-coupling.md
+      - "ADR-0002: Catalogus design": architecture/adr-0002-catalogus-design.md
+      - "ADR-0003: ACL default-fill": architecture/adr-0003-default-fill.md
+      - "ADR-0004: BDD framework": architecture/adr-0004-bdd-framework.md
   - Working in Gitea: gitea-workflow.md
   - Runbooks:
       - CI: runbooks/ci.md

register-referentie.slnx

@@ -0,0 +1,16 @@
+<Solution>
+  <Folder Name="/services/" />
+  <Folder Name="/services/acl/">
+    <Project Path="services/acl/Acl.Api/Acl.Api.csproj" />
+    <Project Path="services/acl/Acl.Application/Acl.Application.csproj" />
+    <Project Path="services/acl/Acl.Infrastructure/Acl.Infrastructure.csproj" />
+    <Project Path="services/acl/Acl.Tests/Acl.Tests.csproj" />
+  </Folder>
+  <Folder Name="/services/bff/">
+    <Project Path="services/bff/Bff.Api/Bff.Api.csproj" />
+    <Project Path="services/bff/Bff.Tests/Bff.Tests.csproj" />
+  </Folder>
+  <Folder Name="/tests/">
+    <Project Path="tests/acceptance/Acceptance.csproj" />
+  </Folder>
+</Solution>

services/acl/Acl.Api/Acl.Api.csproj

@@ -0,0 +1,14 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <ItemGroup>
+    <ProjectReference Include="..\Acl.Application\Acl.Application.csproj" />
+    <ProjectReference Include="..\Acl.Infrastructure\Acl.Infrastructure.csproj" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+</Project>

services/acl/Acl.Api/Program.cs

@@ -0,0 +1,31 @@
+using Acl.Application;
+using Acl.Infrastructure;
+
+var builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddSingleton<IClock, SystemClock>();
+builder.Services.AddSingleton(sp => sp.GetRequiredService<IConfiguration>()
+    .GetSection("Acl:Defaults").Get<AclDefaults>()
+    ?? throw new InvalidOperationException("Missing configuration section 'Acl:Defaults'"));
+builder.Services.AddSingleton(sp => sp.GetRequiredService<IConfiguration>()
+    .GetSection("Acl:OpenZaak").Get<OpenZaakOptions>()
+    ?? throw new InvalidOperationException("Missing configuration section 'Acl:OpenZaak'"));
+builder.Services.AddHttpClient<IZaakGateway, OpenZaakGateway>();
+builder.Services.AddScoped<AclService>();
+
+var app = builder.Build();
+
+app.MapGet("/health", () => "Healthy");
+
+// The ACL's single operation, exposed as a service endpoint.
+app.MapPost("/zaken", async (OpenZaakRequest body, AclService acl, CancellationToken ct) =>
+{
+    var zaakUrl = await acl.OpenZaakAsync(new DomainRegistration(body.Bsn), ct);
+    return Results.Ok(new { zaakUrl = zaakUrl.ToString() });
+});
+
+app.Run();
+
+public sealed record OpenZaakRequest(string Bsn);
+
+public partial class Program;

services/acl/Acl.Api/Properties/launchSettings.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:5041",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:7260;http://localhost:5041",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

services/acl/Acl.Api/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

services/acl/Acl.Api/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}

services/acl/Acl.Application/Acl.Application.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+</Project>

services/acl/Acl.Application/AclDefaults.cs

@@ -0,0 +1,10 @@
+namespace Acl.Application;
+
+/// <summary>Configured ZGW defaults the ACL fills in (ADR-0003).</summary>
+public sealed class AclDefaults
+{
+    public required string Bronorganisatie { get; init; }
+    public required string VerantwoordelijkeOrganisatie { get; init; }
+    public required string Vertrouwelijkheidaanduiding { get; init; }
+    public required Uri ZaaktypeUrl { get; init; }
+}

services/acl/Acl.Application/AclService.cs

@@ -0,0 +1,20 @@
+namespace Acl.Application;
+
+/// <summary>The ACL's single operation: open a zaak from a domain payload,
+/// default-filling the ZGW-mandatory fields (ADR-0003).</summary>
+public sealed class AclService(IZaakGateway gateway, AclDefaults defaults, IClock clock)
+{
+    public Task<Uri> OpenZaakAsync(DomainRegistration registration, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(registration);
+
+        var request = new ZaakRequest(
+            defaults.Bronorganisatie,
+            defaults.VerantwoordelijkeOrganisatie,
+            defaults.Vertrouwelijkheidaanduiding,
+            defaults.ZaaktypeUrl,
+            clock.Today);
+
+        return gateway.OpenZaakAsync(request, ct);
+    }
+}

services/acl/Acl.Application/DomainRegistration.cs

@@ -0,0 +1,4 @@
+namespace Acl.Application;
+
+/// <summary>Domain-language payload handed to the ACL. No ZGW concepts here.</summary>
+public sealed record DomainRegistration(string Bsn);

services/acl/Acl.Application/IClock.cs

@@ -0,0 +1,7 @@
+namespace Acl.Application;
+
+/// <summary>Abstracts "today" so startdatum default-fill is deterministic in tests.</summary>
+public interface IClock
+{
+    DateOnly Today { get; }
+}

services/acl/Acl.Application/IZaakGateway.cs

@@ -0,0 +1,8 @@
+namespace Acl.Application;
+
+/// <summary>Port to the ZGW Zaken API. Implemented in Infrastructure — the only
+/// code that talks to OpenZaak (ADR-0001).</summary>
+public interface IZaakGateway
+{
+    Task<Uri> OpenZaakAsync(ZaakRequest request, CancellationToken ct = default);
+}

services/acl/Acl.Application/ZaakRequest.cs

@@ -0,0 +1,9 @@
+namespace Acl.Application;
+
+/// <summary>The fully default-filled zaak the gateway will create in OpenZaak.</summary>
+public sealed record ZaakRequest(
+    string Bronorganisatie,
+    string VerantwoordelijkeOrganisatie,
+    string Vertrouwelijkheidaanduiding,
+    Uri Zaaktype,
+    DateOnly Startdatum);

services/acl/Acl.Infrastructure/Acl.Infrastructure.csproj

@@ -0,0 +1,13 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <ItemGroup>
+    <ProjectReference Include="..\Acl.Application\Acl.Application.csproj" />
+  </ItemGroup>
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+</Project>

services/acl/Acl.Infrastructure/OpenZaakGateway.cs

@@ -0,0 +1,48 @@
+using System.Net.Http.Headers;
+using System.Net.Http.Json;
+using System.Text.Json.Serialization;
+using Acl.Application;
+
+namespace Acl.Infrastructure;
+
+/// <summary>The only code that talks to OpenZaak's Zaken API (ADR-0001).</summary>
+public sealed class OpenZaakGateway(HttpClient http, OpenZaakOptions options) : IZaakGateway
+{
+    public async Task<Uri> OpenZaakAsync(ZaakRequest request, CancellationToken ct = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+
+        using var message = new HttpRequestMessage(
+            HttpMethod.Post, new Uri(options.BaseUrl, "/zaken/api/v1/zaken"))
+        {
+            Content = JsonContent.Create(new ZaakDto(
+                request.Bronorganisatie,
+                request.Zaaktype.ToString(),
+                request.VerantwoordelijkeOrganisatie,
+                request.Startdatum.ToString("yyyy-MM-dd"),
+                request.Vertrouwelijkheidaanduiding)),
+        };
+        message.Headers.Authorization =
+            new AuthenticationHeaderValue("Bearer", ZgwToken.Mint(options.ClientId, options.Secret));
+        // ZRC is a geo API; it requires the CRS headers.
+        message.Headers.Add("Accept-Crs", "EPSG:4326");
+        message.Content.Headers.Add("Content-Crs", "EPSG:4326");
+
+        using var response = await http.SendAsync(message, ct);
+        response.EnsureSuccessStatusCode();
+
+        var created = await response.Content.ReadFromJsonAsync<ZaakCreatedDto>(ct)
+            ?? throw new InvalidOperationException("OpenZaak returned an empty zaak response");
+        return new Uri(created.Url);
+    }
+
+    private sealed record ZaakDto(
+        [property: JsonPropertyName("bronorganisatie")] string Bronorganisatie,
+        [property: JsonPropertyName("zaaktype")] string Zaaktype,
+        [property: JsonPropertyName("verantwoordelijkeOrganisatie")] string VerantwoordelijkeOrganisatie,
+        [property: JsonPropertyName("startdatum")] string Startdatum,
+        [property: JsonPropertyName("vertrouwelijkheidaanduiding")] string Vertrouwelijkheidaanduiding);
+
+    private sealed record ZaakCreatedDto(
+        [property: JsonPropertyName("url")] string Url);
+}

services/acl/Acl.Infrastructure/OpenZaakOptions.cs

@@ -0,0 +1,9 @@
+namespace Acl.Infrastructure;
+
+/// <summary>Connection + credential config for OpenZaak's ZGW APIs.</summary>
+public sealed class OpenZaakOptions
+{
+    public required Uri BaseUrl { get; init; }
+    public required string ClientId { get; init; }
+    public required string Secret { get; init; }
+}

services/acl/Acl.Infrastructure/SystemClock.cs

@@ -0,0 +1,8 @@
+using Acl.Application;
+
+namespace Acl.Infrastructure;
+
+public sealed class SystemClock : IClock
+{
+    public DateOnly Today => DateOnly.FromDateTime(DateTime.UtcNow);
+}

services/acl/Acl.Infrastructure/ZgwToken.cs

@@ -0,0 +1,29 @@
+using System.Security.Cryptography;
+using System.Text;
+using System.Text.Json;
+
+namespace Acl.Infrastructure;
+
+/// <summary>Mints a ZGW (vng-api-common) JWT: HS256 over the standard claims.</summary>
+internal static class ZgwToken
+{
+    public static string Mint(string clientId, string secret)
+    {
+        var header = B64Url(JsonSerializer.SerializeToUtf8Bytes(new { alg = "HS256", typ = "JWT" }));
+        var payload = B64Url(JsonSerializer.SerializeToUtf8Bytes(new
+        {
+            iss = clientId,
+            iat = DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
+            client_id = clientId,
+            user_id = "acl",
+            user_representation = "acl",
+        }));
+        var signingInput = $"{header}.{payload}";
+        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
+        var signature = B64Url(hmac.ComputeHash(Encoding.UTF8.GetBytes(signingInput)));
+        return $"{signingInput}.{signature}";
+    }
+
+    private static string B64Url(byte[] bytes) =>
+        Convert.ToBase64String(bytes).TrimEnd('=').Replace('+', '-').Replace('/', '_');
+}

services/acl/Acl.Tests/Acl.Tests.csproj

@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" Version="6.0.4" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageReference Include="xunit" Version="2.9.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Using Include="Xunit" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\Acl.Application\Acl.Application.csproj" />
+    <ProjectReference Include="..\Acl.Infrastructure\Acl.Infrastructure.csproj" />
+  </ItemGroup>
+
+</Project>

services/acl/Acl.Tests/AclServiceTests.cs

@@ -0,0 +1,47 @@
+using Acl.Application;
+
+namespace Acl.Tests;
+
+public class AclServiceTests
+{
+    private sealed class FakeGateway : IZaakGateway
+    {
+        public ZaakRequest? Captured;
+        public Uri Result { get; } = new("http://openzaak/zaken/api/v1/zaken/abc");
+
+        public Task<Uri> OpenZaakAsync(ZaakRequest request, CancellationToken ct = default)
+        {
+            Captured = request;
+            return Task.FromResult(Result);
+        }
+    }
+
+    private sealed class FixedClock(DateOnly today) : IClock
+    {
+        public DateOnly Today { get; } = today;
+    }
+
+    [Fact]
+    public async Task Opening_a_zaak_default_fills_zgw_fields_and_returns_the_zaak_url()
+    {
+        var gateway = new FakeGateway();
+        var defaults = new AclDefaults
+        {
+            Bronorganisatie = "517439943",
+            VerantwoordelijkeOrganisatie = "517439943",
+            Vertrouwelijkheidaanduiding = "openbaar",
+            ZaaktypeUrl = new("http://openzaak/catalogi/api/v1/zaaktypen/big"),
+        };
+        var service = new AclService(gateway, defaults, new FixedClock(new DateOnly(2026, 6, 4)));
+
+        var url = await service.OpenZaakAsync(new DomainRegistration("123456782"));
+
+        Assert.Equal(gateway.Result, url);
+        var req = Assert.IsType<ZaakRequest>(gateway.Captured);
+        Assert.Equal("517439943", req.Bronorganisatie);
+        Assert.Equal("517439943", req.VerantwoordelijkeOrganisatie);
+        Assert.Equal("openbaar", req.Vertrouwelijkheidaanduiding);
+        Assert.Equal(defaults.ZaaktypeUrl, req.Zaaktype);
+        Assert.Equal(new DateOnly(2026, 6, 4), req.Startdatum);
+    }
+}

services/acl/Acl.Tests/OpenZaakGatewayTests.cs

@@ -0,0 +1,51 @@
+using System.Net;
+using System.Net.Http.Json;
+using Acl.Application;
+using Acl.Infrastructure;
+
+namespace Acl.Tests;
+
+public class OpenZaakGatewayTests
+{
+    private sealed class StubHandler(Func<HttpRequestMessage, Task<HttpResponseMessage>> onSend)
+        : HttpMessageHandler
+    {
+        protected override Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken ct)
+            => onSend(request);
+    }
+
+    [Fact]
+    public async Task Posts_zaak_to_openzaak_with_bearer_and_default_fields_and_returns_url()
+    {
+        HttpRequestMessage? seen = null;
+        string? body = null;
+        var handler = new StubHandler(async req =>
+        {
+            seen = req;
+            body = await req.Content!.ReadAsStringAsync();
+            return new HttpResponseMessage(HttpStatusCode.Created)
+            {
+                Content = JsonContent.Create(new { url = "http://openzaak/zaken/api/v1/zaken/xyz" }),
+            };
+        });
+        var gateway = new OpenZaakGateway(
+            new HttpClient(handler),
+            new OpenZaakOptions { BaseUrl = new("http://openzaak"), ClientId = "cid", Secret = "sec" });
+        var request = new ZaakRequest(
+            "517439943", "517439943", "openbaar",
+            new("http://openzaak/catalogi/api/v1/zaaktypen/big"), new DateOnly(2026, 6, 4));
+
+        var url = await gateway.OpenZaakAsync(request);
+
+        Assert.Equal("http://openzaak/zaken/api/v1/zaken/xyz", url.ToString());
+        Assert.Equal(HttpMethod.Post, seen!.Method);
+        Assert.Equal("http://openzaak/zaken/api/v1/zaken", seen.RequestUri!.ToString());
+        Assert.Equal("Bearer", seen.Headers.Authorization!.Scheme);
+        Assert.False(string.IsNullOrWhiteSpace(seen.Headers.Authorization.Parameter));
+        Assert.Contains("\"bronorganisatie\":\"517439943\"", body);
+        Assert.Contains("\"verantwoordelijkeOrganisatie\":\"517439943\"", body);
+        Assert.Contains("\"vertrouwelijkheidaanduiding\":\"openbaar\"", body);
+        Assert.Contains("\"startdatum\":\"2026-06-04\"", body);
+        Assert.Contains("\"zaaktype\":\"http://openzaak/catalogi/api/v1/zaaktypen/big\"", body);
+    }
+}

services/acl/Acl.slnx

@@ -0,0 +1,6 @@
+<Solution>
+  <Project Path="Acl.Api/Acl.Api.csproj" />
+  <Project Path="Acl.Application/Acl.Application.csproj" />
+  <Project Path="Acl.Infrastructure/Acl.Infrastructure.csproj" />
+  <Project Path="Acl.Tests/Acl.Tests.csproj" />
+</Solution>

tests/acceptance/Acceptance.csproj

@@ -0,0 +1,23 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsPackable>false</IsPackable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="coverlet.collector" Version="6.0.4" />
+    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />
+    <PackageReference Include="Reqnroll.xUnit" Version="3.3.4" />
+    <PackageReference Include="xunit" Version="2.9.3" />
+    <PackageReference Include="xunit.runner.visualstudio" Version="3.1.4" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\services\acl\Acl.Application\Acl.Application.csproj" />
+    <ProjectReference Include="..\..\services\acl\Acl.Infrastructure\Acl.Infrastructure.csproj" />
+  </ItemGroup>
+
+</Project>

tests/acceptance/Features/EenZaakOpenen.feature

@@ -0,0 +1,27 @@
+# language: en
+# Drives S-04 (#5). The ACL is the only code that talks to ZGW (ADR-0001); it
+# default-fills the ZGW-mandatory zaak fields the domain never sees (ADR-0003).
+# Real-OpenZaak verification is a separate slice — this scenario exercises the
+# use case against an in-memory stand-in for the Zaken API.
+Feature: Een zaak openen vanuit een registratie
+  Als domein wil ik de ACL vragen een zaak te openen
+  zodat de ZGW-verplichte velden worden ingevuld zonder dat het domein ze kent.
+
+  Scenario: De ACL vult de ZGW-verplichte velden default in
+    Given a domain registration for BSN "123456782"
+    And the ACL is configured with these defaults:
+      | field                        | value                                         |
+      | bronorganisatie              | 517439943                                     |
+      | verantwoordelijkeOrganisatie | 517439943                                     |
+      | vertrouwelijkheidaanduiding  | openbaar                                      |
+      | zaaktype                     | http://openzaak/catalogi/api/v1/zaaktypen/big |
+    And today is "2026-06-04"
+    When the domain asks the ACL to open a zaak
+    Then a zaak is created with these default-filled fields
+      | field                        | value                                         |
+      | bronorganisatie              | 517439943                                     |
+      | verantwoordelijkeOrganisatie | 517439943                                     |
+      | vertrouwelijkheidaanduiding  | openbaar                                      |
+      | zaaktype                     | http://openzaak/catalogi/api/v1/zaaktypen/big |
+      | startdatum                   | 2026-06-04                                    |
+    And the ACL returns the URL of the created zaak

tests/acceptance/Steps/EenZaakOpenenSteps.cs

@@ -0,0 +1,65 @@
+using Acceptance.Support;
+using Acl.Application;
+using Reqnroll;
+using Xunit;
+
+namespace Acceptance.Steps;
+
+/// <summary>Bindings for <c>EenZaakOpenen.feature</c>. Reqnroll creates one
+/// instance per scenario, so instance fields hold scenario-scoped state.</summary>
+[Binding]
+public sealed class EenZaakOpenenSteps
+{
+    private readonly InMemoryZaakGateway _gateway = new();
+    private DomainRegistration? _registration;
+    private AclDefaults? _defaults;
+    private DateOnly _today;
+    private Uri? _returnedUrl;
+
+    [Given("a domain registration for BSN \"(.*)\"")]
+    public void GivenADomainRegistrationForBsn(string bsn)
+        => _registration = new DomainRegistration(bsn);
+
+    [Given("the ACL is configured with these defaults:")]
+    public void GivenTheAclIsConfiguredWithTheseDefaults(DataTable defaults)
+    {
+        var values = ToFieldMap(defaults);
+        _defaults = new AclDefaults
+        {
+            Bronorganisatie = values["bronorganisatie"],
+            VerantwoordelijkeOrganisatie = values["verantwoordelijkeOrganisatie"],
+            Vertrouwelijkheidaanduiding = values["vertrouwelijkheidaanduiding"],
+            ZaaktypeUrl = new Uri(values["zaaktype"]),
+        };
+    }
+
+    [Given("today is \"(.*)\"")]
+    public void GivenTodayIs(string date)
+        => _today = DateOnly.Parse(date);
+
+    [When("the domain asks the ACL to open a zaak")]
+    public async Task WhenTheDomainAsksTheAclToOpenAZaak()
+    {
+        var service = new AclService(_gateway, _defaults!, new FixedClock(_today));
+        _returnedUrl = await service.OpenZaakAsync(_registration!);
+    }
+
+    [Then("a zaak is created with these default-filled fields")]
+    public void ThenAZaakIsCreatedWithTheseDefaultFilledFields(DataTable expected)
+    {
+        var request = Assert.IsType<ZaakRequest>(_gateway.Captured);
+        var fields = ToFieldMap(expected);
+        Assert.Equal(fields["bronorganisatie"], request.Bronorganisatie);
+        Assert.Equal(fields["verantwoordelijkeOrganisatie"], request.VerantwoordelijkeOrganisatie);
+        Assert.Equal(fields["vertrouwelijkheidaanduiding"], request.Vertrouwelijkheidaanduiding);
+        Assert.Equal(fields["zaaktype"], request.Zaaktype.ToString());
+        Assert.Equal(fields["startdatum"], request.Startdatum.ToString("yyyy-MM-dd"));
+    }
+
+    [Then("the ACL returns the URL of the created zaak")]
+    public void ThenTheAclReturnsTheUrlOfTheCreatedZaak()
+        => Assert.Equal(InMemoryZaakGateway.CreatedZaakUrl, _returnedUrl);
+
+    private static Dictionary<string, string> ToFieldMap(DataTable table)
+        => table.Rows.ToDictionary(r => r["field"], r => r["value"]);
+}

tests/acceptance/Support/FixedClock.cs

@@ -0,0 +1,10 @@
+using Acl.Application;
+
+namespace Acceptance.Support;
+
+/// <summary>A clock pinned to a known date so <c>startdatum</c> is deterministic
+/// in scenarios (ADR-0003).</summary>
+public sealed class FixedClock(DateOnly today) : IClock
+{
+    public DateOnly Today { get; } = today;
+}

tests/acceptance/Support/InMemoryZaakGateway.cs

@@ -0,0 +1,20 @@
+using Acl.Application;
+
+namespace Acceptance.Support;
+
+/// <summary>An in-memory stand-in for the OpenZaak Zaken API. It captures the
+/// fully default-filled <see cref="ZaakRequest"/> the ACL builds and returns a
+/// fixed zaak URL, so the acceptance scenario can verify the use case without a
+/// running OpenZaak (real-OpenZaak verification is a separate slice).</summary>
+public sealed class InMemoryZaakGateway : IZaakGateway
+{
+    public static readonly Uri CreatedZaakUrl = new("http://openzaak/zaken/api/v1/zaken/created-123");
+
+    public ZaakRequest? Captured { get; private set; }
+
+    public Task<Uri> OpenZaakAsync(ZaakRequest request, CancellationToken ct = default)
+    {
+        Captured = request;
+        return Task.FromResult(CreatedZaakUrl);
+    }
+}

workflows/registratie.bpmn

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<definitions xmlns="http://www.omg.org/spec/BPMN/20100524/MODEL"
+             xmlns:flowable="http://flowable.org/bpmn"
+             xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI"
+             xmlns:omgdc="http://www.omg.org/spec/DD/20100524/DC"
+             xmlns:omgdi="http://www.omg.org/spec/DD/20100524/DI"
+             targetNamespace="http://respellion.nl/big">
+
+  <!-- S-03: minimal "Registratie ontvangen" flow.
+       start -> external-worker task (OpenZaakAanmaken) -> end.
+       The external task is handled by the Workflow Client / ACL in later slices. -->
+  <process id="registratie" name="Registratie ontvangen" isExecutable="true">
+
+    <startEvent id="start" name="Registratie ontvangen"/>
+
+    <sequenceFlow id="flow1" sourceRef="start" targetRef="OpenZaakAanmaken"/>
+
+    <serviceTask id="OpenZaakAanmaken" name="OpenZaak aanmaken"
+                 flowable:type="external-worker"
+                 flowable:topic="OpenZaakAanmaken"/>
+
+    <sequenceFlow id="flow2" sourceRef="OpenZaakAanmaken" targetRef="end"/>
+
+    <endEvent id="end" name="Zaak aangemaakt"/>
+  </process>
+
+  <bpmndi:BPMNDiagram id="diagram">
+    <bpmndi:BPMNPlane id="plane" bpmnElement="registratie">
+      <bpmndi:BPMNShape id="s_start" bpmnElement="start">
+        <omgdc:Bounds x="100" y="100" width="30" height="30"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="s_task" bpmnElement="OpenZaakAanmaken">
+        <omgdc:Bounds x="200" y="85" width="120" height="60"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="s_end" bpmnElement="end">
+        <omgdc:Bounds x="400" y="100" width="30" height="30"/>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNEdge id="e_flow1" bpmnElement="flow1">
+        <omgdi:waypoint x="130" y="115"/>
+        <omgdi:waypoint x="200" y="115"/>
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="e_flow2" bpmnElement="flow2">
+        <omgdi:waypoint x="320" y="115"/>
+        <omgdi:waypoint x="400" y="115"/>
+      </bpmndi:BPMNEdge>
+    </bpmndi:BPMNPlane>
+  </bpmndi:BPMNDiagram>
+</definitions>