@andresmassello/uscha 1.91.0 → 1.93.0

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

@@ -131,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                                                              #
@@ -216,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")
@@ -224,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
@@ -264,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):
@@ -382,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:

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.91.0",
+  "version": "1.93.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.91.0",
+  "version": "1.93.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.91.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.93.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,7 +591,7 @@ python3 $QL simplicity-check --diff changes.diff --json        # consumed by usc
 
 ## Ledger subcommands
 
-`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`.
+`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.91.0
+uscha-kit 1.93.0

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

@@ -459,6 +459,20 @@ 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, no source-relevant change since the last
+  snapshot's commit (a non-source difference — docs, the ledger, the reports themselves —
+  seals with a `note` naming what moved; ADR-039), 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.
@@ -544,6 +558,12 @@ up as `narrated_only` and does NOT close (measured beats narrated, per criterion
 A JUnit report older than the repo's source code is treated as STALE (the code changed
 after the tests ran) and is DISCARDED — a criterion backed only by stale reports stays
 UNMEASURED, never falsely closed or vetoed (kit 1.31.0; surfaced as `stale_reports`).
+Since 1.93.0 (ADR-039) that clock rule is not the only one: a report the clock rejects is still
+FRESH when its `sha256` matches what the last `snapshot` recorded for it AND git shows no
+source-relevant change since that snapshot's commit — so a clone, a `git worktree add`, a merge
+or a CI checkout, which re-date every file without changing a byte, no longer un-measure green
+evidence. Either rule suffices; with no git, no recorded commit or no recorded hash the clock
+rule decides alone, exactly as before.
 So: when you write the tests for a criterion, put its AC-n in the test name; run
 `spec-check --acceptance ACCEPTANCE.md` up front (zero traceable criteria / duplicate
 IDs block as structural FACTS). Files without IDs fall back to the checkbox ratio