fix(infra): compare the gate's service sets, not their counts

Second review round on the PR. Nine findings were real; four were not, and
are listed at the bottom with what settled them.

**The readiness gate could pass a stack missing a declared service.** Its
exit condition was `no unhealthy rows && observed == declared`. One service
never created plus one orphan still running gives equal counts, so the gate
broke out reporting success. I added the missing/extra sets in the previous
commit for the diagnostic message and left the exit test on counts — the
sets were computed one branch too late to be used for the decision.

Proven on a live stack rather than argued: `meilisearch` removed, a healthy
orphan `ghost` created by Compose itself under the same project, 14 observed
against 14 declared, everything else green. Old condition → `exit 0`, "All
compose services running; every healthcheck green". New condition → `exit 1`,
"saw 14 of 14 declared services; never created: meilisearch; orphaned
(docker compose down --remove-orphans): ghost". Healthy stack still exits 0.

Getting that proof took two false starts worth recording, both the same
shape as everything else this branch has been fixing. A hand-built orphan
carrying Compose's labels is not counted by `docker compose ps`, so the
scenario I first "reproduced" never existed. Then the old-condition copy ran
from the scratchpad, where `REPO_ROOT` resolves relative to `BASH_SOURCE`, so
it inspected an empty directory and failed for a reason that had nothing to do
with the condition under test.

**`TenantContextBehavior`'s comment described RLS as working.** It read "they
are issued by `TransactionBehavior` at step 6". `grep -rn "set_config\|SET LOCAL"
backend/src` returns nothing: no code in this repository sets the GUCs, and
RLS is not enforced at runtime until Packet 7. The reasoning about *why* the
GUCs belong inside the transaction is correct and stays; the tense does not.

**ADR-0032's registration sample was still missing its guards** — the three
`ArgumentNullException`/`ArgumentException` lines the shipped
`ProviderResilienceRegistration` opens with. This is the same fence whose
earlier comparison reported "13 lines, zero differences" because the
normaliser dropped exactly the `ArgumentNullException` lines. The skill's copy
has them; the ADR's did not. Recorded in Amendment 2; § Decision is
byte-identical to `main` (same md5).

**Phase 01's defect list said "All of these were remediated".** One of its six
entries is branch protection, which was *deferred by maintainer decision*, not
fixed. Now scoped, with the trigger named.

**`DROP DATABASE keycloak` was documented with Keycloak still running.**
PostgreSQL refuses to drop a database with a connected client, and Keycloak
holds its pool for its whole lifetime. Stop first, `up -d` after.

**`local-dev-setup` grew a fifth copy of the service inventory.** The previous
commit rebuilt that table from `docker compose config` — accurate, and a second
source of truth next to `infra/compose/README.md`, which carries image,
endpoint and credentials for every service. Replaced with a link plus the three
facts a reader setting up actually needs from it.

Also: both canonical producer fences dropped `CohortId`, a field the command
carries and the event declares, so anyone copying either silently lost it;
README's "two images cannot carry one" conflated the gate's input (Compose
service definitions) with the reason (`daprio/placement` and `daprio/daprd`
ship a single binary on an empty base), and now names both.

**The three new Standards 12 sections cite their derivation** — ADR-0002 for
the compose-stack rules, ADR-0035 for development credentials. I did not mint
an ADR: these tighten how an existing decision is operated rather than deciding
anything new, and the file already derives from six ADRs. If you want a
dedicated record for the dev-loop hygiene rules, that is your call to make.
My own check caught that I had cited a "§ Network Exposure" heading that does
not exist in Standards 11; it points at § Transport now.

Not changed, with the reason:

- **Convert the adapter's `text` flow diagram to mermaid.** CLAUDE.md's mermaid
  rule governs documentation diagrams and requires a readable text fallback —
  which is what this fence already is. Three skills use `text` flows and one
  uses mermaid; converting one of the three makes the corpus less consistent,
  not more. A sweep is its own change.
- **Rewrite ADR-0017's remaining Identity references.** Deliberate. Amendment 2
  carries the correction and dated banners sit above each stale passage; the
  body below them is the record of what was decided in May. Editing it would
  undo the governance choice the amendment exists to express.
- **"`List<Entity<CourseId>>.Contains(b)` should say same-id true, different-id
  false."** The sentence is describing the *defect* a sneaky explicit
  re-implementation produces — `Contains` answering true for different ids —
  which is the measured behaviour the entry exists to warn about. Correct as
  written.
- **Add `.env` as a prerequisite to `down` / `clean` / `logs` / `ps`.** Those
  targets work without it: every compose variable has a `${VAR:-default}`
  fallback and the project name is a literal in `dev.yml`. Creating a file as
  a side effect of tearing down is worse than the inconsistency.

227 tests green, build 0/0, format clean, 1337 links resolve, gate exercised
against a live 14-service stack and torn down.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: cemililik

.claude/skills/add-integration-event/SKILL.md

@@ -87,6 +87,7 @@ await outbox.EnqueueAsync(new EnrollmentCreatedIntegrationEventV1
     EnrollmentId = enrollment.Id.Value,
     LearnerId = request.LearnerId.Value,
     CourseVersionId = request.CourseVersionId.Value,
+    CohortId = request.CohortId?.Value,
     Source = request.Source.ToString().ToLowerInvariant(),
 }, cancellationToken);
 

.claude/skills/add-mediatr-handler/SKILL.md

@@ -150,6 +150,7 @@ public sealed class CreateEnrollmentCommandHandler(
             EnrollmentId = enrollment.Id.Value,
             LearnerId = request.LearnerId.Value,
             CourseVersionId = request.CourseVersionId.Value,
+            CohortId = request.CohortId?.Value,
             // OccurredAt is auto-populated by IntegrationEventBase — do not set
             // it manually. If you need it explicitly, inject IClock and use
             // clock.UtcNow per 02-backend-coding.md § Time.

.claude/skills/local-dev-setup/SKILL.md

@@ -105,34 +105,28 @@ What `make dev` expands to:
 docker compose --env-file .env -f infra/compose/dev.yml up -d
 ```
 
-The components and their default ports:
-
-| Component | Published port(s) | Purpose |
-|-----------|-------------------|---------|
-| Postgres | 5432 | Main DB. |
-| Valkey | 6379 | Cache + Dapr state. |
-| Kafka | *(none)* | Dapr pub/sub backend. Reached over the compose network only — nothing on the host speaks to it directly. |
-| Kafka UI | 8081 | Optional UI for topics. |
-| Vault (dev mode) | 8200 | Secrets backend; dev root token, **not** for production. |
-| Keycloak | 8080 | Two realms: `learnstack` (tenants) + `learnstack-hub` (operators). |
-| SeaweedFS | 9000 (S3 API) / 9001 (filer UI) / 9333 (master) / 8084 | Object storage (single dev binary: master + volume + filer + S3 gateway). |
-| Meilisearch | 7700 | Search. |
-| LiveKit | 7880 (API) / 7881 (TLS) / 7882 (RTC) / 50000-50100 (UDP media) | Live classroom. |
-| coturn | 3478 (UDP+TCP) / 5349 / 49152-49200 (UDP relay) | TURN for LiveKit. |
-| Mailpit | 8025 (UI) / 1025 (SMTP) | Captures outbound email in dev. |
-| Dapr sidecar (api) | 3500 (HTTP) / 50001 (gRPC) | Building-block runtime. |
-| Dapr placement | *(none)* | Actor placement; compose network only. |
-| APISIX | 9080 (HTTP gateway) / 9443 (HTTPS) / 9091 (Prometheus metrics) | File-driven standalone (`data_plane`) per ADR-0015 — no Admin API, no dashboard companion. `apisix.yaml` is the only source of truth. |
-
-Every one of these binds to `127.0.0.1`, never `0.0.0.0` — see
-[Infrastructure Standards § Published ports](../../../docs/standards/12-infrastructure.md).
-Regenerate the table from the stack itself rather than by hand —
-`docker compose --env-file .env -f infra/compose/dev.yml config --format json`
-is the source of truth.
-
-Neither application host is a compose service. `LearnStack.Api` runs on the
-workstation via `dotnet run` on the `ASPNETCORE_URLS` port in `.env.example`
-(5080), and `apps/web` runs via `pnpm dev` on 3000.
+The canonical service inventory — image, local endpoint and default credentials
+for every service in the stack — lives in
+[`infra/compose/README.md`](../../../infra/compose/README.md), grouped by the
+Phase 01 packet that introduced each one. It is not repeated here; a second copy
+is a second thing to keep true, and this file has no way to notice when
+`dev.yml` changes.
+
+Three properties of that inventory matter while you are setting up:
+
+- **Every published port binds `127.0.0.1`, never `0.0.0.0`** — see
+  [Infrastructure Standards § Published ports](../../../docs/standards/12-infrastructure.md).
+- **Kafka and the Dapr placement service publish nothing.** They are reached
+  over the compose network only; nothing on the host speaks to them directly.
+- **Neither application host is a compose service.** `LearnStack.Api` runs on
+  the workstation via `dotnet run` on the `ASPNETCORE_URLS` port in
+  `.env.example` (5080), and `apps/web` runs via `pnpm dev` on 3000.
+
+To read the resolved truth rather than any document, ask the stack:
+
+```bash
+docker compose --env-file .env -f infra/compose/dev.yml config --format json
+```
 
 ### Step 4: First-run bootstrap
 

README.md

@@ -73,8 +73,11 @@ make dev       # bring local stack up
 make seed      # verify health + print demo credentials
 ```
 
-> `make seed` exits 0 on a clean stack. The health gate used to time out on every run —
-> it flagged any service with no healthcheck, and two images cannot carry one.
+> `make seed` exits 0 on a clean stack. The health gate used to time out on every run:
+> it read every service's `healthcheck:` block in the Compose file and flagged any
+> service that declared none, but `dapr-placement` and `dapr-sidecar-api` cannot
+> declare one — their images ship a single binary on an empty base, with no shell
+> and no `wget`/`curl`/`nc` to probe with.
 > [Phase 02a Packet 3b](docs/roadmap/phase-02a-kernel-tenancy.md) repaired that along
 > with the rest of the Phase 01 development-loop debt.
 

backend/src/LearnStack.Application/Pipeline/TenantContextBehavior.cs

@@ -49,14 +49,17 @@ public Task<TResponse> Handle(
             return Task.FromResult(Result.FailFor<TResponse>(TenantMismatchError));
         }
 
-        // Nothing to do here for RLS. The GUCs are transaction-local
-        // (set_config('app.tenant_id', ..., true)), and this behavior runs at
-        // step 4 with no transaction open, so they are issued by
-        // TransactionBehavior at step 6 as the first statement inside the
-        // transaction — Security Standards § Tenant Context. A
-        // DbConnectionInterceptor cannot do it either: it fires at connection
-        // open, not at transaction start, so the value would be discarded
-        // before the query it protects ever runs.
+        // Nothing to do here for RLS, and nothing anywhere else yet: no code
+        // in this repository issues set_config today. Packet 7 adds it to
+        // TransactionBehavior, and until then RLS is not enforced at runtime.
+        //
+        // Why it belongs there and not here: the GUCs are transaction-local
+        // (set_config('app.tenant_id', ..., true)) and this behavior runs at
+        // step 4 with no transaction open, so the value would be discarded
+        // before the query it protects ever runs. TransactionBehavior at step 6
+        // issues them as the first statement inside the transaction — Security
+        // Standards § Tenant Context. A DbConnectionInterceptor cannot do it
+        // either: it fires at connection open, which precedes BEGIN.
 
         return next();
     }

docs/decisions/0032-exception-handling-logging-and-observability.md

@@ -575,6 +575,10 @@ public static class ProviderResilienceRegistration
         // no ResilientProviderAdapter<TPort> can satisfy `: TPort`. Adapters take
         // IProviderResilience<TPort> as a collaborator and route outbound calls
         // through Pipeline.ExecuteAsync themselves.
+        ArgumentNullException.ThrowIfNull(services);
+        ArgumentNullException.ThrowIfNull(configuration);
+        ArgumentException.ThrowIfNullOrWhiteSpace(portName);
+
         var options = configuration
             .GetSection($"Resilience:{portName}")
             .Get<ResilienceOptions>() ?? new ResilienceOptions();

docs/roadmap/phase-01-repository-tooling.md

@@ -111,8 +111,12 @@
 >
 > ### Known defects this phase shipped with, and where they are fixed
 >
-> All of these were remediated in **[Phase 02a Packet 3b](phase-02a-kernel-tenancy.md)**
-> — see its [delivery record](phase-02a-kernel-tenancy.md#delivery-record-packet-3b) —
+> All but one were remediated in **[Phase 02a Packet 3b](phase-02a-kernel-tenancy.md)**
+> — see its [delivery record](phase-02a-kernel-tenancy.md#delivery-record-packet-3b).
+> The exception is **branch protection**: the missing approval and
+> bypass settings are *deferred by maintainer decision*, not fixed, and stay
+> that way until a second contributor gains write access — see
+> [CONTRIBUTING § Branch protection](../../.github/CONTRIBUTING.md). Packet 3b
 > which exists precisely so that Phase 01's record does not have to be rewritten. The
 > list below is kept as written, because what a phase shipped with is part of its
 > record:

docs/standards/12-infrastructure.md

@@ -88,6 +88,10 @@ otel-collector          # Phase 11 (Production hardening — observability stack
 
 ### Healthchecks and the readiness gate
 
+**Derives from:** [ADR-0002 Initial Architecture](../decisions/0002-initial-architecture.md)
+— these tighten how the local development stack that ADR describes is operated;
+they introduce no new architectural decision.
+
 - **A service in the default compose profile declares a `healthcheck` when one can be
   written.** `make seed` waits on the default-profile set and treats a service that is
   running but not `healthy` as not ready.
@@ -106,6 +110,9 @@ otel-collector          # Phase 11 (Production hardening — observability stack
 
 ### Published ports
 
+**Derives from:** [ADR-0002 Initial Architecture](../decisions/0002-initial-architecture.md)
+and [Security Standards § Transport](11-security.md#transport).
+
 - **Every published port binds `127.0.0.1`** — `"127.0.0.1:5432:5432"`, never
   `"5432:5432"`. A bare mapping listens on every interface, so a laptop on a café
   network publishes its development database, and `dev.yml` ships committed development
@@ -124,6 +131,10 @@ otel-collector          # Phase 11 (Production hardening — observability stack
 
 ### Development credentials
 
+**Derives from:** [ADR-0035 Demand-Gated Infrastructure](../decisions/0035-demand-gated-infrastructure.md)
+— `ConfigurationSecretProvider` is the shipped default, so `.env` is the local
+expression of the secret port rather than a parallel mechanism.
+
 - **Compose files carry no bare credential literals.** Every credential is
   `${VAR:-fallback}` so `.env` can override it and the fallback is visibly a default.
   `.env.example` lists every such variable — it is the source of truth for what a

infra/keycloak/README.md

@@ -107,11 +107,14 @@ default behaviour). To force a clean re-seed of the realm itself, wipe the
 Keycloak database first:
 
 ```bash
+# Stop Keycloak first: PostgreSQL refuses to drop a database that still has a
+# connected client, and Keycloak holds a pool open for its whole lifetime.
+docker compose --env-file .env -f infra/compose/dev.yml stop keycloak
 docker compose --env-file .env -f infra/compose/dev.yml exec postgres \
   psql -U learnstack -d learnstack -c "DROP DATABASE keycloak;"
 docker compose --env-file .env -f infra/compose/dev.yml exec postgres \
   psql -U learnstack -d learnstack -c "CREATE DATABASE keycloak OWNER learnstack;"
-docker compose --env-file .env -f infra/compose/dev.yml restart keycloak
+docker compose --env-file .env -f infra/compose/dev.yml up -d keycloak
 ```
 
 ## What does NOT live here

scripts/seed.sh

@@ -116,21 +116,27 @@ while true; do
     # never got created fails the gate instead of passing by omission.
     declared=$(docker compose "${ENV_FILE_ARGS[@]+"${ENV_FILE_ARGS[@]}"}" -f "$COMPOSE_FILE" config --services | wc -l | tr -d ' ')
     observed=$(docker compose "${ENV_FILE_ARGS[@]+"${ENV_FILE_ARGS[@]}"}" -f "$COMPOSE_FILE" ps -a --format '{{.Service}}' | wc -l | tr -d ' ')
-    if [[ -z "$not_healthy" && "$observed" -eq "$declared" ]]; then
+    # Compare the SETS, not just the counts. One service missing plus one
+    # orphan present gives observed == declared, and a count-only test would
+    # break out of the loop reporting success on a stack that is missing a
+    # declared service.
+    missing=$(comm -13 \
+        <(docker compose "${ENV_FILE_ARGS[@]+"${ENV_FILE_ARGS[@]}"}" -f "$COMPOSE_FILE" ps -a --format '{{.Service}}' | sort -u) \
+        <(docker compose "${ENV_FILE_ARGS[@]+"${ENV_FILE_ARGS[@]}"}" -f "$COMPOSE_FILE" config --services | sort -u) \
+        | xargs)
+    extra=$(comm -23 \
+        <(docker compose "${ENV_FILE_ARGS[@]+"${ENV_FILE_ARGS[@]}"}" -f "$COMPOSE_FILE" ps -a --format '{{.Service}}' | sort -u) \
+        <(docker compose "${ENV_FILE_ARGS[@]+"${ENV_FILE_ARGS[@]}"}" -f "$COMPOSE_FILE" config --services | sort -u) \
+        | xargs)
+
+    if [[ -z "$not_healthy" && -z "$missing" && -z "$extra" ]]; then
         break
     fi
-    if [[ "$observed" -ne "$declared" ]]; then
+
+    if [[ -n "$missing" || -n "$extra" ]]; then
         if [[ -n "$not_healthy" ]]; then
             not_healthy="${not_healthy}"$'\n'
         fi
-            missing=$(comm -13 \
-            <(docker compose "${ENV_FILE_ARGS[@]+"${ENV_FILE_ARGS[@]}"}" -f "$COMPOSE_FILE" ps -a --format '{{.Service}}' | sort -u) \
-            <(docker compose "${ENV_FILE_ARGS[@]+"${ENV_FILE_ARGS[@]}"}" -f "$COMPOSE_FILE" config --services | sort -u) \
-            | xargs)
-        extra=$(comm -23 \
-            <(docker compose "${ENV_FILE_ARGS[@]+"${ENV_FILE_ARGS[@]}"}" -f "$COMPOSE_FILE" ps -a --format '{{.Service}}' | sort -u) \
-            <(docker compose "${ENV_FILE_ARGS[@]+"${ENV_FILE_ARGS[@]}"}" -f "$COMPOSE_FILE" config --services | sort -u) \
-            | xargs)
         detail="saw $observed of $declared declared services"
         if [[ -n "$missing" ]]; then
             detail="$detail; never created: $missing"