@andresmassello/uscha 1.90.0 → 1.92.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`.
 """
 
@@ -44,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
@@ -62,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).
@@ -102,6 +131,17 @@ ACTIONS = {
     "TAGGED": "machine: run the case",
 }
 
+# INV-TOP-06 (ADR-038): what a row that is green ON PAPER is actually waiting on when the
+# seal is broken. Presentation, like ACTIONS above: the engine says WHAT broke (the reason),
+# this says what the reader does about it, and the mapping is by reason prefix so a new
+# reason class degrades to the generic line instead of to silence.
+SEAL_ACTIONS = (
+    ("stale seal", "seal: snapshot at HEAD"),
+    ("repo subtree dirty", "seal: commit or discard, then snapshot"),
+    ("evidence altered", "seal: re-run the suite, then snapshot"),
+    ("evidence missing", "seal: re-run the suite, then snapshot"),
+)
+
 
 # --------------------------------------------------------------------------- #
 # pure rendering                                                              #
@@ -151,6 +191,11 @@ def _pad(text, width):
     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.
@@ -182,7 +227,15 @@ def _pct_line(terminado):
     """INV-TOP-01: the DONE bar carries an explicit `N unmeasured` suffix whenever anything
     is unmeasured, and the engine has already capped the percentage below 100 while any
     obligation sits outside MEASURED_PASS -- the renderer republishes that fact, it never
-    recomputes it (AC-T-01, AC-T-04, AC-T-23)."""
+    recomputes it (AC-T-01, AC-T-04, AC-T-23).
+
+    INV-TOP-06 (ADR-038) rides on the same line: when the engine's seal is MEASURED broken
+    (`terminado.sealed.ok is False`) the bar says so and names the first reason -- and the
+    percentage beside it is already capped below 100, in the engine, for the same reason the
+    unmeasured cap is (single derivation, AC-T-24). An UNMEASURED seal (`ok is null`: no git
+    work tree, the state of every frozen fixture) adds NOTHING here: the seal is shown only
+    when it is measured, and decorating a header with the absence of a measurement would
+    turn INV-TOP-05's `—` into noise on every board."""
     done = terminado.get("done")
     total = terminado.get("total")
     pct = terminado.get("pct")
@@ -190,9 +243,37 @@ def _pct_line(terminado):
     line = "DONE %s/%s (%s%%)" % (_num(done), _num(total), _num(pct))
     if unm:
         line += " %s %d unmeasured" % (MID, unm)
+    # the state is a FILE a human can hand us (`--state`), so `sealed` is guarded by TYPE and
+    # not merely by truthiness: a string there would answer `.get` with an AttributeError, and a
+    # `reasons` that is a string is iterable -- the frame would name its first CHARACTER as the
+    # reason. Same guards `_top_spec_diff` applies on the engine side, for the same reason.
+    seal = terminado.get("sealed")
+    seal = seal if isinstance(seal, dict) else {}
+    if seal.get("ok") is False:
+        raw = seal.get("reasons")
+        reasons = [r for r in raw if isinstance(r, str) and r] if isinstance(raw, list) else []
+        line += " %s unsealed (%s)" % (MID, _safe(reasons[0]) if reasons
+                                       else "no reason recorded")
     return line
 
 
+def _seal_action(sealed):
+    """The ACTION cell of a row that is green on paper while the seal is broken. Empty
+    whenever the seal is not MEASURED broken -- an unmeasured seal changes no row, and a
+    `sealed` of the wrong TYPE reads as no seal at all rather than raising mid-frame."""
+    seal = sealed if isinstance(sealed, dict) else {}
+    if seal.get("ok") is not False:
+        return ""
+    raw = seal.get("reasons")
+    for reason in (raw if isinstance(raw, list) else []):
+        if not isinstance(reason, str):
+            continue
+        for prefix, action in SEAL_ACTIONS:
+            if reason.startswith(prefix):
+                return action
+    return "seal: re-snapshot the current state"
+
+
 def _burnup_line(burnup, cols):
     """The score trend, labelled as a score trend. v0.1 has no obligation-count history
     (ADR-035/2), so calling this a burn-up of closed obligations would be a lie the label
@@ -230,15 +311,21 @@ def _cases_text(ob):
     return "%s/%s" % (_num(ob.get("cases_pass")), total)
 
 
-def _row(ob, selected):
+def _row(ob, selected, seal_action=""):
     # 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 "  "
+    action = ACTIONS.get(ob.get("state"), DASH)
+    # INV-TOP-06: only the rows that CLAIM to be done change, and only while the seal is
+    # measured broken. A failing or unmeasured row already names its own debtor; telling it
+    # about the seal too would bury the thing it is actually waiting for.
+    if seal_action and ob.get("state") == "MEASURED_PASS":
+        action = seal_action
     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))
+        _num(ob.get("age_hours")), action)
 
 
 def _safe(text):
@@ -294,6 +381,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)
 
 
@@ -346,8 +435,9 @@ def _render_board(state, size, sel, plain, status=""):
     top = max(0, top)
 
     table = []
+    seal_action = _seal_action(terminado.get("sealed"))
     for i, ob in enumerate(obligations[top:top + body], start=top):
-        line = _fit(_row(ob, i == sel), cols)
+        line = _fit(_row(ob, i == sel, seal_action), cols)
         table.append(line if plain else _colorize(line, ob.get("state")))
     hidden = len(obligations) - len(table)
     if hidden > 0:
@@ -386,11 +476,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
@@ -552,6 +643,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)  #
 # --------------------------------------------------------------------------- #
@@ -795,6 +1030,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).
 
@@ -808,7 +1122,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
@@ -821,9 +1154,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"):
@@ -840,7 +1185,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
@@ -904,6 +1253,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
@@ -947,6 +1315,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
@@ -997,6 +1385,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,9 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.90.0",
+  "version": "1.92.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.",
+  "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, 53 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",
     "url": "https://github.com/andresmassello"

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

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

package/uscha-kit/README.md

@@ -1,6 +1,6 @@
 # uscha-kit
 
-**Kit version:** v1.90.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.92.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,
@@ -591,11 +591,7 @@ python3 $QL simplicity-check --diff changes.diff --json        # consumed by usc
 
 ## Ledger subcommands
 
-`doctor - rubric-ingest - init - snapshot - check-coverage - log-step - ingest-gate - phase -
-converged - oscillation - escalate - resolve-escalation - log-gate - flag-blocker -
-production-finding - spec-doubt - spec-change-request - regression-check - summary - readiness -
-execution-policy - dashboard - rebuild - simplicity-check - waste-check - pit-check - gate-check -
-spec-check - golden-diff` - the exact current `qa_ledger.py` parser surface; each supports `--help`.
+`bench - bench-curate - bench-r2 - bench-roundtrip - bootstrap-oracle - bootstrap-variance - check-coverage - check-terminado - cleanroom - compile-ingest - compile-validate - converged - curate - curation-check - dashboard - discover - doctor - escalate - execution-policy - facts - fastpath-eval - fidelity - flag-blocker - gate-check - golden-coverage - golden-diff - ingest-gate - init - ir-extract - ir-render - lang-compare - log-gate - log-step - oscillation - phase - pit-check - production-finding - promote - readiness - rebuild - regression-check - resolve-escalation - roundtrip - rubric-ingest - simplicity-check - snapshot - spec-change-request - spec-check - spec-doubt - spec-drift - summary - top - waste-check` - the exact current `qa_ledger.py` parser surface (53 subcommands, derived from `SYSTEM-FACTS.json`, itself introspected from `build_parser()`); each supports `--help`.
 
 The **fact gates** (golden-diff, gate-check, pit-check, simplicity) are PERSISTED with
 `log-gate`: a fail blocks convergence and caps readiness ≤65 via the ledger. A CONSTITUTION

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.90.0
+uscha-kit 1.92.0

package/uscha-kit/install-uscha.py

@@ -842,6 +842,10 @@ def cmd_top(args):
     # and uscha_top.py falls back to $USERNAME/$USER, then to curate's own default.
     if getattr(args, "human", None):
         cmd += ["--human", args.human]
+    # and so does the rerun command (1.91.0, ADR-037): `o` runs what the HUMAN passed at
+    # launch and nothing else -- the launcher forwards the string, it never supplies one.
+    if getattr(args, "rerun_cmd", None):
+        cmd += ["--rerun-cmd", args.rerun_cmd]
     rc = subprocess.call(cmd)
     if rc:
         raise SystemExit(rc)
@@ -1051,6 +1055,7 @@ def build_parser():
     top.add_argument("--once", action="store_true", help="print one plain frame and exit (implied without a TTY)")
     top.add_argument("--refresh", type=float, default=2.0, help="seconds between mtime polls of the ledger (default: 2, floor 0.5); `r` still forces a re-read")
     top.add_argument("--human", default=None, help="who is at the keyboard: the name recorded on every verdict this session writes (default: $USERNAME/$USER, then `curate`'s own default)")
+    top.add_argument("--rerun-cmd", default=None, help="the shell command `o` reruns in the first configured repo (e.g. \"pytest -q\"); never guessed and never read from config -- without it `o` is inert. The engine's own `snapshot` ingests the report afterwards, red runs included")
     top.add_argument("--json", action="store_true", help="print the engine's read-only `top --json` contract instead of rendering it")
     top.set_defaults(func=cmd_top)
     return parser

package/uscha-kit/skills/uscha-devloop/SKILL.md

@@ -459,6 +459,18 @@ BLOCKER/CRITICAL + no open escalation), never self-declared — if it exits 1, t
 output lists exactly which facts are missing; do NOT open the PR, close the gap.
 A `spike/*` branch NEVER passes this gate (kit 1.19.0): spike code is disposable
 by contract — its only legitimate output is an ADR with lessons, never a merge.
+- **Before declaring TERMINADO, run the seal (kit 1.92.0, INV-T1 / ADR-038):**
+
+```bash
+python3 $QL check-terminado          # 0 = sealed · 1 = broken · 2 = UNMEASURED
+```
+
+  It recomputes, from the ledger and the tree, whether the recorded evidence still belongs to
+  the code on disk: the repo subtree clean, `HEAD` equal to the last snapshot's commit, every
+  ingested report still hashing to what was recorded. **Exit 1** — do not declare TERMINADO:
+  re-snapshot on the CURRENT state (`snapshot --repo <REPO> --phase post`) and record why the
+  seal broke. **Exit 2** — the seal is UNMEASURED (no git, or no snapshot recorded): say so
+  plainly; an answer nobody could measure is not a TERMINADO either.
 - Ensure conventional-commit history is clean.
 - Open the PR(s). Confirm CI is green.
 - **STOP.** Present the PR link(s) and wait for the human to merge.