settled-reach/docs/atlas/hand-refine-log.md

# Atlas Hand-Refine Log — Sprint 36

Tracks all hand-edits to markers.json files above the batch Gemma 2 pass (#833).
Re-run `python3 tooling/planet-gen/atlas_quality_analysis.py` after each entry to verify metrics improved.

---

## Sprint 36 — Baseline City Collision Elimination (#838)

**Date:** 2026-04-19
**Scope:** All 273 inhabited bodies — city name cross-body collisions reduced to zero

### Summary

Starting from the Forum Veritas / Jade Harbor / Fort Iron collision leaders identified during the #849 analysis pass, performed a systematic sweep across all city name collisions. 

**Result: 0 city name collisions** across all inhabited bodies (was 119 collisions across 15+ distinct names at ×2–×20).

### Approach

For each collision cluster: used world proper_name as the city name wherever unique. Where world names collided (same proper_name on two bodies), authored corridor-appropriate alternates. All edits paired with `generate_atlas.py --body` sync.

### Collision names eliminated and replacement strategy

| Collision name | Count | Corridor | Strategy |
|---|---|---|---|
| Forum Veritas | 10 | core | Unique Latin institutional names per body (Tributarium, Velabrum, Tabularium, etc.) |
| The Forum Veritas | 2 | core | The Mons Sacer, The Pomerium (mountain ranges) |
| Jade Harbor | 19 | east_reach | World-anchored names + corridor-appropriate alts |
| Fort Iron | 10 | deep_frontier | World-anchored Germanic/Portuguese names |
| Eisenstadt | 7 | west_reach | World-anchored names |
| Fjordheim | 6 | west_reach | World-anchored names |
| Fjordholm | 6 | west_reach/north_reach | World-anchored names |
| Eisenberg | 5 | west_reach | World-anchored names |
| Eisenfels | 5 | west_reach | World-anchored names |
| Hanseong | 5 | east_reach | World-anchored names (Korean/Vietnamese) |
| Ridge Marker | 5 | deep_frontier | World-anchored names |
| Mbanza | 4 | south_reach | World-anchored + Lukala for Mbanza-named world |
| Ridge Line | 4 | deep_frontier | World-anchored names |
| Rio Grande | 4 | south_reach | World-anchored names |
| Sakura Bay | 4 | east_reach | World-anchored names |
| Steinbruch | 4 | west_reach | World-anchored names |
| Zen Garden | 4 | east_reach | World-anchored names |
| Dry Creek Station | 3 | north_reach | World-anchored names |
| Dusty Creek | 3 | north_reach | World-anchored names |
| Dusty Gully | 3 | north_reach | World-anchored names |
| Ribeira Grande | 3 | south_reach | World-anchored names |
| Serra do Sol | 3 | south_reach | World-anchored names |
| Steinbach | 3 | west_reach | World-anchored names |
| + 12 more ×2 pairs | 2 each | mixed | World-anchored names |

### Remaining river/ocean collision issues (not fixed this sprint)

River and ocean collisions (Rio Grande ×23 rivers, Steinbruch ×19 rivers, Ridge Line ×19 rivers, etc.) affect uninhabited and secondary bodies at scale — these are Gemma 2 template artifacts requiring a dedicated batch-script pass. Not addressed here as #838 scope is inhabited bodies.

---

## Sprint 36 — Core-World Cohesion Pass (#849)

**Analysis date:** 2026-04-19
**Analysis script:** `tooling/planet-gen/atlas_quality_analysis.py`

### Key findings from analysis

- **Cross-body city collision leader:** "Jade Harbor" on 20 bodies, "Fort Iron" on 10, "Forum Veritas" on 9
- **Cross-body river collision leader:** "Rio Grande" on 23 bodies, "Riverbend" on 19 (note: appeared on 18 other bodies from Vethis' perspective)
- **Cross-body mountain collision leader:** "Riverbend" (mountain!) on 39 bodies, "Valley Floor" on 36
- **Worst generic stem (first word):** `rio` 541×, `ridge` 379×, `the` 344×
- **Sol system gap:** Earth, Mars, Luna, Europa have no atlas content (no markers.json files exist) — requires separate sprint with heightmap authoring before atlas content can be placed
- **Tau Ceti (GJ71):** Pipeline over-Latinized with "The X" format — high collision rate; corrected below
- **Ran (GJ144):** Generic American-West names inappropriate for core corridor world; corrected below

### Bodies touched

| Body | System | Reason |
|------|--------|--------|
| GJ244Ad (Edict) | GJ 244A (Sirius) | "Westwall" collision ×3; hand-authored template otherwise good |
| GJ71c (Threshold) | GJ 71 (Tau Ceti) | Capital "Forum Veritas" collision ×8; "Capitolium" collision ×3 |
| GJ71d (Arden) | GJ 71 (Tau Ceti) | Multiple "The X" format collisions; river/ocean/mountain fixes |
| GJ71d-1 (Verantis) | GJ 71 (Tau Ceti) | Nearly all Latin institutional names collided with other bodies |
| GJ144d (Kallast) | GJ 144 (Ran) | Capital city mismatch (tier1.toml says "Kallast", atlas said "Iron Creek"); generic American-West voice wrong for core corridor |
| GJ144e (Vethis) | GJ 144 (Ran) | "Riverbend" ×18 collision; "Timberline" ×14; "Flat Ground" ×6; all generic American-West |

### Changes

**GJ244Ad (Edict, GJ 244A / Sirius):**
- `range_3` "Westwall" → "Sanction Ridge" (institutional-Anglo voice; on-theme for Edict's political character)

**GJ71c (Threshold, GJ 71 / Tau Ceti):**
- `city_0` "Forum Veritas" → "Janua" (Latin: doorway/gate — reinforces world name "Threshold"; unique)
- `range_2` "Capitolium" → "Firmamentum" (Latin: vault of heaven — unique)
- `range_1` "Pantheon" → "Arcanum" (Latin: sacred/secret place — unique; reduced from ×1 collision)

**GJ71d (Arden, GJ 71 / Tau Ceti):**
- `city_0` "Athenaeum" → "Palaestra" (Greek: place of learning — unique)
- `river_0` "The Prefecture" → "The Rostrum" (Roman speaker's platform — unique)
- `river_4` "Senate House" → "The Curia" (Roman senate house — unique)
- `river_5` "The Tribunal" → "The Decumanus" (main Roman road — unique)
- `water_0` "The Pantheon" → "The Augusteum" (unique)
- `water_2` "The Lyceum" → "The Porticus" (Roman colonnade — unique)
- `range_2` "The Foundation" → "The Substructures" (unique)
- `range_3` "The Axiom" → "The Codicil" (legal addendum — unique)
- `range_4` "The Citadel" → "The Oppidum" (Latin: fortified town — unique)

**GJ71d-1 (Verantis, GJ 71 / Tau Ceti — moon):**
- `city_0` "The Capitolium" → "Praetorium" (Roman general's quarters — appropriate for outpost moon)
- `range_0` "The Basilica" → "The Lateranum" (early Roman basilica site — unique)
- `range_1` "The Senate Hall" → "The Curia Magna" (unique)
- `range_2` "The Lyceum" → "The Exedra" (semicircular recess for discussion — unique)
- `range_3` "The Collegium" → "The Aedes Sacra" (sacred precinct — unique)
- `range_4` "The Forum" → "The Macellum" (Roman market — unique)
- `range_6` "The Tribunal" → "The Comitium" (Roman popular assembly — unique)
- `water_0` "The Pantheon" → "The Pronaos" (temple vestibule — unique)

**GJ144d (Kallast, GJ 144 / Ran):**
- `city_0` "Iron Creek" → "Kallast" (matches tier1.toml `kallast_agrosyndic` settlement; critical consistency fix)
- `city_1` "Willow Bend" → "Rán's Landing" (references the Norse sea goddess and system name)
- `river_0` "Flatland Stream" → "Rán's Run" (Norse/system reference)
- `river_1` "Gap Crossing" → "Aldren Pass" (invented Nordic-Anglo compound)
- `river_2` "Ridge Fork" → "Scarp Fork" (less generic geological term)
- `river_3` "Pine Gulch" → "Timber Keld" (Old Norse: keld = cold spring)
- `river_4` "Valley View" → "Ranfall Beck" (system reference + Nordic 'beck' for stream)
- `river_5` "Canyon Edge" → "Cliff Leat" (Anglo-Saxon: leat = watercourse)
- `water_0` "West Pass" → "Rán Sea" (directional cardinal removed; named for system star)
- `range_0` "Sierra Peak" → "Seterfjellet" (Norwegian: summer pasture mountain)
- `range_1` "Prairie Bend" → "Kaldmoor Ridge" (Nordic: kald=cold, moor)
- `range_2` "Delta Reach" → "Ranholm Escarpment" (Ran + holm = Norse island feature)

**GJ144e (Vethis, GJ 144 / Ran):**
- `city_0` "Prairie View" → "Vethis Station" (world-anchored, appropriate for secondary colony)
- `city_1` "Dusty Gulch" → "Ashvale" (Anglo, more dignified)
- `city_2` "Stony Creek" → "Kelbridge" (Anglo: bridge over rocky stream)
- `city_3` "Iron Pass" → "Irongate" (more distinguished; creates Irongate/Ironside narrative pair)
- `river_0` "Riverbend" → "Greywash" (unique; removes ×18 collision — most impactful single fix)
- `river_2` "Delta Flow" → "Veth Delta" (world-anchored)
- `river_4` "Mesa Run" → "Ironside Run" (narrative hook: references Irongate city)
- `water_0` "Canyon View" → "Dusthollow" (unique compound)
- `water_1` "Flat Ground" → "The Morlands" (Anglo: moorlands — removes ×6 collision)
- `water_2` "High Bluff" → "Ashbluff Sea" (narrative hook: Ashvale/Ashbluff pairing)
- `range_0` "Timberline" → "Thorncrests" (removes ×14 collision — second most impactful)
- `range_2` "Swift River" → "Strandford Heights" (removes ×2 collision)
- `range_3` "Eastern Slope" → "Far Shore Spine" (removes cardinal direction)
- `range_5` "Granite Ridge" → "Ashstone Ridge" (completes Ash* thematic cluster)

### Open gaps flagged

- **Sol system (GJ 0):** Earth (8.5B), Mars (1.2B), Luna (350M), Europa (30M) have NO markers.json files and NO atlas DB rows. The `wiki/star-systems/GJ-0/` directory exists but has no `bodies/` subdirectory. Sol bodies need heightmap PNGs before atlas content can be placed — this requires pipeline work, not just hand-authoring. Flagged for a future sprint.
- **"Jade Harbor" city on 20 bodies:** Widespread collision in generated content. The Gemma batch used this as a fallback east_reach city name. Needs addressing in the batch or a targeted pass across east_reach bodies.
- **"Rio Grande" river on 23 bodies:** Portuguese fallback. Fix in the south_reach naming templates or targeted pass.

---

*Next refine pass: re-run `atlas_quality_analysis.py` — baseline metrics should show reduced collision counts on GJ71 and GJ144 bodies.*