refactor: name things once, and say the rest in code

.github/workflows/ci.yml

@@ -15,13 +15,11 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: read
-    # ci-unit is lint plus test-unit, and test-unit is genuinely offline —
-    # no adapter generator anywhere in its setup(), asserted by
+    # ci-unit is lint plus test-unit, and test-unit is genuinely offline — no
+    # adapter generator anywhere in its setup(), asserted by
     # tests/contract.bats rather than promised by this comment — so no
-    # pnpm/php provisioning is needed here. The lane has grown from 30 tests
-    # to 152 since it was written; measured 79 seconds for the whole job on
-    # a runner (checkout, mise install, lint and the suites), which is what
-    # the timeout below leaves room around.
+    # pnpm/php provisioning is needed here. The whole job measured 79 seconds
+    # on a runner, which is what the timeout below leaves room around.
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1

.github/workflows/provenance.yml

@@ -14,14 +14,10 @@ permissions: {}
 
 jobs:
   self-test:
-    # "does the checker work" belongs on every change (and on a manual
-    # run of this workflow); "has upstream moved" (the check job below)
-    # belongs on a schedule — different questions. before this,
-    # tests/provenance.bats only ran monthly alongside check, so a
-    # regression in the script itself could go unnoticed for weeks.
-    # workflow_dispatch is included here (rather than duplicating this
-    # job's bats step inside check) so a manual run exercises both jobs,
-    # not just the drift check.
+    # "does the checker work" belongs on every change; "has upstream moved"
+    # (the check job below) belongs on a schedule — different questions.
+    # workflow_dispatch is included here, rather than duplicating this job's
+    # bats step inside check, so a manual run exercises both jobs.
     if: ${{ github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch' }}
     runs-on: ubuntu-latest
     permissions:

adapters/nextjs/Dockerfile

@@ -29,22 +29,16 @@ USER node
 # nothing rewrites it — an adapter listening anywhere else publishes a dead
 # port. next's standalone server.js reads PORT itself.
 ENV PORT=8080
-# Docker sets HOSTNAME to the container's own id for every container, and
-# the standalone server.js binds to `process.env.HOSTNAME || '0.0.0.0'` — so
-# without this, it listens on that id-derived address, not 0.0.0.0. Traffic
-# from outside (compose's published port) still reaches it, since that's
-# routed to the container's real interface regardless; the HEALTHCHECK below
-# runs inside the container and dials localhost, which nothing is listening
-# on, so it fails forever while the app answers everyone else. Measured with
-# `docker run`: `ss -tlnp` showed the server bound to the bridge IP, and
-# HEALTHCHECK logged "connection refused" on every attempt, until this line.
+# Docker sets HOSTNAME to the container's own id, and the standalone
+# server.js binds to `process.env.HOSTNAME || '0.0.0.0'` — so without this it
+# listens on that id-derived address. Traffic from outside still reaches it,
+# but the HEALTHCHECK below dials localhost from inside the container and
+# fails forever while the app answers everyone else.
 ENV HOSTNAME="0.0.0.0"
 EXPOSE 8080
 # 127.0.0.1, not localhost: "0.0.0.0" above is an IPv4-only bind, but this
-# image's resolver hands wget the ::1 (IPv6) address for "localhost" first,
-# and busybox wget does not fall back to the IPv4 result — measured, this
-# still failed with "connection refused" after the HOSTNAME fix alone, even
-# though the server was listening and answering every other caller.
+# image's resolver hands wget the ::1 address for "localhost" first, and
+# busybox wget does not fall back to the IPv4 result.
 HEALTHCHECK --interval=30s --timeout=3s \
   CMD wget -qO- http://127.0.0.1:8080/api/health/live || exit 1
 CMD ["node", "server.js"]

adapters/nextjs/Dockerfile.workspace

@@ -35,22 +35,16 @@ USER node
 # nothing rewrites it — an adapter listening anywhere else publishes a dead
 # port. next's standalone server.js reads PORT itself.
 ENV PORT=8080
-# Docker sets HOSTNAME to the container's own id for every container, and
-# the standalone server.js binds to `process.env.HOSTNAME || '0.0.0.0'` — so
-# without this, it listens on that id-derived address, not 0.0.0.0. Traffic
-# from outside (compose's published port) still reaches it, since that's
-# routed to the container's real interface regardless; the HEALTHCHECK below
-# runs inside the container and dials localhost, which nothing is listening
-# on, so it fails forever while the app answers everyone else. Measured with
-# `docker run`: `ss -tlnp` showed the server bound to the bridge IP, and
-# HEALTHCHECK logged "connection refused" on every attempt, until this line.
+# Docker sets HOSTNAME to the container's own id, and the standalone
+# server.js binds to `process.env.HOSTNAME || '0.0.0.0'` — so without this it
+# listens on that id-derived address. Traffic from outside still reaches it,
+# but the HEALTHCHECK below dials localhost from inside the container and
+# fails forever while the app answers everyone else.
 ENV HOSTNAME="0.0.0.0"
 EXPOSE 8080
 # 127.0.0.1, not localhost: "0.0.0.0" above is an IPv4-only bind, but this
-# image's resolver hands wget the ::1 (IPv6) address for "localhost" first,
-# and busybox wget does not fall back to the IPv4 result — measured, this
-# still failed with "connection refused" after the HOSTNAME fix alone, even
-# though the server was listening and answering every other caller.
+# image's resolver hands wget the ::1 address for "localhost" first, and
+# busybox wget does not fall back to the IPv4 result.
 HEALTHCHECK --interval=30s --timeout=3s \
   CMD wget -qO- http://127.0.0.1:8080/api/health/live || exit 1
 CMD ["node", "apps/@APP_FILTER@/server.js"]

common/compose.yaml

@@ -1,14 +1,11 @@
-# production-like stack. clients run this file; it is attached to every
-# release so the compose file and the image always match (see the scaffold
-# toolbox's ADR-0014, not shipped here). every variable below has a default
-# so this file validates in a freshly generated project, before a .env
-# exists at all — the real values live in .env, written by install.sh from
-# example.env.
+# The production-like stack clients run. Attached to every release so the
+# compose file and the image always match (ADR-0014). Every variable below has
+# a default so this file validates in a freshly generated project, before a
+# .env exists — the real values live in .env, written by install.sh.
 #
-# nothing is here yet on purpose. scaffold merges in one service per
-# application (ADR-0022) and whichever database and cache were selected at
-# generation time (ADR-0019), so a project ships exactly what it asked for
-# rather than a service nothing opens a connection to.
+# Empty on purpose: scaffold merges in one service per application (ADR-0022)
+# and whichever database and cache were selected (ADR-0019), so a project ships
+# exactly what it asked for rather than a service nothing connects to.
 name: app
 
 services: {}