docs(ltv): rework plan around peer generation schemes [LTV-M2]#106
Merged
Conversation
Acts on the maintainer decision that leadforge becomes a platform hosting two
PARALLEL, peer generation schemes (lead_scoring + lifecycle), not a
lead-scoring framework with an LTV bolt-on.
design.md:
- New §2.5 "peer generation schemes": decisions D10 (extract the
GenerationScheme abstraction EARLY, against the known-good lead-scoring path,
output byte-identical) and D11 (physically reorganize into
leadforge/schemes/{lead_scoring,lifecycle}/ now). Adds the scheme→recipe→
bundle hierarchy, the GenerationScheme protocol shape, a shared-envelope vs
per-scheme table, the target package layout, reorg safety rails for the
published 1.x package, and a note that LTV-Pb (#104) already aligns.
- §10 inventory: lifecycle modules now live under schemes/lifecycle/; adds
schemes/base.py; recipe declares scheme: lifecycle.
roadmap.md (reshaped to 9 milestones / ~18 PRs, Pa..Pr):
- New LTV-M2 "Generation-scheme architecture + physical reorg" (LTV-Pd/Pe/Pf):
protocol+registry against lead-scoring → move lead-scoring into
schemes/lead_scoring/ → scaffold schemes/lifecycle/ and relocate the
LTV-Pb/Pc specs.
- Lifecycle build milestones (population/engine/snapshots) renumbered to
M3-M5 and now land directly under schemes/lifecycle/.
- LTV-M6 registers LifecycleScheme end-to-end + recipe + manifest
generation_scheme + schema v6.
.agent-plan.md: scheme-architecture summary + revised status (M2 next; can run
in parallel with M1 since it only touches the existing lead-scoring path).
Stacked on the LTV-Pb branch (#104) because it references that work as done.
No package code in this PR.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
shaypal5
added
type: docs
|
pr-agent-context report: No unresolved review comments, failing checks, or actionable patch coverage gaps were found on PR #106 in repository https://github.com/leadforge-dev/leadforge. Treat this PR as all clear unless new signals appear.Run metadata: |
There was a problem hiding this comment.
Pull request overview
Docs-only update that reshapes the LTV workstream plan around the decision to treat leadforge as a platform hosting two peer generation schemes (lead_scoring and lifecycle), with an early GenerationScheme abstraction and a physical reorg into leadforge/schemes/....
Changes:
- Updates the LTV roadmap to introduce the peer-schemes architecture context and renumber milestones/PRs accordingly.
- Extends the LTV design doc with a new decision pass (§2.5) describing scheme → recipe → bundle hierarchy and target package layout.
- Updates
.agent-plan.mdto reflect the new peer-schemes framing and updated milestone/PR ranges.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
| docs/ltv/roadmap.md | Renumbers milestones and rewrites the roadmap sequencing to land the scheme abstraction + physical reorg early (LTV-M2). |
| docs/ltv/design.md | Adds §2.5 capturing the peer-schemes architecture and updates the framework-changes inventory note/table. |
| .agent-plan.md | Updates the tracker with the peer-schemes framing and revised milestone/PR ranges for the LTV workstream. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | `LTV-M7` | CLI, notebooks, publish | `LTV-Pm`, `LTV-Pn`, `LTV-Po` | | | ||
|
|
||
| Total: ~15 PRs across 8 milestones (LTV-M0 = planning). | ||
| | `LTV-M0` | Planning + design lock | `LTV-Pa` | #102, #103 (+ scheme reframe) | |
Comment on lines
+513
to
+517
| ### New files (logical role → lives under `schemes/lifecycle/`) | ||
|
|
||
| | file | purpose | | ||
| |------|---------| | ||
| | `leadforge/simulation/lifecycle.py` | `simulate_lifecycle()` — weekly-step subscription simulator | | ||
| | `leadforge/simulation/customer_population.py` | `build_customer_population()` — customer entities + latents + staggered starts | | ||
| | `leadforge/render/customer_snapshots.py` | `build_customer_snapshot(cutoff=…)` — per-customer row at a cutoff; serves both regimes | | ||
| | `leadforge/mechanisms/lifecycle_hazards.py` | churn hazard, expansion propensity, payment failure | | ||
| | `leadforge/recipes/b2b_saas_ltv_v1/{recipe,narrative,difficulty_profiles}.yaml` | new recipe | | ||
| | `schemes/lifecycle/engine.py` | `simulate_lifecycle()` — weekly-step subscription simulator | |
Comment on lines
524
to
525
| ### Modified files | ||
|
|
Comment on lines
+507
to
+511
| > **Note (peer-schemes reorg, §2.5):** the lifecycle modules below live under | ||
| > `leadforge/schemes/lifecycle/`, not the flat `simulation/`/`render/`/ | ||
| > `mechanisms/` paths. The flat paths in this table are the *logical* roles; | ||
| > the physical home is the scheme package. `LTV-M2` performs the reorg (moving | ||
| > the existing lead-scoring pipeline into `schemes/lead_scoring/` too). |
Comment on lines
17
to
21
| Goal: add a **predictive-lifetime-value (pLTV) regression** dataset family — | ||
| post-conversion subscription lifecycle (renewals, expansion, churn, payment | ||
| failure) on the same Veridian vertical. New recipe on the existing framework | ||
| via a `recipe_type: lifecycle` dispatch hook, **not** a fork. | ||
|
|
Comment on lines
+42
to
+45
| Status: `LTV-M0` planning landed (#102) + reframed to pLTV regression (#103) + | ||
| reframed to peer schemes. `LTV-M1`: `LTV-Pb` (lifecycle entity rows + | ||
| registries) opened as **#104** (awaiting review). Next is `LTV-M2` | ||
| (`GenerationScheme` abstraction + physical reorg, `LTV-Pd…Pf`) — can start in |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Reworks the LTV plan around the maintainer decision that leadforge becomes a
platform hosting two parallel, peer generation schemes (
lead_scoring+lifecycle) — not a lead-scoring framework with an LTV bolt-on. Docs only.(Supersedes the stacked PR #105, which GitHub auto-closed when its base branch
was deleted on #104's merge. Rebased onto
main; theLTV-Pbcommits droppedas already-upstream, so this is plan-only.)
Decisions captured (design.md §2.5)
GenerationSchemeabstraction early, against the known-good lead-scoring path (wrap, output byte-identical, hash-determinism guarded) before lifecycle plugs inleadforge/schemes/{lead_scoring,lifecycle}/nowPlus the scheme → recipe → bundle hierarchy, the
GenerationSchemeprotocol shape, a shared-envelope-vs-per-scheme table, the target package
layout, and reorg safety rails for the published 1.x package.
Roadmap reshape (9 milestones / ~18 PRs,
Pa..Pr)LTV-M2— Generation-scheme architecture + physical reorg(
LTV-Pd/Pe/Pf).M3–M5, landing underschemes/lifecycle/.LTV-M6registersLifecycleScheme+ recipe + manifestgeneration_scheme🤖 Generated with Claude Code