#226: say the icon enum's one rule once

The append-only rule was stated at the top of Icon and then restated eight
more times down the list - "appended, same rule", "inserting anywhere
earlier renumbers every icon int already stored in every scene" - about
twenty-five lines carrying one fact. What each comment actually contributed
was the glyph's subject: a wide hauler hull, a directional sensor dish, the
workshop and the drone it sends out.

Rule once at the top, then each entry says what it depicts. The DISTORDER
note stays, reworded: the name is stale (it became the Energy Propulser) and
CANNOT follow the art without renumbering, which is worth knowing.

The enum order is byte-identical - 48 entries, verified against HEAD before
committing. Reordering it would silently repoint every icon in every scene,
which is the exact hazard the comment is about.

This is the whole of what the sweep found. Searched for the same failure
elsewhere with a near-duplicate detector and no other file repeats itself;
the detector fires on the pre-fix version of this file, so its silence is
worth something.

The ticket's broader premise did not hold. Across 181 non-test files (24946
lines, 21% comments): the 79 single-line comments sitting above code state
intent rather than action; GameState has no function comment that restates
its own name and exactly two single-line in-body comments in 4219 lines; and
the densest files are dense because the reasoning is - SurfaceBackground
gives the arithmetic behind its bake resolution.

Still open, and deliberately not done alone: 491 issue-number citations.
Stripping them is a real simplification but they are traceable history, and
the ticket warns against deleting what cannot be re-explained.

173/175 in the run, both misses being 120s timeouts under JOBS=4 contention;
they pass in 81s and 79s run uncontended.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019AJMdB7iuHuLFZM1aBu3GD

ui/IconButton.gd

@@ -8,21 +8,21 @@ extends Control
 
 signal pressed
 
-# Scenes store `icon` as a plain int, so NEW ENTRIES MUST BE APPENDED -
+# Scenes store `icon` as a plain int, so NEW ENTRIES MUST BE APPENDED.
-# inserting one would silently repoint every button after it.
+# Inserting one anywhere but the end silently repoints every button after
+# it, in every scene file that already names an icon by number. The entries
+# below are therefore in the order they were added, not in any sensible one.
 enum Icon {
 	MAP, CLOSE, SHIP, DOWN_ARROW, UP_ARROW, BUILD, ROTATE_CW, ROTATE_CCW,
 	# One per building, each a miniature of what actually gets placed. The
 	# build menu used to pick from the generic set, which left the mothership
-	# and the command centre sharing a folded-map glyph and neither of them
+	# and the command centre sharing a folded-map glyph.
-	# looking anything like the structure they build.
 	MOTHERSHIP, CRAFTER, COMMAND_CENTER, EXTRACTOR, TRANSPORT_HUB, SHIP_LAB,
-	# Moving ore between the fleet and a building (#24). Two arrows passing
+	# Two arrows passing each other. The single up/down arrows already mean
-	# each other: the single up/down arrows already mean "load" and "store"
+	# "load" and "store" one way each, and this is where both live.
-	# one way each, and this button is the place where both live.
 	TRANSFER,
-	# Ship-lab upgrade glyphs. These deliberately describe the effect rather
+	# Ship-lab upgrades, drawn as the EFFECT rather than the building that
-	# than the building hosting it, so cards remain scannable at a glance.
+	# sells it, so a card full of them stays scannable.
 	UPGRADE_DAMAGE, UPGRADE_RATE, UPGRADE_RANGE, UPGRADE_THRUSTERS,
 	UPGRADE_SHIELD_HITS, UPGRADE_SHIELD_RECHARGE, UPGRADE_CARGO,
 	UPGRADE_ENGINES, UPGRADE_UNLOCK_SHIELD,
@@ -31,44 +31,30 @@ enum Icon {
 	LEFT_ARROW, RIGHT_ARROW,
 	MINUS, PLUS,
 	SHIELD_VESSEL,
+	# The ship and the thing it drops - the same two-icon split as
+	# LASER_VESSEL/LASER_SHOT below.
 	GAS_BOMBER, GAS_BOMB,
-	# Appended, not inserted alongside the other building icons above -
-	# inserting there would silently renumber every icon int already
-	# stored in existing scenes (#54).
 	GAS_BURNER,
-	# Same append-only rule (#57): a wide hauler hull, distinct from every
+	# A wide hauler hull, distinct from every vessel glyph above.
-	# vessel glyph above.
 	CARRIER_VESSEL,
-	# #58: LASER_VESSEL is the ship glyph, LASER_SHOT the action button -
-	# same two-icon split as GAS_BOMBER/GAS_BOMB above.
 	LASER_VESSEL, LASER_SHOT,
-	# #59 drew this as a warped ring, for a vessel then called a space-time
+	# Drawn as an engine bell, not the warped ring the name suggests: this
-	# distorder. #77 renamed it the Energy Propulser and the glyph is now an
+	# was a "space-time distorder" before it became the Energy Propulser.
-	# engine bell; the enum name stays put because renumbering it would
+	# The name cannot follow the art without renumbering everything after it.
-	# silently renumber every icon int stored in every scene.
 	DISTORDER_VESSEL,
-	# #78: switching a converter off and on. Appended, like everything above -
+	# Switching a converter off and on.
-	# inserting anywhere earlier renumbers every icon int already stored in a
-	# scene file.
 	PAUSE, RESUME,
-	# #102: appended, like everything above - inserting anywhere earlier
-	# renumbers every icon int already stored in every scene.
 	OUTPOST,
-	# #106: appended, same rule.
 	PLANNING_CENTER,
-	# #116: the workshop and the drone it sends out. Appended, same rule.
+	# The workshop and the drone it sends out.
 	WORKSHOP, REPAIR_DRONE,
-	# #140: the standing objective. Appended, same rule as everything above -
+	# The standing objective.
-	# inserting anywhere earlier renumbers every icon int already stored in
-	# every scene.
 	QUEST,
-	# #179: a fleet-wide thrust burst, distinct from the Propulser vessel icon.
+	# A fleet-wide thrust burst, distinct from the Propulser vessel icon.
 	DASH,
-	# Development tools: three sliders, used only by the editor-only sandbox
+	# Three sliders. Used only by the editor-only sandbox button.
-	# button. Appended to preserve every serialized icon number above.
 	DEV_TOOLS,
-	# #193: a directional sensor dish. Appended: scene files store these as
+	# A directional sensor dish.
-	# integers, so insertion would change every icon after it.
 	SCANNER,
 }