feat(lifecycle): calendar-anchored customer snapshot [LTV-Pl]

[shaypal5]

Summary

LTV-Pl (roadmap LTV-M5): the calendar-anchored customer snapshot — the pLTV scheme's ML-ready table, one row per customer active at the observation_date cutoff, with the three continuous ltv_revenue_{90,365,730}d targets.

New: schemes/lifecycle/features.py

CUSTOMER_SNAPSHOT_FEATURES — 27-column catalog (firmographics, at-cutoff subscription state, last-12-week health aggregates, financial signals, leakage trap, 4 targets). This discharges the feature-catalog half of LTV-Pc; the regression task specs + task_type move to LTV-Pn with the task-split writer.

Two design.md §8 columns are deliberately omitted (documented in the module docstring + pinned by test):

• current_plan — the engine has no plan-change mechanism, so it would duplicate initial_plan exactly;
• downgrade_count — no downgrade mechanism, so it would be zero-variance (violates the published-bundle invariant).

New: schemes/lifecycle/snapshots.py

build_customer_snapshot(population, sim, *, cutoff=…, difficulty_params=…, seed=…):

• At-cutoff state from the event chain, not the terminal row — current_mrr, renewal_count, expansion_count, mrr_change_at_snapshot are reconstructed from subscription_events ≤ cutoff (the subscription row holds end-of-simulation state and would leak).
• Health aggregates over (cutoff − 12w, cutoff]; active_user_trend_l12w is an OLS slope; last_nps_score scans the whole history (NPS is quarterly — a 12-week window would miss most customers' latest response purely by phase).
• Targets (D6/D7): gross revenue = paid + recovered invoices, attributed by issuance date, summed over (cutoff, cutoff + window]; churned_within_180d from churn_at. cutoff > observation_date is rejected — the engine only guarantees complete forward windows up to the anchor, so a later cutoff would silently censor targets.
• Trap (design.md §7): mrr_change_full_period = terminal − initial MRR; diverges from the valid counterpart for ~67% of rows on an expansion-led world.
• weeks_to_next_renewal uses the same round(k·term·52/12) boundary as is_renewal_week, so the feature and the hazard spike agree exactly.

Refactor: render/distortions.py

The difficulty-distortion algorithm (noise / MCAR missingness / outliers) extracted verbatim from the lead-scoring snapshot builder into scheme-agnostic apply_difficulty_distortions(feature_specs=…, exempt_cols=…); lead-scoring delegates with its catalog + total_touches_all exemption. Verified byte-identical: sha256 of a distorted lead-scoring snapshot is 196bc45f… before and after the extraction. The lifecycle trap is distortion-exempt for the same pedagogical reason.

Tests (39 new; full suite 1754 passed / 51 skipped)

• Censoring leakage probe: rebuild the snapshot from a sim result with all post-cutoff events deleted — every non-target, non-trap column must be identical. Any feature that changes, leaks.
• Target derivation re-computed row-by-row from the invoice table; failed/written_off exclusion proven on a payment-fragile world (uncollected sum > 0 and totals reconcile).
• ZILN target shape (non-negative, right-skewed, heavy tail), window monotonicity (90 ≤ 365 ≤ 730).
• Trap-divergence invariant (>10% of rows); trap + targets exempt from distortion; distortion determinism per seed.
• Catalog invariants incl. a regression guard pinning the current_plan/downgrade_count omission decision.

Roadmap

• docs/ltv/roadmap.md: LTV-Pl ✓; LTV-Pc annotated (catalog half discharged here, task-spec half folds into LTV-Pn).
• Next: LTV-Pm — early-pLTV tenure-anchored task family reusing this builder with a per-customer cutoff.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds the lifecycle (pLTV) calendar-anchored customer snapshot builder and its feature catalog, plus extracts the snapshot difficulty-distortion logic into a shared scheme-agnostic utility so lifecycle and lead-scoring can reuse identical behavior.

Changes:

• Introduces CUSTOMER_SNAPSHOT_FEATURES and build_customer_snapshot(...) to produce an ML-ready, cutoff-safe customer snapshot with forward-window revenue targets and a deliberate leakage trap.
• Extracts lead-scoring’s snapshot distortion algorithm into leadforge/render/distortions.py and delegates from lead-scoring + lifecycle.
• Adds comprehensive lifecycle snapshot/catalog tests and updates LTV roadmap/agent plan docs.

Reviewed changes

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

Show a summary per file

File	Description
tests/schemes/lifecycle/test_snapshots.py	Adds end-to-end tests for snapshot safety (cutoff censoring), feature derivations, targets, trap, and distortions.
tests/schemes/lifecycle/test_features.py	Adds invariant tests for the lifecycle snapshot feature catalog (targets, trap, omissions).
leadforge/schemes/lifecycle/snapshots.py	Implements the lifecycle customer snapshot builder and helper aggregations.
leadforge/schemes/lifecycle/features.py	Defines the lifecycle snapshot feature catalog (including targets + leakage trap).
leadforge/schemes/lead_scoring/render/snapshots.py	Refactors lead-scoring snapshot distortions to call the shared distortion utility.
leadforge/render/distortions.py	Adds shared distortion implementation (noise/missingness/outliers) driven by FeatureSpec.
docs/ltv/roadmap.md	Updates roadmap status/notes to reflect LTV-Pl completion and scope split.
.agent-plan.md	Updates agent plan status notes for the newly opened/merged roadmap items.

---

💡 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 #119 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/render/distortions.py:105
URL: https://github.com/leadforge-dev/leadforge/pull/119#discussion_r3402599015
Status: outdated
Root author: copilot-pull-request-reviewer

Comment:
    The post-noise non-negative clamps currently include any `non_negative` column in the feature catalog, even if it’s a target or explicitly exempt. This can violate the contract that targets are never distorted (and could also accidentally clamp an exempt leakage-trap column if it were marked non_negative in the future). Filter these clamp lists the same way as the distortion-eligible lists: exclude targets and `exempt_cols`.

## COPILOT-2
Location: leadforge/render/distortions.py:149
URL: https://github.com/leadforge-dev/leadforge/pull/119#discussion_r3402599067
Root author: copilot-pull-request-reviewer

Comment:
    Missingness injection converts `Int64` columns to `Float64` and writes `np.nan`, which changes schema dtypes and loses integer-ness even though pandas nullable `Int64` supports missing values. Consider assigning `pd.NA` directly (and avoid dtype conversion) so distorted snapshots can retain the catalog’s nullable dtypes.

Run metadata:

Tool ref: v4
Tool version: 4.0.21
Trigger: commit pushed
Workflow run: 27412981060 attempt 1
Comment timestamp: 2026-06-12T11:31:54.454632+00:00
PR head commit: 93c720d327f6f85d99133883e82a4f1b11e50ed6