@andresmassello/uscha 1.89.0 → 1.91.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.89.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.91.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,25 +82,29 @@ 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.89.0, 52 subcommands, all measured):**
+**What each arrow is, in the engine (kit 1.91.0, 52 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.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.89.0",
+  "version": "1.91.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)
 
 
@@ -8288,9 +8406,17 @@ def _top_clean(text):
     observation statement, a tool name) -- human and CLI input -- so an ESC or a C0 byte
     inside one would be a control sequence the board obeys instead of prints. It dies HERE,
     in the engine, and the renderer drops it again on the way out: two cheap guards over one
-    attack surface. What is filtered is exactly C0 and DEL (ADR-032)."""
+    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)
+    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())
 
 
@@ -8441,6 +8567,78 @@ 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"}
+
+
 def cmd_top(args):
     """`uscha top` — the WHOLE projection of the ledger as one read-only JSON (ADR-032).
 
@@ -8573,6 +8771,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.