Phase 3a: /intel/gravity — multiphase implementation plan

What we're building

A ranked structural view of the codebase's gravitational load-bearers — symbols whose change propagates farthest through the dependency graph. Unlike hotspots (churn over time) gravity is purely topological: it measures how many production symbols transitively depend on a given symbol.

The defining visual is the depth-distribution sparkline: a miniature histogram showing whether a symbol's reach is broad-shallow (high tier-1 count) or narrow-deep (long transitive tail). That shape tells you more about blast-zone character than gravity_pct alone.

Data shape — muse code gravity --json

{
  "total_production_symbols": 1883,
  "symbols": [{
    "address": "musehub/storage/backends.py::StorageBackend.get",
    "name": "get",
    "kind": "async_method",
    "file": "musehub/storage/backends.py",
    "gravity_pct": 36.2,
    "direct_dependents": 424,
    "transitive_dependents": 682,
    "max_depth": 5,
    "depth_distribution": {"1": 424, "2": 206, "3": 46, "4": 5, "5": 1}
  }]
}

depth_distribution is the sparkline source. It is not currently stored — it is the load-bearing addition in Phase 1.

Page layout

GET /{owner}/{repo}/intel/gravity
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

┌─ bg-base ─────────────────────────────────────────────────────────────┐
│                                                                        │
│  ┌─ .intel-gravity-header ─────────────────────────────────────────┐  │
│  │  [⊙ activity 24px]  G r a v i t y  ← gradient-spectral fill    │  │
│  │  Symbols whose change ripples farthest through the codebase.    │  │
│  │                                                                  │  │
│  │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐  │  │
│  │  │  1 883 symbols   │  │  38.9% max pull  │  │  depth 9 max │  │  │
│  │  │  bg-elevated     │  │  bg-elevated     │  │  bg-elevated │  │  │
│  │  └──────────────────┘  └──────────────────┘  └──────────────┘  │  │
│  └─────────────────────────────────────────────────────────────────┘  │
│                                                                        │
│  ┌─ .intel-filter-bar  bg-surface border-default ──────────────────┐ │
│  │  [all ×] [function] [method] [class] [async_method]              │ │
│  │                                            top [ 20 ▾]           │ │
│  └──────────────────────────────────────────────────────────────────┘ │
│                                                                        │
│  ┌─ .gravity-table  bg-surface border-default ─────────────────────┐ │
│  │                                                                   │ │
│  │   #    SYMBOL                        GRAVITY     REACH    WELL   │ │
│  │  ───  ────────────────────────────  ──────────  ───────  ──────  │ │
│  │                                                                   │ │
│  │   1   S3Backend._key               38.9% ████   11/733  ▂▇▃▁▁▁  │ │
│  │       storage/backends.py [meth]         ░░░░           d 1–6   │ │
│  │                                                                   │ │
│  │   2   S3Backend._get_client        38.8% ████   11/731  ▂▇▃▁▁▁  │ │
│  │       storage/backends.py [meth]         ░░░░           d 1–6   │ │
│  │                                                                   │ │
│  │  16   StorageBackend.get           36.2% ███   424/682  ▇▄▁▁▁   │ │
│  │       storage/backends.py [asyn]         ░░░            d 1–5   │ │
│  │                                                                   │ │
│  │  [  Load more  ]                                                  │ │
│  └───────────────────────────────────────────────────────────────────┘ │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

Depth sparkline

Normalize each bucket against the max bucket in the current symbol, map to 8-step block chars ▁▂▃▄▅▆▇█. Render inline, --font-mono, --color-purple.

{"1":11,  "2":484, "3":197, "4":35, "5":5,  "6":1}           →  ▂▇▃▁▁▁
{"1":424, "2":206, "3":46,  "4":5,  "5":1}                    →  ▇▄▁▁▁
{"1":1,   "2":17,  "3":27,  "4":406,"5":189,"6":42,"7":5}  →  ▁▁▁▇▄▁▁

Broad-shallow (large d:1 count, e.g. StorageBackend.get) vs narrow-deep (small d:1 but long tail) tells you more about blast-zone character than gravity_pct alone.

Gravity bar

Width proportional to gravity_pct / max_gravity_pct in the result set. Never inline pixel widths — use a CSS custom property:

<div class="gravity-bar" style="--grav: 0.{{ (symbol.gravity_pct / max_gravity_pct) | round(3) }}">
  <div class="gravity-bar__fill"></div>
</div>

Fill: background: var(--gradient-spectral). Track: background: var(--bg-elevated). Fixed 120px container. --border-subtle on the track.

Phase 1 — Schema extension (migration 0005)

musehub_symbol_intel currently stores only gravity FLOAT. Add:

New index: (repo_id, gravity_pct DESC) — primary sort key for the page query.

Phase 2 — GravityProvider

New IntelProvider subclass in musehub_intel_providers.py:

• Job type: intel.gravity
• Command: muse -C <root> code gravity --json (no --top limit — all symbols)
• Upsert: pg_insert(MuseHubSymbolIntel).on_conflict_do_update(...) — update the 6 new columns only; leave churn/blast columns untouched
• Enqueue in job_types_for_push for code-domain repos

Phase 3 — Route

New handler intel_gravity_page in musehub/api/routes/musehub/ui_intel.py:

GET /{owner}/{repo}/intel/gravity
  ?kind=method|function|class|async_method   (optional)
  ?top=20|50|100                              (default 20)

Query shape:

SELECT address, symbol_kind, gravity_pct, gravity_direct, gravity_transitive,
       gravity_max_depth, gravity_depth_dist, last_commit_id
FROM musehub_symbol_intel
WHERE repo_id = :repo_id
  AND gravity_pct IS NOT NULL
  AND (:kind IS NULL OR symbol_kind = :kind)
ORDER BY gravity_pct DESC
LIMIT :top

Template context includes max_gravity_pct (first row's value, used for bar normalization).

Phase 4 — Template

musehub/templates/musehub/pages/intel_gravity.html

Jinja2 macro depth_sparkline(dist) — accepts the gravity_depth_dist dict, returns the ▁▂▇▃▁ string. Pure Python inside the macro; no JS required.

Phase 5 — SCSS (two-layer split)

The split is absolute: zero layout properties in components/, zero color properties in pages/.

Additions to src/scss/components/_intel.scss:

• .gravity-bar — border, border-radius, background track (--bg-elevated), --border-subtle
• .gravity-bar__fill — background: var(--gradient-spectral), height, transition
• .depth-sparkline — color: var(--color-purple), font-family: var(--font-mono), letter-spacing
• .kind-badge--method, .kind-badge--async-method — --domain-code-* colors
• .kind-badge--class — --color-purple border + bg override
• .kind-badge--function — default .badge colors, no override needed

New file src/scss/pages/_intel_gravity.scss:

• .intel-gravity-header — flex, gap, padding, alignment
• .intel-gravity-stats — flex wrap, --space-4 gap
• .intel-filter-bar — flex row, align-items, gap, padding
• .gravity-table — CSS grid columns: 40px 1fr 160px 90px 80px
• .gravity-row — min-height 56px, align-items center, hover: background: var(--bg-hover) (in components, not here)
• .gravity-cell--rank — text-align center, padding
• .gravity-cell--well — text-align right, white-space nowrap

Phase 6 — Nav wiring

Add Gravity link to the intel sub-nav in intel_dashboard.html. Use icon("activity", 14). Active state via border-color: var(--color-accent) only.

Spectral theme rules

1. Background depth order: --bg-base → --bg-surface → --bg-elevated → --bg-hover. Never skip a level, never go backwards.
2. No bare hex — every color must trace to a token in _tokens.scss.
3. Gravity bar fill = --gradient-spectral. This is the page's primary visual anchor.
4. Depth sparkline color = --color-purple. Page's signature accent.
5. Heading text fill = --gradient-spectral via background-clip: text; -webkit-text-fill-color: transparent.
6. Kind badges = existing .badge base. Map kinds to existing badge tokens — no new badge class variants.
7. Filter pills = .btn.btn-ghost. Active: border-color: var(--color-accent) only. No background change on active.
8. Spacing = 8pt grid only. All padding and gap via --space-* tokens.
9. Mono font only for: addresses, sparklines, percentages, counts. Labels and prose use --font-sans.
10. SCSS layer discipline is absolute — running grep 'padding\|margin\|display\|flex\|grid\|width\|height' components/_intel.scss must return zero new lines from this feature; running grep 'color\|background\|border\|font-\|opacity\|shadow' pages/_intel_gravity.scss must return zero lines.

Acceptance criteria

• Migration 0005 adds 6 columns to musehub_symbol_intel; existing rows preserved
• GravityProvider populates all 6 new columns on push
• /intel/gravity renders from DB in < 200ms; no subprocess at request time
• Depth sparkline correct for distributions from depth 1 through depth 9
• Gravity bar width proportional to gravity_pct / max in result set
• Kind filter + top-N work (HTMX or form GET — no full-page JS framework)
• SCSS two-layer rule passes: zero layout in components/, zero color in pages/
• Zero bare hex or hardcoded rgb() values in new templates or SCSS