@andresmassello/uscha 1.87.0 → 1.89.0

package/README.md

@@ -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.87.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.89.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,7 +85,7 @@ automatic tool can perform: a human verdict.
    from the compiled code: 0.062 measured (12 archetypes) — names, not yet semantics
 ```
 
-**What each arrow is, in the engine (kit 1.87.0, 52 subcommands, all measured):**
+**What each arrow is, in the engine (kit 1.89.0, 52 subcommands, all measured):**
 
 | Leg | Subcommands | What it establishes |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.87.0",
+  "version": "1.89.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

@@ -8232,6 +8232,215 @@ def _top_ac_key(cid):
         return (2, str(cid), 0)
 
 
+TOP_EVENTS_TAIL = 8          # how many steps the feed carries; the TUI shows what fits
+TOP_EVENT_WIDTH = 72         # one feed line, short enough to survive the 80-column floor
+TOP_OBS_TITLE_WIDTH = 72     # the verdict queue's one-line label; the CLAIM is never capped
+
+# kind -> level, the FIXED map ADR-032 (amended 1.88.0, M2) requires. `level` and `text` do
+# not exist in `ledger["steps"]`; they are derived here, once, so the TUI renders a feed it
+# did not author (ADR-034). A kind absent from this map reads `info`: an unclassified step
+# is never a green one. Four kinds get their level REFINED below from the record the step
+# announces (the iteration/escalation with the same `n`, the k-th clean-room record of the
+# repo) -- and when that correlation misses, the level stays at its neutral value instead of
+# guessing a verdict.
+TOP_EVENT_LEVELS = {
+    "snapshot": "info",                      # -> fail when the snapshot recorded red tests
+    "qa-step": "info",                       # -> pass when nothing was reported, or all fixed
+    "static-gate": "info",                   # -> pass/fail by the gated finding count
+    "cleanroom": "info",                     # -> pass/fail by the record's `ok`
+    "fastpath-eval": "info",
+    "gate-not-run": "unmeasured",            # a gate nobody ran is UNMEASURED, not a pass
+    "escalation": "human",
+    "escalation-resolved": "human",
+    "production-finding": "human",
+    "production-finding:resolve": "human",
+    "spec-doubt": "human",
+    "spec-doubt:resolve": "human",
+    "spec-change-request": "human",
+    "spec-change-request:resolve": "human",
+}
+
+
+def _top_ts(iso):
+    """HH:MM:SS in UTC, or None. A stamp carrying an offset is normalized to UTC (machine-
+    independent); it is never converted to the LOCAL zone, which would make the same ledger
+    read differently on two boxes and break the golden frames."""
+    dt = _top_dt(iso)
+    if dt is None:
+        return None
+    if dt.tzinfo is not None:
+        dt = dt.astimezone(timezone.utc)
+    return dt.strftime("%H:%M:%S")
+
+
+def _top_key(value):
+    """A dict key that cannot raise. The writers always put a scalar in `n`, `at` and `repo`,
+    but the ledger is JSON on disk and a hand edit can leave a list or a dict there --
+    `unhashable type` is not how a read-only readout gets to report that."""
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return repr(value)
+
+
+def _top_clean(text):
+    """One state-supplied string with every control character gone and its whitespace
+    collapsed. The contract's free text is ledger prose (an escalation reason, an
+    observation statement, a tool name) -- human and CLI input -- so an ESC or a C0 byte
+    inside one would be a control sequence the board obeys instead of prints. It dies HERE,
+    in the engine, and the renderer drops it again on the way out: two cheap guards over one
+    attack surface. What is filtered is exactly C0 and DEL (ADR-032)."""
+    txt = "".join(" " if c in ("\t", "\n", "\r") else c for c in str(text))
+    txt = "".join(c for c in txt if ord(c) >= 32 and ord(c) != 127)
+    return " ".join(txt.split())
+
+
+def _top_cap(text, width):
+    """A capped string that SAYS it was cut. Never used on a claim the human has to judge --
+    only on labels (a feed line, an observation title), whose full text the contract carries
+    somewhere else (M3: `candidate[]` holds the whole claim, `title` only its head)."""
+    return text if len(text) <= width else text[:width - 1] + "…"
+
+
+def _top_event_text(*parts):
+    """One feed line: free text of the contract that reaches a terminal, sanitized and
+    capped to survive the 80-column floor."""
+    return _top_cap(_top_clean(" · ".join(str(p) for p in parts
+                                          if p not in (None, "", "?"))), TOP_EVENT_WIDTH)
+
+
+def _top_obs_view(o, repo):
+    """ONE uncurated observation as the verdicts queue reads it (ADR-032, amended 1.89.0 for
+    M3). The delta record is the only source: `type`, `statement`, `provenance.files`,
+    `evidence_class` -- nothing here is inferred, and a member the delta does not carry comes
+    out empty rather than guessed.
+
+    - `repo` is the delta's OWN repo, and it is in the contract because the write path needs
+      it: `curate` takes `--repo`, so a queue without it would force the TUI to pick one --
+      the one derivation the TUI is never allowed to make (ADR-033).
+    - `title` is the statement's HEAD, capped and marked with an ellipsis when cut. It is a
+      label for the list line only. The claim the human judges is in `candidate[]` in full:
+      a verdict recorded on half a sentence is the failure this split exists to prevent.
+    - a delta is JSON on disk, so `provenance` can arrive as a list from a hand edit -- the
+      read-only readout degrades that observation to no evidence line, it does not raise."""
+    prov = o.get("provenance") if isinstance(o.get("provenance"), dict) else {}
+    raw = prov.get("files") if isinstance(prov.get("files"), list) else []
+    files = [f for f in (_top_clean(x) for x in raw) if f]
+    statement = _top_clean(o.get("statement"))
+    otype = _top_clean(o.get("type"))
+    site = files[0] if files else ""
+    candidate = ["type: %s%s" % (otype or "?", (" · site: %s" % site) if site else "")]
+    if statement:
+        candidate.append("claim: " + statement)          # WHOLE, never capped
+    evidence = list(files)
+    cls, tool = _top_clean(o.get("evidence_class")), _top_clean(prov.get("tool"))
+    if cls or tool:
+        evidence.append("evidence_class: %s%s" % (cls or "?",
+                                                  (" · tool: %s" % tool) if tool else ""))
+    return {"id": o.get("id"), "ac": o.get("canonical_match"), "repo": repo,
+            "title": _top_cap(statement, TOP_OBS_TITLE_WIDTH) if statement else None,
+            "candidate": candidate, "evidence": evidence,
+            # no per-observation first-seen timestamp exists (ADR-032/035): the queue is
+            # ordered by the criterion it anchors, not by an age nobody recorded.
+            "age_hours": None}
+
+
+def _top_events(ledger, limit=TOP_EVENTS_TAIL):
+    """events_tail[]: the last `limit` steps as {ts, level, text}, NEWEST FIRST.
+
+    Deterministic given the ledger and read-only, like the rest of `cmd_top`. The step
+    records carry `n, at, kind, repo` plus a few per-kind fields; everything else the feed
+    shows comes from the record that step announces, correlated the way the ledger really
+    supports it: by `n` for iterations, escalations and fast-path entries (the writer copies
+    the counter into both), in ORDER for clean-room records (step and record are appended in
+    the same call), and by `(repo, at)` for snapshots. A miss degrades that one line to
+    `info` -- under-claiming a verdict, never inventing one."""
+    nodes = dict(ledger.get("repos") or {})
+    nodes["integration"] = ledger.get("integration") or {}
+    iters, snaps = {}, {}
+    for rname, node in nodes.items():
+        for it in (node or {}).get("iterations") or []:
+            if isinstance(it, dict) and it.get("n") is not None:
+                iters[(rname, _top_key(it.get("n")))] = it
+        for sn in (node or {}).get("snapshots") or []:
+            if isinstance(sn, dict):
+                snaps.setdefault((rname, _top_key(sn.get("at"))), sn)
+    esc = {_top_key(e.get("n")): e for e in ledger.get("escalations") or []
+           if isinstance(e, dict) and e.get("n") is not None}
+    fastp = {_top_key(e.get("n")): e for e in ledger.get("fast_path") or []
+             if isinstance(e, dict) and e.get("n") is not None}
+    crs = {}
+    for rec in ledger.get(CLEAN_ROOM_KEY) or []:
+        if isinstance(rec, dict):
+            crs.setdefault(str(rec.get("repo") or ""), []).append(rec)
+    cr_seen = {}
+
+    events = []
+    for st in ledger.get("steps") or []:
+        if not isinstance(st, dict):
+            continue
+        kind = str(st.get("kind") or "")
+        level = TOP_EVENT_LEVELS.get(kind, "info")
+        try:
+            repo = str(st.get("repo") or "")
+            n = _top_key(st.get("n"))
+            head, tail = kind or "step", None
+
+            if kind == "snapshot":
+                head = "snapshot " + repo if repo else "snapshot"
+                tail = "phase %s" % st.get("phase") if st.get("phase") else None
+                tests = (snaps.get((repo, _top_key(st.get("at")))) or {}).get("tests") or {}
+                red = (tests.get("failures") or 0) + (tests.get("errors") or 0)
+                if tests.get("report_found") and red:
+                    level, tail = "fail", "%d red test(s)" % red
+            elif kind in ("qa-step", "static-gate", "gate-not-run"):
+                head = "%s %s" % (kind, "/".join(str(p) for p in (repo, st.get("tool")) if p))
+                it = iters.get((repo, n)) or {}
+                rep, fixed = it.get("reported"), it.get("fixed")
+                gated = it.get("gated_reported")
+                if kind == "gate-not-run":
+                    tail = "not run — nobody measured it"
+                elif kind == "static-gate" and isinstance(gated, int):
+                    level = "fail" if gated >= 1 else "pass"
+                    tail = "%d gated finding(s)" % gated if gated else "clean"
+                elif kind == "qa-step" and isinstance(rep, int):
+                    if rep == 0 or (isinstance(fixed, int) and fixed >= rep):
+                        level = "pass"
+                    tail = "%d reported, %s fixed" % (rep,
+                                                      fixed if fixed is not None else "?")
+            elif kind == "cleanroom":
+                head = "cleanroom " + repo if repo else "cleanroom"
+                queue = crs.get(repo) or []
+                idx = cr_seen.get(repo, 0)
+                cr_seen[repo] = idx + 1
+                rec = queue[idx] if idx < len(queue) else {}
+                if rec.get("status") and rec.get("ok") is not None:
+                    level = "pass" if rec.get("ok") else "fail"
+                    tail = str(rec.get("status"))
+            elif kind == "fastpath-eval":
+                head = "fastpath-eval " + repo if repo else "fastpath-eval"
+                tail = (fastp.get(n) or {}).get("verdict")
+            elif kind in ("escalation", "escalation-resolved"):
+                head = "%s %s" % (kind, repo) if repo else kind
+                # `escalation-resolved` gets a FRESH counter of its own, so there is no
+                # record to look up: it says what happened and nothing more.
+                tail = (esc.get(n) or {}).get("reason") if kind == "escalation" else None
+            else:
+                head = "%s %s" % (kind, repo) if repo else (kind or "step")
+                tail = st.get("id")
+            text = _top_event_text(head, tail)
+        except Exception:
+            # a ledger is JSON on disk: any field can arrive as a list, a dict or a number
+            # from a hand edit. ONE unreadable step degrades to a neutral line naming its
+            # kind -- the readout never raises and never loses the JSON the board needs
+            # (the same fail-soft rule _top_dt already applies to timestamps).
+            level, text = "info", _top_event_text(kind or "step")
+
+        events.append({"ts": _top_ts(st.get("at")), "level": level, "text": text})
+
+    events.reverse()                          # newest first, as the board reads top-down
+    return events[:max(0, int(limit))]
+
+
 def cmd_top(args):
     """`uscha top` — the WHOLE projection of the ledger as one read-only JSON (ADR-032).
 
@@ -8282,15 +8491,15 @@ def cmd_top(args):
             cid = o.get("canonical_match")
             if cid and cid not in quarantine:
                 quarantine[cid] = o["id"]
-            observations.append({
-                "id": o.get("id"), "ac": cid,
-                # no separate short label exists on an observation; `statement` is the only
-                # prose field, so `title` is null and the TUI may head-truncate candidate[0]
-                "title": None,
-                "candidate": [o.get("statement")],
-                "evidence": list((o.get("provenance") or {}).get("files") or []),
-                "age_hours": None})
-    observations.sort(key=lambda o: o.get("id") or "")
+            observations.append(_top_obs_view(o, rname))
+    # the queue's order: the criterion each observation anchors first (by the same key the
+    # board orders obligations with), the unanchored ones after, and the content-addressed
+    # id as the tie-break. Deterministic given the delta -- which is what lets a golden frame
+    # be the oracle for the verdicts pane. AGE-descending, which the SPEC drafted, is not
+    # derivable: every age_hours is null (no first-seen timestamp), and ordering by a value
+    # that does not exist would be the fabrication INV-TOP-05 forbids.
+    observations.sort(key=lambda o: ((_top_ac_key(o["ac"]) if o.get("ac") else (3, "", 0)),
+                                     o.get("id") or ""))
 
     # obligations: one row per DISTINCT tagged criterion of the acceptance file. kind is
     # "AC" for all of them -- there is no per-INV ledger in the general path (the mirador's
@@ -8348,7 +8557,9 @@ def cmd_top(args):
         "generated_at": _now(),
         "obligations": obligations,
         "observations": observations,
-        "events_tail": [],                # the live feed is M2; the key ships empty, not absent
+        # the live feed (M2): the last steps, newest first, with `level`/`text` derived by the
+        # fixed per-kind map above -- in the engine, so the TUI authors no verdict of its own.
+        "events_tail": _top_events(ledger),
         "counts": {"measured_pass": done, "measured_fail": fail, "quarantine": quar,
                    "unmeasured": _n("UNMEASURED"), "traced": 0, "tagged": 0, "total": total},
         "terminado": {"done": done, "total": total, "pct": pct, "unmeasured": unmeasured},