@andresmassello/uscha 1.89.0 → 1.91.0

package/uscha-kit/.claude/skills/uscha-devloop/uscha_top.py

@@ -20,6 +20,18 @@ TUI never opens the ledger for writing and never builds a curation record, so it
 drift from the record shape the engine owns. It records a judgement; it does not promote,
 does not rerun, and never moves DONE (INV-TOP-03).
 
+M4 scope (phase 2, ADR-037): `d` opens a READ-ONLY spec↔code drift pane over `spec_diff`, the
+advisory record `qa_ledger.py spec-drift` already left in the ledger -- it measures nothing and
+runs nothing; with no recorded run the pane says so instead of showing a clean board. `o` reruns
+the command THE HUMAN supplied at launch (`--rerun-cmd`, ADR-008 style: the tool never guesses a
+test command) and then lets the engine's own `snapshot` ingest whatever the run produced -- so the
+board still moves only on measured evidence, and the TUI still writes nothing itself. Three spawns
+exist BEYOND THE READ BOUNDARY and no more: `curate` (a verdict), `snapshot` (the ingest) and the
+human's own command, one per keypress, none inside a loop. The read boundary itself -- the one
+`top --json` call in `load_state` -- is a fourth `subprocess.run` in this module and always was;
+counting it among the three read as a false claim to anyone who grepped (1.91.0 blind review), so
+the sentence now says which side of the boundary it counts. Four call sites total, no fifth.
+
 Stdlib only. Python 3.8+. Runnable directly or via `python -m uscha_top`.
 """
 
@@ -30,6 +42,7 @@ import shutil
 import subprocess
 import sys
 import time
+import unicodedata
 
 DEFAULT_LEDGER = "QA-LEDGER.json"
 FALLBACK_SIZE = (100, 32)
@@ -43,6 +56,11 @@ MIN_REFRESH = 0.5       # a poll faster than this is a busy loop, not a refresh
 
 MODE_BOARD = "board"
 MODE_VERDICTS = "verdicts"
+MODE_DIFF = "diff"
+# DIFF geometry: title, rule, the measurement line, the rule under it, the table header, the
+# rule above the status line, the status line, the key hint. The rest is drift rows.
+DIFF_CHROME = 8
+DIFF_HINT = "advisory (ADR-005) -- a stale spec is a conversation, never a gate"
 # VERDICTS geometry: title, rule, the pending line, the rule under the list, the rule under
 # the pane, the status line, the key hint. Everything else is queue rows + the detail pane.
 VERDICT_CHROME = 7
@@ -61,6 +79,18 @@ VERDICT_COOLDOWN = 0.25
 VERDICT_COOLDOWN_MSG = ("verdict recorded -- release the key (the queue advanced; the next "
                         "observation is a new judgement)")
 
+# `o` (ADR-037, option B). The command is NEVER guessed and never read from config: it is the
+# shell string the human passed at launch, the same discipline `cleanroom --run` follows
+# (ADR-008). Without it the key is inert and says why.
+RERUN_MISSING_MSG = "no rerun command given -- pass --rerun-cmd"
+# The same courtesy a refused verdict key gets: a held `o` is one rerun, and the presses the
+# cooldown eats must SAY they were eaten. A keypress that vanishes silently reads as a dropped
+# input, and the next reflex is to press it again -- the repeat the cooldown exists to stop.
+RERUN_COOLDOWN_MSG = ("rerun in progress or just finished -- release the key (the board "
+                      "reloaded; press `o` again to run it once more)")
+RERUN_FROZEN_MSG = "--state is a frozen snapshot -- a rerun needs a live ledger"
+RERUN_NO_REPO_MSG = "no repo configured in this ledger -- nothing to rerun and nothing to ingest"
+
 # ANSI SGR by obligation state. TRACED and TAGGED deliberately share the UNMEASURED gray:
 # the v0.1 engine has no source for either rung (ADR-032), so they must read as "not
 # measured", never as PASS (INV-TOP-02, AC-T-08).
@@ -105,21 +135,76 @@ ACTIONS = {
 # --------------------------------------------------------------------------- #
 # pure rendering                                                              #
 # --------------------------------------------------------------------------- #
+def _dw(text):
+    """Display width in TERMINAL COLUMNS, not codepoints.
+
+    `len()` counts codepoints, and the frame's whole contract is columns: a CJK project name
+    or a full-width event text takes two columns per codepoint, so a line `len()` called
+    exactly `cols` wide draws twice that and the frame every golden pins stops being a frame
+    (1.86.1 fresh review, LOW, deferred until a fixture existed -- `state-wide.json` is it).
+
+    Three classes, and no font metric anywhere: East Asian Wide and Fullwidth cost 2, a
+    combining mark costs 0 (it draws on the previous cell), everything else costs 1. East
+    Asian *Ambiguous* deliberately counts 1 -- that is the class the renderer's own glyphs
+    fall into (`…`, `·`, `─`, `│`, `▁`, `—`), so on an ASCII state `_dw` is `len` and every
+    frame captured before this function existed stays byte-identical."""
+    width = 0
+    for ch in str(text):
+        if unicodedata.combining(ch):
+            continue
+        width += 2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1
+    return width
+
+
+def _cut(text, width):
+    """The longest PREFIX of `text` that fits in `width` columns, whole characters only.
+
+    A wide character is never split: half a glyph is not half a column, it is a cell the
+    terminal fills however it likes and a frame nobody can snapshot."""
+    if width <= 0:
+        return ""
+    out, used = [], 0
+    for ch in str(text):
+        w = 0 if unicodedata.combining(ch) else (
+            2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1)
+        if used + w > width:
+            break
+        out.append(ch)
+        used += w
+    return "".join(out)
+
+
+def _pad(text, width):
+    """`str.ljust` measured in columns. Padding by codepoints puts a wide cell's second
+    column inside the next field and every column after it walks."""
+    return str(text) + " " * max(0, width - _dw(text))
+
+
+def _rjust(text, width):
+    """`str.rjust` measured in columns -- `_pad`'s mirror, for the numeric columns."""
+    return " " * max(0, width - _dw(text)) + str(text)
+
+
 def _fit(text, cols):
     """One line, never wider than the terminal. Wrapping would break the frame's row
-    accounting, so an over-long line is cut and marked."""
+    accounting, so an over-long line is cut and marked.
+
+    Measured and cut in COLUMNS (`_dw`/`_cut`): cutting by codepoints was the bug. Note the
+    cut may leave one column short rather than land exactly on `cols - 1` -- when the
+    character at the boundary is wide it is dropped whole, and a frame one column narrow is
+    correct where a frame one column wide is not."""
     if cols <= 0:
         return ""
-    if len(text) <= cols:
+    if _dw(text) <= cols:
         return text
-    return text[:cols - 1] + "…" if cols > 1 else text[:cols]
+    return _cut(text, cols - 1) + "…" if cols > 1 else _cut(text, cols)
 
 
 def _spread(left, right, cols):
     """left ... right on one line, right-aligned, degrading to just `left` when tight."""
-    if len(left) + len(right) + 1 > cols:
+    if _dw(left) + _dw(right) + 1 > cols:
         return _fit(left, cols)
-    return left + " " * (cols - len(left) - len(right)) + right
+    return left + " " * (cols - _dw(left) - _dw(right)) + right
 
 
 def _num(value):
@@ -151,7 +236,7 @@ def _burnup_line(burnup, cols):
     note = "  (readiness score, not closed obligations)"
     if not points:
         return label + DASH + "  (no `readiness --record` history yet)"
-    room = max(4, min(BURNUP_MAX, cols - len(label) - len(note)))
+    room = max(4, min(BURNUP_MAX, cols - _dw(label) - _dw(note)))
     bars = "".join(BLOCKS[min(len(BLOCKS) - 1, max(0, int(p) * len(BLOCKS) // 101))]
                    for p in points[-room:])
     return label + bars + note
@@ -180,10 +265,13 @@ def _cases_text(ob):
 
 
 def _row(ob, selected):
+    # the three left columns are cut and padded in COLUMNS: an id or state carrying wide
+    # characters used to eat its neighbour's field and walk every column after it.
     gutter = "> " if selected else "  "
-    return "%s%-8s%-9s%-15s%7s%5s  %s" % (
-        gutter, _safe(ob.get("id") or "?")[:8], _safe(ob.get("gate") or DASH)[:8],
-        _safe(ob.get("state") or "?")[:14], _cases_text(ob),
+    return "%s%s%s%s%7s%5s  %s" % (
+        gutter, _pad(_cut(_safe(ob.get("id") or "?"), 8), 8),
+        _pad(_cut(_safe(ob.get("gate") or DASH), 8), 9),
+        _pad(_cut(_safe(ob.get("state") or "?"), 14), 15), _cases_text(ob),
         _num(ob.get("age_hours")), ACTIONS.get(ob.get("state"), DASH))
 
 
@@ -191,8 +279,22 @@ def _safe(text):
     """No control character reaches the terminal through the feed. The engine already
     strips them where the text is derived (`_top_event_text`); this is the second guard on
     the same surface, because the renderer also accepts a frozen state file a human wrote,
-    and one ESC in it would be a control sequence the board obeys instead of prints."""
-    return "".join(c for c in str(text or "") if ord(c) >= 32 and ord(c) != 127)
+    and one ESC in it would be a control sequence the board obeys instead of prints.
+
+    Dropped (1.90.0), matching the engine's `_top_clean` exactly: C0 and DEL, the C1 range
+    U+0080-U+009F (a terminal reading the stream as latin-1 takes those for CSI/OSC), and
+    every Unicode format character (category `Cf`) -- U+200B costs a codepoint and no column,
+    U+202E reverses everything after it. A character that cannot be seen must not be able to
+    move what is."""
+    out = []
+    for ch in str(text or ""):
+        code = ord(ch)
+        if code < 32 or code == 127 or 0x80 <= code <= 0x9F:
+            continue
+        if unicodedata.category(ch) == "Cf":
+            continue
+        out.append(ch)
+    return "".join(out)
 
 
 def _feed_line(ev, cols, plain):
@@ -226,6 +328,8 @@ def render(state, size, sel=0, plain=True, mode=MODE_BOARD, status=""):
     """
     if mode == MODE_VERDICTS:
         return _render_verdicts(state, size, sel, plain, status)
+    if mode == MODE_DIFF:
+        return _render_diff(state, size, sel, plain, status)
     return _render_board(state, size, sel, plain, status)
 
 
@@ -318,11 +422,12 @@ def _render_board(state, size, sel, plain, status=""):
         out[-1] = _fit("status %s %s" % (MID, _safe(status)), cols)
     for i in range(feed_n):
         out.append(_feed_line(shown[i], cols, plain) if i < len(shown) else "")
-    # `[v] verdicts` lost its `(M3)` marker in 1.89.0 because the key now works; `[d]/[o]`
-    # keeps its `phase 2` marker because those two still do nothing (SPEC s1/s6). A hint that
-    # labels a live key as future is the same class of stale claim the frames exist to catch.
-    out.append("[j/k] move %s [r] reload %s [q] quit %s [v] verdicts %s "
-               "[d]/[o] phase 2" % (MID, MID, MID, MID))
+    # every key on this line WORKS as of 1.91.0: `[v]` lost its `(M3)` marker when verdicts
+    # shipped, and `[d]/[o]` lose their `phase 2` marker here for the same reason. A hint that
+    # labels a live key as future is the same class of stale claim the frames exist to catch --
+    # and one that labels a dead key as live is the worse half of it.
+    out.append("[j/k] move %s [r] reload %s [q] quit %s [v] verdicts %s [d]iff %s [o] rerun"
+               % (MID, MID, MID, MID, MID))
     # a coloured line was already fitted BEFORE its escape bytes went in (table rows and
     # feed lines both), and re-fitting it here would count those bytes as visible width --
     # cutting the coloured frame ~9 characters shorter than the plain one it is supposed to
@@ -355,14 +460,17 @@ def _wrap(text, width):
     for word in _safe(text).split():
         if not line:
             line = word
-        elif len(line) + 1 + len(word) <= width:
+        elif _dw(line) + 1 + _dw(word) <= width:
             line += " " + word
         else:
             out.append(line)
             line = word
-        while len(line) > width:
-            out.append(line[:width])
-            line = line[width:]
+        # the hard split is measured in columns too, and `_cut` never breaks a wide
+        # character in half -- so a wide token continues on the next line, whole.
+        while _dw(line) > width:
+            head = _cut(line, width)
+            out.append(head)
+            line = line[len(head):]
     if line:
         out.append(line)
     return out or [""]
@@ -374,10 +482,10 @@ def _obs_row(i, ob, selected, cols):
     gutter = "> " if selected else "  "
     idx = "[%d]" % (i + 1) if i < VERDICT_LIST_MAX else "   "
     tail = " %s %s %s pending" % (MID, _safe(ob.get("ac")) or ("AC " + DASH), MID)
-    head = "%s%-4s%-18s" % (gutter, idx, _safe(ob.get("id"))[:18])
-    room = max(4, cols - len(head) - len(tail))
+    head = "%s%-4s%s" % (gutter, idx, _pad(_cut(_safe(ob.get("id")), 18), 18))
+    room = max(4, cols - _dw(head) - _dw(tail))
     title = _fit(_safe(ob.get("title")) or DASH, room)
-    return head + title.ljust(room) + tail
+    return head + _pad(title, room) + tail
 
 
 def _column_widths(cols):
@@ -412,7 +520,7 @@ def _pane(ob, cols, height):
             pad = max(len(left), len(right))
             left += [""] * (pad - len(left))
             right += [""] * (pad - len(right))
-            body = head + [("  %s │ %s" % (l.ljust(lw), r)).rstrip()
+            body = head + [("  %s │ %s" % (_pad(l, lw), r)).rstrip()
                            for l, r in zip(left, right)]
         else:
             body = (head + ["  CANDIDATE"] + ["  " + ln for ln in block("candidate", cols - 2)]
@@ -481,6 +589,150 @@ def _render_verdicts(state, size, sel, plain, status):
     return out[:rows] + [""] * max(0, rows - len(out))
 
 
+# --------------------------------------------------------------------------- #
+# DIFF mode -- spec <-> code drift, read-only (ADR-037 phase 2)                 #
+# --------------------------------------------------------------------------- #
+def first_repo(state):
+    """The repo this session acts on: the FIRST configured one, which is the same repo
+    `spec_pin` already labels the board with (ADR-032). Returns (name, path) or (None, None).
+
+    The choice is the engine's, not the TUI's -- `repos[]` arrives in configuration order and
+    this only takes the head of it. A multi-repo project therefore reruns and ingests ONE
+    repo, the first, and every line that depends on the choice says which repo it picked
+    rather than leaving the reader to assume it was all of them."""
+    repos = [r for r in (state.get("repos") or []) if isinstance(r, dict) and r.get("name")]
+    if not repos:
+        return None, None
+    return _safe(repos[0]["name"]), _safe(repos[0].get("path") or ".")
+
+
+def _lag_text(value):
+    """A lag in days, or the em dash when the record carries none. `%g` so a whole number of
+    days reads as `60` and a fractional one keeps its tenth -- the record rounds to one
+    decimal and this neither adds precision nor drops it."""
+    if not isinstance(value, (int, float)):
+        return DASH
+    return "%g" % value
+
+
+def _cut_tail(text, width):
+    """The longest SUFFIX of `text` that fits in `width` columns, whole characters only.
+    `_cut` read backwards -- same no-split-a-wide-glyph rule, same column arithmetic."""
+    if width <= 0:
+        return ""
+    out, used = [], 0
+    for ch in reversed(str(text)):
+        w = 0 if unicodedata.combining(ch) else (
+            2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1)
+        if used + w > width:
+            break
+        out.append(ch)
+        used += w
+    return "".join(reversed(out))
+
+
+def _fit_tail(text, cols):
+    """Like `_fit`, but it keeps the END of the string. Used only for paths: a governed file
+    cut at the front still shows the file that moved, cut at the back it shows a directory.
+
+    Measured and cut in COLUMNS (`_dw`/`_cut_tail`), like `_fit`: `len()` and slicing count
+    codepoints, and a CJK path component draws two columns per codepoint -- the DIFF pane was
+    the one surface still measuring itself in codepoints after 1.90.0 fixed the board. As
+    with `_fit`, the cut may land one column short rather than exactly on `cols - 1` when the
+    character at the boundary is wide: one column narrow keeps the frame, one column wide
+    does not."""
+    text = _safe(text)
+    if cols <= 0:
+        return ""
+    if _dw(text) <= cols:
+        return text
+    return "…" + _cut_tail(text, cols - 1) if cols > 1 else _cut_tail(text, cols)
+
+
+def _diff_widths(cols):
+    """`  <doc>  <lag>  <code ref>` -- 2 for the gutter, 2+2 for the separators, 6 for LAG."""
+    lag = 6
+    code = max(10, (cols - 4 - lag - 2) // 2)
+    doc = max(10, cols - 4 - lag - 2 - code)
+    return doc, lag, code
+
+
+def _diff_head(diff, state):
+    """The one line that says WHEN this was measured, or that nobody measured it.
+
+    The honest empty case is the whole point of the pane: with no `spec-drift` record the
+    board must not read as "no drift" -- it says there is no run and names the command that
+    would produce one (INV-TOP-05, the same rule the feed's empty label follows)."""
+    if not diff:
+        repo, _path = first_repo(state)
+        return ("no spec-drift run recorded -- run `qa_ledger.py spec-drift --repo %s`"
+                % (repo or "<repo>"))
+    stale = [s for s in (diff.get("stale") or []) if isinstance(s, dict)]
+    lag = diff.get("max_lag_days")
+    # the COUNT sits before the timestamp on purpose: at the 80-column floor this line is the
+    # one that gets cut, and "2 of 4 stale" is the fact the reader came for.
+    return ("spec %s code drift %s advisory %s %d of %d doc(s) stale (lag > %s d) %s "
+            "measured %s" % ("↔", MID, MID, len(stale), diff.get("docs_total") or 0,
+                             _num(lag), MID, _safe(diff.get("measured_at")) or DASH))
+
+
+def _render_diff(state, size, sel, plain, status):
+    """The spec↔code drift pane: `spec_diff` drawn, nothing derived and nothing run.
+
+    Read-only twice over. `d` never invokes `spec-drift` (that command walks git and WRITES
+    its latest-state record; this pane is a projection of that record, ADR-037), and `render`
+    performs no I/O at all (ADR-034). What is on screen is what the last real run measured,
+    with its own timestamp beside it so an old measurement cannot pass for a fresh one.
+
+    `sel` and `plain` are accepted and unused: this pane has no cursor (v1 shows the worst
+    lags first and NAMES the shortfall rather than scrolling) and no colour of its own -- a
+    green/red here would read as a gate, and ADR-005 drift never gates."""
+    cols, rows = size
+    cols = max(20, int(cols))
+    rows = max(DIFF_CHROME + 1, int(rows))
+    diff = state.get("spec_diff") if isinstance(state.get("spec_diff"), dict) else None
+    doc_w, lag_w, code_w = _diff_widths(cols)
+
+    out = [_spread("uscha top %s %s %s spec drift"
+                   % (MID, _safe(state.get("project")) or "(unnamed project)", MID),
+                   "step #%s" % _safe(_num(state.get("step"))), cols),
+           RULE * cols,
+           _fit(_diff_head(diff, state), cols),
+           RULE * cols,
+           "  %s  %s  %s" % (_pad("DOC", doc_w), _rjust("LAG/d", lag_w),
+                             "A NEWER GOVERNED FILE")]
+
+    body = []
+    stale = [s for s in ((diff or {}).get("stale") or []) if isinstance(s, dict)]
+    for s in stale:
+        ref = _fit_tail(s.get("code_ref") or DASH, code_w)
+        more = s.get("newer_files_total")
+        if isinstance(more, int) and more > 1:
+            # the row shows ONE file of the N that outran the doc, and says so: a single
+            # path with no cardinality beside it reads as "one file changed".
+            ref = _fit(ref + " (1 of %d)" % more, code_w)
+        body.append("  %s  %s  %s" % (_pad(_fit(_safe(s.get("doc")) or "?", doc_w), doc_w),
+                                      _rjust(_lag_text(s.get("lag_days")), lag_w), ref))
+    if not diff:
+        body = ["  nothing to show until a spec-drift run is recorded %s `d` reads that "
+                "record, it never runs it" % MID]
+    elif not stale:
+        body = ["  no spec document is stale at this lag %s every one reads CLEAN, unmapped "
+                "or untracked" % MID]
+
+    avail = rows - DIFF_CHROME
+    if len(body) > avail:
+        body = body[:max(0, avail - 1)] + ["  %s %d more stale doc(s) do not fit at this size "
+                                           "(worst lag first)" % (DASH, len(body) - avail + 1)]
+    out.extend(body[:avail])
+    out.extend([""] * max(0, avail - len(body)))
+    out.append(RULE * cols)
+    out.append(_fit("status %s %s" % (MID, _safe(status) or DIFF_HINT), cols))
+    out.append(_fit("[t]/[Esc] back %s [r] reload %s [q] quit" % (MID, MID), cols))
+    out = [line if "\x1b" in line else _fit(line, cols) for line in out]
+    return out[:rows] + [""] * max(0, rows - len(out))
+
+
 # --------------------------------------------------------------------------- #
 # state loading (the ONE read boundary -- it shells out, it never re-derives)  #
 # --------------------------------------------------------------------------- #
@@ -724,6 +976,85 @@ def apply_verdict(ob, verdict, args, engine=None):
     return False, said or ("curate exited %s -- nothing was recorded" % rc)
 
 
+def _rerun_call(cmd, cwd):
+    """The human's OWN command, run in the tracked repo's directory (ADR-037, option B).
+
+    `shell=True` is the decision, not an oversight: what arrives here is the shell string the
+    human typed after `--rerun-cmd` (`pytest -q && npm test`), exactly the way `cleanroom
+    --run` and `golden-coverage --harness` take theirs -- the engine never decides what to
+    run, and neither does this TUI (ADR-008). The trust boundary is the human's own shell,
+    which ADR-037 states rather than pretends to mitigate: a misspelt flag runs whatever the
+    shell makes of it, in that directory, the same as typing it there.
+
+    Output is NOT captured: a test suite writes to the terminal the human is watching, and
+    swallowing it would replace measured output with a spinner. One function on purpose --
+    it is the boundary the suite replaces to assert the command and the ONE call per keypress
+    without running anything (AC-T-26). Returns the exit code."""
+    return subprocess.run(cmd, shell=True, cwd=cwd).returncode
+
+
+def _snapshot_call(engine, ledger, repo):
+    """The INGEST, made by the engine's own `snapshot` -- the same subcommand the dev loop
+    runs at every pass close. This is what makes `o` honest: the board moves on ingested
+    evidence or it does not move at all, and the TUI still builds no record of its own
+    (ADR-033's rule, one more engine subcommand under it -- ADR-037).
+
+    Returns (returncode, the engine's own last line)."""
+    argv = [sys.executable, engine, "snapshot", "--ledger", ledger, "--repo", repo]
+    proc = subprocess.run(argv, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    said = ((proc.stderr or b"").decode("utf-8", "replace").strip().splitlines()
+            or (proc.stdout or b"").decode("utf-8", "replace").strip().splitlines())
+    return proc.returncode, (said[-1] if said else "")
+
+
+def rerun_banner(cmd, repo):
+    """What the board says WHILE the command runs. Pure, so the frame that carries it stays
+    a pure function of its inputs; the loop draws it before it blocks."""
+    return ("rerun: %s %s running in %s (first configured repo) %s verdict keys locked"
+            % (_safe(cmd), MID, _safe(repo), MID))
+
+
+def run_rerun(state, args, engine=None):
+    """One keypress -> the human's command, then the engine's ingest, then a reload upstream.
+    Returns (ran?, the line the status bar shows).
+
+    The order is the decision: the snapshot runs **whether or not the command exited 0**. A
+    red suite is evidence too, and the whole point of `o` is that what lands on the board is
+    what a report says, never what an exit code narrated -- refusing to ingest a red run
+    would leave the board showing the previous, greener measurement (measured red beats
+    narrated green, kit 1.48.1). What a non-zero exit changes is the STATUS LINE, which names
+    it, and nothing else.
+
+    Three refusals come first, none of which spawns anything: no `--rerun-cmd` (the command
+    is the human's to supply, ADR-008), a `--state` frozen snapshot (the ledger on disk is
+    not the one on screen -- the same refusal a verdict gets), and a ledger with no configured
+    repo (there is no cwd to run in and no repo to ingest for)."""
+    cmd = getattr(args, "rerun_cmd", None)
+    if not cmd:
+        return False, RERUN_MISSING_MSG
+    if getattr(args, "state", None):
+        return False, RERUN_FROZEN_MSG
+    repo, path = first_repo(state)
+    if not repo:
+        return False, RERUN_NO_REPO_MSG
+    eng = engine or engine_path()
+    if not eng:
+        return False, "qa_ledger.py not found next to uscha_top.py"
+    cwd = os.path.join(os.path.dirname(os.path.realpath(args.ledger)) or ".", path or ".")
+    if not os.path.isdir(cwd):
+        return False, "repo path '%s' does not exist -- nothing was run" % path
+    code = _rerun_call(cmd, cwd)
+    rc, said = _snapshot_call(eng, args.ledger, repo)
+    tail = said or ("snapshot exited %s" % rc)
+    if rc != 0:
+        return True, ("rerun exit %s %s snapshot FAILED (%s) -- nothing was ingested"
+                      % (code, MID, tail))
+    if code != 0:
+        # a red run is still a measurement: it is ingested, and the line says both facts.
+        return True, "rerun exit %s (red) %s ingested: %s" % (code, MID, tail)
+    return True, "rerun exit 0 %s ingested: %s" % (MID, tail)
+
+
 def after_verdict(sel, count):
     """Where the cursor lands once the queue has been re-read: (selection, mode).
 
@@ -737,7 +1068,26 @@ def after_verdict(sel, count):
     return max(0, min(sel, count - 1)), MODE_VERDICTS
 
 
-def dispatch_mode(key, mode, sel, count, cooling=False):
+def is_rerun_key(key, mode, cooling=False, rerunning=False):
+    """Is this keypress a rerun request (ADR-037)? A pure predicate, and deliberately NOT a
+    sixth member of `dispatch_mode`'s tuple: that shape is what M3 measured, and widening a
+    measured contract so it can carry a second action is how a keymap grows a second write
+    path nobody counted. The caller spends a True on exactly one `_rerun_call` + one
+    `_snapshot_call`, never a loop (AC-T-29).
+
+    `o` answers on the BOARD only -- the verdicts queue and the drift pane have their own
+    jobs -- and it is refused while a rerun is in flight or while the 250 ms cooldown after
+    one is still running, so a HELD `o` is one rerun and not a queue of them (the same guard
+    a held verdict key gets, ADR-033)."""
+    return key in ("o", "O") and mode == MODE_BOARD and not cooling and not rerunning
+
+
+# `rerunning=True` is never passed by `_loop`, and that is not an oversight: the rerun is
+# SYNCHRONOUS (the spawn blocks the loop, and `drain_keys` throws away whatever was typed
+# meanwhile), so the sync block plus the drain IS the lock -- the flag would have nothing to
+# guard against. It exists as a MEASURED contract: the predicate is what a future async rerun
+# would have to honour, and AC-T-27 pins it as a pure function rather than racing a terminal.
+def dispatch_mode(key, mode, sel, count, cooling=False, rerunning=False):
     """The mode machine: key + current mode -> (mode, selection, quit?, reload?, verdict).
 
     Pure, and the ONE place a keypress becomes a write decision -- `verdict` is a string the
@@ -750,9 +1100,21 @@ def dispatch_mode(key, mode, sel, count, cooling=False):
     stays pure). While it is true, `p`/`f`/`u` produce NO verdict: a key held down repeats,
     and the second repeat would judge the observation that just took the cursor's place. Every
     other key keeps working -- the cooldown blocks writes, not the reader."""
+    if mode == MODE_DIFF:
+        # a read-only pane with a read-only keymap: leave, re-read, or quit. No cursor (the
+        # pane names what does not fit instead of scrolling) and no write of any kind.
+        if key in ("q", "Q", "\x03"):
+            return mode, sel, True, False, None
+        if key in ("t", "T", "\x1b", "d", "D"):
+            return MODE_BOARD, 0, False, False, None
+        if key == "r":
+            return mode, sel, False, True, None
+        return mode, sel, False, False, None
     if mode != MODE_VERDICTS:
         if key in ("v", "V"):
             return MODE_VERDICTS, 0, False, False, None
+        if key in ("d", "D"):
+            return MODE_DIFF, 0, False, False, None
         sel, quit_now, reload_now = dispatch(key, sel, count)
         return MODE_BOARD, sel, quit_now, reload_now, None
     if key in ("q", "Q", "\x03"):
@@ -769,7 +1131,11 @@ def dispatch_mode(key, mode, sel, count, cooling=False):
         # an empty queue produces NO verdict: there is nothing selected to judge, and a
         # keypress that writes anyway would be a verdict the human never aimed at an OBS.
         # Neither does a queue still cooling from the last one.
-        return mode, sel, False, False, (VERDICTS[key] if (count and not cooling) else None)
+        # `rerunning` is the same refusal for a different reason (ADR-037): while a rerun is
+        # in flight the queue on screen was read BEFORE it, and a verdict recorded against a
+        # queue the ingest is about to move is a judgement aimed at the wrong observation.
+        return mode, sel, False, False, (VERDICTS[key] if (count and not cooling
+                                                           and not rerunning) else None)
     if len(str(key)) == 1 and key in "123456789":
         n = int(key) - 1
         return mode, (n if n < count else sel), False, False, None
@@ -833,6 +1199,25 @@ def _apply_and_advance(state, args, queue, cur, verdict):
     return state, cur, mode, status, True
 
 
+def _rerun_and_reload(state, args):
+    """ONE keypress -> ONE command -> ONE `snapshot` -> re-read. Returns (state, status).
+
+    A function of its own for the same structural reason `_apply_and_advance` is one, and the
+    suite asserts it the same way (AC-T-29): the module's single call to `run_rerun` must have
+    no `for`/`while` above it, so no later edit can quietly turn one keypress into a pass over
+    the repos. The re-read afterwards is what makes the new measurement visible; DONE moves
+    here or nowhere, because the ingest is the only thing that can move it (INV-TOP-03).
+
+    The input buffer is drained whether anything ran or not: a suite that takes a minute is
+    exactly when a human types, and those keystrokes belong to the terminal they were typed
+    into, not to the board that comes back."""
+    ran, status = run_rerun(state, args)
+    drain_keys()
+    if not ran:
+        return state, status
+    return _reload(state, args), status
+
+
 def _loop(state, args):
     sel = 0                       # the board's cursor
     vsel = 0                      # the verdict queue's cursor, kept apart from it
@@ -876,6 +1261,26 @@ def _loop(state, args):
                     cooldown_until = time.time() + VERDICT_COOLDOWN
                     if wrote:
                         _fresh, seen = _changed(paths, seen)
+                elif is_rerun_key(key, mode, cooling=cooling):
+                    if getattr(args, "rerun_cmd", None):
+                        # the frame the human watches WHILE the command runs, drawn before
+                        # the spawn because the spawn blocks this loop until it returns.
+                        # That synchronous shape is also why the verdict lock is measured on
+                        # `dispatch_mode(..., rerunning=True)` and not raced against a
+                        # terminal (AC-T-27): while the suite runs, no key is read at all --
+                        # what is typed lands in the buffer and the drain throws it away.
+                        sys.stdout.write("\x1b[H\x1b[2J" + "\n".join(render(
+                            state, terminal_size(args.cols, args.rows), sel=sel, plain=False,
+                            mode=mode, status=rerun_banner(args.rerun_cmd,
+                                                           first_repo(state)[0] or "?"))))
+                        sys.stdout.flush()
+                    state, status = _rerun_and_reload(state, args)
+                    # the same 250 ms a verdict gets, for the same reason: a held `o` must be
+                    # one rerun, not a queue of them.
+                    cooldown_until = time.time() + VERDICT_COOLDOWN
+                    _fresh, seen = _changed(paths, seen)
+                elif key in ("o", "O") and cooling and mode == MODE_BOARD:
+                    status = RERUN_COOLDOWN_MSG
                 elif key in VERDICTS and cooling:
                     # the key WAS a verdict and it was refused: say why. A keypress that
                     # vanishes silently reads as a dropped input, and the next reflex is to
@@ -926,6 +1331,13 @@ def build_parser():
                              "set, `curate`'s own default applies). The person pressing the "
                              "key is the author of the judgement -- the TUI never invents a "
                              "name for it")
+    parser.add_argument("--rerun-cmd", default=None,
+                        help="the shell command `o` reruns, in the first configured repo's "
+                             "directory (e.g. \"pytest -q\"). The tool NEVER guesses it and "
+                             "never reads it from config (ADR-008/037): without this flag "
+                             "`o` is inert and says so. After the command, the engine's own "
+                             "`snapshot` ingests the report -- on a red run too, because a "
+                             "red measurement is still a measurement")
     parser.add_argument("--cols", type=int, default=None)
     parser.add_argument("--rows", type=int, default=None)
     return parser

package/uscha-kit/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.89.0",
+  "version": "1.91.0",
   "displayName": "Uscha",
   "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 52 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {

package/uscha-kit/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.89.0",
+  "version": "1.91.0",
   "description": "Uscha spec-driven development methodology for coding agents. Includes npm/npx router.",
   "author": {
     "name": "Andres Massello",