docs(decisions): file D-237 authored specialization layer + re-amend D-233

Add D-237: each inhabited system carries three authored, static (t=0),
deterministic per-system identity fields sourced from
wiki/economics/system_specialization.toml — economic_specialization
(27-value vocabulary, scale encoded in the value), cultural_specialization
(unified activity + heritage vocabulary), and dominant_faction (populate
the existing system_factions column, 8 values, lattice_commission dropped).
Authored lore wins; a deterministic-varied seed-hashed weighted draw is the
fallback for unnamed systems so they don't read identically.

Re-amend D-233 to source dominant_bulk_class x dominant_production_ubiquity
from this authored layer (heuristic becomes fallback). Groombridge encodes
as a financial_hub Specialist district with the GSH clearing house as a
D-222/D-232 landmark rather than a composite vocabulary value.

Add the specialization-layer d2 diagram (3 fields -> D-233/D-232/D-214
consumers). Produced by the system-economic-specialization workshop.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

decisions/architecture.md

@@ -1667,6 +1667,7 @@ Technical foundation decisions that constrain implementation: engine, client-ser
 - **Raised by:** Burnelli, economic-built-world workshop round 2, 2026-05-25.
 - **Cross-reference:** [D-194](#d-194) (district mix — upstream), [D-184](content.md#d-184) (commodity catalog — amended), [D-199](#d-199) (read-set — amended), [D-220](#d-220) (density), [D-197](#d-197) (prosperity), [D-142](content.md#d-142) (zone types — downstream), [D-176](#d-176), [D-180](#d-180) (EconEvent — overlay trigger), [D-198](#d-198) (condition overlay — amended), [D-229](#d-229)
 - **Dissent:** None
+- **Re-amended 2026-05-31 (D-237 — authored specialization layer):** The settlement's `dominant_bulk_class` and `dominant_production_ubiquity` are now sourced from the authored specialization layer (D-237) rather than derived directly from the highest-output production chain. Derivation chain: (1) If `system_economy.economic_specialization` is authored → resolve via `specialization_vocabulary(economic_specialization)` → `(commodity_id, production_ubiquity_override)` → `(BulkClass, ProductionUbiquity)`. Use the vocabulary-specified `ProductionUbiquity` (which may override the catalog default per the equal-or-higher rule). (2) If `economic_specialization` is NULL → run the deterministic-varied heuristic (D-237 §fallback: seed-hashed weighted draw over the vocabulary using `economic_role` + corp HQ signals + noise term) → same projection. In both cases the resolved `(BulkClass, ProductionUbiquity)` populates `CityGenerationContext.dominant_bulk_class` and `CityGenerationContext.dominant_production_ubiquity`. Frozen-amber constraint unchanged: `fill_chunk(ctx, seed)` holds no `PressureState` reference. Within-system body variation (weighted draw over body-level candidates anchored to system commodity) remains seed-hashed. **Groombridge clarification:** The vocabulary expresses district-level character. Singular MonopolySource-class landmarks within a Specialist district (e.g. GSH within Groombridge's `financial_hub` cluster) are expressed via D-222 multi-block reservation + D-232 hero-element pin, not via composite vocabulary values.
 
 ---
 
@@ -1700,4 +1701,26 @@ Technical foundation decisions that constrain implementation: engine, client-ser
 
 ---
 
-*95 decisions (D-001 through D-235, excluding gaps). Last updated: 2026-05-25 (economic-built-world workshop rounds 2–3 — D-229 building-property-tag schema, D-230 FillChunk execution, D-231 door/interior contract, D-232 architecture-flavor as an economically-gated/seed-drawn/wiki-biased trait-template catalog [round-3 rewrite], D-233 economic block-fill, D-234 morphology→street, D-235 exterior visual grammar + asset fallback hierarchy). D-101/D-104/D-105/D-107 superseded in part by D-232.*
+### D-237: Authored per-system specialisation layer — `economic_specialization` + `cultural_specialization` + `dominant_faction`
+- **Date:** 2026-05-31
+- **Decision:** Each inhabited star system carries three authored per-system identity fields, statically compiled from `wiki/economics/system_specialization.toml` at build time via `import_economics.py`. These fields constitute the lore-authored identity layer above the heuristic and are the primary source for D-233/D-232/D-214 generator inputs for named systems. All three fields are static (t=0), deterministic (D-010), and NULL-safe (NULL = heuristic fallback runs).
+
+  **(1) `system_economy.economic_specialization TEXT` (new column).** A 27-value curated vocabulary compiled from `wiki/economics/specialization_vocabulary.toml` into a `specialization_vocabulary` DB table. Each value maps to `(commodity_id, production_ubiquity_override_or_null)` → `(BulkClass, ProductionUbiquity)` for D-233. Scale is encoded in the value (no separate scale column): `breadbasket` pins `ProductionUbiquity = Specialist` where the catalog default would be `Ubiquitous`; `terroir_agriculture` pins `MonopolySource`. Equal-or-higher rule: a `production_ubiquity_override` may only be equal or higher concentration than the commodity's global default (CI hard error V-SES-03). Authored for ~80–100 named systems; deterministic-varied heuristic fallback for ~200 unnamed systems (seed-hashed weighted draw over the vocabulary: W_ROLE_PRIMARY=8,000 bps, W_CORP=5,000 bps, W_NOISE=400 bps to every vocabulary value; same seed+system_id always produces the same value; the noise term ensures ~5–10% of unnamed systems draw an off-primary value, preventing all unnamed agricultural worlds from being identical).
+
+  **(2) `system_economy.cultural_specialization TEXT` (new column).** Directs D-232's template pool when a system's cultural character diverges from corridor baseline. Single field carrying two value sub-types: *activity/character values* (`agrarian`, `industrial_heritage`, `institutional`, `scholarly`, `artistic`, `financial_technocratic`, `cosmopolitan`, `compact_cooperative`, etc.) and *heritage-type values* (`scottish`, `vietnamese`, `zulu`, `afrikaans_cape`, `tagalog`, `chinese`, `italian_northern`, `french_provencal`, `norse_compact`, etc.). Heritage values take precedence when both apply. `NULL` = use corridor default (D-232 existing algorithm). Authored for ~60–100 systems where the corridor default would produce wrong D-232 architectural draws in Phase 4 (not a thin Phase 6 concern: a Vietnamese-founded system in the east_reach Korean/Japanese corridor draws the wrong templates without an explicit pin). Does NOT replace `system_culture.cultural_register` (prose NPC/dialogue voice); consumed by the physical generator only.
+
+  **(3) `system_factions.dominant_faction TEXT` — populated, not added.** Column already exists (D-199 field 4); VALUES for named systems are authored in this pass via `system_specialization.toml`. 8-value vocabulary: `concord_assembly | compact | compact_sympathetic | syndic_dominant | veil_institute | independent | disputed | mixed`. `lattice_commission` is dropped — the Commission is a regulatory body under Assembly authority, not a governing faction; ACB and Bastion are `concord_assembly`. Authored for ~40–60 named systems; existing Commission-presence + currency-zone derivation serves as fallback.
+
+  **Groombridge landmark mechanism:** Where a system's authored identity includes a singular MonopolySource-class institution within a Specialist-scale district (Groombridge: `financial_hub`/Specialist + GSH clearing house), the district character is encoded as Specialist in the vocabulary. The singular landmark is expressed via D-222 multi-block reservation + D-232 `atlas_body_trait_bias` hero pin — not via a composite vocabulary value. The vocabulary expresses district-level character; landmark-level identity is the D-232/D-222 mechanism.
+
+  **CI guardrails:** 6 hard errors (vocabulary FK integrity, inhabitance coverage, production_ubiquity monotonicity, vocabulary constraint for all three fields); 8 soft warnings (MonopolySource review list, distribution balance, prose/field divergence, D-172 faction/currency alignment, Compact monoeconomy flag, authoring gap lists). Full CI spec in `docs/workshops/system-economic-specialization/workshop-outcomes.md §8`.
+
+  **Source:** `wiki/economics/system_specialization.toml` (per-system entries) + `wiki/economics/specialization_vocabulary.toml` (vocabulary definition). Both added to `IMPORT_ECONOMICS_SOURCES` for meta-stamp tracking. `system_economy` gains two new columns via `COLUMN_MIGRATIONS` in `import_economics.py`; `specialization_vocabulary` is a new read-only reference table.
+- **Rationale:** The pre-existing D-233 heuristic (`economic_role` + corp HQ + `planet_class` → dominant commodity) fails predictably for: (1) output-vs-input confusions (Cygni B: heuristic sees ore inputs, not freight_hauler outputs); (2) political mandates (Groombridge: financial infrastructure is an institutional choice, not geographic necessity); (3) terroir-locked production (D-177 systems: catalog defaults are globally ubiquitous, not locally monopolistic); (4) service economies (Prometheus, Keid: no heuristic path from available signals to the correct identity). The three-field authored layer resolves all four failure modes. Three fields are the minimum that changes how a system reads without redundancy: economic → D-233 block fill, cultural → D-232 template selection, faction → D-214 political archetype. `cultural_specialization` is a Phase 4 correctness requirement, not Phase 6 enrichment.
+- **Raised by:** System economic-specialization workshop, 2026-05-31. Burnelli-Sheldon (schema, vocabulary, CI, fallback algorithm), Miri (must-pin list, scale gap, D-177 terroir pins, cultural heritage vocabulary), Paula (faction vocabulary, Compact rules, heritage-divergence cultural scope, D-172 compliance), human checkpoint (dual-axis design, scale-in-vocabulary, faction authored, Groombridge landmark mechanism, deterministic-varied fallback).
+- **Dissent:** None.
+- **Cross-reference:** [D-233](#d-233) (re-amended — economic block-fill now sourced from this layer), [D-184](content.md#d-184) (commodity catalog), [D-199](#d-199) (CityGenerationContext read-set — extended), [D-232](#d-232) (architecture-flavor template draw — consumes `cultural_specialization`), [D-214](#d-214) (PoliticalArchetype — consumes `dominant_faction`), [D-172](content.md#d-172) (currency zone alignment — `dominant_faction = compact` validates), [D-174](#d-174) (shadow economy intensity — `compact` elevates), [D-177](content.md#d-177) (productivity constraints — informs monopolistic pins), [D-220](#d-220) (density), [D-197](#d-197) (prosperity), [D-222](#d-222) (multi-block reservation — Groombridge landmark mechanism), [D-178](#d-178) (rolling economy — not touched; this is t=0 authored layer only)
+
+---
+
+*96 decisions (D-001 through D-237, excluding gaps). Last updated: 2026-05-31 (system-economic-specialization workshop — D-237 authored per-system specialization layer: `economic_specialization` + `cultural_specialization` + `dominant_faction`; D-233 re-amended to source from D-237 authored layer).*

docs/diagrams/architecture/specialization-layer.d2

@@ -0,0 +1,83 @@
+# D-237: Authored per-system specialisation layer and its consumers
+# Shows the three authored fields, their sources, and downstream generator consumers.
+
+direction: right
+
+source: "wiki/economics/\nsystem_specialization.toml" {
+  shape: document
+  style.fill: "#e8f4e8"
+}
+
+vocab: "wiki/economics/\nspecialisation_vocabulary.toml" {
+  shape: document
+  style.fill: "#e8f4e8"
+}
+
+db: "systems.db" {
+  shape: cylinder
+  style.fill: "#f0f0f0"
+
+  econ: "system_economy\n.economic_specialization"
+  cult: "system_economy\n.cultural_specialization"
+  fact: "system_factions\n.dominant_faction"
+  specvocab: "specialization_vocabulary\n(compiled reference table)"
+}
+
+fallback: "Deterministic-varied\nheuristic fallback\n(seed-hashed weighted draw\nW_ROLE=8000, W_CORP=5000,\nW_NOISE=400)" {
+  shape: hexagon
+  style.fill: "#fff3cd"
+}
+
+d233: "D-233\nEconomic block-fill\n(BulkClass × ProductionUbiquity\n→ coverage, vocabulary,\noperations surface)" {
+  shape: rectangle
+  style.fill: "#dce8f5"
+}
+
+d232: "D-232\nArchitecture-flavor\n(template pool selection\nfor corridor vs\nheritage-divergent systems)" {
+  shape: rectangle
+  style.fill: "#dce8f5"
+}
+
+d214: "D-214\nPoliticalArchetype\n(settlement spatial layout:\ncommission radial /\ncorporate campus /\ncooperative distributed)" {
+  shape: rectangle
+  style.fill: "#dce8f5"
+}
+
+d174: "D-174\nShadow economy\nintensity" {
+  shape: rectangle
+  style.fill: "#e8dce8"
+}
+
+d172: "D-172\nCurrency zone\nvalidation" {
+  shape: rectangle
+  style.fill: "#e8dce8"
+}
+
+groombridge: "Groombridge\nlandmark mechanism:\nfinancial_hub (Specialist)\n+ GSH hero-element\nvia D-222 + D-232 pin" {
+  shape: oval
+  style.fill: "#fde8cc"
+}
+
+source -> db.econ: "import_economics.py\nimport_system_specialization()" {
+  style.stroke-dash: 3
+}
+source -> db.cult: {
+  style.stroke-dash: 3
+}
+source -> db.fact: {
+  style.stroke-dash: 3
+}
+vocab -> db.specvocab: "compiled reference" {
+  style.stroke-dash: 3
+}
+
+db.econ -> d233: "primary source\n(authored wins)"
+db.econ -> fallback: "NULL → heuristic"
+fallback -> d233
+
+db.cult -> d232: "D-232 template\npool override"
+db.fact -> d214
+db.fact -> d174
+db.fact -> d172
+
+d233 -> groombridge: "Specialist district\ncharacter"