@andresmassello/uscha 1.91.0 → 1.92.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.91.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.92.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.828 measured (12 archetypes) — names AND behaviour
 ```
 
-**What each arrow is, in the engine (kit 1.91.0, 52 subcommands, all measured):**
+**What each arrow is, in the engine (kit 1.92.0, 53 subcommands, all measured):**
 
 | Leg | Subcommands | What it establishes |
 |---|---|---|
@@ -145,7 +145,7 @@ and see which file, which test, and when.
 | `/uscha-mirador` | Bird's-eye HTML dashboard: readiness, trail, acceptance, loops |
 | `/uscha-status` | One-line progress readout, in chat |
 
-**A measurement engine** (`qa_ledger.py`, 52 subcommands, Python stdlib) that ingests
+**A measurement engine** (`qa_ledger.py`, 53 subcommands, Python stdlib) that ingests
 evidence from **11 language stacks** — maven, gradle, ant, python, node, go, rust, dotnet,
 cpp, swift, flutter — and computes a readiness score with hard caps and visible provenance.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.91.0",
+  "version": "1.92.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/SKILL.md

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

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

@@ -704,7 +704,14 @@ def _source_newest_mtime(repo_path):
 def _test_evidence_provenance(repo_path, repo_type):
     """Explain which JUnit reports back a snapshot and whether they are newer
     than relevant source/test files. No discoverable source is explicitly
-    uncorrelated-but-usable to preserve synthetic/report-only workflows."""
+    uncorrelated-but-usable to preserve synthetic/report-only workflows.
+
+    Since 1.92.0 (ADR-038) each report also carries its CONTENT hash. Path and mtime
+    answer "which file, and was it written after the source"; they cannot answer "is
+    this still the file that was ingested" -- a log swapped or edited after the run
+    keeps its name and can keep its date. The hash is taken over the same files this
+    function already selects and the parser already reads: no new file is opened, and
+    `None` (unreadable) is recorded as absence, never as a match."""
     files = _junit_files_for(repo_path, repo_type)
     reports = []
     for path in files:
@@ -717,6 +724,7 @@ def _test_evidence_provenance(repo_path, repo_type):
             "mtime_ns": mtime_ns,
             "mtime": datetime.fromtimestamp(
                 mtime_ns / 1_000_000_000, timezone.utc).isoformat(),
+            "sha256": _sha256_file(path),
         })
     if not reports:
         status = "not-applicable" if repo_type == "flutter" else "missing"
@@ -8639,6 +8647,205 @@ def _top_spec_diff(ledger):
             "source": "spec-drift"}
 
 
+SEAL_NO_GIT = "no git work tree — seal UNMEASURED"
+SEAL_NO_COMMIT = "git repo without commits — seal UNMEASURED"
+
+
+def _seal_git(repo_path, *argv):
+    """One git read for the seal, or None. Same OSError posture as `_evidence_origin`:
+    git absent, or a repo path that does not exist, is an ordinary state of the world and
+    must degrade to UNMEASURED, never take down the command it only annotates."""
+    try:
+        r = subprocess.run(["git"] + list(argv), cwd=repo_path, capture_output=True,
+                           text=True, encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    return r if r.returncode == 0 else None
+
+
+def _seal_rel(work_tree, path):
+    """`path` as git names it: relative to the work tree root, forward slashes, or None
+    when it falls outside the tree.
+
+    BOTH sides go through `realpath` first. On Windows one API answers with an 8.3 short
+    name (`RUNNER~1`) and another with the long one, and `relpath` between the two yields
+    `..\\..` for a file plainly inside the tree — the CI-only failure paid for on
+    2026-08-02. A None here can only WITHHOLD an exemption, so the seal fails closed."""
+    try:
+        rel = os.path.relpath(os.path.realpath(path), os.path.realpath(work_tree))
+    except (OSError, ValueError):
+        return None
+    rel = rel.replace("\\", "/")
+    return None if rel == ".." or rel.startswith("../") else rel
+
+
+def _porcelain_paths(text):
+    """Every path named by `git status --porcelain -uall`, rename destinations included.
+
+    A path with special characters comes back C-quoted; the quotes are stripped and any
+    escape inside is left as-is. That can only fail to MATCH an exemption, which leaves the
+    seal broken — the safe direction: an unrecognized change is dirt, never a pass."""
+    out = []
+    for line in (text or "").splitlines():
+        if len(line) < 4:
+            continue
+        for part in line[3:].split(" -> "):
+            part = part.strip()
+            if len(part) >= 2 and part[0] == '"' and part[-1] == '"':
+                part = part[1:-1]
+            if part:
+                out.append(part.replace("\\", "/"))
+    return out
+
+
+def _sealed_state(ledger, ledger_path):
+    """INV-T1 (ADR-038): is the recorded evidence bound to the code state on disk RIGHT NOW?
+
+    Derived at read time, never written: nothing here creates a file, and re-deriving it is
+    the only way it can be trusted — a stored verdict is a claim about a tree that has moved
+    on since. Three questions, all answerable from what the ledger already carries:
+
+      1. is the TRACKED REPO'S SUBTREE clean -- `git status ... -- .` inside the configured
+         repo path, the same per-path scoping `_evidence_origin` uses (ADR-007), so a
+         monorepo sibling's edit is not this repo's dirt -- ignoring the ledger itself and
+         the report files the last snapshot names (those two are the seal's own footprint,
+         exactly as the reference `sh` package exempts `EVIDENCIA.md` and the logs it hashes);
+      2. is `HEAD` the commit that snapshot was taken at (`origin.commit`, ADR-007);
+      3. does every report the snapshot names still exist and still hash to what was
+         recorded at ingest (`sha256`, added in 1.92.0).
+
+    Three verdicts, never two: `True` sealed, `False` a MEASURED break (the reasons say
+    which), `None` UNMEASURED — no git work tree, or a snapshot old enough to predate the
+    content hash. A measured break outranks an unmeasured check (fail-closed); an unmeasured
+    check never reads as a pass (INV-TOP-05). The repo is the FIRST configured one, the same
+    choice `_top_spec_pin` and `_top_repos` make, and it is named in the `repo` member so
+    every reason below is read against it.
+
+    The block carries NO timestamp of its own. It is recomputed on every read, so a
+    "checked at" would be a second wall clock inside a payload whose only other one is
+    `generated_at` -- and two consecutive `top --json` runs must differ in nothing else
+    (AC-T-24 measures exactly that, and caught this before it shipped)."""
+    out = {"ok": None, "reasons": [], "commit": None, "repo": None}
+    repos = (ledger.get("config", {}) or {}).get("repos") or []
+    if not repos:
+        out["reasons"].append("no repo configured — seal UNMEASURED")
+        return out
+    name = repos[0].get("name")
+    path = repos[0].get("path", ".")
+    out["repo"] = _top_clean(name) if name else None
+
+    top = _seal_git(path, "rev-parse", "--show-toplevel")
+    if top is None or not top.stdout.strip():
+        out["reasons"].append(SEAL_NO_GIT)
+        return out
+    head = _seal_git(path, "rev-parse", "HEAD")
+    if head is None or not head.stdout.strip():
+        # a git tree with no commit yet: `rev-parse HEAD` fails on an unborn branch. It is a
+        # DIFFERENT absence from "not a work tree" and the reason says so -- the verdict is
+        # the same UNMEASURED, but a reason that misnames the cause sends the reader to the
+        # wrong fix.
+        out["reasons"].append(SEAL_NO_COMMIT)
+        return out
+    head_sha = head.stdout.strip()
+    work_tree = top.stdout.strip()
+    out["commit"] = head_sha
+
+    snaps = ((ledger.get("repos") or {}).get(name) or {}).get("snapshots") or []
+    if not snaps:
+        # UNMEASURED, not broken. The reference `sh` package calls a missing EVIDENCIA.md a
+        # rejection, and that is right for a file whose only job is to be the seal -- but a
+        # snapshot is the INGEST record, and with none recorded there is nothing to compare
+        # the tree against: not "the evidence is stale", not "the evidence was altered",
+        # simply no anchor. Calling that a break would also make the seal non-deterministic
+        # for a board whose evidence is read live from reports (the `top` fixtures are
+        # exactly that), and INV-TOP-05 already fixes the posture: absence renders as
+        # absence. The teeth stay where they bite -- `check-terminado` exits 2, so a hook or
+        # a human gating on exit 0 still refuses. The LIMIT this leaves is stated out loud in
+        # SPEC §4: a board at 100% with no snapshot at all carries no seal marker.
+        out["reasons"].append("no snapshot recorded yet")
+        return out
+    snap = snaps[-1]
+
+    failures, unmeasured = [], []
+    snap_commit = (snap.get("origin") or {}).get("commit")
+    if not snap_commit:
+        unmeasured.append("snapshot recorded no commit — seal UNMEASURED")
+    elif snap_commit != head_sha:
+        failures.append("stale seal: snapshot at %s, HEAD is %s"
+                        % (snap_commit[:8], head_sha[:8]))
+
+    reports = [r for r in ((snap.get("tests") or {}).get("reports") or [])
+               if isinstance(r, dict) and r.get("path")]
+    exempt = set()
+    for candidate in [ledger_path] + [os.path.join(path, r["path"]) for r in reports]:
+        rel = _seal_rel(work_tree, candidate)
+        if rel:
+            exempt.add(rel)
+    # `core.quotepath=false`: without it git C-quotes any non-ASCII path, so a report named
+    # `junit-acción.xml` would appear in the reason as `junit-acción.xml` -- a reason
+    # nobody can act on, and an exemption that cannot match. Set on the command, never in the
+    # user's config: the engine reads git, it does not configure it.
+    st = _seal_git(path, "-c", "core.quotepath=false",
+                   "status", "--porcelain", "-uall", "--", ".")
+    if st is None:
+        unmeasured.append("repo subtree state unreadable — seal UNMEASURED")
+    else:
+        dirty = sorted(set(_porcelain_paths(st.stdout)) - exempt)
+        if dirty:
+            failures.append("repo subtree dirty: changes no snapshot covers (%s)" % dirty[0])
+
+    for r in reports:
+        rel, full = r["path"], os.path.join(path, r["path"])
+        if not os.path.isfile(full):
+            failures.append("evidence missing: %s" % rel)
+        elif not r.get("sha256"):
+            unmeasured.append("evidence hash unmeasured: %s — no hash recorded at ingest "
+                              "(older snapshot, or the file was unreadable)" % rel)
+        elif _sha256_file(full) != r["sha256"]:
+            failures.append("evidence altered after ingest: %s" % rel)
+
+    out["reasons"] = failures + unmeasured
+    out["ok"] = False if failures else (None if unmeasured else True)
+    return out
+
+
+def cmd_check_terminado(args):
+    """The enforcement side of INV-T1: the SAME `_sealed_state` derivation `top --json`
+    publishes, with an exit code a hook or a human can act on. It measures the tree and
+    prints; it writes nothing and it decides nothing else.
+
+    0 = sealed · 1 = a measured break · 2 = UNMEASURED (no git work tree, no configured
+    repo, a snapshot with no recorded hash -- or no readable ledger at all). 2 is the
+    reference script's error class: "I could not answer" is not "yes".
+
+    A missing or corrupt ledger is UNMEASURED, not a break: `_load` exits 1 by design, and 1
+    here means "I checked and the seal is broken". Reporting "not sealed" for a file the
+    command never managed to read would be a verdict on evidence nobody looked at -- the
+    exact failure this command exists to catch."""
+    try:
+        ledger = _load(args.ledger)
+    except SystemExit as exc:
+        message = exc.code if isinstance(exc.code, str) else None
+        print(message or "[qa_ledger] check-terminado: ledger '%s' unreadable" % args.ledger)
+        print("[qa_ledger] check-terminado: UNMEASURED — no readable ledger, no seal.")
+        sys.exit(2)
+    sealed = _sealed_state(ledger, args.ledger)
+    ok = sealed.get("ok")
+    if getattr(args, "json", False):
+        print(json.dumps(sealed, indent=2, ensure_ascii=False))
+    else:
+        verdict = "SEALED" if ok is True else ("UNSEALED" if ok is False else "UNMEASURED")
+        where = " at %s" % sealed["commit"][:8] if sealed.get("commit") else ""
+        print("[qa_ledger] check-terminado: %s%s (repo %s)"
+              % (verdict, where, sealed.get("repo") or "?"))
+        for reason in sealed.get("reasons") or []:
+            print("  - %s" % reason)
+        if ok is not True:
+            print("  TERMINADO is not enabled: re-run the evidence and `snapshot` "
+                  "on the current state.")
+    sys.exit(0 if ok is True else (1 if ok is False else 2))
+
+
 def cmd_top(args):
     """`uscha top` — the WHOLE projection of the ledger as one read-only JSON (ADR-032).
 
@@ -8744,6 +8951,15 @@ def cmd_top(args):
     done, fail, quar = _n("MEASURED_PASS"), _n("MEASURED_FAIL"), _n("QUARANTINE")
     unmeasured = _n("UNMEASURED") + _n("TRACED")
     pct = _top_pct(done, total)
+    # INV-TOP-06 (ADR-038): DONE never publishes 100% while the seal is MEASURED broken --
+    # every criterion green against evidence that no longer belongs to this code state is
+    # the same lie INV-TOP-01 forbids one row earlier. The cap lives HERE, beside the
+    # rounding cap, so no renderer is the place it happens. An UNMEASURED seal (`ok is
+    # None` -- no git) does NOT cap: absence of measurement is not evidence of a break, and
+    # capping on it would put an unearned 99 on every non-git tree.
+    sealed = _sealed_state(ledger, args.ledger)
+    if sealed.get("ok") is False and pct >= 100:
+        pct = 99
     measured = done + fail
     out = {
         "schema": TOP_SCHEMA,
@@ -8760,7 +8976,10 @@ def cmd_top(args):
         "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},
+        # `sealed` is DERIVED at read time from the ledger plus the tree (ADR-038); it is
+        # never stored, so it cannot go stale the way the claim it guards can.
+        "terminado": {"done": done, "total": total, "pct": pct, "unmeasured": unmeasured,
+                      "sealed": sealed},
         "debtors": {"machine": fail, "you": quar, "untagged": unmeasured},
         "honesty": {"measured": measured, "total": total,
                     "pct": _top_pct(measured, total)},
@@ -11952,6 +12171,14 @@ def build_parser():
     ptop.add_argument("--json", action="store_true")
     ptop.set_defaults(func=cmd_top)
 
+    pct = sub.add_parser("check-terminado",
+                         help="INV-T1 (ADR-038): is TERMINADO sealed to the code state on "
+                              "disk? Same derivation `top --json` publishes. Exit 0 sealed, "
+                              "1 broken, 2 UNMEASURED")
+    add_ledger(pct)
+    pct.add_argument("--json", action="store_true")
+    pct.set_defaults(func=cmd_check_terminado)
+
     pb = sub.add_parser("rebuild",
                         help="rebuild test: is the SPEC complete enough to "
                              "regenerate the system? (completeness, not correctness)")

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.92.0",
   "displayName": "Uscha",
-  "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 52 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
+  "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 53 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",
     "url": "https://github.com/andresmassello"

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

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

package/uscha-kit/README.md

@@ -1,6 +1,6 @@
 # uscha-kit
 
-**Kit version:** v1.91.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.92.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,
@@ -591,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.92.0

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

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

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

@@ -704,7 +704,14 @@ def _source_newest_mtime(repo_path):
 def _test_evidence_provenance(repo_path, repo_type):
     """Explain which JUnit reports back a snapshot and whether they are newer
     than relevant source/test files. No discoverable source is explicitly
-    uncorrelated-but-usable to preserve synthetic/report-only workflows."""
+    uncorrelated-but-usable to preserve synthetic/report-only workflows.
+
+    Since 1.92.0 (ADR-038) each report also carries its CONTENT hash. Path and mtime
+    answer "which file, and was it written after the source"; they cannot answer "is
+    this still the file that was ingested" -- a log swapped or edited after the run
+    keeps its name and can keep its date. The hash is taken over the same files this
+    function already selects and the parser already reads: no new file is opened, and
+    `None` (unreadable) is recorded as absence, never as a match."""
     files = _junit_files_for(repo_path, repo_type)
     reports = []
     for path in files:
@@ -717,6 +724,7 @@ def _test_evidence_provenance(repo_path, repo_type):
             "mtime_ns": mtime_ns,
             "mtime": datetime.fromtimestamp(
                 mtime_ns / 1_000_000_000, timezone.utc).isoformat(),
+            "sha256": _sha256_file(path),
         })
     if not reports:
         status = "not-applicable" if repo_type == "flutter" else "missing"
@@ -8639,6 +8647,205 @@ def _top_spec_diff(ledger):
             "source": "spec-drift"}
 
 
+SEAL_NO_GIT = "no git work tree — seal UNMEASURED"
+SEAL_NO_COMMIT = "git repo without commits — seal UNMEASURED"
+
+
+def _seal_git(repo_path, *argv):
+    """One git read for the seal, or None. Same OSError posture as `_evidence_origin`:
+    git absent, or a repo path that does not exist, is an ordinary state of the world and
+    must degrade to UNMEASURED, never take down the command it only annotates."""
+    try:
+        r = subprocess.run(["git"] + list(argv), cwd=repo_path, capture_output=True,
+                           text=True, encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    return r if r.returncode == 0 else None
+
+
+def _seal_rel(work_tree, path):
+    """`path` as git names it: relative to the work tree root, forward slashes, or None
+    when it falls outside the tree.
+
+    BOTH sides go through `realpath` first. On Windows one API answers with an 8.3 short
+    name (`RUNNER~1`) and another with the long one, and `relpath` between the two yields
+    `..\\..` for a file plainly inside the tree — the CI-only failure paid for on
+    2026-08-02. A None here can only WITHHOLD an exemption, so the seal fails closed."""
+    try:
+        rel = os.path.relpath(os.path.realpath(path), os.path.realpath(work_tree))
+    except (OSError, ValueError):
+        return None
+    rel = rel.replace("\\", "/")
+    return None if rel == ".." or rel.startswith("../") else rel
+
+
+def _porcelain_paths(text):
+    """Every path named by `git status --porcelain -uall`, rename destinations included.
+
+    A path with special characters comes back C-quoted; the quotes are stripped and any
+    escape inside is left as-is. That can only fail to MATCH an exemption, which leaves the
+    seal broken — the safe direction: an unrecognized change is dirt, never a pass."""
+    out = []
+    for line in (text or "").splitlines():
+        if len(line) < 4:
+            continue
+        for part in line[3:].split(" -> "):
+            part = part.strip()
+            if len(part) >= 2 and part[0] == '"' and part[-1] == '"':
+                part = part[1:-1]
+            if part:
+                out.append(part.replace("\\", "/"))
+    return out
+
+
+def _sealed_state(ledger, ledger_path):
+    """INV-T1 (ADR-038): is the recorded evidence bound to the code state on disk RIGHT NOW?
+
+    Derived at read time, never written: nothing here creates a file, and re-deriving it is
+    the only way it can be trusted — a stored verdict is a claim about a tree that has moved
+    on since. Three questions, all answerable from what the ledger already carries:
+
+      1. is the TRACKED REPO'S SUBTREE clean -- `git status ... -- .` inside the configured
+         repo path, the same per-path scoping `_evidence_origin` uses (ADR-007), so a
+         monorepo sibling's edit is not this repo's dirt -- ignoring the ledger itself and
+         the report files the last snapshot names (those two are the seal's own footprint,
+         exactly as the reference `sh` package exempts `EVIDENCIA.md` and the logs it hashes);
+      2. is `HEAD` the commit that snapshot was taken at (`origin.commit`, ADR-007);
+      3. does every report the snapshot names still exist and still hash to what was
+         recorded at ingest (`sha256`, added in 1.92.0).
+
+    Three verdicts, never two: `True` sealed, `False` a MEASURED break (the reasons say
+    which), `None` UNMEASURED — no git work tree, or a snapshot old enough to predate the
+    content hash. A measured break outranks an unmeasured check (fail-closed); an unmeasured
+    check never reads as a pass (INV-TOP-05). The repo is the FIRST configured one, the same
+    choice `_top_spec_pin` and `_top_repos` make, and it is named in the `repo` member so
+    every reason below is read against it.
+
+    The block carries NO timestamp of its own. It is recomputed on every read, so a
+    "checked at" would be a second wall clock inside a payload whose only other one is
+    `generated_at` -- and two consecutive `top --json` runs must differ in nothing else
+    (AC-T-24 measures exactly that, and caught this before it shipped)."""
+    out = {"ok": None, "reasons": [], "commit": None, "repo": None}
+    repos = (ledger.get("config", {}) or {}).get("repos") or []
+    if not repos:
+        out["reasons"].append("no repo configured — seal UNMEASURED")
+        return out
+    name = repos[0].get("name")
+    path = repos[0].get("path", ".")
+    out["repo"] = _top_clean(name) if name else None
+
+    top = _seal_git(path, "rev-parse", "--show-toplevel")
+    if top is None or not top.stdout.strip():
+        out["reasons"].append(SEAL_NO_GIT)
+        return out
+    head = _seal_git(path, "rev-parse", "HEAD")
+    if head is None or not head.stdout.strip():
+        # a git tree with no commit yet: `rev-parse HEAD` fails on an unborn branch. It is a
+        # DIFFERENT absence from "not a work tree" and the reason says so -- the verdict is
+        # the same UNMEASURED, but a reason that misnames the cause sends the reader to the
+        # wrong fix.
+        out["reasons"].append(SEAL_NO_COMMIT)
+        return out
+    head_sha = head.stdout.strip()
+    work_tree = top.stdout.strip()
+    out["commit"] = head_sha
+
+    snaps = ((ledger.get("repos") or {}).get(name) or {}).get("snapshots") or []
+    if not snaps:
+        # UNMEASURED, not broken. The reference `sh` package calls a missing EVIDENCIA.md a
+        # rejection, and that is right for a file whose only job is to be the seal -- but a
+        # snapshot is the INGEST record, and with none recorded there is nothing to compare
+        # the tree against: not "the evidence is stale", not "the evidence was altered",
+        # simply no anchor. Calling that a break would also make the seal non-deterministic
+        # for a board whose evidence is read live from reports (the `top` fixtures are
+        # exactly that), and INV-TOP-05 already fixes the posture: absence renders as
+        # absence. The teeth stay where they bite -- `check-terminado` exits 2, so a hook or
+        # a human gating on exit 0 still refuses. The LIMIT this leaves is stated out loud in
+        # SPEC §4: a board at 100% with no snapshot at all carries no seal marker.
+        out["reasons"].append("no snapshot recorded yet")
+        return out
+    snap = snaps[-1]
+
+    failures, unmeasured = [], []
+    snap_commit = (snap.get("origin") or {}).get("commit")
+    if not snap_commit:
+        unmeasured.append("snapshot recorded no commit — seal UNMEASURED")
+    elif snap_commit != head_sha:
+        failures.append("stale seal: snapshot at %s, HEAD is %s"
+                        % (snap_commit[:8], head_sha[:8]))
+
+    reports = [r for r in ((snap.get("tests") or {}).get("reports") or [])
+               if isinstance(r, dict) and r.get("path")]
+    exempt = set()
+    for candidate in [ledger_path] + [os.path.join(path, r["path"]) for r in reports]:
+        rel = _seal_rel(work_tree, candidate)
+        if rel:
+            exempt.add(rel)
+    # `core.quotepath=false`: without it git C-quotes any non-ASCII path, so a report named
+    # `junit-acción.xml` would appear in the reason as `junit-acción.xml` -- a reason
+    # nobody can act on, and an exemption that cannot match. Set on the command, never in the
+    # user's config: the engine reads git, it does not configure it.
+    st = _seal_git(path, "-c", "core.quotepath=false",
+                   "status", "--porcelain", "-uall", "--", ".")
+    if st is None:
+        unmeasured.append("repo subtree state unreadable — seal UNMEASURED")
+    else:
+        dirty = sorted(set(_porcelain_paths(st.stdout)) - exempt)
+        if dirty:
+            failures.append("repo subtree dirty: changes no snapshot covers (%s)" % dirty[0])
+
+    for r in reports:
+        rel, full = r["path"], os.path.join(path, r["path"])
+        if not os.path.isfile(full):
+            failures.append("evidence missing: %s" % rel)
+        elif not r.get("sha256"):
+            unmeasured.append("evidence hash unmeasured: %s — no hash recorded at ingest "
+                              "(older snapshot, or the file was unreadable)" % rel)
+        elif _sha256_file(full) != r["sha256"]:
+            failures.append("evidence altered after ingest: %s" % rel)
+
+    out["reasons"] = failures + unmeasured
+    out["ok"] = False if failures else (None if unmeasured else True)
+    return out
+
+
+def cmd_check_terminado(args):
+    """The enforcement side of INV-T1: the SAME `_sealed_state` derivation `top --json`
+    publishes, with an exit code a hook or a human can act on. It measures the tree and
+    prints; it writes nothing and it decides nothing else.
+
+    0 = sealed · 1 = a measured break · 2 = UNMEASURED (no git work tree, no configured
+    repo, a snapshot with no recorded hash -- or no readable ledger at all). 2 is the
+    reference script's error class: "I could not answer" is not "yes".
+
+    A missing or corrupt ledger is UNMEASURED, not a break: `_load` exits 1 by design, and 1
+    here means "I checked and the seal is broken". Reporting "not sealed" for a file the
+    command never managed to read would be a verdict on evidence nobody looked at -- the
+    exact failure this command exists to catch."""
+    try:
+        ledger = _load(args.ledger)
+    except SystemExit as exc:
+        message = exc.code if isinstance(exc.code, str) else None
+        print(message or "[qa_ledger] check-terminado: ledger '%s' unreadable" % args.ledger)
+        print("[qa_ledger] check-terminado: UNMEASURED — no readable ledger, no seal.")
+        sys.exit(2)
+    sealed = _sealed_state(ledger, args.ledger)
+    ok = sealed.get("ok")
+    if getattr(args, "json", False):
+        print(json.dumps(sealed, indent=2, ensure_ascii=False))
+    else:
+        verdict = "SEALED" if ok is True else ("UNSEALED" if ok is False else "UNMEASURED")
+        where = " at %s" % sealed["commit"][:8] if sealed.get("commit") else ""
+        print("[qa_ledger] check-terminado: %s%s (repo %s)"
+              % (verdict, where, sealed.get("repo") or "?"))
+        for reason in sealed.get("reasons") or []:
+            print("  - %s" % reason)
+        if ok is not True:
+            print("  TERMINADO is not enabled: re-run the evidence and `snapshot` "
+                  "on the current state.")
+    sys.exit(0 if ok is True else (1 if ok is False else 2))
+
+
 def cmd_top(args):
     """`uscha top` — the WHOLE projection of the ledger as one read-only JSON (ADR-032).
 
@@ -8744,6 +8951,15 @@ def cmd_top(args):
     done, fail, quar = _n("MEASURED_PASS"), _n("MEASURED_FAIL"), _n("QUARANTINE")
     unmeasured = _n("UNMEASURED") + _n("TRACED")
     pct = _top_pct(done, total)
+    # INV-TOP-06 (ADR-038): DONE never publishes 100% while the seal is MEASURED broken --
+    # every criterion green against evidence that no longer belongs to this code state is
+    # the same lie INV-TOP-01 forbids one row earlier. The cap lives HERE, beside the
+    # rounding cap, so no renderer is the place it happens. An UNMEASURED seal (`ok is
+    # None` -- no git) does NOT cap: absence of measurement is not evidence of a break, and
+    # capping on it would put an unearned 99 on every non-git tree.
+    sealed = _sealed_state(ledger, args.ledger)
+    if sealed.get("ok") is False and pct >= 100:
+        pct = 99
     measured = done + fail
     out = {
         "schema": TOP_SCHEMA,
@@ -8760,7 +8976,10 @@ def cmd_top(args):
         "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},
+        # `sealed` is DERIVED at read time from the ledger plus the tree (ADR-038); it is
+        # never stored, so it cannot go stale the way the claim it guards can.
+        "terminado": {"done": done, "total": total, "pct": pct, "unmeasured": unmeasured,
+                      "sealed": sealed},
         "debtors": {"machine": fail, "you": quar, "untagged": unmeasured},
         "honesty": {"measured": measured, "total": total,
                     "pct": _top_pct(measured, total)},
@@ -11952,6 +12171,14 @@ def build_parser():
     ptop.add_argument("--json", action="store_true")
     ptop.set_defaults(func=cmd_top)
 
+    pct = sub.add_parser("check-terminado",
+                         help="INV-T1 (ADR-038): is TERMINADO sealed to the code state on "
+                              "disk? Same derivation `top --json` publishes. Exit 0 sealed, "
+                              "1 broken, 2 UNMEASURED")
+    add_ledger(pct)
+    pct.add_argument("--json", action="store_true")
+    pct.set_defaults(func=cmd_check_terminado)
+
     pb = sub.add_parser("rebuild",
                         help="rebuild test: is the SPEC complete enough to "
                              "regenerate the system? (completeness, not correctness)")

package/uscha-kit/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/templates/esceptico-prompt.md

@@ -0,0 +1,65 @@
+# The Sceptic — claims audit before TERMINADO (optional, one call)
+
+> This is a PORTABLE prompt, like the rubric grader's: instructions for ANY runner —
+> Claude Code, Codex, Gemini CLI, Cursor, a `curl` to any API, or a human with the
+> diff open. Nothing about it is vendor-specific.
+>
+> **It writes nothing and it gates nothing.** There is no ingest command for its output,
+> no ledger field it fills and no exit code anyone checks: it produces a short markdown
+> table a human reads before deciding. Unlike `check-terminado` (ADR-038), which is a
+> mechanical recomputation over recorded evidence, this is a JUDGEMENT — and it is a
+> **hypothesis until it has been used against real runs**. Treat its verdict as an
+> opinion with citations, never as a measurement.
+
+You are uscha's closing Sceptic. Your only job is to audit **claims**, not code. You treat
+every claim of completeness as false until you have seen the evidence. You are not hunting
+for new bugs and you are not reviewing the design: you are auditing the bookkeeping of a
+delivery.
+
+## Inputs
+
+1. `CLAIMS`: the handoff, PR description, changelog, or whatever was declared about the
+   state of the work.
+2. The **evidence** the claims rest on: the ingested reports the ledger names (the paths in
+   the last snapshot's `tests.reports`), gate logs, test runs.
+3. `DIFF`: the diff of the delivery.
+
+## What to attack
+
+1. **Claims with no artifact**: every past-tense verb ("tested", "verified", "works on X")
+   requires a file among the evidence above that backs it.
+2. **Evidence that does not say what the claim says**: a log is attached, but skipped tests
+   are counted as passed, warnings are omitted, a partial run is presented as a full one.
+3. **Residue of incompleteness**: new TODO/FIXME/XXX in the diff, stubs, unticked
+   checkboxes, hardcoded values where the claim says "configurable".
+4. **Inflated scope**: "migrated all of X" — enumerate which parts of X the diff really
+   touches and which it does not.
+5. **Silences**: files in the diff no claim mentions; limits that were never declared.
+
+## Rules
+
+- Do not punish honesty: a declared limit ("not tested on macOS") is NOT a finding; the
+  finding is the limit that was NOT declared.
+- Every finding quotes the claim verbatim plus the absent or contradictory artifact (with
+  `file:line` where it applies). No exact citation, no finding.
+- If you find nothing: your output MUST list, claim by claim, the evidence that backs it
+  (claim -> artifact -> verified). "All OK" without that table is an invalid output.
+
+## Output (markdown, short)
+
+```
+## Claims audit — <date>
+
+| Claim (quoted) | Evidence | Status |
+|---|---|---|
+| "..." | reports/junit.xml | BACKED |
+| "..." | (none) | UNBACKED |
+
+### Blocking findings
+- <quoted claim>: <what is missing, or what contradicts it>
+
+### Verdict: BACKED / HAS GAPS
+```
+
+HAS GAPS = at least one central claim has no backing. The decision to proceed anyway
+belongs to the human, but it is now written down.

package/uscha-kit/uscha.config.json

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