feat(lifecycle): customer population builder [LTV-Ph]

[shaypal5]

Summary

First implementation milestone of the pLTV workstream (LTV-Ph, milestone
LTV-M3). Adds the lifecycle customer population builder — the starting
point for the post-conversion subscription simulation.

What's added

leadforge/schemes/lifecycle/population.py:

• build_customer_population(n_customers, seed, motif_family, *, n_accounts, observation_date, acquisition_window_weeks) → CustomerPopulationResult — single public entry point; fully deterministic via two named RNG substreams.
• CustomerPopulationResult / CustomerLatentState — output dataclasses.
• 5 retention motif families (LIFECYCLE_MOTIF_FAMILIES), each with distinct latent-mean biases:

family	primary driver
product_led_retention	latent_product_fit ↑
relationship_led_retention	latent_champion_strength ↑
expansion_led_growth	latent_adoption_velocity ↑
payment_fragile	latent_budget_stability ↓
churner_dominated	latent_product_fit ↓, latent_champion_strength ↓

• 5 customer latent traits: latent_product_fit, latent_adoption_velocity, latent_budget_stability, latent_champion_strength, latent_organizational_stability.
• D3 seam (independent generation): opportunity_id=None on every customer; reserved for future chaining from a lead-scoring bundle.
• D4 staggered starts: customer_start_at sampled uniformly in [obs_date − acquisition_window_weeks, obs_date), so tenure at the observation date naturally varies from near-zero (cold-start) to the full window.
• Plan + MRR: employee-band-conditional plan tier selection; MRR ranges $1k–$25k/month.

Tests (28)

tests/schemes/lifecycle/test_population.py: shape, determinism, FK integrity (customer→account; latent-state coverage), staggered-start boundary and spread, D3 seam assertion, latent [0,1] bounds + 5-trait completeness, all 5 motif families, motif-bias direction test, field-value assertions.

• Full suite 1565 passed / 51 skipped (+28); ruff + mypy clean.

Next

LTV-Pi — lifecycle motif families + mechanism policies (assign_lifecycle_mechanisms()): churn hazard, expansion propensity, payment-failure params, keyed to the 5 retention motif families built here.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Implements the first lifecycle (pLTV) “customer population builder” for the lifecycle scheme, generating accounts + lifecycle customers + latent traits with deterministic RNG substreams, and adds a comprehensive test suite plus roadmap/plan references.

Changes:

• Added leadforge/schemes/lifecycle/population.py with build_customer_population(...), output dataclasses, motif families, and generation logic.
• Added tests/schemes/lifecycle/test_population.py covering determinism, FK integrity, staggered start dates, latent bounds/shape, motif families, and key field assertions.
• Updated LTV roadmap and agent plan docs to reference the milestone/PR.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
leadforge/schemes/lifecycle/population.py	New lifecycle population generator (accounts/customers/latents) with motif-family latent biases and staggered acquisition window.
tests/schemes/lifecycle/test_population.py	New tests validating shape, determinism, constraints, motif behavior, and field population.
docs/ltv/roadmap.md	Roadmap updated to link milestone item to PR #113.
.agent-plan.md	Agent plan updated to reflect M3 start / PR tracking.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

pr-agent-context report:

This run includes unresolved review comments on PR #113 in repository https://github.com/leadforge-dev/leadforge

For each unresolved review comment, recommend one of: resolve as irrelevant, accept and implement
the recommended solution, open a separate issue and resolve as out-of-scope for this PR, accept and
implement a different solution, or resolve as already treated by the code.

After I reply with my decision per item, implement the accepted actions, resolve the corresponding
PR comments, and push all of these changes in a single commit.

# Copilot Comments

## COPILOT-1
Location: leadforge/schemes/lifecycle/population.py
URL: https://github.com/leadforge-dev/leadforge/pull/113#discussion_r3397854263
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    The module docstring says the two RNG substreams make “population and latent draws … independently stable”, but the code only separates account vs customer generation (entities + latents share the same stream). This wording is misleading; either split entity vs latent substreams or update the docstring to reflect what is actually independent.

## COPILOT-2
Location: leadforge/schemes/lifecycle/population.py
URL: https://github.com/leadforge-dev/leadforge/pull/113#discussion_r3397854322
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    The docstring claims the default observation_date is `_WORLD_BASE_DATE + 1 year`, but the implementation derives it from `acquisition_window_weeks` (and currently adds an extra 4 weeks). Please align the docstring with the implemented default (or vice versa) to avoid surprising callers.

## COPILOT-3
Location: leadforge/schemes/lifecycle/population.py:241
URL: https://github.com/leadforge-dev/leadforge/pull/113#discussion_r3397854353
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    `build_customer_population` doesn’t validate `n_customers`, `n_accounts`, or `acquisition_window_weeks`. Some invalid-but-plausible inputs currently lead to confusing runtime errors (e.g., `n_accounts=0` makes `rng.choice(accounts)` crash), and `acquisition_window_weeks=0` violates the documented `[acq_start, obs_date)` invariant by producing `customer_start_at == obs_date`. Add basic positive-int validation and make the default `observation_date` consistent with the acquisition window without the extra 4-week offset.

Run metadata:

Tool ref: v4
Tool version: 4.0.21
Trigger: commit pushed
Workflow run: 27368792404 attempt 1
Comment timestamp: 2026-06-11T18:30:24.054928+00:00
PR head commit: 86548f1f4bb3330155d1f2f72177837791819a94