refactor(api): resolve_config carries lifecycle config fields [LTV-Po.2a]

[shaypal5]

Summary

First half of the split LTV-Po.2 (the config-plumbing enabler; the recipe YAMLs + end-to-end round-trip are Po.2b). Recipe.resolve_config and Generator.from_recipe/generate were lead-scoring-shaped — they only threaded n_accounts/n_contacts/n_leads to GenerationConfig — so a scheme: lifecycle recipe couldn't size its customer cohort (n_customers always took the package default).

Change

• resolve_config now resolves n_customers (from default_population, an explicit kwarg, or the override dict) and early_tenure_weeks / observation_date (from override), and passes all three to GenerationConfig.
• forward_windows_days is deliberately not resolvable — the lifecycle scheme locks it to its exported constant and rejects overrides (LTV-Pn.4c).
• Generator.from_recipe and generate gain an n_customers parameter.

Lead-scoring is unchanged

A recipe without these keys leaves the lifecycle fields at their GenerationConfig defaults — exactly what the previous construction produced. Verified byte-identical via full-bundle SHA-256 of a lead-scoring bundle (both exposure modes) against main.

Tests (4 new; full suite 1885 passed / 51 skipped)

n_customers flows from default_population; kwarg + override precedence; lifecycle fields via override; a lead-scoring-style recipe keeps the lifecycle defaults.

Next: Po.2b — the b2b_saas_ltv_v1 recipe YAMLs (narrative.yaml with ≥2 industries + ≥2 geographies per the Po.1 constraint, difficulty_profiles.yaml), registry registration, difficulty_params resolution in build_world, and the Generator.from_recipe("b2b_saas_ltv_v1").generate() round-trip — which completes M6.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR refactors the public API config plumbing so Recipe.resolve_config and Generator can carry lifecycle-specific sizing/config fields (notably n_customers) through to GenerationConfig, enabling lifecycle recipes to control cohort size instead of always using package defaults.

Changes:

• Extend Recipe.resolve_config to resolve n_customers, early_tenure_weeks, and observation_date into GenerationConfig.
• Add n_customers support to Generator.from_recipe(...) and per-call overrides in Generator.generate(...).
• Add lifecycle-focused resolve_config tests and update LTV roadmap/agent plan notes to reflect the Po.2a split.

Reviewed changes

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

Show a summary per file

File	Description
tests/api/test_resolve_config_lifecycle.py	Adds tests covering lifecycle-field resolution via resolve_config.
leadforge/api/recipes.py	Threads lifecycle config fields (n_customers, early_tenure_weeks, observation_date) through config resolution.
leadforge/api/generator.py	Adds n_customers parameter passthrough/override support in from_recipe and generate.
docs/ltv/roadmap.md	Documents Po.2 split and records Po.2a scope/constraints.
.agent-plan.md	Updates workstream plan text to reflect the Po.2a/Po.2b split.

---

💡 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 #131 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/api/generator.py:55
URL: https://github.com/leadforge-dev/leadforge/pull/131#discussion_r3433266088
Root author: copilot-pull-request-reviewer

Comment:
    `n_customers` was added to `from_recipe(...)`, but the docstring Args list below still jumps from `n_leads` to `horizon_days`, so the new parameter isn't discoverable via docs/help text.

## COPILOT-2
Location: leadforge/api/generator.py:133
URL: https://github.com/leadforge-dev/leadforge/pull/131#discussion_r3433266119
Root author: copilot-pull-request-reviewer

Comment:
    `generate(...)` now accepts `n_customers`, but the docstring still describes only `n_accounts`/`n_contacts`/`n_leads` + `difficulty` as supported per-call overrides, and the Args list omits `n_customers`.

## COPILOT-3
Location: tests/api/test_resolve_config_lifecycle.py:55
URL: https://github.com/leadforge-dev/leadforge/pull/131#discussion_r3433266142
Root author: copilot-pull-request-reviewer

Comment:
    This test module doesn't exercise the advertised override/kwarg precedence for `n_customers` (i.e., override dict beats recipe defaults, and an explicit kwarg beats override). Adding a small precedence test would prevent regressions in the new plumbing.

Run metadata:

Tool ref: v4
Tool version: 4.0.21
Trigger: commit pushed
Workflow run: 27781743840 attempt 1
Comment timestamp: 2026-06-18T18:45:22.676985+00:00
PR head commit: 1bf02d5f2b3921a31d6a456a838061e8a12a2388