feat(u7): filename groups — the last v1 unit, and a table that did not reproduce

Completes U7 with its fourth component: a jump-to-group rail derived from
filename prefixes, replacing the subfolder sections ROADMAP named. The scope
departure was ratified by the operator 2026-09-22; this commit deletes
test_no_group_rail_is_shipped_yet, the guard that held it back, in the same
change that builds what it guarded against.

All seven v1 capabilities are now landed. The 1.0 cut is a decision, not a
dependency, and it is the operator's — no version bump here, because a commit
is not a release.

THE RULE CHANGED AT IMPLEMENTATION, ON MEASURED GROUNDS. The contract specified
`strip ONE trailing run of digits`; run against the live set that yields 24
groups for sindra-bakeoff's 40 images and 27 for sindra's 30 — a rail with a row
per tile — because it keys on the END of the stem, where the instance number
lives. The contract's own table claimed 5 and 1 for those two booths and neither
reproduces; the numbers are reachable only by two OTHER heuristics, so the table
that justified the design was assembled from more than one rule. Its own worked
example contradicts it in plain sight.

The shipped rule keys on the first separator-delimited segment, where the family
lives, destemming only when the stem has no separator at all — so `ac01` -> `ac`
while `v30-seed8302` and `v35-seed8302` stay apart. Re-measured across all 17
live booths; the table is in the contract.

INV-3 GAINED ITS SECOND DEGENERACY. The contract guarded one group for
everything (sc-iso-spread: DSC0001-DSC0006). The live set's actual failure is
the opposite — pewpew-ui-brief yields 23 groups for 34 items, dfa-concepts 13
for 20 — and the contract as written would have shipped a rail that is a second
copy of the grid. The rail now renders only when grouping is informative: two or
more groups, and the middle group holding more than one item. That predicate
gets all 17 booths right.

Grouping is a VIEW. The grid stays sorted(rel) and the zoom ring stays that
order filtered to images; the group fixture interleaves across subdirectories
precisely so a (group, rel) re-sort goes red. Groups are derived from the
RENDERED list, not the full gallery, so no anchor points at a filtered-out tile.

booth/items.py       _group_of + Item.group, derived in the resolver (INV-1)
booth/app.py         _groups() builds the rail rows; build_gallery carries it
booth/templates/     the rail-groups nav and its CSS
tests/               +16 tests; 639 green

Every new falsifier was proved by running its defeating change (12/12). Three
were vacuous first time out: one fixture's positional order happened to be
alphabetical, one assertion miscounted elements, and the harness itself
certified a broken test twice — no green baseline, and byte-identical mutations
silently defeated by the pyc cache's one-second mtime granularity.

booth/app.py

@@ -520,6 +520,8 @@ def build_gallery(child: Path) -> list[dict]:
                 "doc": it.doc,
                 "url": it.url,
                 "section": it.section,
+                # U7. Derived in the resolver (INV-1); this only carries it.
+                "group": it.group,
                 "caption": it.caption,
                 "rendered": rendered,
                 "rendered_html": rendered_html,
@@ -1007,14 +1009,57 @@ def create_app(
                 buckets["annotated"].append(it)
             if any(m.id in open_ids for m in mine):
                 buckets["unanswered"].append(it)
+        shown = buckets[active]
         rail = {
             "active": active,
             # ORDER: the declaration order of FILTERS. Stated because a rail is
             # an ordered collection and invariant 6 binds to it like any other.
             "counts": [{"key": f, "n": len(buckets[f])} for f in FILTERS],
             "total": len(gallery),
+            "groups": _groups(shown),
         }
-        return rail, buckets[active]
+        return rail, shown
+
+    def _groups(shown: list[dict]) -> list[dict]:
+        """The jump-to-group rows, or [] when grouping would not help.
+
+        DERIVED FROM `shown`, NOT FROM THE FULL GALLERY, so every anchor lands
+        on a tile the page actually rendered. A row pointing at an item the
+        current filter has hidden scrolls nowhere, which is the same defect as
+        a wrong id arriving by a different route.
+
+        ORDER: the position of each group's FIRST member in the rendered
+        sequence — which is `sorted(rel)` narrowed by the filter and never
+        re-sorted. So the rail reads in the direction the grid does, and adding
+        a file reshuffles nothing unless it lands first in its group. Settled by
+        the operator 2026-09-22; ROADMAP carries the row. `dict` preserves
+        insertion order, so walking `shown` once IS the rule.
+
+        ⚠ THE RAIL IS ABSENT UNLESS GROUPING IS INFORMATIVE: two or more
+        groups, and the middle group holding more than one item. TWO
+        degeneracies, not one. The contract named only the first --
+        `sindra` and `sc-iso-spread` put every file in ONE group, and a rail
+        with a single row cannot navigate. The second is the one the live set
+        actually exhibits: `pewpew-ui-brief` yields 23 groups for 34 items and
+        `dfa-concepts` 13 for 20, a rail that is a second copy of the grid.
+        Both render as no rail, because a navigation affordance that cannot
+        navigate is worse than none -- it occupies the space where the real one
+        would be.
+        """
+        by_group: dict[str, list[dict]] = {}
+        for it in shown:
+            if it["group"] is not None:
+                by_group.setdefault(it["group"], []).append(it)
+        sizes = sorted(len(v) for v in by_group.values())
+        if len(sizes) < 2 or sizes[len(sizes) // 2] <= 1:
+            return []
+        return [
+            # The anchor is the FIRST member's existing tile id. The template
+            # already stamps `id="item-<rel>"` on every figure; minting a
+            # parallel `#group-<key>` would be a second identity for one tile.
+            {"key": k, "n": len(v), "anchor": f"item-{v[0]['name']}"}
+            for k, v in by_group.items()
+        ]
 
     def _board_rows(booth: Path) -> list[dict]:
         """The link board's rows, or [] for a board that cannot be read.

booth/items.py

@@ -15,6 +15,7 @@ See docs/contracts/u1_item_record.contract.md.
 
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Sequence
@@ -89,6 +90,7 @@ class Item:
     url: str
     kind: str
     section: str | None
+    group: str | None
     caption: str | None
     blurred: bool
     doc: str | None
@@ -115,6 +117,43 @@ def _section_of(rel: str) -> str | None:
     return None if str(parent) == "." else parent.as_posix()
 
 
+# One separator run between name segments. A filename is the only grouping
+# signal the live booths actually carry: 0 of 11 galleries have a subdirectory.
+_SEG = re.compile(r"[-_. ]+")
+
+
+def _group_of(rel: str) -> str | None:
+    """The grouping key for an item, or None when it has none.
+
+    THE RULE, in one line: **the first separator-delimited segment of the
+    basename's stem — with a trailing digit run stripped only when the stem has
+    no separator at all.** `00-sheet-c1-market-noon.png` -> `00`;
+    `m-c1-market-noon-9401.png` -> `m`; `flag-rear.png` -> `flag`;
+    `ac01.png` -> `ac` (no separator, so the digits are the separator);
+    `v30-seed8302.png` -> `v30` (separator present, so `v30` survives and does
+    not merge with `v35`, which is the axis that booth is about).
+
+    None for a stem with nothing before the digits -- `01.png` has no prefix to
+    group on, and inventing one would file every numbered render under the
+    empty string.
+
+    ⚠ THIS IS NOT THE RULE THE CONTRACT FIRST NAMED. `strip ONE trailing run of
+    digits` was measured against the live set on 2026-09-22 and yields 24 groups
+    for sindra-bakeoff's 40 images and 27 for sindra's 30 -- a rail with one row
+    per tile. The contract's own table claimed 5 and 1 for those two booths;
+    neither reproduces under the rule it states beside them. The rewritten table
+    carries the re-measurement.
+
+    Derived HERE and nowhere else (INV-1). A route body that re-derived it would
+    be the caption bug in a new field.
+    """
+    stem = Path(rel).stem  # basename without its last suffix; `a.tar.gz` -> `a.tar`
+    segs = _SEG.split(stem)
+    if len(segs) == 1:
+        return re.sub(r"\d+$", "", stem) or None
+    return segs[0] or None
+
+
 def _resolve_captions(by_rel: dict[str, Path]) -> tuple[dict[str, str], set[str]]:
     """(caption-by-rel, rels consumed as sidecars).
 
@@ -203,6 +242,7 @@ def booth_items(booth: Path) -> list[Item]:
                 url=quote(rel, safe="/"),
                 kind=classify(p.name),
                 section=_section_of(rel),
+                group=_group_of(rel),
                 caption=caption.get(rel),
                 blurred=rel in blurred,
                 doc=doc_kind(p.name),

booth/templates/base.html

@@ -529,6 +529,15 @@
             opacity:.65;border:1px solid transparent}
     .rail-f:hover{opacity:1}
     .rail-f.on{opacity:1;border-color:var(--line,#2a2a2a);background:rgba(255,255,255,.06)}
+    /* The group row. Wraps rather than scrolls: 16 groups is the live maximum
+       and a horizontal scroller hides half of them behind a gesture. */
+    .rail-groups{display:flex;gap:.35rem;flex-wrap:wrap;align-items:baseline;
+                 padding-left:.5rem;margin-left:.25rem;border-left:1px solid var(--line,#2a2a2a)}
+    .rail-g{font-size:.8em;padding:.1rem .4rem;border-radius:3px;text-decoration:none;
+            opacity:.6;border:1px solid transparent}
+    .rail-g:hover{opacity:1;border-color:var(--line,#2a2a2a)}
+    /* The jumped-to tile, so a fragment jump says where it landed. */
+    figure.item:target{outline:2px dashed #7aa2f7;outline-offset:3px}
     figure.item.is-cursor{outline:2px solid #7aa2f7;outline-offset:2px}
   </style>
 </head>

booth/templates/booth.html

@@ -251,11 +251,11 @@
      ORDER: the declaration order of FILTERS in app.py. A rail is an ordered
      collection and invariant 6 binds to it like any other.
 
-     ⚠ NO JUMP-TO-GROUP ANCHORS YET. Replacing directory sections with
-     filename-derived groups is a scope departure from ROADMAP's U7 row that
-     the operator has not ruled on; see docs/contracts/u7_navigation.contract.md
-     and tests/test_navigation.py::test_no_group_rail_is_shipped_yet, which
-     fails the moment somebody builds it anyway. #}
+     THE GROUP ROW is `rail.groups`, which is EMPTY unless grouping is
+     informative — see `_groups` in app.py. `{% raw %}{% if rail.groups %}{% endraw %}`
+     is therefore the whole guard; the two degenerate cases (one group for
+     everything, one group per item) are decided in Python, where they can be
+     measured, rather than by a count in a template. #}
   <div class="rail">
     <span class="rail-total">{{ rail.total }} item{{ '' if rail.total == 1 else 's' }}</span>
     {% for f in rail.counts %}
@@ -264,6 +264,17 @@
          href="/b/{{ name_url }}/{% if f.key != 'all' %}?filter={{ f.key }}{% endif %}"
          {% if f.key == filter %}aria-current="true"{% endif %}>{{ f.key }} <b>{{ f.n }}</b></a>
     {% endfor %}
+    {% if rail.groups %}
+    <nav class="rail-groups" aria-label="jump to group">
+      {% for g in rail.groups %}
+        {# The anchor is the first member's EXISTING tile id, so a group has one
+           identity on the page rather than two. Plain fragment links: no JS,
+           and the browser's own back button undoes the jump. #}
+        <a class="rail-g" data-group="{{ g.key }}"
+           href="#{{ g.anchor }}">{{ g.key }} <b>{{ g.n }}</b></a>
+      {% endfor %}
+    </nav>
+    {% endif %}
   </div>
   <div class="gallery" id="grid" tabindex="-1">
     {% for it in items %}