feat: Milestone 1 — canonical config, recipe, and model objects

[shaypal5]

Summary

Implements the typed configuration and recipe system that all simulation work will depend on (Milestone 1 / v0.2.0).

• core/rng.py — RNGRoot: single seeded root with SHA-256-derived deterministic named substreams; every stochastic component must obtain its random.Random via root.child(name)
• core/hashing.py — hash_config(): stable SHA-256 digest of a GenerationConfig for manifest identity
• core/serialization.py — load_yaml, load_json, dump_json helpers used across the package
• core/models.py — GenerationConfig gains __post_init__ validation (positive counts, non-negative seed, enum coercion) and a package_version field
• api/recipes.py — typed Recipe dataclass (frozen) with from_dict() validation and resolve_config() implementing the full 4-layer config precedence: explicit kwargs > override dict > recipe defaults > package defaults
• api/generator.py — Generator.from_recipe() fully implemented; generate() stubs to v0.3.0
• Recipe assets — narrative.yaml (company, product, market, GTM, personas, funnel stages) and difficulty_profiles.yaml (intro / intermediate / advanced signal-noise profiles) for b2b_saas_procurement_v1

Test plan

• 39 new tests across tests/core/test_rng.py, tests/core/test_hashing.py, tests/api/test_recipes.py, tests/api/test_generator.py — total 59 passing
• ruff clean, mypy clean (31 source files)
• Config precedence all 4 layers covered by property-style tests
• RNG determinism: same seed → same sequence; different names → different sequences
• Hash stability: same config → same hash; field change → different hash
• Real recipe round-trip: load → Recipe.from_dict → resolve_config → Generator

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Implements Milestone 1’s canonical config/recipe plumbing that future simulation layers will build on, including deterministic RNG substreams, stable config hashing for manifest identity, and typed recipe/config resolution.

Changes:

• Add RNGRoot for deterministic named RNG substreams and hash_config() for stable GenerationConfig digests.
• Introduce typed Recipe with validation + 4-layer config precedence resolution; wire Generator.from_recipe() to recipe registry loading.
• Add serialization helpers and new recipe narrative/difficulty profile YAML assets, plus a test suite covering core behaviors.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
leadforge/core/rng.py	Adds seeded RNG root with SHA-256-derived deterministic child streams.
leadforge/core/hashing.py	Adds canonicalization + SHA-256 hashing for GenerationConfig.
leadforge/core/serialization.py	Adds shared YAML/JSON load + JSON dump helpers.
leadforge/core/models.py	Adds GenerationConfig validation + package_version field; updates milestone notes.
leadforge/api/recipes.py	Introduces frozen Recipe model, validation, narrative/profile loaders, and config precedence resolution.
leadforge/api/generator.py	Implements Generator.from_recipe() and adds config property; generate() remains stubbed.
leadforge/api/__init__.py	Exposes Recipe and list_recipes in the public API.
leadforge/recipes/b2b_saas_procurement_v1/narrative.yaml	Adds narrative defaults asset for the recipe.
leadforge/recipes/b2b_saas_procurement_v1/difficulty_profiles.yaml	Adds difficulty profiles asset for the recipe.
tests/core/test_rng.py	Adds determinism/independence/validation tests for RNGRoot.
tests/core/test_hashing.py	Adds stability/difference tests for hash_config().
tests/api/test_recipes.py	Adds validation + config precedence tests for Recipe.
tests/api/test_generator.py	Adds tests for Generator.from_recipe() config wiring + determinism.
tests/api/__init__.py	Adds package marker for API tests (empty init).
.agent-plan.md	Updates project plan status to reflect Milestone 1 completion and Milestone 2 focus.

---

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

[Copilot]

Pull request overview

Copilot reviewed 14 out of 15 changed files in this pull request and generated 7 comments.

---

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

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 6 comments.

---

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

[Copilot]

Pull request overview

Copilot reviewed 16 out of 17 changed files in this pull request and generated 1 comment.

---

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

[github-actions]

pr-agent-context report:

This run includes an unresolved review comment on PR #4.

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/recipes.py:106
URL: https://github.com/leadforge-dev/leadforge/pull/4#discussion_r3107487349
Root author: copilot-pull-request-reviewer

Comment:
    `horizon_days` is coerced via `int(...)`, which will silently accept `True` (→ 1) and truncate floats. That can let malformed recipe YAML pass validation and produce unintended horizons. Validate `horizon_days` as a positive plain `int` (explicitly rejecting `bool`) and raise `InvalidRecipeError` on bad types/values, similar to `GenerationConfig.__post_init__`.

Run metadata:

Tool ref: v4
Tool version: 4.0.18
Trigger: commit pushed
Workflow run: 24639305551 attempt 1
Comment timestamp: 2026-04-19T21:15:34.877212+00:00
PR head commit: fce7ef90c5dd5ed1a730a1f0accb9f100e8ab11d