Spaces:
Paused
Merge branch 'claude/code-review-report-lyazay': close out the review follow-ups
Browse filesThe 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 +29 -0
- README.md +18 -8
- docs/code-improvement-tiers.md +13 -3
- hudPanelSignature.js +8 -2
|
@@ -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:
|
|
@@ -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
|
| 228 |
-
|
| 229 |
-
|
| 230 |
-
|
|
|
|
|
|
|
|
|
|
| 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`
|
| 237 |
-
-
|
| 238 |
-
|
| 239 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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 |
|
|
@@ -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
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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**
|
| 419 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 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 |
|
|
@@ -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,
|
| 12 |
-
|
| 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";
|