refactor: move lead-scoring compute core under schemes/lead_scoring/ [LTV-Pf.1]

[shaypal5]

Summary

First half of the physical reorg (LTV-Pf.1, milestone LTV-M2).
Relocates the lead-scoring hidden-world compute core —
simulation/, mechanisms/, structure/ — as whole directories under
leadforge/schemes/lead_scoring/, so the scheme owns its internals.

Hard break, no shims (decision D12): old import paths are removed and every
in-repo caller updated. Public API (leadforge.api, CLI) is unchanged and
generated bundles are byte-identical — only direct imports of these internal
modules break.

Mechanics

• git mv of the three directories — 21 file renames, history preserved.
• Repo-wide rewrite of the three absolute import prefixes across package +
  tests + scripts; no residual bare references:

old	new
leadforge.simulation.*	leadforge.schemes.lead_scoring.simulation.*
leadforge.mechanisms.*	leadforge.schemes.lead_scoring.mechanisms.*
leadforge.structure.*	leadforge.schemes.lead_scoring.structure.*

Scope (and what's deferred)

• Not in this PR: render/{snapshots,relational,tasks} (that's LTV-Pf.2,
  which also splits render/relational.py so the shared write_relational_tables
  stays in the envelope), and the lead-scoring schema specs (split lands with
  LTV-Pg). Splitting LTV-Pf keeps each PR reviewable and byte-identical.
• Known, intentional: core.models / render.relational carry TYPE_CHECKING-only
  references to the moved structure/simulation paths (a core→scheme type-only
  reference); the layering cleanup is tracked for M6.

Downstream consumer

The leadforge-datasets-private build scripts import these internals and must
update to the new paths — a breakage issue is being filed there. The package
stays on the 1.x line with a CHANGELOG "Moved" note (the public contract is
unchanged).

Verification

✅ BYTE-IDENTICAL vs main (14 files)

• Full suite 1508 passed / 51 skipped; ruff + mypy clean; compileall
  clean for scripts/ + leadforge/.
• BUNDLE_SCHEMA_VERSION unchanged.

🤖 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 #109 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: commit pushed
Workflow run: 27282544984 attempt 1
Comment timestamp: 2026-06-10T14:15:07.802620+00:00
PR head commit: a0fe82e3ed5dafc32623501659f2727ca96790ea

[Copilot]

Pull request overview

Refactors the lead-scoring scheme by physically relocating its compute core (simulation/, mechanisms/, structure/) under leadforge/schemes/lead_scoring/ and rewriting all in-repo import paths accordingly, while keeping the public API unchanged.

Changes:

• Moved lead-scoring internal modules to leadforge.schemes.lead_scoring.{simulation,mechanisms,structure} and updated call sites across package code, tests, and scripts.
• Updated scheme and project documentation (roadmap, changelog, repo layout docs) to reflect the new module locations and the intentional hard-break.
• Adjusted Sphinx references / TYPE_CHECKING imports to point at the new module paths.

Reviewed changes

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

Show a summary per file

File	Description
tests/test_difficulty_modulation.py	Updates mechanism-policy import to new scheme-owned path.
tests/structure/test_sampler.py	Updates structure imports + module-path docstring.
tests/structure/test_rewiring.py	Updates structure imports, including local imports inside tests.
tests/structure/test_node_types.py	Updates node_types import path + module-path docstring.
tests/structure/test_motifs.py	Updates motifs/node_types/graph imports + module-path docstring.
tests/structure/test_graph.py	Updates graph/node_types imports + module-path docstring.
tests/simulation/test_population.py	Updates simulation/structure imports, including a private helper import.
tests/simulation/test_engine.py	Updates simulation/structure imports (multi-line import formatting).
tests/render/test_snapshot_windowed.py	Updates render test imports to new scheme-owned simulation/structure paths.
tests/render/test_render.py	Updates render test imports to new scheme-owned simulation/structure paths.
tests/mechanisms/test_mechanisms.py	Updates mechanism imports to scheme-owned mechanisms package.
scripts/spike_category_signal.py	Updates script imports to new scheme-owned simulation/structure paths.
leadforge/schemes/lead_scoring/structure/sampler.py	Updates structure sampler imports and Sphinx references to new paths.
leadforge/schemes/lead_scoring/structure/rewiring.py	Updates rewiring imports and Sphinx references to new paths.
leadforge/schemes/lead_scoring/structure/node_types.py	Introduces scheme-owned NodeType definitions (StrEnum) and related sets.
leadforge/schemes/lead_scoring/structure/motifs.py	Updates motifs’ imports and Sphinx references to new structure package.
leadforge/schemes/lead_scoring/structure/graph.py	Updates node_types import to new scheme-owned location.
leadforge/schemes/lead_scoring/structure/init.py	Package marker for relocated structure modules.
leadforge/schemes/lead_scoring/simulation/state.py	Updates docstring Sphinx reference to new engine path.
leadforge/schemes/lead_scoring/simulation/population.py	Updates TYPE_CHECKING WorldGraph import to new structure path.
leadforge/schemes/lead_scoring/simulation/engine.py	Updates mechanisms/simulation/structure imports and doc references to new paths.
leadforge/schemes/lead_scoring/simulation/init.py	Package marker for relocated simulation modules.
leadforge/schemes/lead_scoring/mechanisms/transitions.py	Updates mechanisms imports and Sphinx references to new paths.
leadforge/schemes/lead_scoring/mechanisms/static.py	Updates base mechanism imports to new paths.
leadforge/schemes/lead_scoring/mechanisms/scores.py	Updates base mechanism imports and Sphinx references to new paths.
leadforge/schemes/lead_scoring/mechanisms/policies.py	Updates mechanisms imports and Sphinx references to new paths.
leadforge/schemes/lead_scoring/mechanisms/measurement.py	Updates base mechanism imports to new paths.
leadforge/schemes/lead_scoring/mechanisms/influence.py	Updates base mechanism imports to new paths.
leadforge/schemes/lead_scoring/mechanisms/hazards.py	Updates mechanism imports and Sphinx references to new paths.
leadforge/schemes/lead_scoring/mechanisms/counts.py	Updates base mechanism imports to new paths.
leadforge/schemes/lead_scoring/mechanisms/categorical.py	Updates base mechanism imports to new paths.
leadforge/schemes/lead_scoring/mechanisms/base.py	Updates Sphinx reference to policy entry point under new path.
leadforge/schemes/lead_scoring/mechanisms/init.py	Package marker for relocated mechanisms modules.
leadforge/schemes/lead_scoring/init.py	Updates scheme docstring + imports used by build_world to new internal locations.
leadforge/render/snapshots.py	Updates imports/TYPE_CHECKING references to new scheme-owned simulation paths.
leadforge/render/relational.py	Updates TYPE_CHECKING references to new scheme-owned simulation paths.
leadforge/render/manifests.py	Updates TYPE_CHECKING WorldGraph reference to new structure path.
leadforge/exposure/metadata.py	Updates internal assign_mechanisms import to new scheme-owned path.
leadforge/core/models.py	Updates TYPE_CHECKING references to scheme-owned simulation/structure paths.
docs/ltv/roadmap.md	Updates roadmap narrative/split for Pf.1/Pf.2 and hard-break decision.
CLAUDE.md	Updates repo layout documentation to reflect the new schemes/lead_scoring internal structure.
CHANGELOG.md	Documents the internal-path breaking move and provides old→new import path mapping.
.agent-plan.md	Updates project tracker text to reflect Pf split and hard-break decision.

Comments suppressed due to low confidence (11)

leadforge/schemes/lead_scoring/mechanisms/policies.py:34

• The if TYPE_CHECKING: block is currently interleaved within the runtime import section, with additional imports following it. This breaks the import-block pattern used elsewhere in the repo and is likely to trip Ruff's import-sorting (I*) rules; it also makes it less clear which imports are type-only vs required at runtime.
  leadforge/schemes/lead_scoring/structure/rewiring.py:7
• This docstring line exceeds the repo's 100-character line limit (Ruff E501). The longer module path after the refactor pushes it over; wrapping keeps lint green.
  leadforge/schemes/lead_scoring/simulation/engine.py:7
• Several docstring lines here exceed the configured 100-character limit (Ruff E501) after the longer module paths were introduced. Wrapping these references keeps linting green.
  leadforge/schemes/lead_scoring/structure/rewiring.py:4
• This docstring line is now over the 100-character limit (Ruff E501) due to the longer fully-qualified path. Please wrap the Sphinx reference onto its own line.
  leadforge/schemes/lead_scoring/structure/motifs.py:6
• The new longer module path makes these docstring lines exceed the 100-character limit (Ruff E501). Wrapping avoids lint failures without changing meaning.
  leadforge/schemes/lead_scoring/mechanisms/scores.py:6
• These docstring lines exceed the 100-character limit (Ruff E501) with the longer fully-qualified mechanism paths. Splitting the Sphinx references across lines keeps formatting/lint consistent.
  leadforge/schemes/lead_scoring/mechanisms/hazards.py:27
• This docstring argument line is now long enough to violate the 100-character limit (Ruff E501). Wrapping the Sphinx reference onto its own indented line keeps the docstring readable and lint-clean.
  leadforge/schemes/lead_scoring/mechanisms/transitions.py:99
• This docstring line likely exceeds the configured 100-character limit (Ruff E501) after expanding the fully-qualified path. Wrapping the Sphinx reference avoids lint failures.
  leadforge/schemes/lead_scoring/mechanisms/policies.py:244
• This docstring summary line exceeds the 100-character limit (Ruff E501) with the longer fully-qualified class path. Splitting the description across lines keeps linting green.
  leadforge/schemes/lead_scoring/mechanisms/policies.py:258
• These docstring lines are now long enough to violate the 100-character limit (Ruff E501) due to the expanded module paths. Wrapping the class references onto separate lines will keep linting green.
  leadforge/schemes/lead_scoring/simulation/state.py:5
• This docstring line exceeds the 100-character limit (Ruff E501) after expanding the fully-qualified simulate_world path. Wrapping keeps linting green.

---

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