feat: Milestone 5 — population generation and latent state initialisation

.agent-plan.md

@@ -6,33 +6,44 @@
 
 ## Current System State
 
-**v0.3.0 in progress — Milestone 4 complete (PR open).** Hidden world graph fully implemented:
-typed node system, DAG-validated WorldGraph, all 5 v1 motif families, stochastic rewiring, and
-graph sampler. 327 tests passing.
+**v0.3.0 in progress — Milestone 5 complete (PR open).** Population generation fully
+implemented: accounts, contacts, leads with all observable fields, full latent state
+(8 traits across 3 entity types), motif-family-aware bias, and FK integrity guaranteed.
+358 tests passing.
 
 ---
 
-## Active Task Breakdown — Milestone 5: Population Generation (v0.3.0)
+## Active Task Breakdown — Milestone 6: Mechanism Layer v1 (v0.3.0)
 
-Goal: Generate the base commercial world population before dynamic events begin.
+Goal: Implement the static and dynamic mechanisms that drive simulation behavior.
 
-- [ ] **1. Account generation** (`simulation/population.py`) — accounts with latent traits
-- [ ] **2. Contact generation** — contacts conditional on account properties
-- [ ] **3. Lead creation** — leads anchored to contacts/accounts
-- [ ] **4. Latent-state initialisation** — sample core latent traits tied to graph/motif
+- [ ] **1. Base mechanism interface** (`mechanisms/base.py`)
+- [ ] **2. Static mechanisms** — categorical, ordinal, bounded-numeric draws (`mechanisms/static.py`)
+- [ ] **3. Transition mechanisms** — lead-stage advancement logic (`mechanisms/transitions.py`)
+- [ ] **4. Score/hazard mechanisms** — latent-to-observable scoring, conversion hazard (`mechanisms/scores.py`, `mechanisms/hazards.py`)
+- [ ] **5. Measurement mechanisms** — noisy proxy observation of latent traits (`mechanisms/measurement.py`)
 
 ---
 
 ## Context Pointers
 
-- Milestone 5 scope: `docs/leadforge_implementation_plan.md` §8 "Milestone 5"
-- Structure spec: `docs/leadforge_architecture_spec.md` §11
+- Milestone 6 scope: `docs/leadforge_implementation_plan.md` §9 "Milestone 6"
+- Mechanism types: `docs/leadforge_architecture_spec.md` §10 "Mechanism layer"
 - Latent variables: `docs/leadforge_architecture_spec.md` §9
 
 ---
 
 ## Completed Phases
 
+### Milestone 5 — Population Generation ✓ (v0.3.0 in PR)
+- `leadforge/simulation/population.py`: `build_population()` — accounts (3 latent traits),
+  contacts (4 latent traits, conditional on account), leads (1 latent trait, FK-consistent),
+  `LatentState` and `PopulationResult` output types
+- Motif-family latent biases (`_MOTIF_LATENT_BIAS`) linking world structure to population
+- `tests/simulation/test_population.py`: 26 tests covering counts, determinism, FK integrity,
+  latent value ranges, trait completeness, motif bias properties, and observable field validity
+- Total: 358 tests passing
+
 ### Milestone 4 — World Structure Layer ✓ (v0.3.0 in PR)
 - `leadforge/structure/node_types.py`: `NodeType` enum (9 categories); `ROOT_ELIGIBLE`,
   `REQUIRES_PARENT`, `LEAF_ONLY` constraint sets