feat(reports): leftover-map axis share on grouping comparison graphic (v2.62.0)

AGENTS.md

@@ -273,7 +273,7 @@ stops startup instead of leaving a healthy-looking partial schema, and
 application code must not compensate for a missing table.
 
 Period leftover pairs (ADR 0017 / 0018 / 0048 / 0049 / 0119 / 0158 / 0162 /
-0163 / 0164 / 0182 / 0185 / 0201 / 0233 / 0266 / 0267 / 0268 / 0269 / 0270 / 0271 / 0272 / 0273 / 0274 / 0275 / 0276 / 0277 / 0278 / 0279 / 0280 / 0281 / 0282 / 0283 / 0284 / 0285 / 0286 / 0287 / 0288 / 0289 / 0290 / 0291 / 0292 / 0293 / 0294 / 0295 / 0296 / 0297 / 0298 / 0299 / 0300 / 0301 / 0302 / 0303 / 0304) are computed in `lineageweave/leftover_pairs.py` from the
+0163 / 0164 / 0182 / 0185 / 0201 / 0233 / 0266 / 0267 / 0268 / 0269 / 0270 / 0271 / 0272 / 0273 / 0274 / 0275 / 0276 / 0277 / 0278 / 0279 / 0280 / 0281 / 0282 / 0283 / 0284 / 0285 / 0286 / 0287 / 0288 / 0289 / 0290 / 0291 / 0292 / 0293 / 0294 / 0295 / 0296 / 0297 / 0298 / 0299 / 0300 / 0301 / 0302 / 0303 / 0304 / 0305) are computed in `lineageweave/leftover_pairs.py` from the
 residual after a real GRM/GPCM score, never invented. Distances are
 Euclidean on the two-dimensional Gabriel leftover map; missing cells stay
 out of the factorization. Closest and farthest post–criterion pairs
@@ -487,7 +487,13 @@ buttons when four leftover-map axes are finite; a missing or non-finite axis
 omits that pair from the comparison graphic and does not invent coordinates
 from leftover-map rank, leftover-map distance, leftover-map reconstruction, or
 leftover residual. Omit the comparison graphic when no leftover pair has four
-finite leftover-map coordinates.
+finite leftover-map coordinates. ADR 0305 returns persisted leftover-map axes on
+`GET /api/reports/compare/{period}` and captions leftover-map axis share on the
+grouping comparison leftover-map graphic when that share is finite; a missing or
+non-finite share omits that leftover-map comparison axis share badge and keeps
+leftover map comparison axis text. Do not invent leftover-map axis share from
+leftover-map rank, leftover-map distance, leftover-map reconstruction, leftover
+residual, leftover pair count, or the count of unused axes.
 When `R`, `R̂`, `U`, `x`,
 `s`, and `e` are finite, `e + s + x = 1`. When `Y`, `E`, and `R` are
 finite, `Y − E = R`. When `R`, `R̂`, and `U` are
@@ -535,6 +541,8 @@ coordinates `ξ` / `ζ` on `GET /api/reports/compare/{period}` leftover pairs.
 Grouping comparison leftover-map graphic display (ADR 0304) draws the leftover-map
 graphic of those already-named coordinates above grouping comparison leftover-pair
 buttons when four leftover-map axes are finite.
+Grouping comparison leftover-map axis share (ADR 0305) captions that grouping
+comparison leftover-map graphic with persisted leftover-map axis share.
 Item complete-case coverage
 (ADR 0282) captions the leftover-map graphic with how many scored criteria
 entered the map. Item complete-case coverage on the pair list (ADR 0285)

ARCHITECTURE.md

@@ -700,6 +700,10 @@ ADR 0303 returns persisted leftover-map coordinates `ξ` / `ζ` on
 ADR 0304 draws the leftover-map graphic display of those already-named
 coordinates above grouping comparison leftover-pair buttons when four
 leftover-map axes are finite.
+ADR 0305 returns persisted leftover-map axes on
+`GET /api/reports/compare/{period}` and captions leftover-map axis share
+on that grouping comparison leftover-map graphic when the persisted share
+is finite.
 Click a post marker or a pair button
 opens that post. Those ADRs are the normative mathematical, storage, and
 display contracts. Leftover-map axis share
@@ -731,8 +735,9 @@ incomplete item coverage (ADR 0292), leftover-map reconstruction `R̂`
 (ADR 0300), leftover-map rank
 (ADR 0301), leftover-map coordinates `ξ` / `ζ`
 (ADR 0302), leftover-map coordinates on the compare leftover-pair payload
-(ADR 0303), and leftover-map graphic display on the grouping comparison strip
-(ADR 0304);
+(ADR 0303), leftover-map graphic display on the grouping comparison strip
+(ADR 0304), and leftover-map axis share on the grouping comparison leftover-map
+graphic (ADR 0305);
 `POST .../rebuild` scores every grouping kind (post_admin). `make seed`
 folds A-100/B-200 Event Lineage fixtures (and the Riverbend calendar
 post) that already have constructed IRT cells into the same shared

CHANGELOG.d/2.62.0-leftover-map-compare-plot-axis-share.md

@@ -0,0 +1,15 @@
+## 2.62.0 — Leftover-map axis share on grouping comparison leftover-map graphic
+
+- Name leftover-map axis share on the grouping comparison leftover-map
+  graphic (ADR 0305). After `make seed`, closest and farthest leftover pairs
+  sit above the member list with the Gabriel biplot of already-named
+  coordinates, and each leftover-map comparison axis names its persisted
+  Gabriel inertia share when finite; click a post marker or a pair button
+  opens that post. A missing or non-finite share omits that leftover-map
+  comparison axis share badge and keeps leftover map comparison axis text.
+  Rank-0 unused axes still name zero leftover-map axis share. Do not invent
+  leftover-map axis share from leftover-map rank, leftover-map distance, or
+  leftover-map reconstruction. A finite negative leftover is shown, never
+  clamped. This increment does not caption leftover-map coverage on the
+  comparison graphic. Never invent a leftover score. Never invent a theta.
+  No new columns.

CHANGELOG.md

@@ -8,6 +8,67 @@ All notable changes to this project are documented here. Format follows
 
 ### Added
 
+- Period leftover pairs now name leftover-map axis share on the grouping
+  comparison leftover-map graphic (ADR 0305 / v2.62.0). After `make seed`,
+  closest and farthest leftover pairs sit above the member list with the
+  Gabriel biplot of already-named coordinates, leftover-map axis share when
+  finite, leftover-map axis share on the grouping comparison leftover-map
+  graphic when finite, axis ticks that match `ξ (x, y) ζ (x, y)` on the pair
+  row, pair segments that match `d` on the pair row, pair segments that match
+  `R̂` on the pair row, pair segments that match `R̂²/R²` on the pair row,
+  pair segments that match `U²/R²` on the pair row, pair segments that match
+  `2R̂U/R²` on the pair row, pair segments that match `U` on the pair row,
+  pair segments that match `R` on the pair row, pair segments that match `Y`
+  on the pair row, pair segments that match `E` on the pair row, pair segments
+  that match leftover-map rank on the pair row, a plot caption that matches
+  leftover-map complete-case coverage above the pair list, a plot caption that
+  matches leftover-map item complete-case coverage, a plot caption that matches
+  leftover-map incomplete post coverage, a plot caption that matches leftover-map
+  incomplete item coverage, a pair-list note that matches leftover-map post
+  complete-case coverage, a pair-list note that matches leftover-map item
+  complete-case coverage, a pair-list note that matches leftover-map incomplete
+  post coverage, a pair-list note that matches leftover-map incomplete item
+  coverage, a grouping comparison note that matches leftover-map post
+  complete-case coverage, a grouping comparison note that matches leftover-map
+  item complete-case coverage, a grouping comparison note that matches leftover-map
+  incomplete post coverage, a grouping comparison note that matches leftover-map
+  incomplete item coverage, grouping comparison leftover-pair buttons that match
+  leftover-map reconstruction `R̂` on the pair row, grouping comparison leftover-pair
+  buttons that match leftover-map explained leftover share `e` on the pair row,
+  grouping comparison leftover-pair buttons that match leftover-map unexplained
+  leftover share `s` on the pair row, grouping comparison leftover-pair buttons
+  that match leftover-map cross share `x` on the pair row, grouping comparison
+  leftover-pair buttons that match leftover-map unexplained leftover `U` on the
+  pair row, grouping comparison leftover-pair buttons that match leftover residual
+  `R` on the pair row, grouping comparison leftover-pair buttons that match leftover
+  observed `Y` on the pair row, grouping comparison leftover-pair buttons that match
+  leftover expected `E` on the pair row, grouping comparison leftover-pair buttons
+  that match leftover-map rank on the pair row, grouping comparison leftover-pair
+  buttons that match leftover-map coordinates `ξ` / `ζ` on the pair row, a live
+  compare payload that carries those persisted leftover-map coordinates, the
+  grouping comparison leftover-map graphic of those already-named coordinates when
+  four leftover-map axes are finite, and leftover-map axis share on that grouping
+  comparison leftover-map graphic when the persisted share is finite; click a post
+  marker or a pair button opens that post. A missing or non-finite leftover-map
+  axis share omits that leftover-map comparison axis share badge and keeps leftover
+  map comparison axis text, leftover-map rank when that rank is a non-negative
+  integer, leftover expected `E` when finite, leftover observed `Y` when finite,
+  leftover residual `R` when finite, leftover-map unexplained leftover `U` when
+  finite, leftover-map cross share `x` when finite, leftover-map unexplained leftover
+  share `s` when finite, leftover-map explained leftover share `e` when finite,
+  leftover-map reconstruction `R̂` when finite, leftover-map distance `d`, plus
+  the strip coverage notes. Rank-0 origin cells still plot at `(0, 0)` and still
+  name zero leftover-map axis share when those persisted axes are stored. Do not
+  invent leftover-map axis share from leftover-map rank, leftover-map distance,
+  leftover expected, leftover observed, leftover residual, leftover-map
+  reconstruction, leftover-map unexplained leftover, leftover-map post coverage,
+  leftover-map item coverage, leftover-map incomplete post coverage, leftover-map
+  incomplete item coverage, leftover pair count, or the count of unused axes. A
+  finite negative leftover is shown, never clamped. Omit the comparison graphic
+  when no leftover pair has four finite leftover-map coordinates. This increment
+  does not caption leftover-map coverage on the comparison graphic. Never invent
+  a leftover score or a theta. No new columns.
+
 - Period leftover pairs now draw the leftover-map graphic display of
   persisted leftover-map coordinates `ξ` / `ζ` above grouping comparison
   leftover-pair buttons (ADR 0304 / v2.61.0). After `make seed`, closest

CLAUDE.md

@@ -49,7 +49,7 @@ cutoff. Global Ask optional `knowledge_cutoff` uses the same cover
 
 Create/start endpoint rules (ADR 0017 / 0021), tie-vs-miss similarity
 (ADR 0026), R&R catalog ids (ADR 0019 / 0027), leftover pairs
-(ADR 0048–0164 / 0182 / 0185 / 0201 / 0233 / 0266 / 0267 / 0268 / 0269 / 0270 / 0271 / 0272 / 0273 / 0274 / 0275 / 0276 / 0277 / 0278 / 0279 / 0280 / 0281 / 0282 / 0283 / 0284 / 0285 / 0286 / 0287 / 0288 / 0289 / 0290 / 0291 / 0292 / 0293 / 0294 / 0295 / 0296 / 0297 / 0298 / 0299 / 0300 / 0301 / 0302 / 0303 / 0304), occupational construct catalog search
+(ADR 0048–0164 / 0182 / 0185 / 0201 / 0233 / 0266 / 0267 / 0268 / 0269 / 0270 / 0271 / 0272 / 0273 / 0274 / 0275 / 0276 / 0277 / 0278 / 0279 / 0280 / 0281 / 0282 / 0283 / 0284 / 0285 / 0286 / 0287 / 0288 / 0289 / 0290 / 0291 / 0292 / 0293 / 0294 / 0295 / 0296 / 0297 / 0298 / 0299 / 0300 / 0301 / 0302 / 0303 / 0304 / 0305), occupational construct catalog search
 (ADR 0257), the text-channel embedding swap and cosine
 clamp (ADR 0190), per-edge channel-score persistence (ADR 0195),
 token-backed status notices (ADR 0220),

backend/app/report_ingestion.py

@@ -1088,6 +1088,23 @@ async def fetch_period_comparison(
     leftover_coverage_by_key = {
         (row["grouping_kind"], row["grouping_key"]): row for row in leftover_coverage
     }
+    leftover_axes = await conn.fetch(
+        """
+        select grouping_kind, grouping_key, axis_index, leftover_singular_value, leftover_share
+        from report_leftover_map_axis
+        where period_code = $1 and rubric_version = $2
+          and grouping_kind = any($3::text[])
+        order by grouping_kind, grouping_key, axis_index
+        """,
+        period_code,
+        RUBRIC_VERSION,
+        list(GROUPING_KINDS),
+    )
+    leftover_axes_by_key: dict[tuple[str, str], list[asyncpg.Record]] = defaultdict(list)
+    for axis_row in leftover_axes:
+        leftover_axes_by_key[(axis_row["grouping_kind"], axis_row["grouping_key"])].append(
+            axis_row
+        )
     payload: list[dict[str, Any]] = []
     for row in rows:
         label = await resolve_grouping_label(conn, row["grouping_kind"], row["grouping_key"])
@@ -1154,6 +1171,16 @@ async def fetch_period_comparison(
                 "leftover_map_coverage": _leftover_map_coverage_payload(
                     leftover_coverage_by_key.get((row["grouping_kind"], row["grouping_key"]))
                 ),
+                "leftover_map_axes": [
+                    {
+                        "axis_index": int(axis_row["axis_index"]),
+                        "leftover_singular_value": float(axis_row["leftover_singular_value"]),
+                        "leftover_share": float(axis_row["leftover_share"]),
+                    }
+                    for axis_row in leftover_axes_by_key.get(
+                        (row["grouping_kind"], row["grouping_key"]), []
+                    )
+                ],
             }
         )
     return payload

backend/tests/test_api.py

@@ -5833,6 +5833,13 @@ def test_seed_period_report_surfaces_on_get_reports(client, demo_analyst_token,
     assert leftover_compare_coverage is not None
     assert leftover_compare_coverage["map_post_count"] <= leftover_compare_coverage["scored_post_count"]
     assert leftover_compare_coverage["scored_post_count"] > 0
+    leftover_compare_axes = leftover_thread.get("leftover_map_axes", [])
+    assert [axis["axis_index"] for axis in leftover_compare_axes] == [1, 2]
+    assert all(axis["leftover_singular_value"] >= 0 for axis in leftover_compare_axes)
+    assert all(0.0 <= axis["leftover_share"] <= 1.0 for axis in leftover_compare_axes)
+    assert leftover_compare_axes[0]["leftover_share"] != len(
+        leftover_thread.get("leftover_pairs", [])
+    )
     assert leftover_compare_coverage["incomplete_post_count"] == (
         leftover_compare_coverage["scored_post_count"] - leftover_compare_coverage["map_post_count"]
     )

docs/adr/0269-leftover-map-axis-share-plot.md

@@ -3,6 +3,9 @@
 **Decision status:** Accepted
 **Date:** 2026-08-28
 
+**Amended by:** [ADR 0305](0305-leftover-map-compare-plot-axis-share.md)
+(leftover-map axis share on the grouping comparison leftover-map graphic)
+
 Amends [ADR 0148](0148-leftover-map-axis-share.md) and
 [ADR 0268](0268-leftover-map-graphic-display.md). Independent of leftover-map
 explained leftover share ([ADR 0266](0266-leftover-map-explained-share.md)),
@@ -53,8 +56,8 @@ or non-finite share omits that axis badge and keeps the existing
 leftover-map axis text. Axis 1 and axis 2 stay independently named:
 one missing share does not hide the other. Click a post marker to
 open that post. Criterion markers are not post buttons. The grouping
-comparison strip (ADR 0149) stays on its reduced leftover payload and
-does not gain this caption.
+comparison strip later captions leftover-map axis share on its leftover-map
+graphic from already-named leftover-map axes (ADR 0305).
 
 Do not add SQL. Do not edit shipped migrations. Do not persist inner
 product, cosine, or length as separate columns. Do not invent a

docs/adr/0304-leftover-map-compare-graphic.md

@@ -3,6 +3,9 @@
 **Decision status:** Proposed
 **Date:** 2026-08-31
 
+**Amended by:** [ADR 0305](0305-leftover-map-compare-plot-axis-share.md)
+(leftover-map axis share on the grouping comparison leftover-map graphic)
+
 Amends leftover pairs on the grouping comparison strip
 ([ADR 0149](0149-leftover-pairs-on-comparison-strip.md)), leftover-map
 graphic display ([ADR 0268](0268-leftover-map-graphic-display.md)), leftover-map
@@ -205,8 +208,7 @@ leftover share on pair segments, leftover-map unexplained leftover share
 persistence, leftover-map explained leftover share on pair segments,
 leftover-map explained leftover share persistence, leftover-map reconstruction
 on pair segments, leftover-map reconstruction persistence, leftover-map item
-complete-case coverage on the graphic display, leftover-map item complete-case
-coverage on the pair list, leftover-map incomplete post coverage on the graphic
+complete-case coverage on the graphic display, leftover-map item complete-case coverage on the pair list, leftover-map incomplete post coverage on the graphic
 display, leftover-map incomplete post coverage on the pair list, leftover-map
 incomplete item coverage on the graphic display, leftover-map incomplete item
 coverage on the pair list, leftover-map post complete-case coverage fail-closed