settled-reach/docs/design/atlas-generator-refinement-notes.md

# Atlas Generator Refinement Notes — Sprint 36

**Scope:** Systems-level sanity pass across 273 inhabited bodies (ticket #838).
**Date:** 2026-04-19
**Author:** Gestalt (systems)

This document records systematic generator artifacts found during the Sprint 36 atlas refinement pass. Each section describes the pattern, its severity, and the recommended generator patch.

---

## 1. Cross-Body City Name Collisions (SEVERE)

The Gemma naming pipeline exhausted its per-corridor vocabulary and defaulted to repeating high-probability names across bodies. 49 city names appear on more than one body; the worst offenders:

| Name | Bodies | Corridor |
|---|---|---|
| "Jade Harbor" | 20 | east_reach |
| "Fort Iron" | 10 | deep_frontier |
| "Forum Veritas" | 9 | core |
| "Ridge Marker" | 8 | deep_frontier |
| "Eisenstadt" | 7 | west_reach |
| "Fjordheim" | 6 | west_reach |
| "Fjordholm" | 6 | west_reach / north_reach |
| "Ridge Line" | 6 | deep_frontier |
| "Dusty Gully" | 5 | north_reach |
| "Eisenberg" | 5 | west_reach |
| "Eisenfels" | 5 | west_reach |
| "Hanseong" | 5 | east_reach |

**Root cause:** The dedup set in `gemma_naming.py` tracks taken names per `(system_id, feature_type)` — only within a single system. Cross-system dedup does not exist. Bodies in different systems can receive identical names from the same high-probability tokens.

**Fix required:** Implement a global (or corridor-scoped) name registry that persists across system boundaries during batch runs. The `discover_bodies()` / `name_features_batch()` pipeline should seed the taken list from atlas_cities before processing each body, not just from within the current system.

**Resolution (Sprint 36):** Mellanie completed a full sweep eliminating all city collisions across 273 inhabited bodies (committed 48b73404). Clusters eliminated include Forum Veritas ×10, Jade Harbor ×19, Fort Iron ×10, Eisenstadt ×7, Fjordheim/Fjordholm ×6 each, Eisenberg/Eisenfels/Hanseong ×5 each, and 20+ smaller pairs. City collision count is now zero.

---

## 2. Cross-Body Mountain Name Collisions (SEVERE)

The same problem afflicts mountain ranges at a larger scale. From atlas_mountain_ranges (15,190 total features across all bodies):

| Name | Bodies |
|---|---|
| "" (empty/unnamed) | 186 bodies |
| "Riverbend" | 39 bodies |
| "Valley Floor" | 36 bodies |
| "Steinbruch" | 26 bodies |
| "Ridge Line" | 26 bodies |
| "Ridge Crest" | 25 bodies |
| "Gyeongju" | 24 bodies |
| "Bamboo Grove" | 24 bodies |
| "Zen Garden" | 23 bodies |
| "River Bend" | 23 bodies |
| "Ballynahown" | 23 bodies |
| "Oakhaven" | 22 bodies |
| "Feldberg" | 22 bodies |
| "Rio Grande" | 21 bodies |
| "Hanseong" | 21 bodies |

**186 empty-name mountain ranges** — the generator simply failed to produce a name for these features. They exist in the markers.json with `"name": ""`.

**Root cause:** Same as city collisions — no cross-system dedup. Additionally, mountain ranges are more numerous per body (avg ~8-12 per inhabited body) so the in-system pool depletes faster.

**Fix required:**
1. Cross-system mountain name dedup (same approach as city fix above).
2. Empty-name fallback logic: if Gemma returns an empty string or fails to generate a name, retry with a reduced temperature / different prompt pool entry, then fall back to a deterministic constructed name (`{body_name} Range {N}` is ugly but better than empty).

---

## 3. Mountain Suffix Monotony (MEDIUM)

On per-body passes, certain corridors show suffix clustering that makes mountain ranges feel templated rather than settled. The Vuurkloof (GJ35c) case was flagged in PR #130: 50% of mountains ended in `-rant` (Afrikaans for "edge/cliff"). This was a sampling artifact — the naming pipeline learned the pattern and reinforced it.

**Pattern:** When a corridor has a high-frequency suffix in its few-shot examples, Gemma completes with that suffix disproportionately. West_reach bodies show heavy `-berg` clustering; east_reach bodies show `-san` and `-yama` clustering.

**Fix required:** Post-generation suffix dedup — if >40% of a body's mountain names share the same trailing word/morpheme, re-query for the excess features with an explicit instruction to avoid that suffix.

---

## 4. Directional Compass Labels as Feature Names (MEDIUM)

Several template bodies (bodies with hand-authored names that the pipeline preserves) used pure directional compass labels for mountain ranges:

- Estrade (GJ280Ad): "Eastern Shelf", "Western Range", "Southern Heights" (all three mountains were compass labels)
- Cairnside (GJ892d): "Westwall Range" (directional)

These convey no cultural or geographic character — they're the naming equivalent of "Mountain A, B, C."

**Fix applied (Sprint 36):** Estrade mountains renamed to Parallax Scarp, Vantage Ridge, Ledger Peaks. Cairnside "Westwall Range" renamed to Kappa Escarpment.

**Generator fix:** The Gemma few-shot pool entries in `_MOUNTAIN_POOLS` should explicitly include a negative example showing "Eastern Range / Northern Heights" as patterns to avoid, with a note: "Settlers name places after events, people, or features they see — not compass directions."

---

## 5. Zero Cross-Cultural Mixing on Corridor-Mismatched Bodies (MEDIUM)

Vuurkloof (GJ35c, south_reach corridor) was pure Afrikaans monoculture. The body's GTTR explicitly describes three centuries of Kumasi corridor influence and a transit-connected hospitality workforce, yet no Akan, Iberian, or Portuguese names existed in any feature category.

**Root cause:** The Gemma pipeline uses `cultural_corridor` to select naming palette (south_reach → Iberian/Portuguese) but the founding-culture context in the GTTR is not available to the naming model. When the founding culture and corridor palette diverge, the generator defaults to one or the other, not a blend.

**Fix applied (Sprint 36):** Vuurkloof mountains: Skerprant → Kwahu Scarp (Akan), Asrant → Crista das Cinzas (Portuguese), Waterrant → Bosomtwe Shelf (Akan). River: Rooistroom → Obotan (Akan). Ocean: Suidelike Poel → Lagoa do Sul (Portuguese).

**Generator fix:** The `gemma_naming.py` pipeline already reads `gttr_hook` per body. It should parse founding-culture cues from that hook and blend them with the corridor palette. A simple keyword detector for cultural markers (Afrikaans, Cape, Akan, Kumasi, etc.) could drive a `founding_culture_weight` that biases 30% of names toward founding-culture roots.

---

## 6. River Abstract/Navigational Naming (LOW-MEDIUM)

73 river names were flagged as abstract or navigational (using terms like "Flow", "Current", "Meridian", "Northern Flow"). Examples:

- "Delta Flow", "Northern Flow", "Celestial Flow" — generic
- "The Meridian" — navigational abstraction
- "Fogo Current", "Lagos Current", "M'Banza Current" — ocean-current framing applied to rivers

**Note:** "X Current" is appropriate for ocean surface currents; it reads oddly as a river name. Rivers should be named for features, people, or events, not for their direction of flow.

**Root cause:** The `_RIVER_POOLS` in `gemma_naming.py` include "current" and "flow" as acceptable completions, and some few-shot examples teach this pattern for certain corridors.

**Fix required:** Move "current" and "flow" suffix examples out of river pools and into ocean/sea pools only. Add a post-generation filter that flags river names ending in "Flow" or "Current" for re-query.

---

## 7. Coverage Gaps — Inhabited Bodies Missing Cities (AUDIT)

6 of 273 inhabited bodies have no cities in atlas_cities:

| Body | Name | Corridor | Class |
|---|---|---|---|
| GJ0d | Earth | sol-gateway-axis | temperate |
| GJ0d-1 | Luna | sol-gateway-axis | barren |
| GJ0e | Mars | sol-gateway-axis | arid |
| GJ0f-2 | Europa | sol-gateway-axis | frozen |
| GJ3522-belt | Pilbara Belt | core | — |
| GJ820B-belt | — | core | — |

**Earth, Luna, Mars, Europa** — deferred to Paula's #849 core-world cohesion pass (Sol system, hop 0).

**Pilbara Belt, GJ820B-belt** — asteroid belts. These may not need traditional city placements. Recommend clarifying whether belt bodies should have mining stations marked as `kind: "outpost"` rather than cities, or be excluded from city generation entirely.

---

## 8. Road/Railroad Naming Gap (SEVERE — now fixed)

80% of all roads (37/46) and railroads (37/44) across inhabited bodies had empty names. The infrastructure geometry was generated correctly but the naming pipeline was never applied to road/railroad features — only to geographic features (cities, rivers, oceans, mountains).

**Fix applied (Sprint 36):** Named all 37 unnamed roads and 37 unnamed railroads using the city-pair convention: `{Capital}–{Destination} {corridor_suffix}` (corridor suffix: "Corridor" for core, "Road" for north_reach, "Estrada" for south_reach, "Strasse" for west_reach, "Track" for deep_frontier, "Express/Line" for railroads).

**Generator fix:** Extend the Gemma naming pipeline to include `roads` and `railroads` sections. Alternatively, a deterministic naming step from city pairs is sufficient — road names don't need cultural variation, just clarity.

---

## Metrics Before vs After Sprint 36 Refinement

| Metric | Before | After |
|---|---|---|
| Cross-body city collision names | 49 | 0 (Mellanie Sprint 36 full sweep) |
| Worst collision ("Jade Harbor") | 20 bodies | 0 (eliminated) |
| Unnamed roads | 37 / 46 (80%) | 0 / 46 (0%) |
| Unnamed railroads | 37 / 44 (84%) | 0 / 44 (0%) |
| Mountain cardinal-direction names (inhabited bodies) | ~45+ | 14 / 1638 (0%) |

---

## Fixes Applied This Sprint

### Pass 1 — Template bodies (PR #130 review)

| Body | Body Name | System | What Changed |
|---|---|---|---|
| GJ892d | Cairnside | GJ 892 (Cairnside) | "Westwall Range" → "Kappa Escarpment" |
| GJ280Ad | Estrade | GJ 280A (Parallax) | "Eastern Shelf" → "Parallax Scarp"; "Western Range" → "Vantage Ridge"; "Southern Heights" → "Ledger Peaks" |
| GJ35c | Vuurkloof | GJ 35 (Vuurkloof) | Mountains: Skerprant → Kwahu Scarp, Asrant → Crista das Cinzas, Waterrant → Bosomtwe Shelf; River: Rooistroom → Obotan; Ocean: Suidelike Poel → Lagoa do Sul |

### Pass 2 — Mid-tier bodies (severity-ranked pass)

| Body | Body Name | System | What Changed |
|---|---|---|---|
| GJ7547c | Brandwacht | Skemeraand | 6 cardinal mountains → Afrikaans names; city "Ridge Marker" → "Wagpos" |
| GJ528Ac | Klaarstroom | Ouplaas | 4 cardinal mountains → Afrikaans names; city "Ridge Line" → "Klaardorp"; river "Riverbend" → "Die Draai" |
| GJ68f | Winter | Schuilhoek | All 6 cardinal/navigational rivers renamed to Afrikaans; cities "Dust Bowl Flats"/"Barren Meadow" → "Stofkamp"/"Kaalveld" |
| GJ68d | Lente | Schuilhoek | Wrong-type mountain names removed; 3 landscape-desc rivers → Afrikaans; 2 cap cities renamed |
| GJ667Ad | Geelong | New Ballarat | 2 wrong-type mountain names → Anglo-Australian; 2 cap cities → Australian flora names |
| GJ661Ad | Ys | Crown's Hollow | 2 collision city names → Anglo-Saxon unique names |
| GJ15Ac | Gongshu | Lu Ban | Wrong-type mountain; 2 collision cities → institutional core names; 1 collision river |
| GJ879d | Patiala | Singh's Landing | "Billabong" (water concept) + 6 cardinal mountains → Punjabi names; "Dusty Gully" → "Phillaur" |
| GJ556c | Idanha | Recanto | 4 cardinal/wrong-type mountains → Portuguese names; cap city → "Miradouro" |
| GJ138c | Portel | Sertão | Cap city → "Marco Sertão"; 4 concatenated river names → Portuguese |
| GJ174c | Clausthal | Tiefenbach | Cardinal + wrong-type mountains → German names; cap city → "Bergstation"; 3 wrong-type rivers |
| GJ421Bc | Serpa | Pedra Seca | 4 wrong-type mountains (flatland/valley floor used as mountains) → Portuguese names; cap city |
| GJ566Ac | Haodu | Haodu | "Jade Harbor" (worst collision, 20 bodies) → "Lianyun Harbor" |
| GJ674c | Provenance | Provenance | "Capitol Heights" → "Provenance Heights" |
| GJ68c | Zomer | Schuilhoek | 2 collision city names → Afrikaans |

### Pass 2 — Infrastructure naming (all inhabited bodies)

All 37 unnamed roads and 37 unnamed railroads across 36+ inhabited bodies were named using the city-pair convention. Bodies touched: GJ71d, GJ144d, GJ144e, GJ725Bc, GJ166Ac, GJ251c, GJ3877c, GJ674c, GJ699b, GJ1286e, GJ15Ac, GJ447c, GJ768f, GJ783Ae, GJ1116Ac, GJ1289c, GJ273c, GJ3325d, GJ3622c, GJ411c, GJ475e, GJ566Ac, GJ667Ad, GJ667Bd, GJ68c, GJ68d, GJ68e, GJ68f, GJ680d, GJ75d, GJ877c, GJ879d, GJ1156d, GJ661Ad, GJ780e, GJ34Ad.

All bodies re-synced via `generate_atlas.py --body <id>` and verified in atlas_* tables.

---

## Deferred to Paula (#849)

- Edict (GJ244Ad / Sirius system): "Westwall" was not present in current markers.json or DB — either removed in a prior pass or the query data was stale. Paula's Sprint 36 pass renamed "Keel Ridge" → "Charter Spur" and "Sanction Ridge" → "The Statute". Edict mountains are clean. "Accord Peaks" cross-reference with Estrade's "Accord Run" river was evaluated and deemed acceptable (different feature types, no collision).
- Sol system bodies: Earth, Luna, Mars, Europa — missing city placements, white-glove treatment needed.
- Lendel (GJ380c / Groombridge system): check for any quality issues.

---

## 9. POI Audit — Sprint 36 (LOW severity)

**Scope:** `atlas_pois` and `atlas_body_grids` audited post-#838.

### atlas_body_grids
Pure structural data (body_id, grid_w, grid_h, updated_at). No name column. **Clean — no action required.**

### atlas_pois
287 total POIs across 267 inhabited bodies. Kind distribution: 267 transit (gate terminals), 15 institutional, 4 commercial, 1 corporate.

**Zero empty names.** All 267 transit POIs have names. Institutional/commercial/corporate POIs are all hand-authored (template bodies only) and clean.

**Cross-body duplicates (LOW):**

| Name | Bodies | Note |
|---|---|---|
| "North Fork" | 5 | Geographic feature name used as transit POI — reads as generic |
| "Transit Hub" | 4 | Generator fallback — no locally grounded name derived |
| "Shizuka Port" | 3 | east_reach name on 3 separate bodies |
| "Ordnungshof" | 3 | west_reach name on 3 separate bodies |
| 8 others | 2 each | Minor |

**Assessment:** Severity is LOW. Max collision depth is 5 bodies ("North Fork") vs. 20 for worst city collision. No empty names. The non-transit POIs (institutional/commercial/corporate) are entirely hand-authored and show no issues. Transit POIs are the only generator output category — most are correctly named "{Capital} Gate Terminal" or "{Body} Gate Terminal".

**No hand-fixes required this sprint.** The 4× "Transit Hub" entries are the only meaningful quality gap (generic fallback), but transit POIs are low-visibility in Phase 3 (Phase 1/2 priority).

**Generator fixes recommended (add to #853):**

7. **Transit POI deterministic naming** — derive gate terminal name from body's capital city: `{capital_name} Gate Terminal`. Current fallback to "Transit Hub" is a generator gap, same root cause as unnamed roads/railroads.
8. **Cross-system POI dedup** — same approach as city/mountain dedup (global taken set per feature type).

---

## Generator Patches Required (Future Ticket)

Recommend creating a generator-patch ticket to address:

1. **Cross-system city name dedup** — seed taken list from global atlas_cities
2. **Cross-system mountain name dedup** — same approach
3. **Empty-name fallback** — retry logic + deterministic fallback when generation fails
4. **Suffix monotony post-filter** — re-query if >40% same suffix per body
5. **Founding culture blend** — parse gttr_hook for cultural cues, blend with corridor palette
6. **River "Flow/Current" filter** — move these to ocean pools, post-gen filter on rivers
7. **Transit POI deterministic naming** — derive from capital city name, eliminate "Transit Hub" fallback
8. **Cross-system POI name dedup** — extend global dedup to atlas_pois
9. **River/ocean cross-body name dedup (secondary/uninhabited bodies)** — Mellanie's Sprint 36 sweep confirmed river/ocean collisions remain on secondary and uninhabited bodies (Rio Grande ×23, Steinbruch ×19, others). Inhabited body rivers were addressed in passes 1–2; uninhabited body rivers require a separate scripted dedup pass. Same root cause as city/mountain: no global taken set in Gemma pipeline.