feat(engine): Family Bond Kundali Phase 1.5 — rashyadhipati, cross-chart, wealth flow

Add 6 new engine compute modules and 3 model files for cross-chart
family analysis. Key fix: Rahu/Ketu gemstone recommendations now resolve
via sign lord's functional nature per lagna (rashyadhipati principle)
instead of defaulting to "neutral".

New modules:
- functional_nature: any planet's functional classification per lagna +
  Rahu/Ketu shadow planet resolution via BPHS rashyadhipati
- cross_chart: inter-chart planetary overlays (Moon contacts, axis
  contacts, karmic links with Saturn/Rahu/Ketu)
- wealth_flow: earner/accumulator/distributor classification from
  2L/10L/11L house placements
- conjunction_penalty: gemstone weight reduction when lagnesh conjuncts
  Rahu/6L/8L/12L (BV Raman insight)
- family_gemstone_synergy: cross-family gemstone complementarity
  detection ("one's poison = other's nectar")
- dasha_sync: synchronized Mahadasha/Antardasha timeline for family

Extended gem_therapy_core.py to post-process Rahu/Ketu via
get_shadow_planet_nature() — fixes the Gomed miss for Vrischik lagna.

Also fixes stale worktree path in test_yoga_new_definitions.py.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: master12coder

docs/products/family-bond.md

@@ -0,0 +1,93 @@
+# Family Bond Kundali (परिवार बंध कुण्डली)
+
+> Cross-chart family analysis — gemstone synergy, wealth flow, dasha sync
+
+## Status
+
+- **Phase 1.5 (Engine)**: DONE — 6 compute modules, 3 model files, gem_therapy_core extended
+- **Phase 4 (Plugin)**: NOT STARTED — plugin, prompts, CLI commands deferred
+
+## The Discovery
+
+Individual kundali analysis treats each person in isolation. A real Varanasi
+Pandit considers cross-chart interactions:
+
+1. **Rashyadhipati**: Rahu/Ketu give results of their sign lord's functional
+   nature. Without this, Gomed was incorrectly "neutral" for Vrischik lagna
+   when it should be SAFE (Rahu in Dhanu, sign lord = Jupiter = 2+5L = most benefic).
+
+2. **Karmic Complementarity**: One spouse's prohibited stone = the other's
+   recommended stone. "जो एक के लिए विष, दूसरे के लिए अमृत"
+
+3. **Wealth Flow**: Who earns vs who accumulates — determines which spouse
+   should manage finances.
+
+4. **Conjunction Penalty**: Lagnesh conjunct Rahu/6L/8L/12L reduces gemstone
+   weight (stone amplifies ALL conjunct energies).
+
+## Engine Modules (Phase 1.5)
+
+| Module | Purpose | Lines |
+|--------|---------|-------|
+| `compute/functional_nature.py` | Functional nature of any planet per lagna + Rahu/Ketu rashyadhipati | ~140 |
+| `compute/cross_chart.py` | Cross-chart planetary interactions between two charts | ~210 |
+| `compute/wealth_flow.py` | Earner/accumulator/distributor classification | ~120 |
+| `compute/conjunction_penalty.py` | Gemstone weight penalty from malefic conjunctions | ~80 |
+| `compute/family_gemstone_synergy.py` | Cross-family gemstone complementarity analysis | ~170 |
+| `compute/dasha_sync.py` | Synchronised dasha timeline for family members | ~125 |
+| `models/functional_nature.py` | FunctionalNature, ShadowPlanetNature | ~50 |
+| `models/cross_chart.py` | PlanetOverlay, CrossChartResult | ~50 |
+| `models/family_bond.py` | WealthFlowProfile, ConjunctionPenalty, FamilyGemSynergyResult, DashaSyncResult | ~110 |
+
+### Key Extension: gem_therapy_core.py
+
+Post-processes Rahu/Ketu via `get_shadow_planet_nature()`. Rahu/Ketu no longer
+default to "neutral" — they resolve through their sign lord's functional nature
+per the lagna. This is the fix for the Gomed miss.
+
+## API
+
+```python
+# Functional nature (any planet, any lagna)
+from daivai_engine.compute.functional_nature import get_functional_nature, get_shadow_planet_nature
+nature = get_functional_nature("Jupiter", "Scorpio")  # yogakaraka, 2+5L
+shadow = get_shadow_planet_nature("Rahu", chart)  # sign lord resolution
+
+# Cross-chart interactions
+from daivai_engine.compute.cross_chart import compute_cross_chart_interactions
+result = compute_cross_chart_interactions(chart_a, chart_b)
+
+# Wealth flow
+from daivai_engine.compute.wealth_flow import classify_wealth_flow
+profile = classify_wealth_flow(chart)  # "accumulator", "distributor", etc.
+
+# Conjunction penalty
+from daivai_engine.compute.conjunction_penalty import compute_conjunction_penalty
+penalty = compute_conjunction_penalty(chart, "Mercury")  # penalty_factor: 0.50
+
+# Family gemstone synergy
+from daivai_engine.compute.family_gemstone_synergy import compute_family_gem_synergy
+synergy = compute_family_gem_synergy([chart_a, chart_b])
+
+# Dasha sync
+from daivai_engine.compute.dasha_sync import compute_dasha_sync
+sync = compute_dasha_sync([chart_a, chart_b])
+```
+
+## Validation Cases
+
+| Case | Individual | Family Bond |
+|------|-----------|-------------|
+| Gomed for Vrischik lagna (Rahu in Dhanu) | neutral | SAFE (Jupiter = 2+5L) |
+| Pukhraj: Manish (Mithuna) vs Vaishali (Vrischik) | Manish: prohibited | Karmic complement |
+| Mercury conjunct Rahu (Manish) | Panna: recommended | Panna: recommended at 50% weight |
+| Wealth flow (Manish: 2L+11L+10L in 12th) | Not analysed | Distributor pattern |
+
+## Deferred to Phase 4
+
+- `products/plugins/family_bond/` plugin
+- LLM prompt templates (couple_analysis, wealth_strategy, gemstone_family)
+- CLI commands (`daivai family bond`, `daivai family add`)
+- Multi-school validation matrix (7 schools, weighted voting)
+- PDF report rendering
+- `family_bond_rules.yaml` knowledge file

engine/src/daivai_engine/compute/conjunction_penalty.py

@@ -0,0 +1,84 @@
+"""Gemstone weight penalty for planets conjunct malefic influences.
+
+When a recommended planet (e.g., Lagnesh) conjuncts Rahu, 6th lord, 8th lord,
+or 12th lord, the gemstone amplifies ALL conjunct energies — not just the
+target planet.  This module computes a penalty factor (0.0-1.0) to reduce
+the recommended stone weight.
+
+Source: BV Raman, *How to Judge a Horoscope* Vol.II — stone activation
+risk from malefic conjunction partners.
+"""
+
+from __future__ import annotations
+
+from daivai_engine.compute.chart import are_conjunct, get_house_lord
+from daivai_engine.models.chart import ChartData
+from daivai_engine.models.family_bond import ConjunctionPenalty
+
+
+# Penalty factors by conjunct partner type.  1.0 = no penalty.
+_PENALTY_RAHU = 0.65  # Rahu amplifies obsession / shadow qualities
+_PENALTY_KETU = 0.70  # Ketu amplifies detachment / sudden events
+_PENALTY_6L = 0.75  # 6th lord = enemies, disease, debt
+_PENALTY_8L = 0.70  # 8th lord = sudden events, surgery, accident
+_PENALTY_12L = 0.75  # 12th lord = expenditure, loss, foreign lands
+
+# The minimum aggregate penalty factor (floor).
+_MIN_PENALTY = 0.50
+
+
+def compute_conjunction_penalty(chart: ChartData, planet: str) -> ConjunctionPenalty:
+    """Check if *planet* conjuncts Rahu, Ketu, 6L, 8L, or 12L and compute penalty.
+
+    The penalty factor is multiplicative: if the planet conjuncts both Rahu
+    (0.65) and 12L (0.75) the combined factor is 0.65 * 0.75 = ~0.49, floored
+    at 0.50.
+
+    Args:
+        chart: Computed birth chart.
+        planet: The planet whose gemstone weight we are adjusting.
+
+    Returns:
+        ConjunctionPenalty with has_penalty, penalty_factor, conjunct list,
+        and reasoning.
+    """
+    conjunct_with: list[str] = []
+    factor = 1.0
+
+    # Check shadow planets
+    for shadow, pen in [("Rahu", _PENALTY_RAHU), ("Ketu", _PENALTY_KETU)]:
+        if shadow != planet and are_conjunct(chart, planet, shadow):
+            conjunct_with.append(shadow)
+            factor *= pen
+
+    # Check dusthana lords (6, 8, 12)
+    dusthana_map = {6: _PENALTY_6L, 8: _PENALTY_8L, 12: _PENALTY_12L}
+    seen_lords: set[str] = set()
+
+    for house, pen in dusthana_map.items():
+        lord = get_house_lord(chart, house)
+        if lord == planet or lord in seen_lords:
+            continue
+        seen_lords.add(lord)
+        if are_conjunct(chart, planet, lord):
+            conjunct_with.append(f"{lord} ({house}L)")
+            factor *= pen
+
+    factor = max(factor, _MIN_PENALTY)
+    has_penalty = factor < 1.0
+
+    if has_penalty:
+        reasoning = (
+            f"{planet} conjuncts {', '.join(conjunct_with)} → "
+            f"reduce stone weight to {factor:.0%} of base recommendation."
+        )
+    else:
+        reasoning = f"{planet} has no malefic conjunction partners."
+
+    return ConjunctionPenalty(
+        planet=planet,
+        has_penalty=has_penalty,
+        penalty_factor=round(factor, 2),
+        conjunct_with=conjunct_with,
+        reasoning=reasoning,
+    )

engine/src/daivai_engine/compute/cross_chart.py

@@ -0,0 +1,213 @@
+"""Cross-chart (synastry) planetary interaction analysis.
+
+Computes planet-on-planet overlays between two birth charts to identify
+emotional influence (Moon contacts), relationship dynamics (axis contacts),
+karmic bonds (Saturn/Rahu contacts), and general synastry interactions.
+
+Source: Parashari synastry principles adapted for computational analysis.
+"""
+
+from __future__ import annotations
+
+from daivai_engine.compute.chart import get_house_lord
+from daivai_engine.constants.misc import FULL_CIRCLE_DEG, HALF_CIRCLE_DEG
+from daivai_engine.constants.signs import SIGN_LORDS, SIGNS
+from daivai_engine.models.chart import ChartData
+from daivai_engine.models.cross_chart import CrossChartResult, PlanetOverlay
+
+
+_ALL_PLANETS = ["Sun", "Moon", "Mars", "Mercury", "Jupiter", "Venus", "Saturn", "Rahu", "Ketu"]
+_KARMIC_PLANETS = {"Saturn", "Rahu", "Ketu"}
+
+# Aspect orbs (degrees)
+_ORB_CONJUNCTION = 10.0
+_ORB_OPPOSITION = 10.0
+_ORB_TRINE = 8.0
+_ORB_SQUARE = 7.0
+_ORB_SEXTILE = 6.0
+
+# Aspect definitions: (target_degrees, name, orb)
+_ASPECTS: list[tuple[float, str, float]] = [
+    (0.0, "conjunction", _ORB_CONJUNCTION),
+    (180.0, "opposition", _ORB_OPPOSITION),
+    (120.0, "trine", _ORB_TRINE),
+    (240.0, "trine", _ORB_TRINE),
+    (90.0, "square", _ORB_SQUARE),
+    (270.0, "square", _ORB_SQUARE),
+    (60.0, "sextile", _ORB_SEXTILE),
+    (300.0, "sextile", _ORB_SEXTILE),
+]
+
+
+def compute_cross_chart_interactions(
+    chart_a: ChartData,
+    chart_b: ChartData,
+    orb: float = _ORB_CONJUNCTION,
+) -> CrossChartResult:
+    """Find where Person A's planets overlay Person B's chart.
+
+    Analyses all planet pairs across two charts and categorises them into:
+    - overlays: all significant aspects between charts
+    - moon_contacts: any planet of A on B's Moon (or vice versa)
+    - axis_contacts: Lagnesh-on-Moon, 7th-lord-on-Lagna cross-references
+    - karmic_links: Saturn or Rahu/Ketu contacts indicating deep karmic bonds
+
+    Args:
+        chart_a: First person's birth chart.
+        chart_b: Second person's birth chart.
+        orb: Default orb for conjunction detection (degrees).
+
+    Returns:
+        CrossChartResult with categorised overlays and a bond strength score.
+    """
+    overlays: list[PlanetOverlay] = []
+    moon_contacts: list[PlanetOverlay] = []
+    axis_contacts: list[PlanetOverlay] = []
+    karmic_links: list[PlanetOverlay] = []
+
+    # Compute all inter-chart aspects
+    for pa_name in _ALL_PLANETS:
+        pa = chart_a.planets[pa_name]
+        for pb_name in _ALL_PLANETS:
+            pb = chart_b.planets[pb_name]
+            aspect = _find_aspect(pa.longitude, pb.longitude)
+            if aspect is None:
+                continue
+
+            aspect_type, orb_deg = aspect
+            effect = _classify_effect(aspect_type, pa_name, pb_name)
+            sign = SIGNS[pa.sign_index]
+
+            overlay = PlanetOverlay(
+                person_a_name=chart_a.name,
+                person_b_name=chart_b.name,
+                planet_a=pa_name,
+                planet_b=pb_name,
+                sign=sign,
+                orb_degrees=round(orb_deg, 2),
+                interaction_type=aspect_type,
+                effect=effect,
+                description=_describe(
+                    chart_a.name, pa_name, chart_b.name, pb_name, aspect_type, effect
+                ),
+            )
+            overlays.append(overlay)
+
+            # Categorise
+            if pb_name == "Moon" or pa_name == "Moon":
+                moon_contacts.append(overlay)
+            if pa_name in _KARMIC_PLANETS or pb_name in _KARMIC_PLANETS:
+                karmic_links.append(overlay)
+
+    # Axis contacts: Lagnesh-on-Moon, 7L-on-Lagna
+    axis_contacts = _find_axis_contacts(chart_a, chart_b, overlays)
+
+    bond_strength = _compute_bond_strength(overlays, moon_contacts, axis_contacts, karmic_links)
+
+    summary = _build_summary(chart_a.name, chart_b.name, overlays, moon_contacts, karmic_links)
+
+    return CrossChartResult(
+        person_a=chart_a.name,
+        person_b=chart_b.name,
+        overlays=overlays,
+        moon_contacts=moon_contacts,
+        axis_contacts=axis_contacts,
+        karmic_links=karmic_links,
+        bond_strength=round(bond_strength, 1),
+        summary=summary,
+    )
+
+
+def _find_aspect(lon_a: float, lon_b: float) -> tuple[str, float] | None:
+    """Check if two longitudes form a significant aspect."""
+    diff = (lon_b - lon_a) % FULL_CIRCLE_DEG
+    for target, name, max_orb in _ASPECTS:
+        orb_deg = abs(diff - target)
+        if orb_deg > HALF_CIRCLE_DEG:
+            orb_deg = FULL_CIRCLE_DEG - orb_deg
+        if orb_deg <= max_orb:
+            return name, orb_deg
+    return None
+
+
+def _classify_effect(aspect_type: str, planet_a: str, planet_b: str) -> str:
+    """Classify the qualitative effect of an aspect."""
+    if aspect_type in ("trine", "sextile"):
+        return "supportive"
+    if aspect_type in ("square", "opposition"):
+        if planet_a in _KARMIC_PLANETS or planet_b in _KARMIC_PLANETS:
+            return "karmic"
+        return "challenging"
+    # Conjunction
+    if planet_a in _KARMIC_PLANETS or planet_b in _KARMIC_PLANETS:
+        return "karmic"
+    return "neutral"
+
+
+def _find_axis_contacts(
+    chart_a: ChartData,
+    chart_b: ChartData,
+    overlays: list[PlanetOverlay],
+) -> list[PlanetOverlay]:
+    """Find Lagnesh-on-Moon and 7L-on-Lagna cross-references."""
+    axis: list[PlanetOverlay] = []
+    lagnesh_a = SIGN_LORDS[chart_a.lagna_sign_index]
+    lagnesh_b = SIGN_LORDS[chart_b.lagna_sign_index]
+    seventh_lord_a = get_house_lord(chart_a, 7)
+    seventh_lord_b = get_house_lord(chart_b, 7)
+
+    axis_pairs = {
+        (lagnesh_a, "Moon"),  # A's identity on B's emotions
+        ("Moon", lagnesh_b),  # B's identity on A's emotions
+        (seventh_lord_a, lagnesh_b),  # A's 7L on B's Lagna
+        (seventh_lord_b, lagnesh_a),  # B's 7L on A's Lagna
+    }
+
+    for ov in overlays:
+        if (ov.planet_a, ov.planet_b) in axis_pairs:
+            axis.append(ov)
+    return axis
+
+
+def _compute_bond_strength(
+    overlays: list[PlanetOverlay],
+    moon_contacts: list[PlanetOverlay],
+    axis_contacts: list[PlanetOverlay],
+    karmic_links: list[PlanetOverlay],
+) -> float:
+    """Compute a 0-100 bond strength score."""
+    score = 0.0
+    # Each overlay contributes based on type
+    weights = {"conjunction": 4.0, "trine": 3.0, "sextile": 2.0, "opposition": 2.5, "square": 1.5}
+    for ov in overlays:
+        score += weights.get(ov.interaction_type, 1.0)
+    # Moon contacts are emotionally significant
+    score += len(moon_contacts) * 3.0
+    # Axis contacts indicate deep relationship dynamics
+    score += len(axis_contacts) * 5.0
+    # Karmic links indicate lasting bond
+    score += len(karmic_links) * 2.0
+    return min(score, 100.0)
+
+
+def _describe(
+    name_a: str, planet_a: str, name_b: str, planet_b: str, aspect: str, effect: str
+) -> str:
+    """Build a human-readable description of an overlay."""
+    return f"{name_a}'s {planet_a} {aspect} {name_b}'s {planet_b} — {effect} influence."
+
+
+def _build_summary(
+    name_a: str,
+    name_b: str,
+    overlays: list[PlanetOverlay],
+    moon_contacts: list[PlanetOverlay],
+    karmic_links: list[PlanetOverlay],
+) -> str:
+    """Build a one-paragraph summary of the cross-chart analysis."""
+    parts = [f"{name_a} x {name_b}: {len(overlays)} cross-chart aspects found."]
+    if moon_contacts:
+        parts.append(f"{len(moon_contacts)} Moon contacts (emotional bond).")
+    if karmic_links:
+        parts.append(f"{len(karmic_links)} karmic links (Saturn/Rahu/Ketu).")
+    return " ".join(parts)