Claude Claude Opus 4.8 commited on
Commit
6d03c42
Β·
unverified Β·
2 Parent(s): fa58c7d2b4cf02

Merge branch 'claude/code-review-report-lyazay': close out the review follow-ups

Browse files

The three items left open when the review itself merged.

Branch protection on main could not be automated β€” no MCP tool covers the API
and a direct call returns 403 β€” so CONTRIBUTING.md now carries the exact
settings and the two required check names verbatim, including the coupling to
the workflow's job `name:` line that would silently unhook the gate if edited.
Applying it still needs a human with repo admin. It is the one thing that
stops this recurring: CI was red for three days and two PRs merged through it.

Docs corrected where this work had falsified them β€” README's module map
(inputCommands.js, and tools/ no longer being purely a bench now that three of
its files ship to the browser and decide Elo outcomes), hudPanelSignature.js's
"800 lines of button construction" argument, and code-improvement-tiers.md's
"6-module UI import cycle, guarded nowhere" (7 modules, and guarded by a Tarjan
membership check β€” the same error the review itself made).

The 152 KB proposal backlog and the player handbook are deliberately untouched:
deciding what is still planned is the owner's call, and nothing in them is
contradicted by this work.

Tagged v1.1.0 at this commit.

npm test 2502 passing, npm run typecheck clean on 5.7.2 and latest.

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

CONTRIBUTING.md CHANGED
@@ -134,6 +134,35 @@ writing the implementation:
134
  Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
135
  ```
136
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
137
  ## Release checklist
138
 
139
  When cutting a release:
 
134
  Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
135
  ```
136
 
137
+ ## Protecting `main` (one-time repo setup β€” not yet done)
138
+
139
+ Everything above is enforced by tests, and the tests run in CI on every push and pull request. But
140
+ nothing stops a red build being merged anyway, and that is not hypothetical: `npm run typecheck`
141
+ failed on every commit from 2026-08-05 to 2026-08-08, and PRs #90 and #91 both merged to `main`
142
+ straight through it. A gate nobody is required to pass is a gate that eventually gets walked past.
143
+
144
+ This is a repository setting, so it cannot live in a file here. It takes about two minutes:
145
+
146
+ **Settings β†’ Branches β†’ Add branch ruleset** (or *Add rule* on the classic UI)
147
+
148
+ - Target branch: `main`
149
+ - β˜‘ **Require status checks to pass before merging**, and add both by name:
150
+ - `tests (node 20)`
151
+ - `tests (node 22)`
152
+
153
+ Both must be listed. The matrix produces one check per Node version, and requiring only one
154
+ lets a version-specific regression through β€” which is the whole reason the matrix exists.
155
+ - β˜‘ **Require branches to be up to date before merging** β€” so a check that passed against a stale
156
+ base cannot count for a merge onto a newer one.
157
+ - β˜‘ **Block force pushes**
158
+
159
+ Leave "Require a pull request before merging" to taste; it is orthogonal to the failure above,
160
+ which was about a red check rather than an unreviewed one.
161
+
162
+ The check names come from `.github/workflows/test.yml`'s job name
163
+ (`name: tests (node ${{ matrix.node-version }})`). If that line is ever edited, the required
164
+ checks silently stop matching and the gate goes quiet β€” so change the two together.
165
+
166
  ## Release checklist
167
 
168
  When cutting a release:
README.md CHANGED
@@ -224,19 +224,29 @@ which is what that "whether it keeps your saves" note above is warning you about
224
  `renderShared.js` / `minimap.js` / `camera.js` / `effects.js` β€” the canvas view. `render.js`
225
  orchestrates the frame; the `render*.js` family draws units, buildings, effects and nodes; there
226
  are no images, every silhouette is vector drawing code.
227
- - `input.js` β€” mouse/keyboard/touch controls and the right-click command ladder.
228
- - `hud.js` / `hudSelection.js` / `overlays.js` / `setup.js` / `landingPicker.js` /
229
- `observerPanel.js` / `techChart.js` / `starmap.js` / `dom.js` β€” UI chrome. `hudSelection.js` owns
230
- the selection panel and is the largest file in the repo.
 
 
 
231
  - `boot.js` / `session.js` / `saveload.js` / `update.js` / `version.js` / `saveShape.js` β€” wiring
232
  the sim to the page, session state, save/load, and the version/auto-update check.
233
  - `sound.js` / `observer.js` β€” audio cues and Observer Mode.
234
  - `data.js` β€” pure content (factions, the commodity catalog, production recipes, the charted
235
  worlds).
236
- - `tools/serve.js` β€” the zero-dependency dev server behind `npm start`.
237
- - `tools/ailab.js` / `tools/selfplay.js` β€” a headless bench for measuring and tuning the Odyssey
238
- AI: it runs the sim without a browser, scores the opponent over a long session, and A/B-tests
239
- candidate AIs supplied as JSON. See [docs/odyssey-ai-review.md](docs/odyssey-ai-review.md).
 
 
 
 
 
 
 
240
 
241
  ## Background: why a separate repo
242
 
 
224
  `renderShared.js` / `minimap.js` / `camera.js` / `effects.js` β€” the canvas view. `render.js`
225
  orchestrates the frame; the `render*.js` family draws units, buildings, effects and nodes; there
226
  are no images, every silhouette is vector drawing code.
227
+ - `input.js` / `inputCommands.js` β€” mouse/keyboard/touch controls. `input.js` owns the stateful
228
+ half (drag boxes, pinch gestures, held keys, control groups); `inputCommands.js` owns the
229
+ stateless half β€” what is at a point, and what the right-click command ladder does about it.
230
+ - `hud.js` / `hudSelection.js` / `hudPanelSignature.js` / `overlays.js` / `setup.js` /
231
+ `landingPicker.js` / `observerPanel.js` / `techChart.js` / `starmap.js` / `dom.js` β€” UI chrome.
232
+ `hudSelection.js` owns the selection panel: one `render*` function per panel family, dispatched
233
+ by `rebuildSelectionPanel`, with `hudPanelSignature.js` deciding when a rebuild is needed at all.
234
  - `boot.js` / `session.js` / `saveload.js` / `update.js` / `version.js` / `saveShape.js` β€” wiring
235
  the sim to the page, session state, save/load, and the version/auto-update check.
236
  - `sound.js` / `observer.js` β€” audio cues and Observer Mode.
237
  - `data.js` β€” pure content (factions, the commodity catalog, production recipes, the charted
238
  worlds).
239
+ - `tools/serve.js` / `tools/ailab.js` / `tools/selfplay-cli.js` β€” Node CLI benches, never loaded by
240
+ the browser: the zero-dependency dev server behind `npm start`, and a headless AI bench that runs
241
+ the sim without a browser, scores the opponent over a long session, A/B-tests candidate AIs
242
+ supplied as JSON, and evolves new ones. See [docs/odyssey-ai-review.md](docs/odyssey-ai-review.md)
243
+ and [docs/ai-evolution-design.md](docs/ai-evolution-design.md).
244
+ - `tools/selfplay.js` / `tools/duelCore.js` / `tools/genome.js` β€” **shipped code that happens to live
245
+ under `tools/`**, not benches. They run a match headlessly, which is what the CLI wants *and* what
246
+ the in-browser competition Worker (`competitionWorker.js`) wants, so `boot.js`, `competition.js`
247
+ and `playerFingerprint.js` import them too. Because a duel's outcome becomes a persisted Elo
248
+ rating, they carry the same determinism and DOM-free requirements as `engine/`, and
249
+ `test/engine-purity.test.js` scans them alongside it.
250
 
251
  ## Background: why a separate repo
252
 
docs/code-improvement-tiers.md CHANGED
@@ -409,14 +409,24 @@ surface.
409
  correct the comment and pin the bound with a characterisation test. Do not leave the comment and the
410
  code disagreeing. **M**
411
  - **Rebuild-signature co-location.** 141 lines with 11 inline IIFEs, each re-deriving a lookup that
412
- `rebuildSelectionPanel` derives again ~1,000 lines later. **M**
 
 
 
 
413
  - **Production rosters copied out of `BUILDINGS[].produces` in three hand-maintained shapes**, with the
414
  Odyssey gate duplicated *differently* from the engine's own. Land the test before the refactor β€” it
415
  passes today. **S**
416
  - **Silhouette collisions** (C6's art half β€” the Gate deserves a bespoke hull), **per-frame allocation**
417
  (measured 2.16 ms of pure JS and 0.9 MB/s of garbage at 306 units, before any rasterization; pop caps go
418
- to 300 *per side*), **five byte-identical cross-module function bodies**, and the **6-module UI import
419
- cycle** (benign today, guarded nowhere, fails as a blank white screen). Each **S–M**.
 
 
 
 
 
 
420
 
421
  ---
422
 
 
409
  correct the comment and pin the bound with a characterisation test. Do not leave the comment and the
410
  code disagreeing. **M**
411
  - **Rebuild-signature co-location.** 141 lines with 11 inline IIFEs, each re-deriving a lookup that
412
+ `rebuildSelectionPanel` derives again further down the file. **M**
413
+ *(Partly done, 2026-08-08: `rebuildSelectionPanel` is now a dispatcher over twelve named
414
+ `renderX()` families instead of one 871-line body, so the "render" third of the registry exists
415
+ already. What is left is moving each family's signature term next to its renderer β€” now a
416
+ per-family move rather than one big one.)*
417
  - **Production rosters copied out of `BUILDINGS[].produces` in three hand-maintained shapes**, with the
418
  Odyssey gate duplicated *differently* from the engine's own. Land the test before the refactor β€” it
419
  passes today. **S**
420
  - **Silhouette collisions** (C6's art half β€” the Gate deserves a bespoke hull), **per-frame allocation**
421
  (measured 2.16 ms of pure JS and 0.9 MB/s of garbage at 306 units, before any rasterization; pop caps go
422
+ to 300 *per side*), **five byte-identical cross-module function bodies** (the two that actually bit
423
+ β€” `clamp`, `negate` β€” are shared now and re-forking is guarded by
424
+ `test/static-integrity.test.js`), and the **UI import cycle** (now 7 modules, not 6: `competition.js`
425
+ joined it deliberately. Still benign only because every back-edge is called at runtime rather than
426
+ at module-evaluation time, and still failing as a blank white screen if that stops being true β€”
427
+ but no longer "guarded nowhere": a Tarjan check in `test/static-integrity.test.js` freezes the
428
+ cluster's exact membership, so a new cycle anywhere, or an eighth member here, fails the suite).
429
+ Each **S–M**.
430
 
431
  ---
432
 
hudPanelSignature.js CHANGED
@@ -8,8 +8,8 @@
8
  state contributes no term to it silently never redraws. (That is not
9
  hypothetical: it is what left the Freight Lane and Colony Policy controls
10
  inert, reading as no-ops and inviting a second click that toggled the change
11
- back.) A model that important should be readable on its own, without scrolling
12
- past 800 lines of button construction β€” and the derivations it shares with the
13
  renderers (factoryStatus, loadableComs, countByType, counterInfo) belong beside
14
  it rather than in the middle of the DOM code, since both sides call them and
15
  the two must never drift.
@@ -24,6 +24,12 @@
24
  that a move rather than a rewrite; test/hudSelection.test.js already drives a
25
  completeness table over every interactive panel family so a missing term fails
26
  loudly instead of shipping dead.
 
 
 
 
 
 
27
  ============================================================ */
28
 
29
  "use strict";
 
8
  state contributes no term to it silently never redraws. (That is not
9
  hypothetical: it is what left the Freight Lane and Colony Policy controls
10
  inert, reading as no-ops and inviting a second click that toggled the change
11
+ back.) A model that important should be readable on its own, rather than buried
12
+ in the middle of the panel's button construction β€” and the derivations it shares with the
13
  renderers (factoryStatus, loadableComs, countByType, counterInfo) belong beside
14
  it rather than in the middle of the DOM code, since both sides call them and
15
  the two must never drift.
 
24
  that a move rather than a rewrite; test/hudSelection.test.js already drives a
25
  completeness table over every interactive panel family so a missing term fails
26
  loudly instead of shipping dead.
27
+
28
+ HALF OF THAT IS NOW DONE, which changes what is left. hudSelection.js's twelve
29
+ panel families each have their own renderX() function and rebuildSelectionPanel
30
+ is a dispatcher β€” so the "render" third of the registry already exists, named
31
+ and separable. What remains is moving each family's SIGNATURE term next to its
32
+ renderer, which is now a per-family move rather than one big one.
33
  ============================================================ */
34
 
35
  "use strict";