astrology-lens-planets-in-transit

Astrology Lens — Planets in Transit

A lens, not a full reading. It looks up Robert Hand's Planets in Transit: Life Cycles for Living in the astro-sources wiki and emits structured, citation-backed transit delineation claims for the compose layer to weave into prose.

When to use

Use this lens when the prompt involves:

• a transit-to-natal aspect, e.g. “Neptune opposing my Ascendant,” “Saturn square Moon,” “Mars trine Neptune”;
• a transiting planet through a natal house, e.g. “Jupiter in my 7th house”;
• a transit calendar/background transit reading where each exact hit needs source-grounded interpretive support;
• user explicitly says “Robert Hand,” “Planets in Transit,” or asks what the book says.

Do not use this lens for static natal placements, decans, rulership chains, or Human Design. It complements, not replaces, astrology-lens-rulership-chains and astrology-lens-decans-36-faces.

Source package

Preferred source locations, in order:

1. $ASTRAL_ASTRO_SOURCES_WIKI when set by an Astral tenant container.
2. /data/hermes/shared-wikis/astro-sources inside Astral tenant Hermes homes.
3. /home/avalon/astro-sources-wiki on Alex's main VPS / astro profile.

Required files:

• concepts/planets-in-transit.md
• raw/books/planets-in-transit/indexes/transit-heading-index.json
• raw/books/planets-in-transit/reports/transit-heading-quality-report.md
• raw/books/planets-in-transit/chapters/*.md

The heading index is the fast path. It was generated by scripts/planets_in_transit_heading_qa.py and has normalized OCR-damaged headings while preserving verbatim page-level evidence.

Lens contract

Input: one or more transit hits from astral-transit-calendar / astral-chart-api, or a natural-language request that can be normalized to a heading.

Output: structured JSON-like claims for the compose layer:

{
  "lens": "planets-in-transit",
  "version": "0.1.0",
  "claims": [
    {
      "kind": "transit-source-delineation",
      "heading": "Neptune Opposition Ascendant",
      "transitingPlanet": "Neptune",
      "aspect": "Opposition",
      "natalPoint": "Ascendant",
      "summary": "Close relationships, advice, partnership and legal/open-enemy situations become foggy; the remedy is explicit communication and critical awareness.",
      "source": "Planets in Transit",
      "pdfPage": 484,
      "chapterFile": "raw/books/planets-in-transit/chapters/chapter-12-neptune.md"
    }
  ],
  "citations": [
    {
      "base": "astro-sources",
      "page": "raw/books/planets-in-transit/chapters/chapter-12-neptune.md",
      "heading": "Neptune Opposition Ascendant",
      "pdfPage": 484
    }
  ],
  "gaps": []
}

Do not emit final reading prose by itself. Return source-grounded claims and citations; astrology-reading-compose weaves the final answer.

Retrieval method

1. Resolve the source wiki root using the location order above.
2. Load raw/books/planets-in-transit/indexes/transit-heading-index.json.
3. Normalize the requested heading: - transit-to-natal aspect: <Transiting Planet> <Aspect> <Natal Point>; - house transit: <Transiting Planet> in the <House Ordinal> House.
4. Lookup the canonical heading in the index.
5. Read only the section span from the chapter file when quotes or a detailed summary are needed.
6. Emit citation metadata: base=astro-sources, chapter path, heading, PDF page, line numbers when available.

A helper script is bundled at scripts/query_planets_in_transit.py:

python3 scripts/query_planets_in_transit.py "Neptune Opposition Ascendant"

Known source QA notes

• The compiled/search artifacts have 719 canonical transit sections: 599 aspect sections and 120/120 house sections.
• The only unresolved theoretical major-aspect grid gap is Pluto Trine Neptune; do not fabricate it from general astrology knowledge.
• Four OCR-damaged headings were normalized in compiled artifacts while preserved in verbatim page JSONL:
• Venus Opposition Mercury
• Mars Trine Neptune
• Neptune Trine Uranus
• Neptune Trine Neptune
• Seven rare/slow outer-planet sections are structurally short because the book itself gives little or no delineation. If a hit resolves to one of these, say the source is sparse rather than padding with generic meaning.

Hard rules

• Always cite Planets in Transit with chapter path + PDF page.
• Do not quote from the book unless you actually read the section text.
• Do not fill missing/short sections with unsourced generic astrology while presenting it as Hand.
• Keep tenant privacy separate: the source wiki is shared/read-only; client birth data, transit calendars, and readings are saved only under ASTRAL_KB_ROOT / tenant knowledge/.
• For broad transit readings, combine this lens with live transit calculations from astral-transit-calendar; do not infer active transits from the book.

Verification

• [ ] transit-heading-index.json exists and contains the requested heading.
• [ ] The cited chapter file exists.
• [ ] PDF page and heading are included in citations.
• [ ] If the requested heading is missing, the gap is explicit and not silently replaced.
• [ ] No final prose is emitted as a standalone reading outside astrology-reading-compose.