@andresmassello/uscha 1.82.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.82.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.82.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

@@ -5976,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:
@@ -5999,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:
@@ -6016,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:
@@ -6078,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.*", ""]

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.82.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.82.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.82.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.82.0
+uscha-kit 1.83.0

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

@@ -5976,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:
@@ -5999,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:
@@ -6016,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:
@@ -6078,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.*", ""]

package/uscha-kit/uscha.config.json

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