docs(ltv): plan the b2b_saas_ltv_v1 LTV dataset workstream [LTV-Pa]

[shaypal5]

Summary

Planning PR (LTV-Pa, milestone LTV-M0) for the new
customer-lifetime-value workstream. Docs only — no package code.

Adds the design (single source of truth) and a milestone/PR roadmap for
b2b_saas_ltv_v1: a post-conversion subscription-lifecycle dataset (renewals,
expansion, churn, payment failure, LTV) on the same Veridian vertical. It is a
new recipe on the existing framework via a recipe_type: lifecycle
dispatch hook in Generator.generate() — not a fork. CLI, bundle format, RNG,
exposure modes, and the validation harness are reused.

Locked design decisions (2026-06-10)

#	Decision
D1	Primary task churn_within_180_days (binary); ltv_bucket_6m as secondary task in the same bundle
D2	Weekly simulation steps (granular health-signal trend curves)
D3	Independent generation for v1; chaining-from-leads designed-for-later
D4	Staggered start dates + fixed absolute observation_date (varying tenure-at-observation)
D5	Bump BUNDLE_SCHEMA_VERSION 5 → 6

D4 is load-bearing: the lifecycle path filters events by an absolute
observation_date, not the lead-scoring path's per-entity relative
snapshot_day. The customer snapshot builder is a separate function so the
lead-scoring path is untouched.

What's inside

• docs/ltv/design.md — entities (subscription_events, health_signals,
  invoices + extended customers/subscriptions), lifecycle mechanisms
  (Weibull churn hazard w/ renewal spike, expansion propensity, payment
  failure + dunning), 5 retention motif families, the
  mrr_change_full_period leakage trap, snapshot-safety contract, framework
  change inventory, difficulty profiles.
• docs/ltv/roadmap.md — milestones LTV-M0…M7, PRs LTV-Pa…Pn.

Planning notation

Work items use an LTV- prefix so they never collide with GitHub PR numbers:
LTV-M1…M7 (milestones) and LTV-Pa…Pn (PRs). Each merged PR records
its GitHub #NNN back into the roadmap table — the two namespaces stay
distinct.

Scope / non-goals

• No package code changes; framework edits begin at LTV-M1.
• The CLAUDE.md hard-constraint clause for lifecycle snapshot-safety lands
  with the recipe wiring (LTV-M5), not here.

🤖 Generated with Claude Code

[github-actions]

pr-agent-context report:

No unresolved review comments, failing checks, or actionable patch coverage gaps were found on PR #102 in repository https://github.com/leadforge-dev/leadforge. Treat this PR as all clear unless new signals appear.

Run metadata:

Tool ref: v4
Tool version: 4.0.21
Trigger: pull request opened
Workflow run: 27258992262 attempt 1
Comment timestamp: 2026-06-10T06:57:57.822338+00:00
PR head commit: 636b9226d55deeaf580a28919e8e10d53b6296ac

[Copilot]

Pull request overview

Planning/documentation PR for the new b2b_saas_ltv_v1 customer lifetime value (post-conversion lifecycle) dataset workstream, establishing the design “single source of truth” plus a milestone/PR roadmap and updating project reference docs to point to them.

Changes:

• Add LTV workstream design spec (docs/ltv/design.md) covering entities, mechanisms, snapshot-safety/leakage traps, and planned framework touchpoints.
• Add LTV workstream roadmap (docs/ltv/roadmap.md) with milestones LTV-M0…M7 and PR breakdown LTV-Pa…Pn.
• Reference the new LTV docs from CLAUDE.md and update .agent-plan.md to reflect the next workstream.

Reviewed changes

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

File	Description
docs/ltv/roadmap.md	Introduces the milestone/PR execution plan for the LTV dataset workstream.
docs/ltv/design.md	Defines the LTV dataset design, constraints (snapshot-safety), and intended framework changes.
CLAUDE.md	Adds the LTV docs under “Reference Docs” for discoverability.
.agent-plan.md	Updates the “Next Workstream” section to the LTV planning effort and links the source-of-truth docs.

---

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