@andresmassello/uscha 1.88.0 → 1.90.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.88.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.90.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)
 
@@ -82,10 +82,10 @@ automatic tool can perform: a human verdict.
                                               system (= 100% drift)
 
    round trip · bench-roundtrip — how much of the asset the reverse organs re-anchor
-   from the compiled code: 0.062 measured (12 archetypes) — names, not yet semantics
+   from the compiled code: 0.828 measured (12 archetypes) — names AND behaviour
 ```
 
-**What each arrow is, in the engine (kit 1.88.0, 52 subcommands, all measured):**
+**What each arrow is, in the engine (kit 1.90.0, 52 subcommands, all measured):**
 
 | Leg | Subcommands | What it establishes |
 |---|---|---|
@@ -94,13 +94,17 @@ automatic tool can perform: a human verdict.
 | 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) |
 | 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.062**, and the **noise floor** under every variance claim (ADR-014/022/027/030) |
+| 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) |
 
 **Read the numbers the way the repo does.** 9 of 12 archetypes regenerate to the same system
-under an oracle the compilers never saw — that is the closed loop working. 0.062 is the mean
+under an oracle the compilers never saw — that is the closed loop working. 0.828 is the mean
 *recoverability* of the asset from compiled code counting only static and behavioural
-footing, with the behaviour dimension still `UNMEASURED` — it says the reverse organs anchor
-**names, not yet semantics**, and it is published rather than smoothed. And `bench-r2` measured
+footing. It read **0.062** until 1.90.0, with the behaviour dimension `UNMEASURED`, because no
+oracle case carried an AC tag — a named absence, not a zero. The 12 bench oracles are now
+curated per case (`ORACLE-TAGS-CURATED.json`, human-authored; payloads and expectations
+untouched), so the dimension is measured and the number says the reverse organs anchor **names
+and behaviour**. Both numbers are published rather than smoothed, and what moved between them
+was the tagging, not the code under test. And `bench-r2` measured
 that same-model reruns differ structurally about as much as different models do (aggregate
 `NOISY`) — so one earlier variance narrative was **retracted**. Every claim above is a subcommand
 you can run; every unmeasured part is labeled. That honesty is the method applied to itself.

package/package.json

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

@@ -3423,6 +3423,15 @@ def cmd_golden_coverage(args):
 
         env = dict(os.environ)
         env["COVERAGE_PROCESS_START"] = rc
+        # COVERAGE_FILE is set EXPLICITLY, not merely inherited. coverage.py resolves its
+        # data_file with the environment variable AFTER the rc file, so an inherited
+        # COVERAGE_FILE (the shape the kit's own suite has under USCHA_COVERAGE=1) silently
+        # overrode the isolated data_file above and the capture landed in the caller's shared
+        # file -- the map then read as "covers nothing" and AC-GM-08 went red under coverage
+        # while passing plain. Writing it here pins the child to OUR file whether or not the
+        # caller has one; the parent's own Coverage(data_file=...) already wins over the
+        # environment because constructor arguments are applied last.
+        env["COVERAGE_FILE"] = data_file
         env["PYTHONPATH"] = tmp + os.pathsep + env.get("PYTHONPATH", "")
         env["PYTHONIOENCODING"] = "utf-8"
         r = subprocess.run([sys.executable, harness], cwd=root, env=env,
@@ -5468,6 +5477,47 @@ def _static_surface_for(cd, unit):
     return so, []
 
 
+def _judged_env():
+    """The environment a JUDGED program gets: this process's, minus the hooks that would make
+    a third party instrument it, plus the one setting that keeps it from leaving anything
+    behind in the tree it is judged from.
+
+    The withheld oracle measures a compiled implementation by its exit code and its stdout. A
+    measurement that changes what it measures is a broken measurement, and coverage.py's
+    documented subprocess hook does exactly that: with `COVERAGE_PROCESS_START` in the
+    environment, coverage.py's own `.pth` (`a1_coverage.pth`, shipped in site-packages) starts
+    a full Coverage in EVERY python process, at interpreter start-up, before any of that
+    process's own code runs. The oracle's children are fixture programs that sit outside every
+    `--source` root, so what they record is empty by construction -- pure cost, no measurement.
+
+    That cost is not theoretical (1.90.0). Running this repo's own smoke suite under
+    `USCHA_COVERAGE=1` spawned ~14,000 such children; `coverage combine` reported
+    "Combined 600 files, skipped 13702" -- 96% of them recorded nothing -- and late in the run
+    Windows began refusing to create processes: seven bench archetypes flipped to FAIL because
+    an oracle child could not start, and a py3.8 interpreter came back 3221225794
+    (0xC0000142, STATUS_DLL_INIT_FAILED) with an empty stderr. Nothing was wrong with the
+    engine or the fixtures; the instrument was crushing the machine it measured on.
+
+    Only the two variables that START coverage in a child are dropped. `COVERAGE_FILE` is
+    left alone: it names a data file, it does not turn anything on, and a caller that set it
+    means it.
+
+    `PYTHONDONTWRITEBYTECODE` is SET, and that one is not about coverage (1.90.0, ADR-030
+    amended). A multi-unit compilation imports its sibling module, so running it writes
+    `__pycache__/*.pyc` INTO the fixture directory -- and the round trip's own criterion is
+    that the instrument regenerates nothing under the bench tree (AC-RT-01 snapshots the file
+    list before and after). It only became reachable when the behaviour dimension started
+    running cases: measured on a clean tree, `bench-roundtrip` left three `.pyc` files behind.
+    In the suite the earlier `bench` block had already warmed the cache, so the red would have
+    waited for a fresh CI clone to appear -- an ordering dependency, which is the kind of
+    green worth nothing. Judging a program must not modify what is being judged."""
+    env = dict(os.environ)
+    for key in ("COVERAGE_PROCESS_START", "COVERAGE_PROCESS_CONFIG"):
+        env.pop(key, None)
+    env["PYTHONDONTWRITEBYTECODE"] = "1"
+    return env
+
+
 def _impl_interpreter(impl_path):
     """Resolve the interpreter argv prefix for one implementation file by extension (ADR-028):
     `.py` runs under this same Python (unchanged); `.js` runs under `node`, resolved from PATH.
@@ -5508,7 +5558,7 @@ def _run_oracle_case(impl_path, case):
         # sibling modules by bare name; single-unit impls are unaffected by their cwd
         r = subprocess.run(interp + [os.path.abspath(impl_path)], input=stdin,
                            capture_output=True, text=True, encoding="utf-8", errors="replace",
-                           timeout=_BOOTSTRAP_CASE_TIMEOUT,
+                           timeout=_BOOTSTRAP_CASE_TIMEOUT, env=_judged_env(),
                            cwd=os.path.dirname(os.path.abspath(impl_path)) or None)
         got, out, err = r.returncode, r.stdout, None
     except subprocess.TimeoutExpired:
@@ -6307,6 +6357,41 @@ def _rt_ids_in(text):
     return out
 
 
+def _rt_ac_key(cid):
+    """ONE spelling for comparing an AC id, so the round-trip's footings cannot disagree over
+    punctuation (ADR-030, amended 1.90.0).
+
+    The three footings read ids from three places that spell them differently: an IR node id is
+    written the way a human wrote the acceptance line and keeps its padding (`AC-DD-07`), a
+    source comment or a curated oracle tag may write `AC-DD-7` or `AC_DD_07`, and `_rt_ids_in`
+    only upper-cases what it finds. Comparing those raw was a match that depended on a zero.
+    The normal form is ADR-036's OWN grammar (`_ac_tag_ids`, family + integer, padding and
+    separator dropped) -- reused rather than reimplemented, because a second grammar for the
+    same id is the drift this function exists to prevent. It is applied to BOTH sides of the
+    behaviour comparison and nowhere else: `per_node["id"]`, the static footing and the
+    manifest footing keep the IR's own spelling, so no report changes shape. A non-AC id
+    (INV-*, ADR-*) has no behaviour footing at all and falls through upper-cased."""
+    ids = _ac_tag_ids(str(cid or ""))
+    return ids[0] if ids else str(cid or "").upper().replace("_", "-")
+
+
+def _rt_case_tags(case):
+    """Every AC id ONE withheld-oracle case is tagged with, normalised (ADR-030, amended
+    1.90.0): the ids literally referenced in its `name`, plus the ids in its curated `ac` list.
+
+    `ac` is a human-curated field on the case (provenance:
+    `tests/fixtures/diamond-bench/ORACLE-TAGS-CURATED.json`) -- the payload and the expectations
+    are untouched by it, so tagging cannot change what a case MEASURES, only what the id map
+    says it measures. Absence stays absence: a missing key, a null, a non-list, or a list with
+    nothing usable in it yields no tags, and an entry whose cases carry none is still
+    behaviour-UNMEASURED rather than behaviour-zero."""
+    out = set(_rt_ids_in(case.get("name", "")))
+    raw = case.get("ac")
+    if isinstance(raw, (list, tuple)):
+        out |= {t for t in (str(x).strip() for x in raw if isinstance(x, str)) if t}
+    return {_rt_ac_key(t) for t in out}
+
+
 def _rt_read_source(cd, unit):
     try:
         with open(os.path.join(cd, unit.replace("/", os.sep)), encoding="utf-8",
@@ -6321,8 +6406,9 @@ def _rt_compilation(entry_dir, cd, ir_graph, cases):
     IR node, whether the mechanical reverse organs find footing for it in the artifact --
     (a) static: a source unit's text or a static observation literally references the id;
     (b) manifest: the compiler's validated trace manifest maps the node to a unit that exists;
-    (c) behaviour: for AC nodes, at least one withheld-oracle case tagged with the id passes
-    (UNMEASURED when no case carries any AC tag). It regenerates NOTHING: no IR', no spec --
+    (c) behaviour: for AC nodes, at least one withheld-oracle case tagged with the id passes --
+    tagged in the case NAME or in its curated `ac` list (ADR-030 amended 1.90.0), and
+    UNMEASURED when no case carries any tag at all. It regenerates NOTHING: no IR', no spec --
     a coverage over the human-authored IR, plus the list of nodes nothing anchors."""
     cj = os.path.join(cd, "COMPILATION.json")
     try:
@@ -6347,26 +6433,40 @@ def _rt_compilation(entry_dir, cd, ir_graph, cases):
         if e.get("unit") in units:
             for nid in e.get("implements") or []:
                 manifest_ids.add(str(nid).upper())
-    # (c) behaviour footing: oracle cases whose NAME carries an AC id (payload tags are not a
-    # convention the bench oracles use today -- absence named, not faked)
+    # (c) behaviour footing: the oracle cases an id is tagged with -- in the case NAME, and
+    # since 1.90.0 in the case's curated `ac` list as well (ADR-030 amended). Before the
+    # curation there was no tag anywhere in this fixture and the whole dimension read
+    # UNMEASURED: a named absence, which is what it was, and it is now measured instead.
     tagged = {}
-    for case in cases:
-        for cid in _rt_ids_in(case.get("name", "")):
-            tagged.setdefault(cid, []).append(case)
-    behaviour_measured = bool(tagged)
+    for i, case in enumerate(cases):
+        for cid in _rt_case_tags(case):
+            tagged.setdefault(cid, []).append(i)
+    # MEASURED only when at least one tag names an AC node of THIS entry's IR (1.90.0 review):
+    # a typo, a stray ADR/INV id or a tag from another archetype anchors nothing, and a tag
+    # that anchors nothing must leave the dimension a named absence, never a measured zero.
+    ir_ac_keys = {_rt_ac_key(n) for n in node_ids if str(n).upper().startswith("AC")}
+    behaviour_measured = any(_rt_ac_key(k) in ir_ac_keys for k in tagged)
     behaviour_ids = set()
     entry_unit = _entry_unit(c.get("source") or [])
     impl = os.path.join(cd, entry_unit.replace("/", os.sep)) if entry_unit else None
     if behaviour_measured and impl and os.path.isfile(impl):
-        for cid, cs in tagged.items():
-            if any(_run_oracle_case(impl, case).get("ok") for case in cs):
+        # one RUN per case, not one per tag: a case tagged with three ids used to be executed
+        # three times, and running a judged program more often than the oracle asked is both
+        # slower and a different experiment
+        verdicts = {}
+        for cid, idxs in tagged.items():
+            for i in idxs:
+                if i not in verdicts:
+                    verdicts[i] = bool(_run_oracle_case(impl, cases[i]).get("ok"))
+            if any(verdicts[i] for i in idxs):
                 behaviour_ids.add(cid)
     per_node = []
     anchored = 0
     for nid in node_ids:
         a_s = nid in static_ids
         a_m = nid in manifest_ids
-        a_b = (nid in behaviour_ids) if (behaviour_measured and nid.startswith("AC-")) else None
+        a_b = ((_rt_ac_key(nid) in behaviour_ids)
+               if (behaviour_measured and nid.startswith("AC-")) else None)
         anchored_any = a_s or a_m or bool(a_b)
         # the MEASURED footing excludes the manifest: the manifest is what the compiler
         # CLAIMED (and the prompt handed it the ids), so counting it as recovered would be
@@ -6423,6 +6523,26 @@ def _rt_entry(entry_dir, name):
     return rec
 
 
+def _rt_behaviour_note(agg):
+    """The report's closing sentence about the behaviour dimension, DERIVED from the aggregate
+    instead of asserted (1.90.0).
+
+    It used to end 'which today is every entry' -- true when written, false the moment the
+    diamond-bench oracles were curated with per-case `ac` tags, and nothing would have caught
+    it: a generated document is exactly where a hardcoded claim rots unseen. Three honest
+    states, one of them chosen by the number beside it."""
+    measured, total = agg.get("behaviour_measured") or 0, agg.get("measured") or 0
+    if not total or not measured:
+        return ("which today is every entry: the honest state of reverse discovery is that it "
+                "anchors names, not semantics, until oracles carry per-AC tags")
+    if measured == total:
+        return ("which today is no entry: every oracle here carries per-AC tags, so this "
+                "dimension is measured rather than named absent, and what it attributes is "
+                "behaviour and not merely a name")
+    return ("which today is %d of the %d measured entries -- the rest carry per-AC tags and "
+            "are attributed by behaviour" % (total - measured, total))
+
+
 def _render_rt_md(recs, agg):
     lines = ["<!-- GENERATED by qa_ledger.py bench-roundtrip (ADR-030) -- measured run; do not hand-edit. -->",
              "", "# DIAMOND-ROUNDTRIP -- how much of the pinned IR the reverse organs can anchor in each compiled artifact", "",
@@ -6460,10 +6580,8 @@ def _render_rt_md(recs, agg):
               "", "*The manifest dimension is what the compiler CLAIMED (validated for shape, "
               "not truth) and is excluded from recoverability; the static dimension is what the "
               "artifact literally names; the behaviour dimension is what the withheld oracle can "
-              "attribute per AC -- and it is UNMEASURED wherever oracle cases are not tagged with "
-              "AC ids, which today is every entry: the honest state of reverse discovery is that "
-              "it anchors names, not semantics, until oracles carry per-AC tags. None of the three "
-              "is a spec.*", ""]
+              "attribute per AC -- UNMEASURED wherever the entry's oracle cases carry no AC tag, "
+              "%s. None of the three is a spec.*" % _rt_behaviour_note(agg), ""]
     return "\n".join(lines)
 
 
@@ -8234,6 +8352,7 @@ def _top_ac_key(cid):
 
 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
@@ -8281,20 +8400,74 @@ def _top_key(value):
     return repr(value)
 
 
-def _top_event_text(*parts):
-    """One feed line: the only free text of the whole contract that reaches a terminal.
+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.
+
+    Filtered (1.90.0): C0 and DEL, the C1 range U+0080-U+009F (a terminal decoding the text
+    as latin-1 reads those as CSI/OSC introducers, so they are the same attack in one byte
+    less), and every Unicode format character (category `Cf`) -- U+200B and friends occupy no
+    column but do occupy a codepoint, and U+202E reverses the rest of the line. A character
+    that cannot be seen must not be able to move what is."""
+    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 and not 0x80 <= ord(c) <= 0x9F
+                  and unicodedata.category(c) != "Cf")
+    return " ".join(txt.split())
+
 
-    Its ingredients are ledger prose (an escalation reason, a tool name) -- human and CLI
-    input -- so an ESC or a C0 byte inside one would be a control sequence the board prints
-    verbatim. Every control character is dropped HERE, in the engine, and the renderer drops
-    them again on the way out: two cheap guards over one attack surface."""
-    txt = " · ".join(str(p) for p in parts if p not in (None, "", "?"))
-    txt = "".join(" " if c in ("\t", "\n", "\r") else c for c in txt)
-    txt = "".join(c for c in txt if ord(c) >= 32 and ord(c) != 127)
-    txt = " ".join(txt.split())
-    if len(txt) > TOP_EVENT_WIDTH:
-        txt = txt[:TOP_EVENT_WIDTH - 1] + "…"
-    return txt
+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):
@@ -8444,15 +8617,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