feat(reports): grouping comparison item coverage (v2.48.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) 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) 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
@@ -396,6 +396,7 @@ structure without the Gabriel scale that produced it; a missing, non-finite,
 or negative singular value omits that `σ` badge independently of leftover-map
 axis share and does not invent `σ_k` from leftover-map axis share.
 ADR 0290 captions the grouping comparison strip with persisted leftover-map post complete-case coverage only when the caller can see the full persisted grouping population. Partial-visibility groupings omit that aggregate; never reconstruct the psychometric denominator from visible members, leftover pairs, or plotted markers.
+ADR 0291 captions the grouping comparison strip with persisted leftover-map item complete-case coverage through leftoverMapItemCoverageCounts only when the caller can see the full persisted grouping population. Partial-visibility rows inherit ADR 0290's fail-closed coverage boundary and never recompute psychometric coverage from visible members, leftover pairs, or plotted criterion markers.
 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

ARCHITECTURE.md

@@ -637,7 +637,7 @@ information at the group's mean θ (Lord, 1980 max-info CAT). Rankings
 persist to `report_item_information`. After those IRT main effects,
 residual SVD leftover pairs on two Gabriel axes (Jeon et al., 2021;
 ADR 0017 / 0048 / 0049 / 0119 / 0148 / 0158 / 0162 / 0163 / 0164 / 0168 /
-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) persist to `report_leftover_pair` with signed residual `R`,
+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) persist to `report_leftover_pair` with signed residual `R`,
 observed `Y`, expected `E[Y|θ, item]`, full leftover-map rank, unexplained
 leftover, ADR 0201 reconstruction evidence, ADR 0185 cross-share evidence,
 ADR 0233 unexplained leftover share `s`, ADR 0266 explained leftover
@@ -670,6 +670,7 @@ incomplete post coverage. ADR 0287 captions the leftover pair list with persiste
 incomplete item coverage. ADR 0288 fail-closes leftover-map post complete-case coverage
 on the leftover pair list through leftoverMapCoverageCounts. ADR 0289 captions leftover-map
 graphic axes with persisted leftover-map singular values `σ_k`. ADR 0290 captions the grouping comparison strip with persisted leftover-map post complete-case coverage under a full-visible-grouping rule; partial-visibility groupings fail closed that aggregate to avoid disclosing a hidden population denominator.
+ADR 0291 captions grouping-comparison persisted item complete-case coverage through leftoverMapItemCoverageCounts only under ADR 0290's full-visible-grouping authorization boundary.
 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
@@ -687,7 +688,7 @@ including on the pair list. Results persist to
 `GET /api/reports/{grouping}` lists the trend;
 `GET /api/reports/{grouping}/{period}` is ABAC-filtered;
 `GET /api/reports/compare/{period}` is the home-page grouping strip
-and carries the same ABAC-filtered leftover pairs (ADR 0149) plus persisted leftover-map post complete-case coverage (ADR 0290) only when the caller-visible member population equals the persisted grouping population;
+and carries the same ABAC-filtered leftover pairs (ADR 0149) plus persisted leftover-map post complete-case coverage (ADR 0290) and item complete-case coverage (ADR 0291) only when the caller-visible member population equals the persisted grouping population;
 `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.48.0-leftover-map-compare-item-coverage.md

@@ -0,0 +1,38 @@
+## 2.48.0 — Leftover-map item complete-case coverage on the grouping comparison strip
+
+- Caption leftover-map item complete-case coverage on the grouping comparison
+  strip through leftoverMapItemCoverageCounts (ADR 0291). 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, 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,
+  and a grouping comparison note that matches leftover-map item
+  complete-case coverage; click a post marker or a pair button opens that
+  post. A missing, non-integer, negative used, non-positive scored, or
+  used-greater-than-scored item coverage omits that leftover-map comparison
+  item coverage note. Coverage `0 of M` is shown when that persisted used
+  count is a non-negative integer and scored is a positive integer. Do not
+  invent item coverage from leftover pair count, plotted criterion marker
+  count, leftover-map distance, leftover-map rank, leftover-map post
+  coverage, leftover-map incomplete post coverage, leftover-map incomplete
+  item coverage, or the count of unused axes. The strip does not gain
+  leftover-map incomplete post coverage, leftover-map incomplete item
+  coverage, or the leftover-map graphic. Never invent a leftover score.
+  Never invent a theta. No new columns.
+
+- Authorization boundary: item coverage is shown only when the caller-visible population equals the persisted grouping population; partial-visibility rows omit the persisted coverage aggregate and never recompute a subset denominator.

CHANGELOG.md

@@ -8,6 +8,8 @@ All notable changes to this project are documented here. Format follows
 
 ### Added
 
+- Grouping comparison rows now name persisted leftover-map item complete-case coverage (ADR 0291 / v2.48.0) only when the caller can see the full persisted grouping population; partial-visibility rows omit the aggregate rather than leaking a denominator or recomputing subset coverage.
+
 - Grouping comparison rows now expose persisted leftover-map post complete-case coverage through `leftoverMapCoverageCounts` (ADR 0290 / v2.47.0) only for fully visible grouping populations. Partial-visibility rows omit the aggregate instead of leaking the full-group denominator or recomputing psychometric coverage from the visible subset.
 
 - Period leftover pairs now caption leftover-map graphic axes with persisted

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), 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), 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),

docs/adr/0291-leftover-map-compare-item-coverage.md

@@ -0,0 +1,151 @@
+# ADR 0291 — Name leftover-map item complete-case coverage on the grouping comparison strip
+
+**Decision status:** Proposed
+**Date:** 2026-08-30
+
+Amends leftover pairs on the grouping comparison strip
+([ADR 0149](0149-leftover-pairs-on-comparison-strip.md)), leftover-map
+complete-case coverage ([ADR 0168](0168-leftover-map-complete-case-coverage.md)),
+and leftover-map complete-case coverage on the grouping comparison strip
+([ADR 0290](0290-leftover-map-compare-coverage.md)). Independent of leftover-map
+post complete-case coverage fail-closed on the pair list
+([ADR 0288](0288-leftover-map-list-post-coverage-helper.md)), leftover-map
+incomplete item coverage on the pair list
+([ADR 0287](0287-leftover-map-list-incomplete-item.md)), leftover-map incomplete
+post coverage on the pair list
+([ADR 0286](0286-leftover-map-list-incomplete-post.md)), leftover-map item
+complete-case coverage on the pair list
+([ADR 0285](0285-leftover-map-list-item-coverage.md)), leftover-map incomplete
+item coverage on the graphic display
+([ADR 0284](0284-leftover-map-plot-incomplete-item.md)), leftover-map incomplete
+post coverage on the graphic display
+([ADR 0283](0283-leftover-map-plot-incomplete.md)), leftover-map item
+complete-case coverage on the graphic display
+([ADR 0282](0282-leftover-map-plot-item-coverage.md)), leftover-map complete-case
+coverage on the graphic display
+([ADR 0281](0281-leftover-map-plot-coverage.md)), leftover-map rank on pair
+segments ([ADR 0280](0280-leftover-map-segment-rank.md)), leftover expected on pair
+segments ([ADR 0279](0279-leftover-map-segment-expected.md)), leftover observed on
+pair segments ([ADR 0278](0278-leftover-map-segment-observed.md)), leftover
+residual on pair segments ([ADR 0277](0277-leftover-map-segment-residual.md)),
+leftover-map unexplained leftover on pair segments
+([ADR 0276](0276-leftover-map-segment-unexplained-leftover.md)), leftover-map
+cross share on pair segments ([ADR 0275](0275-leftover-map-segment-cross-share.md)),
+leftover-map unexplained leftover share on pair segments
+([ADR 0274](0274-leftover-map-segment-unexplained-share.md)), leftover-map
+explained leftover share on pair segments
+([ADR 0273](0273-leftover-map-segment-explained-share.md)), leftover-map
+reconstruction on pair segments
+([ADR 0272](0272-leftover-map-segment-reconstruction.md)), leftover-map
+distance on pair segments ([ADR 0271](0271-leftover-map-segment-distance.md)),
+leftover-map coordinate ticks ([ADR 0270](0270-leftover-map-coordinate-ticks.md)),
+leftover-map axis share on the graphic display
+([ADR 0269](0269-leftover-map-axis-share-plot.md)), leftover residual
+disclosure ([ADR 0162](0162-leftover-residual-disclosure.md)), leftover
+observed `Y` / expected `E` ([ADR 0163](0163-leftover-observed-expected.md)),
+leftover-map explained leftover share persistence
+([ADR 0266](0266-leftover-map-explained-share.md)), leftover-map
+unexplained leftover share persistence
+([ADR 0233](0233-leftover-map-unexplained-share.md)), leftover-map
+reconstruction persistence ([ADR 0201](0201-leftover-map-reconstruction.md)),
+leftover-map cross share persistence
+([ADR 0185](0185-leftover-map-cross-share.md)), leftover-map unexplained leftover
+persistence ([ADR 0182](0182-leftover-map-unexplained.md)), leftover-map rank
+persistence ([ADR 0164](0164-leftover-map-rank.md)), and leftover-map axis
+share persistence ([ADR 0148](0148-leftover-map-axis-share.md)).
+
+## Context
+
+ADR 0168 already persists `map_item_count` / `scored_item_count` on
+`report_leftover_map_coverage`. ADR 0290 already captions leftover-map post
+complete-case coverage on the grouping comparison strip. The strip still does
+not name how many scored criteria entered each grouping's Gabriel factorization,
+so a buyer who compares leftover pairs can treat a 2-of-5 complete-case criterion
+map as if it used the same census as a 5-of-5 map.
+
+This increment captions persisted leftover-map item complete-case coverage on
+each grouping comparison row through leftoverMapItemCoverageCounts. It does not
+add columns. It does not recompute item coverage from leftover pair count,
+plotted criterion marker count, leftover-map distance, or leftover-map rank.
+It does not persist leftover-map inner product, cosine, or length as separate
+columns. Do not invent a leftover score. Do not invent a theta.
+
+The dashboard stack already used neighbouring leftover facts under other
+numbers. This protected increment uses **0291** so it does not collide with
+leftover-map complete-case coverage on the grouping comparison strip (0290),
+leftover-map post complete-case coverage fail-closed on the pair list (0288),
+leftover-map incomplete item coverage on the pair list (0287), leftover-map
+incomplete post coverage on the pair list (0286), leftover-map item
+complete-case coverage on the pair list (0285), leftover-map incomplete
+item coverage on the graphic display (0284), leftover-map incomplete post
+coverage on the graphic display (0283), leftover-map item complete-case
+coverage on the graphic display (0282), leftover-map complete-case coverage
+on the graphic display (0281), leftover-map rank on pair segments (0280),
+or the dashboard stacks.
+
+## Decision
+
+On the grouping comparison strip, caption leftover-map item complete-case
+coverage as `Leftover map used {used} of {scored} scored criteria (complete-case)`
+only when leftoverMapItemCoverageCounts returns usable complete-case integers
+from persisted `map_item_count` / `scored_item_count`. Use the distinct
+accessible name `Leftover map comparison item coverage` so the strip caption
+is not the pair-list note (`Leftover map item coverage`) and is not the graphic
+caption (`Leftover-map graphic item coverage`). A missing coverage row, a
+non-integer count, a negative used count, a non-positive scored count, or used
+greater than scored omits that leftover-map comparison item coverage note and
+keeps the strip leftover-map post coverage note, leftover pairs, leftover-map
+distance `d`, and any leftover-map captions on the pair list and graphic.
+Coverage `0 of M` is shown when that persisted used count is a non-negative
+integer and scored is a positive integer. Do not invent item coverage from
+leftover pair count, plotted criterion marker count, leftover-map distance,
+leftover-map rank, leftover-map post coverage, leftover-map incomplete post
+coverage, leftover-map incomplete item coverage, or the count of unused axes.
+Do not caption leftover-map incomplete post coverage or leftover-map incomplete
+item coverage on the strip in this increment. Do not add the leftover-map
+graphic to the strip. Click a leftover pair on the strip to open that post.
+
+Do not add SQL. Do not edit shipped migrations. Do not persist inner
+product, cosine, or length as separate columns. Do not invent a leftover
+score. Do not invent a theta.
+
+## Consequences
+
+After `make seed`, the grouping comparison strip names persisted leftover-map
+post complete-case coverage and persisted leftover-map item complete-case
+coverage on each grouping row when leftoverMapCoverageCounts /
+leftoverMapItemCoverageCounts return usable integers, then names leftover pairs
+with leftover-map distance `d`. Closest and farthest leftover pairs still sit
+above the member list with the leftover-map graphic display; click a post
+marker or a pair button opens that post.
+Hidden posts stay hidden. Persisted item coverage is returned only when the caller can see the full persisted grouping population; partial-visibility groupings omit the entire persisted coverage aggregate instead of disclosing a hidden denominator or recomputing psychometric coverage from the visible subset.
+
+## Related
+
+Independent of leftover interaction-map persistence, leftover-criterion
+evaluation landing, leftover residual disclosure, leftover-map
+complete-case coverage persistence, leftover-map axis share persistence,
+leftover pairs on the grouping comparison strip, leftover-map complete-case
+coverage on the grouping comparison strip, leftover-map inner product,
+leftover-map cosine, leftover-map length, leftover-map graphic display,
+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, leftover-map incomplete item coverage, and leftover-map post
+complete-case coverage fail-closed on the pair list.
+
+## References
+
+Gabriel, K. R. (1971). The biplot graphic display of matrices with
+application to principal component analysis. *Biometrika, 58*(3),
+453–467. https://doi.org/10.1093/biomet/58.3.453
+
+Jeon, M., Jin, I. H., Schweinberger, M., & Baugh, S. (2021). Mapping
+unobserved item–respondent interactions: A latent space item response
+model with interaction map. *Psychometrika, 86*(2), 378–403.
+https://doi.org/10.1007/s11336-021-09762-5
+(LSIRM interaction `−γ‖ξ_j − ζ_i‖` after main effects
+`α_j − β_i`; typically `p = 2` for the interaction map. Incomplete
+columns are dropped from the complete-case residual rectangle; grouping
+comparison item coverage names how many scored criteria entered that
+factorization for that grouping only when leftoverMapItemCoverageCounts
+returns usable complete-case integers.)

docs/product-technical-gap-baseline.md

@@ -1,5 +1,7 @@
 # Product & Technical Gap Baseline
 
+> 2026-09-07 #822 reconstruction: exact #821 `93eaa40f...` owns ADR 0290/v2.47.0 and the full-visible-grouping coverage boundary. Preserve historical item-coverage composition as ADR 0291/v2.48.0; partial-visibility rows omit the shared persisted coverage aggregate. #963 remains owner of broader current-vs-historical baseline governance.
+>
 > #821 current-parent reconstruction: preserve grouping-comparison leftover-map post complete-case coverage from historical `11a78553...` on exact #820 `503d043e...`, but move the decision to ADR 0290 / v2.47.0 and fail closed persisted coverage whenever ABAC hides any grouping member. Review 5126637582 is the authorization RED authority; #963 still owns the broader current-vs-historical baseline cleanup.
 >
 > #820 exact-current-parent reconstruction: persisted singular-value axis badges