@andresmassello/uscha 1.90.0 → 1.92.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.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,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.92.0, 53 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) |
@@ -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.90.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"
@@ -8567,6 +8575,277 @@ 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"}
+
+
+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).
 
@@ -8672,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,
@@ -8688,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)},
@@ -8699,6 +8990,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.
@@ -11875,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)")