⚑ STATUS BANNER (2026-06-03). This document is historical. Its header below ("reviewed at commit
7c705f6, 2024-04-02"; "the live roadmap is now v3.2") predates the current product by ~two major lines. The shipped version is v4.1.1 (cellauto/__init__.py/pyproject.toml/CHANGELOG.mdall agree). The live roadmap + punchlist is docs/ROADMAP.md; the current full-application review (goals/expectations/results + screenshots) is docs/review/APPLICATION_REVIEW_v4.1.md with all issues in docs/review/ISSUE_REGISTER.md. The../PHASE2_BRUTAL.mdlink referenced below no longer exists (tracked as REV-16). The v1.x→v3.1 gap analysis that follows is preserved as the original record.
Repo: rizzleroc/CellAutomata
Reviewed at: commit 7c705f6 (2024-04-02)
Reviewer date: 2026-05-18 (~2 years after last commit)
Scope (original): 4 Python files, 7 tracked files, ~300 LOC total
Scope (v2.0): package cellauto/ (8 modules), CLI, GUI, headless mode, GIF export, 14 tests, CI workflow
Everything in §4 below is shipped on main. Summary of what landed in v2.0:
| PRD item | Status | Where |
|---|---|---|
| F1 — Rule 1 neighbor-color propagation | ✅ Done | cellauto/rules/natural_selection.py |
| F2 — Rule 2 fires (quantized palette) | ✅ Done | 16-color PALETTE at natural_selection.py:29. Headless run shows ~830 amoebas / 900 cells by step 50. |
F3 — Rule 3 is_new has teeth |
✅ Done | Only set on cells that just changed color; combine sets it false. |
| F4 — Rule 4 amoeba lifecycle | ✅ Done | Amoebas age + die at 25 steps. |
| F5 — "Natural selection" framing honest | Still no fitness/inheritance, but the four rules now actually do what the README says. v2.0 README reframes as "sandbox" rather than literal natural-selection claim. | |
C1 — Delete main_new.py |
✅ Deleted | |
| C2 — Speed slider mislabeled | ✅ Fixed — now an FPS slider. | |
| C3 — Window close handler broken | ✅ Fixed — _quit destroys window. |
|
| C4 — Step button racy during play | ✅ Fixed — disabled while running. | |
C5 — logging not configured |
✅ Fixed — basicConfig in CLI and app.run. |
|
C6 — canvas.delete("all") every frame |
✅ Fixed — persistent item IDs + itemconfigure. |
|
| C7 — No seed / no reproducibility | ✅ Fixed — --seed flag, Engine seeds rule RNG, shown in status bar. |
|
D1 — requirements.txt was markdown |
✅ Fixed | |
| D2 — Conflicting Python versions | ✅ Fixed — 3.10+ everywhere | |
| D3 — Personal email in README | ✅ Removed | |
| D4 — No screenshot | ✅ Added docs/hero.png | |
| D5 — No LICENSE | ✅ MIT — see LICENSE | |
| Tests | ✅ 14 pytest tests, all pass | |
| CI | ✅ GitHub Actions matrix (3.10, 3.11, 3.12) — see .github/workflows/ci.yml | |
.gitignore |
✅ Added | |
pyproject.toml |
✅ Added, installs as cellauto console script |
|
| Type hints | ✅ Throughout | |
| Save/load JSON | ✅ Engine.save/load + GUI File menu | |
| Headless mode | ✅ cellauto simulate subcommand |
|
| Stats overlay | ✅ Status bar shows rule/seed/step/FPS/population | |
| Pluggable rule engine | ✅ Rule Protocol + REGISTRY; ships NaturalSelection, Conway, Wolfram1D |
|
| Tutorial overlay | ✅ Help ▸ Start tutorial, 7 steps | |
| GIF export | ✅ cellauto export + GUI "Record GIF" + Pillow renderer |
Not done (deliberate skip): v3.0 web port (Pyodide / JS rewrite). That's a platform change, not a feature — flagged out of scope at the start.
"A cellular automaton that simulates natural selection."
Four rules:
- Each cell takes on a random color (of a neighbor).
- Two adjacent same-color cells combine into a new color.
- A "new" cell can only combine with other new cells.
- When a new cell combines, it evolves into an "amoeba" — a step in cellular complexity.
Goal: an interactive, visually engaging evolutionary simulation with play/stop/step controls and a speed slider.
| Component | File | LOC | Status |
|---|---|---|---|
Cell model |
cell.py | 32 | Functional, has bugs |
CellularAutomaton grid |
cellular_automaton.py | 39 | Functional, has bugs |
| Tk GUI | main.py | 77 | Functional, has bugs |
| Tk GUI (duplicate) | main_new.py | 77 | Dead duplicate |
| README | README.md | 9 | Exposes author email |
| Manual | manual.md | 59 | Contradicts requirements.txt |
| Requirements | requirements.txt | 4 | Not a real requirements file |
Total git history: 4 commits across 7 days in March–April 2024. No tests, no CI, no .gitignore, no LICENSE, no pyproject.toml/setup.py, no issues, no branches, no tags.
README says "cell takes on a random color around itself" (i.e., from a neighbor). Code at cell.py:13 generates a fully random 24-bit hex color with no reference to neighbors. There is no neighbor-color propagation anywhere in the code. The headline rule of the simulation isn't implemented.
cellular_automaton.py:38 gates combination on cell1.color == cell2.color — exact-equality of two randomly generated 24-bit hex strings. Probability of two independent random colors matching: 1 in 16,777,216. With a 50×50 grid checking ~4 neighbors per cell per step, you'd need ~1,700 steps on average to see a single combination event. The "natural selection" effectively never fires. There is no color quantization, no distance threshold, no buckets.
cellular_automaton.py:13–15 resets is_new = True on every cell at the start of every step. The "only new cells can combine" check at cell.py:22 is therefore always true. The is_new flag is dead state — it could be deleted with zero behavior change.
Once is_ameba=True it's never reset, but change_color() still runs on amoebas every step — they keep randomly recoloring while drawn as ovals instead of rectangles. There's no amoeba lifecycle, no reproduction, no death, no fitness, no movement, no resource. "Evolution into complexity" is a one-bit shape swap.
"Natural selection" implies fitness, reproduction, inheritance, and differential survival. This sim has none of those — it's random recolor + adjacency match. Calling it natural selection is marketing.
The only difference: speed slider max is 10.0 in main, 1.0 in main_new. No README explains which to run. Pick one and delete the other.
The slider value is used as a delay in canvas.after(int(slider * 1000)) at main.py:42. Higher value = slower simulation. Label says "Speed", behavior is "Delay". UX bug.
main.py:74 binds WM_DELETE_WINDOW to app.stop — which only sets self.running = False. Clicking the X stops the animation but does not destroy the window. Should be lambda: (app.stop(), root.destroy()).
Clicking Step while Play is running races with the scheduled callback — cells get an extra mutation between frames, animation stutters.
cell.py:5 imports logging and emits logging.info(...). Without logging.basicConfig(level=INFO) somewhere, every log message is silently discarded.
main.py:56 calls canvas.delete("all") then redraws every cell. For 50×50 = 2,500 shapes/frame. Works at 50×50, dies above ~200×200. Should reuse canvas item IDs with itemconfigure.
random is never seeded. Same simulation cannot be re-run. No way to share an interesting state.
requirements.txt contains markdown headings (# README.md, ## System Requirements) instead of pip dependency lines. pip install -r requirements.txt would error out. Either delete it or put real content.
requirements.txtsaysPython >= 3.6manual.md:7saysPython 3.1 and abovePython 3.1 is from 2009 and is not supported. Pick one — 3.9+ is reasonable for new work.
Justin@futurcraft.ai is in the README. Use a GitHub issues link instead.
A visual project with no visual in the README. First-time visitors can't tell what it does without cloning and running.
Repo is public with no license. Legally, nobody can use, fork, or contribute to it. Add MIT/Apache-2.0.
| Missing | Impact |
|---|---|
| Tests (any kind) | Cannot refactor with confidence. Rules F1–F3 above would be caught by 3 unit tests. |
| CI (GitHub Actions) | No automated lint/test on PR. |
.gitignore |
First contributor will commit __pycache__/. |
pyproject.toml |
Can't pip install . Can't publish. No tool config (ruff/black/mypy). |
| Type hints | Zero. Cell, CellularAutomaton are dynamically typed. |
| Save/load state | Cannot persist or share simulations. |
| Headless mode | Cannot run as a benchmark or generate data — Tk is mandatory. |
| Metrics/stats panel | No "amoeba count", "step #", "FPS" — user can't observe what the sim is doing. |
| Pause-and-edit | Cannot paint cells, seed initial conditions, or set rules at runtime. |
| Presets | No "Conway's Life", "Wolfram Rule 30" — the project name promises a class of automata, ships one. |
Status (2026-05-21): v1.1 → v3.1 are shipped. v3.0's original "web build" stretch was deliberately descoped (platform change, not a feature). The live roadmap is now v3.2 — Living colony & visual identity, below. See PHASE2_BRUTAL.md §POST2 for the verified punch-list checkoff.
- Delete
main_new.py. - Fix
requirements.txt(either remove or make valid). - Add LICENSE,
.gitignore, screenshot in README. - Replace personal email with issue tracker link.
- Fix window-close bug, speed slider label, disable Step during Play.
- Configure
logging.basicConfig. - Reconcile Python version claims (commit to 3.9+).
- F1: Implement neighbor-color propagation (sample from 8-neighborhood).
- F2: Quantize colors to a ~16-color palette so "same color" actually happens.
- F3: Decide whether
is_newmeans anything; if yes, gate it correctly; if no, delete. - F4: Give amoebas a real lifecycle — stop recoloring them, give them a lifespan or reproduction rule.
- Add
--seedCLI flag; show seed in UI.
- Pluggable rule engine (
Ruleinterface; ship Wolfram 1D, Conway's Life, and the current "natural selection" rule as three of N). - Stats overlay: step count, FPS, population counts per state.
- Save/load
.jsonsnapshots. - Headless
simulatesubcommand for batch runs / data export. - Replace per-frame
canvas.delete("all")with persistent item IDs +itemconfigure(10× speedup, supports 200×200+). - Unit tests for each rule; CI on push.
- Optional: swap Tk for
pygameor web-based (HTML canvas) so it's actually shareable.
- Inline per-rule tutorial mode. ✅
- Export run as GIF for sharing (non-blocking, progress + cancel). ✅
- Abiogenesis pipeline (5 stages, citation-backed origin-of-life concepts). ✅
Web build (Pyodide / JS rewrite)— descoped: platform change, not a feature.
- Eigen-Schuster hypercycle fitness replaces the Stage-4 placeholder.
- Windows+Ubuntu CI matrix, mypy, ruff format,
--cov-fail-under=80, pip-audit. - Catalytic Silence visual identity: bundled fonts, museum-plate sections, app icon, About dialog.
- CHANGELOG.md, version 3.1.0.
Shipped: organic blob amoebas that breathe / ripple / look around and show faces at the default grid, an amoeba hero baked from the colony geometry, web favicons, a Catalytic-Silence chrome cleanup, and the Stage-4 / Rule-110 / CLI test+doc nits. Full spec + Definition of Done: docs/design/V3_2_LIVING_COLONY.md. The infrastructure is honest but the experience is unfinished. The signature "cuddly cartoon amoeba" exists only as the header mascot; the colony renders as flat colored dots with faces that never appear at the default grid. And we surface only 4 of ~16 generated art assets.
- Living colony: port the mascot's wobble / blink / 3D-highlight / blobby-body animation into the colony renderer, driven by a continuous tick so it's alive even when paused.
- Visible faces by default: fix the
FACE_MIN_CELL_PXvs default-grid mismatch so the amoebas read as characters out of the box. - Organic bodies: smoothed blob polygons with subtle membrane motion instead of perfect circles.
- Use the art we generated: surface orphaned
whipgen-outplates, pick one canonical icon, generate the missing amoeba hero/sprite. - UI polish: apply Catalytic Silence consistently to the canvas frame; review spacing/typography.
- Residual test/doc nits: Wolfram rule-110 test, CLI-subprocess tests, fix the stale Stage-4 fitness string in the tutorial.
See PHASE2_BRUTAL.md §POST2 for the prioritized V0–V2 punch list.
What you built: a 50×50 Tk grid that randomly recolors every step and rarely (statistically: never) draws an oval instead of a rectangle. ~300 LOC, two copies of the main file, broken requirements file, broken window close, mislabeled slider, an "evolutionary" mechanic that fires once per ~1,700 frames by accident.
What the README sells: a natural-selection simulator with four interlocking rules.
The gap between the marketing and the code is the entire product. Rules 1, 3, and 4 are not implemented or are dead state. Rule 2 is implemented in a way that mathematically never fires. There is no selection, no fitness, no inheritance — the four words "simulates natural selection" do not survive contact with the source.
This isn't a code-quality problem you fix with linting. The simulation needs to be rebuilt from the rule definitions down, with the color-matching mechanic changed to make Rule 2 fire at a meaningful rate, and Rules 1/3/4 actually wired up. Until then, it's a screensaver, not a simulator.
The good news: the GUI shell, the Cell/CellularAutomaton split, and the play/step/stop control flow are a fine scaffold. The fix is ~100 lines, not a rewrite. v1.2 is a weekend.