@andresmassello/uscha 1.81.0 → 1.83.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.81.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.83.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)
 

package/package.json

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

@@ -5582,19 +5582,20 @@ def _bench_entry(entry_dir, name, fidelity=False, curation=None):
             node_ids_f = {nd["id"] for nd in ir_graph.get("nodes") or []}
             covered_f = set()
             units_f, traced_f = set(), set()
+            # `c` was already parsed above for this same COMPILATION.json; reaching this
+            # block requires `unit` to be set, which only happens after that parse
+            # succeeded -- so `c` is guaranteed defined here, no need to re-open/re-parse.
             try:
-                with open(cj, encoding="utf-8-sig") as fh2:
-                    c2 = json.load(fh2)
-                for e2 in c2.get("trace_manifest") or []:
+                for e2 in c.get("trace_manifest") or []:
                     traced_f.add(e2.get("unit"))
                     for nid in e2.get("implements") or []:
                         if nid in node_ids_f:
                             covered_f.add(nid)
                 for sec in ("source", "tests"):
-                    for u2 in c2.get(sec) or []:
+                    for u2 in c.get(sec) or []:
                         if u2.get("unit"):
                             units_f.add(u2["unit"])
-            except (OSError, ValueError, AttributeError):
+            except AttributeError:
                 pass
             sobs, _uns = _extract_static_py(cd, [unit])
             fn_names, cls_names = [], []
@@ -5975,7 +5976,7 @@ def cmd_lang_compare(args):
     """Compare a FREE-prose arm and a CONTROLLED (EARS+STE) arm of the same canonical package
     (ADR-019). The two arms MUST share one withheld oracle -- a differing oracle is a mechanical
     refusal, because the whole comparison rests on the arms targeting the same behaviour. Emits
-    the per-arm metrics, the delta, and a COMPUTED verdict (REDUCED / NO EFFECT / WORSE); a null
+    the per-arm metrics, the delta, and a COMPUTED verdict (REDUCED / IMPROVED / MIXED / NO EFFECT / WORSE); a null
     is a first-class result. Consults no model."""
     hf, hc = _oracle_hash(args.free), _oracle_hash(args.controlled)
     if hf is None or hc is None:
@@ -5998,15 +5999,22 @@ def cmd_lang_compare(args):
     d_green = ctrl["greens"] - free["greens"]
     pf, pc = free["mean_passrate"], ctrl["mean_passrate"]
     d_pass = (pc - pf) if (pf is not None and pc is not None) else None
-    # Verdict is BEHAVIOUR-FIRST (the M4 lesson: lower variance toward a WORSE answer is not a
-    # win). A regression is a lost all-green OR a mean pass-rate drop beyond the pass-rate margin.
+    # Verdict is BEHAVIOUR-FIRST in BOTH directions. The M4 lesson: lower variance toward a
+    # WORSE answer is not a win (MIXED). Its mirror, the ADR-025 scheduler lesson: higher
+    # variance toward a BETTER answer is not a loss (IMPROVED) -- two compilers converging on
+    # the SAME bug reads as low variance, and a rewrite that separates them raises variance
+    # while fixing behaviour. A regression is a lost all-green OR a mean pass-rate drop beyond
+    # the pass-rate margin; an improvement is the exact mirror. ADR-019 + ADR-026.
     variance_reduced = d_var is not None and d_var <= -_LANG_MARGIN
     variance_worse = d_var is not None and d_var >= _LANG_MARGIN
     regressed = (d_green < 0) or (d_pass is not None and d_pass <= -_LANG_PR_MARGIN)
+    improved = (d_green > 0) or (d_pass is not None and d_pass >= _LANG_PR_MARGIN)
     if variance_reduced and regressed:
         verdict = "MIXED"                           # variance down but behaviour regressed
     elif variance_reduced:
-        verdict = "REDUCED"                         # variance down, behaviour held
+        verdict = "REDUCED"                         # variance down, behaviour held or better
+    elif improved and not regressed:
+        verdict = "IMPROVED"                        # behaviour up, variance not down
     elif variance_worse or regressed:
         verdict = "WORSE"
     else:
@@ -6015,6 +6023,7 @@ def cmd_lang_compare(args):
              "unresolved_intent_count": round(d_ui, 3), "oracle_green": d_green,
              "mean_passrate": round(d_pass, 4) if d_pass is not None else None}
     report = {"free": free, "controlled": ctrl, "delta": delta, "verdict": verdict,
+              "regressed": regressed, "improved": improved,
               "margin": _LANG_MARGIN, "passrate_margin": _LANG_PR_MARGIN, "oracle_shared": True}
     if args.out:
         with open(args.out, "w", encoding="utf-8", newline="\n") as fh:
@@ -6077,7 +6086,15 @@ def _render_lang_md(r):
                             "the delta here. A null result, reported as a null — not a failure.",
                "WORSE": "Controlled authoring increased variance, or regressed behaviour (lost an "
                         "all-green or dropped mean pass-rate) beyond the margins — reported "
-                        "honestly."}[r["verdict"]],
+                        "honestly.",
+               "IMPROVED": "Controlled authoring IMPROVED behaviour (gained an all-green or raised "
+                           "mean pass-rate beyond the %.2f margin) while inter-compiler variance "
+                           "did not fall. Behaviour won; variance did not — check whether the free "
+                           "arm's low variance was convergence on a shared reading (right or "
+                           "wrong): two compilers resolving the same ambiguity the same way read "
+                           "as agreement, and a rewrite that separates them raises variance "
+                           "while moving behaviour."
+                           % r.get("passrate_margin", 0.02)}[r["verdict"]],
               "", "*The oracle is byte-identical across both arms, so behaviour is held fixed; "
               "the only variable is the authoring discipline. The judgement of \"same semantic "
               "content\" between the two canonical packages is human — a stated limitation.*", ""]
@@ -10217,7 +10234,9 @@ def build_parser():
     pbc.add_argument("--bench", required=True,
                      help="the bench directory (the store lives at its root)")
     pbc.add_argument("--entry", required=True, help="the archetype entry")
-    pbc.add_argument("--dir", required=True, help="the compilation dir (e.g. c-opus)")
+    pbc.add_argument("--dir", "--compilation", dest="dir", required=True,
+                     help="the compilation dir (e.g. c-opus); --compilation is an alias "
+                          "(bench --dir means the bench root -- a copy-paste hazard)")
     pbc.add_argument("--obs", default=None, help="a single OBS id from --list")
     pbc.add_argument("--verdict", default=None, choices=_BENCH_CURATION_VERDICTS)
     pbc.add_argument("--note", default=None)

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

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.81.0",
+  "version": "1.83.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, 49 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {

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

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.81.0",
+  "version": "1.83.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.81.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.83.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`,

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.81.0
+uscha-kit 1.83.0

package/uscha-kit/reports/junit/.bench-curate-cases.json

@@ -1 +1 @@
-{"AC-BC-01": true, "AC-BC-02": true, "AC-BC-03": true}
+{"AC-BC-04": true, "AC-BC-01": true, "AC-BC-02": true, "AC-BC-03": true}

package/uscha-kit/reports/junit/.sched-cases.json

@@ -0,0 +1 @@
+{"AC-SH-01": true, "AC-SH-02": true, "AC-SH-03": true, "AC-LI-01": true, "AC-LI-02": true, "AC-LI-03": true}

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

@@ -5582,19 +5582,20 @@ def _bench_entry(entry_dir, name, fidelity=False, curation=None):
             node_ids_f = {nd["id"] for nd in ir_graph.get("nodes") or []}
             covered_f = set()
             units_f, traced_f = set(), set()
+            # `c` was already parsed above for this same COMPILATION.json; reaching this
+            # block requires `unit` to be set, which only happens after that parse
+            # succeeded -- so `c` is guaranteed defined here, no need to re-open/re-parse.
             try:
-                with open(cj, encoding="utf-8-sig") as fh2:
-                    c2 = json.load(fh2)
-                for e2 in c2.get("trace_manifest") or []:
+                for e2 in c.get("trace_manifest") or []:
                     traced_f.add(e2.get("unit"))
                     for nid in e2.get("implements") or []:
                         if nid in node_ids_f:
                             covered_f.add(nid)
                 for sec in ("source", "tests"):
-                    for u2 in c2.get(sec) or []:
+                    for u2 in c.get(sec) or []:
                         if u2.get("unit"):
                             units_f.add(u2["unit"])
-            except (OSError, ValueError, AttributeError):
+            except AttributeError:
                 pass
             sobs, _uns = _extract_static_py(cd, [unit])
             fn_names, cls_names = [], []
@@ -5975,7 +5976,7 @@ def cmd_lang_compare(args):
     """Compare a FREE-prose arm and a CONTROLLED (EARS+STE) arm of the same canonical package
     (ADR-019). The two arms MUST share one withheld oracle -- a differing oracle is a mechanical
     refusal, because the whole comparison rests on the arms targeting the same behaviour. Emits
-    the per-arm metrics, the delta, and a COMPUTED verdict (REDUCED / NO EFFECT / WORSE); a null
+    the per-arm metrics, the delta, and a COMPUTED verdict (REDUCED / IMPROVED / MIXED / NO EFFECT / WORSE); a null
     is a first-class result. Consults no model."""
     hf, hc = _oracle_hash(args.free), _oracle_hash(args.controlled)
     if hf is None or hc is None:
@@ -5998,15 +5999,22 @@ def cmd_lang_compare(args):
     d_green = ctrl["greens"] - free["greens"]
     pf, pc = free["mean_passrate"], ctrl["mean_passrate"]
     d_pass = (pc - pf) if (pf is not None and pc is not None) else None
-    # Verdict is BEHAVIOUR-FIRST (the M4 lesson: lower variance toward a WORSE answer is not a
-    # win). A regression is a lost all-green OR a mean pass-rate drop beyond the pass-rate margin.
+    # Verdict is BEHAVIOUR-FIRST in BOTH directions. The M4 lesson: lower variance toward a
+    # WORSE answer is not a win (MIXED). Its mirror, the ADR-025 scheduler lesson: higher
+    # variance toward a BETTER answer is not a loss (IMPROVED) -- two compilers converging on
+    # the SAME bug reads as low variance, and a rewrite that separates them raises variance
+    # while fixing behaviour. A regression is a lost all-green OR a mean pass-rate drop beyond
+    # the pass-rate margin; an improvement is the exact mirror. ADR-019 + ADR-026.
     variance_reduced = d_var is not None and d_var <= -_LANG_MARGIN
     variance_worse = d_var is not None and d_var >= _LANG_MARGIN
     regressed = (d_green < 0) or (d_pass is not None and d_pass <= -_LANG_PR_MARGIN)
+    improved = (d_green > 0) or (d_pass is not None and d_pass >= _LANG_PR_MARGIN)
     if variance_reduced and regressed:
         verdict = "MIXED"                           # variance down but behaviour regressed
     elif variance_reduced:
-        verdict = "REDUCED"                         # variance down, behaviour held
+        verdict = "REDUCED"                         # variance down, behaviour held or better
+    elif improved and not regressed:
+        verdict = "IMPROVED"                        # behaviour up, variance not down
     elif variance_worse or regressed:
         verdict = "WORSE"
     else:
@@ -6015,6 +6023,7 @@ def cmd_lang_compare(args):
              "unresolved_intent_count": round(d_ui, 3), "oracle_green": d_green,
              "mean_passrate": round(d_pass, 4) if d_pass is not None else None}
     report = {"free": free, "controlled": ctrl, "delta": delta, "verdict": verdict,
+              "regressed": regressed, "improved": improved,
               "margin": _LANG_MARGIN, "passrate_margin": _LANG_PR_MARGIN, "oracle_shared": True}
     if args.out:
         with open(args.out, "w", encoding="utf-8", newline="\n") as fh:
@@ -6077,7 +6086,15 @@ def _render_lang_md(r):
                             "the delta here. A null result, reported as a null — not a failure.",
                "WORSE": "Controlled authoring increased variance, or regressed behaviour (lost an "
                         "all-green or dropped mean pass-rate) beyond the margins — reported "
-                        "honestly."}[r["verdict"]],
+                        "honestly.",
+               "IMPROVED": "Controlled authoring IMPROVED behaviour (gained an all-green or raised "
+                           "mean pass-rate beyond the %.2f margin) while inter-compiler variance "
+                           "did not fall. Behaviour won; variance did not — check whether the free "
+                           "arm's low variance was convergence on a shared reading (right or "
+                           "wrong): two compilers resolving the same ambiguity the same way read "
+                           "as agreement, and a rewrite that separates them raises variance "
+                           "while moving behaviour."
+                           % r.get("passrate_margin", 0.02)}[r["verdict"]],
               "", "*The oracle is byte-identical across both arms, so behaviour is held fixed; "
               "the only variable is the authoring discipline. The judgement of \"same semantic "
               "content\" between the two canonical packages is human — a stated limitation.*", ""]
@@ -10217,7 +10234,9 @@ def build_parser():
     pbc.add_argument("--bench", required=True,
                      help="the bench directory (the store lives at its root)")
     pbc.add_argument("--entry", required=True, help="the archetype entry")
-    pbc.add_argument("--dir", required=True, help="the compilation dir (e.g. c-opus)")
+    pbc.add_argument("--dir", "--compilation", dest="dir", required=True,
+                     help="the compilation dir (e.g. c-opus); --compilation is an alias "
+                          "(bench --dir means the bench root -- a copy-paste hazard)")
     pbc.add_argument("--obs", default=None, help="a single OBS id from --list")
     pbc.add_argument("--verdict", default=None, choices=_BENCH_CURATION_VERDICTS)
     pbc.add_argument("--note", default=None)

package/uscha-kit/templates/scripts/uscha_progress.py

@@ -152,7 +152,8 @@ def main():
     repo = _statusline_repo(cfg)
     if not repo:
         return
-    state = {"label": repo.get("label") or str(repo.get("name", "uscha")).upper(),
+    state = {"schema": "uscha/progress@1",
+             "label": repo.get("label") or str(repo.get("name", "uscha")).upper(),
              "pct": None, "done": None, "total": None, "tests": None, "coverage": None,
              "next": None, "phase": None, "loops": None, "stalled": None,
              "acceptance_source": None, "measured_at": None, "score": None, "band": None,

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.81.0",
+  "version": "1.83.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,