@andresmassello/uscha 1.90.0 → 1.91.0

package/README.md

@@ -5,7 +5,7 @@ the rest.* Uscha gives a coding agent a spec to build against, a QA loop that co
 instead of looping forever, and a deterministic ledger that records what was **measured** —
 never what was claimed.
 
-> The tool executes · the method governs · evidence decides · the human approves.
+> The agent executes · the method governs · evidence decides · the human approves.
 
 **[uscha.dev](https://uscha.dev)** — the method, the five rules, the skills, the library
 (the diamond thesis, how-it-works diagrams, essay, 2-day dev course, reference, paper).
@@ -40,7 +40,7 @@ Requires **Python 3.8+** on the machine (the engine is Python stdlib — no pip
 runtime dependencies). The npm package is a thin router; the canonical installer is
 `uscha-kit/install-uscha.py`.
 
-**Kit v1.90.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.91.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
 [changelog](https://github.com/andresmassello/uscha/blob/main/uscha-kit/CHANGELOG.md)
 (the per-release changelogs live in the repo, not in the npm tarball)
 
@@ -85,13 +85,13 @@ automatic tool can perform: a human verdict.
    from the compiled code: 0.828 measured (12 archetypes) — names AND behaviour
 ```
 
-**What each arrow is, in the engine (kit 1.90.0, 52 subcommands, all measured):**
+**What each arrow is, in the engine (kit 1.91.0, 52 subcommands, all measured):**
 
 | Leg | Subcommands | What it establishes |
 |---|---|---|
 | Asset → typed graph | `ir-extract`, `ir-render` | the whole package becomes one canonical IR (M2, ADR-015) — deterministic, `UNTYPED` is a measurement not an error |
 | Forward, the compiler | `compile-validate`, `compile-ingest` | any model produces code; the engine validates the output contract and never compiles (M3, ADR-016) |
-| Forward, is it the *same* system? | `bootstrap-oracle`, `bootstrap-variance`, `bench` | a withheld oracle judges blind compilations — **12 archetypes, 9 PASS · 3 PARTIAL**, three models, JS included (M4/M5, ADR-017/018/028/029) |
+| Forward, is it the *same* system? | `bootstrap-oracle`, `bootstrap-variance`, `bench` | a withheld oracle judges blind compilations — **12 archetypes, 9 PASS · 3 PARTIAL**, three Claude-family models (Haiku · Sonnet · Opus — one vendor; cross-vendor not yet measured), JS included (M4/M5, ADR-017/018/028/029) |
 | Reverse, facts | `discover`, `golden-diff` (+ the `/uscha-characterize` skill) | system map + mechanically captured golden; typed candidate observations with evidence class (M1, ADR-013) |
 | Reverse, the human gate | `curate`, `promote`, `curation-check`, `bench-curate` | one verdict per candidate, append-only ledger verified against git; unjudged → `pr-ready` blocked naming it (ADR-009/010, INV-CURATION-01) |
 | Fidelity, honestly | `fidelity`, `roundtrip`, `bench-roundtrip`, `bench-r2` | per-compiler fidelity vector, id-level round trip, recoverability **0.828**, and the **noise floor** under every variance claim (ADR-014/022/027/030) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.90.0",
+  "version": "1.91.0",
   "description": "Spec-driven development for LLM coding agents: 9 skills + a stdlib evidence engine. Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",

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

@@ -8567,6 +8567,78 @@ def _top_events(ledger, limit=TOP_EVENTS_TAIL):
     return events[:max(0, int(limit))]
 
 
+def _top_repos(ledger):
+    """The configured repos, name and configured path, in configuration order (phase 2).
+
+    Two things the TUI must not decide for itself now have a source: WHICH repo a rerun runs
+    in and ingests for (ADR-037 picks the first configured one, exactly as `_top_spec_pin`
+    picks the sha it labels), and WHICH repo the `d` pane names when it tells the reader how
+    to produce the spec-drift run that is missing. `path` is the path as CONFIGURED --
+    relative to the ledger, never resolved here: an absolute machine path in the contract is
+    a frozen state nobody else can render (the golden frames are files in a repo)."""
+    out = []
+    for r in ((ledger.get("config", {}) or {}).get("repos") or []):
+        if isinstance(r, dict) and r.get("name"):
+            out.append({"name": _top_clean(r["name"]), "path": _top_clean(r.get("path", "."))})
+    return out
+
+
+def _top_spec_diff(ledger):
+    """The advisory spec↔code drift the ledger ALREADY carries, projected for `d` (ADR-037).
+
+    It measures NOTHING: `spec-drift` (ADR-005) is the only command that walks git for this,
+    and `top` is read-only by contract (ADR-032) -- so this reads `ledger["spec_drift"]`, the
+    latest-state record that command leaves behind, and nothing else. **No recorded run ->
+    `null`**, which the TUI renders as "no spec-drift run recorded", never as "no drift":
+    "nobody measured" and "nothing is stale" are different statements and only one of them is
+    ever free (INV-TOP-05).
+
+    Only `SPEC_STALE` rows travel: CLEAN/UNMAPPED/UNTRACKED/NO-CODE are the four ways a doc
+    is NOT drifting, and `docs_total` keeps the denominator visible beside the count so the
+    pane can say `3 of 21`. `code_ref` is ONE of the governed files that outran the doc --
+    the record stores a capped, alphabetically sorted list and no per-file dates, so it is
+    "a newer file", never "the newest one" (under-claim; `newer_files_total` carries the
+    real cardinality)."""
+    rec = ledger.get("spec_drift")
+    if not isinstance(rec, dict):
+        return None
+    results = rec.get("results")
+    results = results if isinstance(results, list) else []
+    docs = [r for r in results if isinstance(r, dict)]
+    stale = []
+    for r in docs:
+        if r.get("verdict") != "SPEC_STALE":
+            continue
+        # `newer_files` is a LIST in the record `spec-drift` writes, but the ledger is JSON on
+        # disk: a hand edit can leave a string there, and a string is iterable -- the old
+        # comprehension would have walked its characters and named `"n"` as the governed file
+        # that outran the doc. A non-list is no evidence, so it yields no code_ref and 0.
+        nf = r.get("newer_files")
+        newer = [f for f in nf if isinstance(f, str)] if isinstance(nf, list) else []
+        lag = r.get("lag_days_actual")
+        total = r.get("newer_files_total")
+        stale.append({
+            "doc": _top_clean(r.get("file") or "?"),
+            "lag_days": lag if isinstance(lag, (int, float)) else None,
+            "code_ref": _top_clean(newer[0]) if newer else None,
+            "newer_files_total": total if isinstance(total, int) else len(newer),
+            "spec_committed_at": (_top_clean(r["spec_committed_at"])
+                                  if r.get("spec_committed_at") else None),
+            "newest_governed_at": (_top_clean(r["newest_governed_at"])
+                                   if r.get("newest_governed_at") else None)})
+    # worst lag first, the doc name as the tie-break: deterministic given the record, which
+    # is what lets a golden frame be the oracle for this pane too (ADR-034).
+    stale.sort(key=lambda s: (-(s["lag_days"] or 0), s["doc"]))
+    lag_days = rec.get("max_lag_days")
+    return {"measured_at": _top_clean(rec["at"]) if rec.get("at") else None,
+            "repo": _top_clean(rec["repo"]) if rec.get("repo") else None,
+            "max_lag_days": lag_days if isinstance(lag_days, int) else None,
+            "docs_total": len(docs),
+            "stale": stale,
+            "advisory": True,               # ADR-005: this never gates, here or anywhere
+            "source": "spec-drift"}
+
+
 def cmd_top(args):
     """`uscha top` — the WHOLE projection of the ledger as one read-only JSON (ADR-032).
 
@@ -8699,6 +8771,11 @@ def cmd_top(args):
         "medians": {"verdict_min": None, "loop_min": _top_loop_median_min(ledger)},
         "checks": _top_checks(ledger),
         "drift_pct": None,                # spec_drift is per-file; an aggregate is ADR-035/3
+        # phase 2 (ADR-037): the repos in configuration order -- the source for the ONE repo
+        # `o` reruns in and `d` names -- and the advisory drift ALREADY recorded by
+        # `spec-drift`. Both are reads of what the ledger holds; `top` still runs nothing.
+        "repos": _top_repos(ledger),
+        "spec_diff": _top_spec_diff(ledger),
         # the ONLY real series is the readiness SCORE history; an obligation-count burn-up
         # needs new persistence (ADR-035/2), so `kind` is emitted for the TUI to label it a
         # score trend and never as a count of closed obligations.

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).
@@ -151,6 +180,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.
@@ -294,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)
 
 
@@ -386,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
@@ -552,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)  #
 # --------------------------------------------------------------------------- #
@@ -795,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).
 
@@ -808,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
@@ -821,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"):
@@ -840,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
@@ -904,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
@@ -947,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
@@ -997,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.90.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.90.0",
+  "version": "1.91.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.91.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 - 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 (52 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.91.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/qa_ledger.py

@@ -8567,6 +8567,78 @@ def _top_events(ledger, limit=TOP_EVENTS_TAIL):
     return events[:max(0, int(limit))]
 
 
+def _top_repos(ledger):
+    """The configured repos, name and configured path, in configuration order (phase 2).
+
+    Two things the TUI must not decide for itself now have a source: WHICH repo a rerun runs
+    in and ingests for (ADR-037 picks the first configured one, exactly as `_top_spec_pin`
+    picks the sha it labels), and WHICH repo the `d` pane names when it tells the reader how
+    to produce the spec-drift run that is missing. `path` is the path as CONFIGURED --
+    relative to the ledger, never resolved here: an absolute machine path in the contract is
+    a frozen state nobody else can render (the golden frames are files in a repo)."""
+    out = []
+    for r in ((ledger.get("config", {}) or {}).get("repos") or []):
+        if isinstance(r, dict) and r.get("name"):
+            out.append({"name": _top_clean(r["name"]), "path": _top_clean(r.get("path", "."))})
+    return out
+
+
+def _top_spec_diff(ledger):
+    """The advisory spec↔code drift the ledger ALREADY carries, projected for `d` (ADR-037).
+
+    It measures NOTHING: `spec-drift` (ADR-005) is the only command that walks git for this,
+    and `top` is read-only by contract (ADR-032) -- so this reads `ledger["spec_drift"]`, the
+    latest-state record that command leaves behind, and nothing else. **No recorded run ->
+    `null`**, which the TUI renders as "no spec-drift run recorded", never as "no drift":
+    "nobody measured" and "nothing is stale" are different statements and only one of them is
+    ever free (INV-TOP-05).
+
+    Only `SPEC_STALE` rows travel: CLEAN/UNMAPPED/UNTRACKED/NO-CODE are the four ways a doc
+    is NOT drifting, and `docs_total` keeps the denominator visible beside the count so the
+    pane can say `3 of 21`. `code_ref` is ONE of the governed files that outran the doc --
+    the record stores a capped, alphabetically sorted list and no per-file dates, so it is
+    "a newer file", never "the newest one" (under-claim; `newer_files_total` carries the
+    real cardinality)."""
+    rec = ledger.get("spec_drift")
+    if not isinstance(rec, dict):
+        return None
+    results = rec.get("results")
+    results = results if isinstance(results, list) else []
+    docs = [r for r in results if isinstance(r, dict)]
+    stale = []
+    for r in docs:
+        if r.get("verdict") != "SPEC_STALE":
+            continue
+        # `newer_files` is a LIST in the record `spec-drift` writes, but the ledger is JSON on
+        # disk: a hand edit can leave a string there, and a string is iterable -- the old
+        # comprehension would have walked its characters and named `"n"` as the governed file
+        # that outran the doc. A non-list is no evidence, so it yields no code_ref and 0.
+        nf = r.get("newer_files")
+        newer = [f for f in nf if isinstance(f, str)] if isinstance(nf, list) else []
+        lag = r.get("lag_days_actual")
+        total = r.get("newer_files_total")
+        stale.append({
+            "doc": _top_clean(r.get("file") or "?"),
+            "lag_days": lag if isinstance(lag, (int, float)) else None,
+            "code_ref": _top_clean(newer[0]) if newer else None,
+            "newer_files_total": total if isinstance(total, int) else len(newer),
+            "spec_committed_at": (_top_clean(r["spec_committed_at"])
+                                  if r.get("spec_committed_at") else None),
+            "newest_governed_at": (_top_clean(r["newest_governed_at"])
+                                   if r.get("newest_governed_at") else None)})
+    # worst lag first, the doc name as the tie-break: deterministic given the record, which
+    # is what lets a golden frame be the oracle for this pane too (ADR-034).
+    stale.sort(key=lambda s: (-(s["lag_days"] or 0), s["doc"]))
+    lag_days = rec.get("max_lag_days")
+    return {"measured_at": _top_clean(rec["at"]) if rec.get("at") else None,
+            "repo": _top_clean(rec["repo"]) if rec.get("repo") else None,
+            "max_lag_days": lag_days if isinstance(lag_days, int) else None,
+            "docs_total": len(docs),
+            "stale": stale,
+            "advisory": True,               # ADR-005: this never gates, here or anywhere
+            "source": "spec-drift"}
+
+
 def cmd_top(args):
     """`uscha top` — the WHOLE projection of the ledger as one read-only JSON (ADR-032).
 
@@ -8699,6 +8771,11 @@ def cmd_top(args):
         "medians": {"verdict_min": None, "loop_min": _top_loop_median_min(ledger)},
         "checks": _top_checks(ledger),
         "drift_pct": None,                # spec_drift is per-file; an aggregate is ADR-035/3
+        # phase 2 (ADR-037): the repos in configuration order -- the source for the ONE repo
+        # `o` reruns in and `d` names -- and the advisory drift ALREADY recorded by
+        # `spec-drift`. Both are reads of what the ledger holds; `top` still runs nothing.
+        "repos": _top_repos(ledger),
+        "spec_diff": _top_spec_diff(ledger),
         # the ONLY real series is the readiness SCORE history; an obligation-count burn-up
         # needs new persistence (ADR-035/2), so `kind` is emitted for the TUI to label it a
         # score trend and never as a count of closed obligations.

package/uscha-kit/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).
@@ -151,6 +180,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.
@@ -294,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)
 
 
@@ -386,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
@@ -552,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)  #
 # --------------------------------------------------------------------------- #
@@ -795,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).
 
@@ -808,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
@@ -821,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"):
@@ -840,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
@@ -904,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
@@ -947,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
@@ -997,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/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.90.0",
+  "version": "1.91.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,