Reword the Molecule scenario comments

They were hard-wrapped at 80 characters, broke mid-parenthesis, and spent lines
restating what the code below them does.

Rewrapped at natural boundaries instead, with the narration dropped and only the
reasons, gotchas and surprises kept. Section dividers stay - they delineate long
plays rather than narrate them.

Comments only; no scenario behaviour changes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SEH3vxYSQ5SV4N5z61eyGT

roles/custom/matrix-alertmanager-receiver/molecule/default/converge.yml

@@ -3,11 +3,9 @@
 # SPDX-License-Identifier: AGPL-3.0-or-later
 
 ---
-# The devture base roles carry the variables this role reads
-# (`devture_systemd_docker_base_*`, `devture_playbook_help_*`), the same way
-# they do when the playbook runs. `matrix-base` is deliberately NOT included:
-# it does far more than this role needs, and the two variables it would supply
-# are set directly in molecule.yml instead.
+# The devture base roles carry the variables this role reads, the same way they do when
+# the playbook runs. `matrix-base` is deliberately NOT included: it does far more than this
+# role needs, and the two variables it would supply are set directly in molecule.yml.
 - name: Include roles for matrix-alertmanager-receiver Molecule tests
   hosts: all
   become: true
@@ -26,8 +24,8 @@
       loop_control:
         loop_var: role_name
 
-# The role installs the unit but does not start it - in the playbook that is
-# `systemd_service_manager`'s job - so the scenario starts it here.
+# The role installs the unit but does not start it; in the playbook that is
+# `systemd_service_manager`'s job.
 - name: Ensure matrix-alertmanager-receiver is started
   hosts: all
   become: true

roles/custom/matrix-alertmanager-receiver/molecule/default/molecule.yml

@@ -31,27 +31,24 @@ provisioner:
         matrix_alertmanager_receiver_path_prefix: /
         matrix_alertmanager_receiver_container_network: matrix-alertmanager-receiver-molecule
 
-        # verify.yml runs as its own play, where the role's defaults are out
-        # of scope, so the paths it reads are pinned here as literals. They
-        # match what the role derives from matrix_base_data_path above.
+        # verify.yml runs as its own play, where the role's defaults are out of scope,
+        # so the paths it reads are pinned here to match what the role derives.
         matrix_alertmanager_receiver_base_path: /matrix/alertmanager-receiver
         matrix_alertmanager_receiver_config_path: /matrix/alertmanager-receiver/config
 
-        # Traefik is not deployed in this scenario, so the labels the role would
-        # render for it are switched off and their absence is asserted instead.
+        # Traefik is not deployed here, so the labels the role would render for it are
+        # switched off and their absence is asserted instead.
         matrix_alertmanager_receiver_container_labels_traefik_enabled: false
 
-        # Deliberately different from the role's own defaults (port 12345,
-        # metrics disabled, alerts under /alerts), so that `verify.yml` can tell
-        # what the role rendered apart from what the application would have done
-        # on its own.
+        # Different from the role's own defaults, so verify.yml can tell what the role
+        # rendered apart from what the application would have done on its own.
         matrix_alertmanager_receiver_config_http_port: 12399
         matrix_alertmanager_receiver_config_http_metrics_enabled: true
         matrix_alertmanager_receiver_config_http_metrics_path: /molecule-metrics
         matrix_alertmanager_receiver_config_http_alerts_path_prefix: /molecule-alerts
 
-        # The homeserver IS reached at startup - the service fetches its joined
-        # rooms and exits 1 if that fails - so prepare.yml stands up a stub for it
+        # The homeserver IS reached at startup: the service fetches its joined rooms and
+        # exits 1 if that fails, so prepare.yml stands up a stub for it.
         matrix_alertmanager_receiver_config_matrix_homeserver_url: http://matrix.molecule.local:8008
         matrix_alertmanager_receiver_config_matrix_user_id: "@alertmanager:molecule.local"
         matrix_alertmanager_receiver_config_matrix_access_token: molecule_access_token_4f2a91

roles/custom/matrix-alertmanager-receiver/molecule/default/prepare.yml

@@ -31,9 +31,8 @@
         docker_daemon_options:
           storage-driver: fuse-overlayfs
 
-    # The role's file tasks set owner/group by name, and Ansible resolves those
-    # through the passwd database - so they have to exist before it runs. In a
-    # real deployment `matrix-base` creates them.
+    # The role's file tasks set owner/group by name, which Ansible resolves through the
+    # passwd database, so they have to exist first. `matrix-base` creates them for real.
     - name: Ensure the matrix group exists
       ansible.builtin.group:
         name: "{{ matrix_group_name }}"
@@ -70,10 +69,9 @@
         - matrix_alertmanager_receiver_molecule_network.rc != 0
         - "'already exists' not in matrix_alertmanager_receiver_molecule_network.stderr"
 
-    # matrix-alertmanager-receiver contacts the homeserver while starting up -
-    # it fetches /_matrix/client/v3/joined_rooms to resolve its room mapping and
-    # exits 1 if that fails - so a homeserver has to exist for it to come up at
-    # all. The shared stub is enough; see molecule-shared/homeserver-stub.py.
+    # The service fetches /_matrix/client/v3/joined_rooms to resolve its room mapping and
+    # exits 1 if that fails, so a homeserver has to exist for it to come up at all.
+    # The shared stub is enough. See molecule-shared/homeserver-stub.py.
     - name: Ensure the homeserver stub is running
       ansible.builtin.include_tasks:
         file: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/../../../molecule-shared/tasks/homeserver-stub.yml"

roles/custom/matrix-alertmanager-receiver/molecule/default/verify.yml

@@ -12,10 +12,9 @@
   gather_facts: false
 
   tasks:
-    # The version is read out of the role's own defaults rather than pinned in
-    # molecule.yml, so that the assertion further down compares the running
-    # image against what defaults/main.yml actually ships. Pinning it here
-    # would make that assertion compare the scenario with itself.
+    # Read from the role's own defaults rather than pinned in molecule.yml, so the version
+    # assertion compares the running image against what defaults/main.yml ships.
+    # Pinning it here would make that assertion compare the scenario with itself.
     - name: Load the role's defaults under a separate name
       ansible.builtin.include_vars:
         file: "{{ lookup('env', 'MOLECULE_PROJECT_DIRECTORY') }}/defaults/main.yml"
@@ -30,10 +29,9 @@
       delay: 5
       failed_when: false
 
-    # `Restart=always` means a crash-looping container still reports `active`,
-    # so the restart counter is checked alongside it. Asserted as `is defined`
-    # too, because `| int` turns a missing property into 0 and would pass
-    # vacuously on a systemd that does not expose it.
+    # `Restart=always` means a crash-looping container still reports `active`, so the restart
+    # counter is checked too. Asserted `is defined` because `| int` turns a missing property
+    # into 0 and would pass vacuously.
     - name: Assert the service is active and has not been restarting
       ansible.builtin.assert:
         that:
@@ -47,9 +45,9 @@
           automatic restart(s)
         success_msg: "matrix-alertmanager-receiver.service is active and has not restarted"
 
-    # Probed from inside the container network rather than from the host: the
-    # role publishes no host port, exactly as it does in a real deployment,
-    # where Traefik reaches it over the network instead.
+    # Probed from inside the container network rather than the host, because the role
+    # publishes no host port - exactly as in a real deployment, where Traefik reaches it
+    # over the network.
     - name: Wait for matrix-alertmanager-receiver to answer on the port the role configured
       ansible.builtin.command:
         argv:
@@ -70,9 +68,8 @@
       delay: 5
       failed_when: false
 
-    # The port and the metrics path are both non-default in this scenario, so a
-    # 200 here is only reachable if the configuration the role rendered is what
-    # the process is actually running on.
+    # Port and metrics path are both non-default here, so a 200 is only reachable if what
+    # the role rendered is what the process is running on.
     - name: Assert the configured port and metrics path reached the process
       ansible.builtin.assert:
         that:
@@ -93,9 +90,8 @@
           The metrics endpoint answered, but did not return Prometheus metrics
         success_msg: "The metrics endpoint returns Prometheus metrics"
 
-    # A negative control for the assertion above: the role's own default metrics
-    # path must NOT answer, or a 200 on the configured path would prove nothing
-    # about the configuration having been applied.
+    # Negative control for the assertion above: the role's own default metrics path must NOT
+    # answer, or a 200 on the configured path would prove nothing.
     - name: Ask for the role's default metrics path, which this scenario moved away from
       ansible.builtin.command:
         argv: