---
name: astrology-lens-rulership-chains
description: Reading lens — Alex's traditional rulership-chain method. Use as ONE lens inside astrology-reading-compose. Not a full reading on its own. Emits structured claims (chains, loops, gateways, terminal planets, condition-modified key planets) plus citations; the compose layer weaves prose. For UI/static diagram work, see references/static-rulership-topology-diagrams.md.
version: 1.0.0
author: Hermes Agent + Alex
license: MIT
metadata:
  hermes:
    tags: [astrology, lens, rulership, traditional-rulers, aspects, natal]
    related_skills: [astrology-reading-compose, astral-chart-api, astrology-location-time-utc, astral-tenant-kb]
---

# Astrology Lens — Rulership Chains (Alex Method)

A **lens**, not a full reading. The compose layer calls this with a chart and gets back structured findings. Prose synthesis is the compose layer's job, not this skill's.

## Lens contract

**Input**: chart JSON from `astral-chart-api` (placements + houses + aspects).

**Output** (structured, append-only to a `lens_outputs[]` array in the compose pipeline):

```json
{
  "lens": "rulership-chains",
  "version": "1.0.0",
  "claims": [
    {"kind": "chain", "of": "Sun", "path": ["Sun in Libra", "Venus in Scorpio", "Mars in Leo", "Sun in Libra"], "note": "Sun-Venus-Mars loop"},
    {"kind": "loop", "members": ["Sun", "Venus", "Mars"], "weight": "main-engine"},
    {"kind": "gateway", "planet": "Mars", "feeds": ["Moon", "Ascendant"]},
    {"kind": "terminal-domicile", "planet": null},
    {"kind": "mutual-reception", "pair": null},
    {"kind": "condition", "planet": "Sun", "state": "fall (in Libra)"},
    {"kind": "aspect-on-topology", "aspect": "Mars square Pluto 1.2°", "effect": "conditions gateway planet"}
  ],
  "citations": [],
  "graph_classification": "Type 1 — single dominant loop with Ascendant extension"
}
```

**Do not emit prose.** The compose layer will pick which claims to surface.

## Method

(Identical to the prior Alex method — content unchanged, just scoped to lens output.)

### Hard rules

- **Traditional rulers only** by default. Mars/Venus/Mercury double rule. Saturn rules Aquarius. Jupiter rules Pisces. Sun rules Leo, Moon rules Cancer.
- Outer planets (Uranus/Neptune/Pluto) participate as **aspect bodies only**, never as sign rulers, unless the user explicitly requests modern rulerships.
- Tropical zodiac unless explicitly told sidereal.

### Traditional sign rulers

Aries→Mars · Taurus→Venus · Gemini→Mercury · Cancer→Moon · Leo→Sun · Virgo→Mercury · Libra→Venus · Scorpio→Mars · Sagittarius→Jupiter · Capricorn→Saturn · Aquarius→Saturn · Pisces→Jupiter

### Dignities

- Domicile: as above
- Detriment: opposite sign
- Exaltations: Sun-Aries, Moon-Taurus, Mercury-Virgo, Venus-Pisces, Mars-Capricorn, Jupiter-Cancer, Saturn-Libra
- Falls: opposite the exaltation

### Algorithm

For each priority point (Sun, Moon, Ascendant, MC, chart ruler, stellium rulers, planets in domicile, angular planets):

1. Note placement.
2. Find ruler of placement sign.
3. Follow that ruler's placement.
4. Repeat until: terminal domicile, mutual reception, closed loop, or merge into existing identified loop.
5. Record as `kind: chain`.

Then classify the chart into one of:

- **Type 1** — single dominant loop
- **Type 2** — single terminal domicile planet
- **Type 3** — multiple independent loops
- **Type 4** — loop with extensions through gateway planets
- **Type 5** — multiple chains, no loop
- **Type 6** — complete/near-complete circuit

### Aspect integration

Sort all major aspects (conj/opp/sq/tri/sex) by orb. Promote aspects within 3° and any aspect involving Sun/Moon/Asc/MC/chart-ruler/loop-member/gateway/terminal. For each promoted aspect emit a claim of `kind: aspect-on-topology` describing whether it sits inside a loop, bridges loops, hits a gateway, modifies a terminal, or is an outer-planet aspect to a loop member.

### Condition

For every planet inside an identified loop/terminal/gateway, emit a `kind: condition` claim with dignity state + house + angularity + retrograde/combust flags if relevant.

## Priority order for the claims list

1. main loops (largest weight first)
2. terminal domicile planets
3. mutual receptions
4. gateway planets and what they feed
5. Sun/Moon/Asc/MC chains
6. aspects on topology
7. conditions of key planets

## Fast UI/topology adapter

For Astral Hermes waiting-state visuals, compute a deterministic fast topology before any LLM prose. This adapter is not a replacement for the full lens; it is the data primitive the full lens can later enrich.

Recommended contract:

```json
{
  "lens": "rulership-chains-fast",
  "version": "0.1",
  "traditional": true,
  "chains": [
    {
      "seed": "Sun",
      "path": [
        {"body":"Sun", "sign":"Libra", "ruler":"Venus"},
        {"body":"Venus", "sign":"Scorpio", "ruler":"Mars"}
      ],
      "termination": {"type":"loop", "members":["Sun","Venus","Mars"]}
    }
  ],
  "loops": [],
  "gateways": [],
  "dominant": null,
  "storyboard": [
    {"kind":"step", "focusBody":"Sun", "focusSign":"Libra", "nextBody":"Venus", "caption":"Sun in Libra answers to Venus."}
  ]
}
```

Fast algorithm:

1. Normalize chart placements into body → sign/longitude/house/speed.
2. Use traditional ruler table only.
3. Trace priority seeds: Sun, Moon, Ascendant, MC, chart ruler, then optional stellium/angular rulers.
4. Stop each path at terminal domicile, mutual reception, closed loop, or merge into a known loop.
5. Classify loops/gateways/terminal planets.
6. Emit storyboard-ready focus fields (`focusBody`, `focusSign`, `nextBody`) without prose beyond short captions.

Keep this path O(seeds × planets), client-safe, and immediate after chart JSON exists. Deeper dignity/aspect interpretation remains owned by the full lens/compose layer.

### No-chart engine/storyboard variant

For secondary animations that explain the chart **without showing the wheel**, reuse the same fast topology but render it as an engine/wiring diagram:

- Treat each traditional planet/angle as a large glyph/card/engine node, with sign glyph + sign as secondary text.
- Draw visual arrows **ruler → ruled** (the same direction as the integrated chart-story arrows), even if the data edge is stored as `ruled -> ruler`.
- Do **not** use a generic graph/force-directed layout and then dress it up when the task is to explain the rulership grammar itself. Choose a purpose-built template from the topology class: two-card reciprocal exchange for mutual reception, ring/circuit for closed loops, tree/org-chart for terminal hierarchy, tributary/merge diagram for chains feeding a main loop, and separate mini-circuits for independent loops.
- If Alex explicitly asks for D3 variants in `/lab/rulership-canvas`, D3 is allowed as an exploratory layer beside the topology-specific canvas/storyboard diagrams. Use it for chart-data views D3 is good at — force authority maps, scale-based cascades, zodiac arcs/density wheels, timelines, heatmaps, matrices — while still keeping the underlying `planet → sign → ruler` proof visible and preserving topology-specific grammar for the main rulership explainer.
- When Alex is evaluating or correcting the diagram grammar, build static examples first: mutual reception, 3/4/5-body closed circuits, hierarchy tree, and hybrid feeders→gateway→circle. Do not add animation, lookup tables, or dynamic chart wiring until the static diagrams are visually approved.
- For reference-image-driven work, match the reference's **technical diagram grammar** first: node grouping, arrows, labels, merge/gateway/circuit callouts, and hierarchy. Apply color/typography/ornament only after the mechanics are visibly correct.
- For reference-image-driven work, match the reference's **technical diagram grammar** first: node grouping, arrows, labels, merge/gateway/circuit callouts, and hierarchy. Apply color/typography/ornament only after the mechanics are visibly correct.
- Ignore fake UI chrome in references unless explicitly requested: status bars, bottom tabs, menus, phone frames, and decorative app shells are not part of the rulership diagram grammar.
- Generate scenes from topology classes: overview, per-priority chain path, mutual reception, closed rulership circle, hierarchy/branches feeding the main loop or terminal, then summary.
- Once Alex asks for an actual chart-driven story, fetch the chart through Astro Engine, normalize it, and generate the canvas scene from `computeRulershipChainsFast(...)`; do not keep demo bodies/topology in the animated story.
- Surface mutual receptions as two-way diagrams with explicit sign-ruler mechanics (e.g. “Venus in Virgo / Virgo ruled by Mercury” and “Mercury in Libra / Libra ruled by Venus”), non-mutual loops as closed circuits/orbits, and gateway/terminal planets as badges or callouts.
- For Alex’s chart, the verified traditional topology is Sun/ASC in Libra → Venus; Venus in Virgo ↔ Mercury in Libra; Moon/MC feed Jupiter → Saturn → Mars → the Venus–Mercury loop. Use this as a QA canary, but recompute from Astro Engine rather than hard-coding it.
- Keep explanatory copy short and topology-first; the LLM/full compose layer can add interpretation later.
- Verify diagram layouts visually or with a DOM bounding-box smoke so large glyph/cards and badges are not clipped by the panel.

Session references:

- `references/no-chart-rulership-engine-storyboards.md` — initial no-chart storyboard mode and data contract.
- `references/technical-rulership-diagram-layouts.md` — later correction: replicate topology-specific technical diagram geometry, not merely GPT-image-style colors/cards.

## Pitfalls

- Using modern rulerships by default.
- Stopping after one dispositor instead of following to a loop/terminus.
- Treating outer-planet presence in a sign as rulership.
- Ignoring extensions: a planet outside the loop is still governed by it through a gateway.
- Confusing centrality with strength: a debilitated planet can still be structurally central.
- Forgetting to surface very-close aspects (<1°) even when they're outside the major topology — they still color the chart.

## Verification before returning

- [ ] Sun, Moon, Asc, MC chains traced to termination
- [ ] At least one chain claim per priority point
- [ ] Graph classification set
- [ ] All <3° aspects to priority points emitted as aspect-on-topology claims
- [ ] Conditions emitted for every planet appearing in any chain/loop/gateway
- [ ] Zero prose in the output object