@andresmassello/uscha 1.73.0 → 1.75.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.73.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.75.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)
 
@@ -76,7 +76,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`, 44 subcommands, Python stdlib) that ingests
+**A measurement engine** (`qa_ledger.py`, 47 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.73.0",
+  "version": "1.75.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

@@ -5298,6 +5298,362 @@ def cmd_compile_ingest(args):
     sys.exit(0)
 
 
+# --------------------------------------------------------------------------- #
+# bootstrap  (Diamond M4: a bounded subsystem's identity is carried by its
+# canonical package + a WITHHELD oracle, not by its implementation. The oracle
+# runner is a measured fact and decides "same system"; variance is advisory
+# evidence that the implementations genuinely differ. ADR-017.)
+# --------------------------------------------------------------------------- #
+_BOOTSTRAP_CASE_TIMEOUT = 15                        # a compiled hook must decide fast
+
+
+def _run_oracle_case(impl_path, case):
+    """Run ONE withheld oracle case against a compiled implementation: feed the case's stdin
+    (raw_stdin verbatim if present, else json.dumps(payload)) to `python <impl>`, and check its
+    result against whichever expectations the case declares. Deterministic execution -- the
+    oracle is a `measured` fact, never an LLM judgment. Returns a per-case result dict.
+
+    A case may assert any of: `expected_exit` (process exit code -- the M4 guard's contract),
+    `expected_stdout` (the program's stdout, compared stripped -- for archetypes that COMPUTE an
+    output, e.g. a parser or transformer), and `expected_json` (stdout parsed as JSON and
+    compared structurally, so an output whose formatting is free but whose value is fixed is not
+    penalised for whitespace or key order). The case passes iff EVERY declared expectation holds;
+    a case that declares none proves nothing and fails."""
+    if "raw_stdin" in case:
+        stdin = case["raw_stdin"]
+    else:
+        stdin = json.dumps(case.get("payload"))
+    try:
+        r = subprocess.run([sys.executable, impl_path], input=stdin, capture_output=True,
+                           text=True, encoding="utf-8", errors="replace",
+                           timeout=_BOOTSTRAP_CASE_TIMEOUT)
+        got, out, err = r.returncode, r.stdout, None
+    except subprocess.TimeoutExpired:
+        got, out, err = None, "", "timeout"
+    except OSError as exc:
+        got, out, err = None, "", "could not run impl: %s" % exc
+    want = case.get("expected_exit")
+    asserted = [k for k in ("expected_exit", "expected_stdout", "expected_json") if k in case]
+    ok = err is None and bool(asserted)
+    if ok and "expected_exit" in case:
+        ok = got == want
+    if ok and "expected_stdout" in case:
+        ok = (out or "").strip() == str(case["expected_stdout"]).strip()
+    if ok and "expected_json" in case:
+        try:
+            ok = json.loads(out) == case["expected_json"]
+        except (ValueError, TypeError):
+            ok = False
+    return {"name": case.get("name"), "expected": want, "got": got, "ok": ok, "error": err}
+
+
+def cmd_bootstrap_oracle(args):
+    """Run a WITHHELD oracle suite (ADR-017) against a compiled implementation. The oracle
+    predates and is physically separate from every compiler input; this runner is the
+    maker!=checker wall made executable. Exit 0 iff every case matches its expected exit,
+    else 1 -- a measured behavioural fact about whether this implementation is the same
+    system. It runs the implementation as a subprocess and consults no model."""
+    try:
+        with open(args.oracle, encoding="utf-8-sig") as fh:
+            oracle = json.load(fh)
+    except (OSError, ValueError) as exc:
+        print("[qa_ledger] bootstrap-oracle: unreadable oracle %s: %s" % (args.oracle, exc),
+              file=sys.stderr)
+        sys.exit(2)
+    cases = oracle.get("cases")
+    if not isinstance(cases, list) or not cases:
+        print("[qa_ledger] bootstrap-oracle: oracle has no cases", file=sys.stderr)
+        sys.exit(2)
+    if not os.path.isfile(args.impl):
+        print("[qa_ledger] bootstrap-oracle: no implementation at %s" % args.impl,
+              file=sys.stderr)
+        sys.exit(2)
+    results = [_run_oracle_case(args.impl, c) for c in cases]
+    passed = sum(1 for r in results if r["ok"])
+    failed = [r for r in results if not r["ok"]]
+    report = {"impl": args.impl, "oracle": args.oracle, "total": len(results),
+              "passed": passed, "failed": len(failed),
+              "oracle_green": not failed, "results": results}
+    if args.ledger and args.repo:
+        ledger = _load(args.ledger)
+        _repo_node(ledger, args.repo)
+        rec = {"impl": os.path.basename(args.impl), "oracle": os.path.basename(args.oracle),
+               "total": len(results), "passed": passed, "failed": len(failed),
+               "oracle_green": not failed,
+               "failing": [r["name"] for r in failed], "at": _now()}
+        ledger.setdefault("bootstrap_oracle", []).append(rec)
+        _save(args.ledger, ledger)
+    if args.json:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+    else:
+        print("BOOTSTRAP-ORACLE %s: %d/%d cases pass -- %s"
+              % (os.path.basename(args.impl), passed, len(results),
+                 "ORACLE GREEN (same system on this suite)" if not failed
+                 else "ORACLE RED (%d divergence(s))" % len(failed)))
+        for r in failed:
+            print("  x %s: expected exit %s, got %s%s"
+                  % (r["name"], r["expected"], r["got"],
+                     " (%s)" % r["error"] if r["error"] else ""))
+    sys.exit(0 if not failed else 1)
+
+
+def _impl_metrics(path):
+    """Structural fingerprint of one implementation: physical LOC, AST node count, function
+    and class counts, and the set of imported top-level modules. Deterministic; no judgment."""
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            src = fh.read()
+    except OSError as exc:
+        return {"path": path, "error": "unreadable: %s" % exc}
+    loc = sum(1 for ln in src.splitlines() if ln.strip())
+    try:
+        tree = ast.parse(src)
+    except SyntaxError as exc:
+        return {"path": path, "loc": loc, "error": "unparseable: %s" % exc}
+    funcs = classes = nodes = 0
+    imports = set()
+    for nd in ast.walk(tree):
+        nodes += 1
+        if isinstance(nd, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            funcs += 1
+        elif isinstance(nd, ast.ClassDef):
+            classes += 1
+        elif isinstance(nd, ast.Import):
+            for a in nd.names:
+                imports.add(a.name.split(".")[0])
+        elif isinstance(nd, ast.ImportFrom):
+            if nd.module:
+                imports.add(nd.module.split(".")[0])
+    return {"path": path, "loc": loc, "ast_nodes": nodes, "functions": funcs,
+            "classes": classes, "imports": sorted(imports),
+            "sha256": hashlib.sha256(src.encode("utf-8")).hexdigest()}
+
+
+def cmd_bootstrap_variance(args):
+    """Prove independent compilations of the same canonical package genuinely DIFFER (ADR-017).
+    Reports per-implementation structural metrics and pairwise divergence. ADVISORY: variance
+    is evidence the implementations differ, never a certificate of 'same system' (only the
+    oracle certifies that) and never a gate -- it cannot change an exit code."""
+    metrics = [_impl_metrics(p) for p in args.impls]
+    pairs = []
+    good = [m for m in metrics if "error" not in m]
+    for i in range(len(good)):
+        for j in range(i + 1, len(good)):
+            a, b = good[i], good[j]
+            ia, ib = set(a["imports"]), set(b["imports"])
+            jac = (len(ia & ib) / len(ia | ib)) if (ia or ib) else 1.0
+            pairs.append({"a": os.path.basename(a["path"]), "b": os.path.basename(b["path"]),
+                          "byte_identical": a["sha256"] == b["sha256"],
+                          "loc_delta": abs(a["loc"] - b["loc"]),
+                          "ast_node_delta": abs(a["ast_nodes"] - b["ast_nodes"]),
+                          "function_delta": abs(a["functions"] - b["functions"]),
+                          "import_jaccard": round(jac, 3)})
+    all_distinct = all(not p["byte_identical"] for p in pairs) if pairs else None
+    report = {"implementations": metrics, "pairs": pairs, "all_distinct": all_distinct,
+              "advisory": True}
+    if args.json:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+    else:
+        for m in metrics:
+            if "error" in m:
+                print("VARIANCE %s: %s" % (os.path.basename(m["path"]), m["error"]))
+            else:
+                print("VARIANCE %s: %d loc, %d ast-nodes, %d fn, %d cls, imports=%s"
+                      % (os.path.basename(m["path"]), m["loc"], m["ast_nodes"],
+                         m["functions"], m["classes"], ",".join(m["imports"]) or "-"))
+        for p in pairs:
+            print("  %s vs %s: %s | dloc=%d dnodes=%d import_jaccard=%.2f"
+                  % (p["a"], p["b"], "IDENTICAL" if p["byte_identical"] else "distinct",
+                     p["loc_delta"], p["ast_node_delta"], p["import_jaccard"]))
+        if all_distinct is not None:
+            print("  all implementations distinct: %s (advisory, never gates)"
+                  % ("yes" if all_distinct else "NO -- convergence, a weak result"))
+    sys.exit(0)
+
+
+# --------------------------------------------------------------------------- #
+# bench  (Diamond M5: the Diamond Bench aggregates the M3/M4 primitives over a
+# set of bounded systems and emits a per-archetype verdict table. It measures
+# REGENERATION FIDELITY of canonical representations, not "which model codes
+# better" -- model identities are anonymized in the headline. Deterministic, no
+# LLM. ADR-018.)
+# --------------------------------------------------------------------------- #
+# min oracle pass-rate for a non-green compilation to still count as PARTIAL (core identity).
+_BENCH_PARTIAL_FLOOR = 0.8
+
+
+def _bench_oracle_all(impl_path, cases):
+    results = [_run_oracle_case(impl_path, c) for c in cases]
+    passed = sum(1 for r in results if r["ok"])
+    return {"passed": passed, "total": len(results), "green": passed == len(results),
+            "failing": [r["name"] for r in results if not r["ok"]]}
+
+
+def _bench_entry(entry_dir, name):
+    """Run compile-validate + the withheld oracle + variance over ONE bench entry and compute
+    its verdict. Reuses the M3/M4 organs unchanged; consults no model. A PASS is >=3 oracle-green
+    compilations that genuinely differ; PARTIAL is core identity with the divergence isolated;
+    FAIL is no green, convergence to near-identical code, or an oracle a degenerate stub can
+    satisfy (non-discriminating); PENDING is an entry not yet fully compiled."""
+    ir_graph, ir_errors = _load_ir_at(os.path.join(entry_dir, IR_FILE))
+    try:
+        with open(os.path.join(entry_dir, "oracle", "ORACLE.json"), encoding="utf-8-sig") as fh:
+            cases = (json.load(fh) or {}).get("cases") or []
+    except (OSError, ValueError):
+        cases = []
+    rec = {"archetype": name, "oracle_cases": len(cases), "compilations": [],
+           "variance": None, "discrimination": None, "verdict": "PENDING", "reason": None}
+    if ir_graph is None or ir_errors or not cases:
+        rec["reason"] = "entry incomplete (missing/invalid IR or oracle)"
+        return rec
+    comp_dirs = sorted(d for d in os.listdir(entry_dir)
+                       if d.startswith("c-") and
+                       os.path.isfile(os.path.join(entry_dir, d, "COMPILATION.json")))
+    for d in comp_dirs:
+        cd = os.path.join(entry_dir, d)
+        cj = os.path.join(cd, "COMPILATION.json")
+        errors, _adv = _validate_compilation(cj, ir_graph)
+        unit, model = None, None
+        try:
+            with open(cj, encoding="utf-8-sig") as fh:
+                c = json.load(fh)
+            src = c.get("source") or []
+            unit = src[0].get("unit") if src else None
+            model = (c.get("compilation_report") or {}).get("model")
+        except (OSError, ValueError, AttributeError, IndexError):
+            pass
+        impl = os.path.join(cd, unit.replace("/", os.sep)) if unit else None
+        ores = (_bench_oracle_all(impl, cases) if impl and os.path.isfile(impl)
+                else {"passed": 0, "total": len(cases), "green": False, "failing": ["<no impl>"]})
+        rec["compilations"].append({"dir": d, "model": model, "impl": impl,
+                                    "compile_valid": not errors, "oracle": ores})
+    impls = rec["compilations"]
+    impl_paths = [i["impl"] for i in impls if i["impl"] and os.path.isfile(i["impl"])]
+    if len(impl_paths) >= 2:
+        metrics = [_impl_metrics(p) for p in impl_paths]
+        shas = [m.get("sha256") for m in metrics if "error" not in m and m.get("sha256")]
+        rec["variance"] = {"all_distinct": len(set(shas)) == len(shas) and len(shas) >= 2,
+                           "metrics": metrics}
+    stub_dir = os.path.join(entry_dir, "stub")
+    stub_green = False
+    if os.path.isdir(stub_dir):
+        stubs = sorted(f for f in os.listdir(stub_dir) if f.endswith(".py"))
+        if stubs:
+            sres = _bench_oracle_all(os.path.join(stub_dir, stubs[0]), cases)
+            stub_green = sres["green"]
+            rec["discrimination"] = {"stub_passed": sres["passed"], "total": sres["total"],
+                                     "stub_green": stub_green}
+    n = len(impls)
+    if n == 0:
+        rec["reason"] = "no compilations yet"
+        return rec                                  # PENDING
+    all_valid = all(i["compile_valid"] for i in impls)
+    greens = sum(1 for i in impls if i["oracle"]["green"])
+    min_rate = min((i["oracle"]["passed"] / i["oracle"]["total"]) if i["oracle"]["total"]
+                   else 0.0 for i in impls)
+    distinct = rec["variance"]["all_distinct"] if rec["variance"] else (n == 1)
+    if stub_green:
+        rec["verdict"], rec["reason"] = "FAIL", ("oracle satisfied by a degenerate stub -- not "
+                                                 "discriminating; the entry proves nothing")
+    elif not all_valid:
+        rec["verdict"], rec["reason"] = "FAIL", "a compilation does not validate against the pinned IR"
+    elif n < 3:
+        rec["verdict"], rec["reason"] = "PENDING", "fewer than 3 compilations (have %d)" % n
+    elif not distinct:
+        rec["verdict"], rec["reason"] = "FAIL", ("implementations converged to a byte-identical "
+                                                 "pair -- a disguised implementation")
+    elif greens == n:
+        rec["verdict"], rec["reason"] = "PASS", ("all %d compilations oracle-green and genuinely "
+                                                 "different -- the same system" % n)
+    elif min_rate >= _BENCH_PARTIAL_FLOOR:
+        rec["verdict"], rec["reason"] = "PARTIAL", ("core identity (min %.0f%% of cases); "
+                                                    "divergence isolated" % (min_rate * 100))
+    else:
+        rec["verdict"], rec["reason"] = "FAIL", ("a compilation below the core-identity floor "
+                                                 "(min %.0f%%)" % (min_rate * 100))
+    return rec
+
+
+def _render_bench_md(table, anon, recs):
+    lines = ["<!-- GENERATED by qa_ledger.py bench (ADR-018) -- every number is a measured run; "
+             "do not hand-edit. -->", "", "# DIAMOND-BENCH", "",
+             "Regeneration fidelity of canonical representations across archetypes. Each row is a "
+             "bounded system compiled blind by independent models through the M3 contract and "
+             "judged by a WITHHELD oracle (M4). Model identities are anonymized here; the mapping "
+             "is published below.", "",
+             "| Archetype | Verdict | Compilers (oracle pass / total) | Distinct | Oracle cases |",
+             "|-----------|---------|--------------------------------|----------|--------------|"]
+    for t in table:
+        dist = "—" if t["distinct"] is None else ("yes" if t["distinct"] else "NO")
+        lines.append("| %s | %s | %s | %s | %d |" % (t["archetype"], t["verdict"],
+                     t["compilers"], dist, t["oracle_cases"]))
+    counts = {}
+    for t in table:
+        counts[t["verdict"]] = counts.get(t["verdict"], 0) + 1
+    lines += ["", "**Coverage:** " + ", ".join("%d %s" % (v, k) for k, v in sorted(counts.items()))
+              + " (of %d entries)." % len(table), "",
+              "**Model map (published, not the headline):** "
+              + (", ".join("%s = %s" % (a, m) for m, a in sorted(anon.items(), key=lambda x: x[1]))
+                 or "none yet") + ".", "",
+              "## Per-entry detail", ""]
+    for r in recs:
+        lines.append("### %s — %s" % (r["archetype"], r["verdict"]))
+        lines.append("*%s*" % (r["reason"] or ""))
+        if r["compilations"]:
+            for i in r["compilations"]:
+                lines.append("- `%s` (%s): oracle %d/%d%s%s" % (
+                    i["dir"], anon.get(i["model"], i["model"] or "?"),
+                    i["oracle"]["passed"], i["oracle"]["total"],
+                    " GREEN" if i["oracle"]["green"] else "",
+                    "" if i["compile_valid"] else " [does not compile-validate]"))
+        if r["discrimination"]:
+            dsc = r["discrimination"]
+            lines.append("- discrimination stub: %d/%d (%s)" % (
+                dsc["stub_passed"], dsc["total"],
+                "NON-DISCRIMINATING" if dsc["stub_green"] else "oracle rejects the stub"))
+        lines.append("")
+    return "\n".join(lines)
+
+
+def cmd_bench(args):
+    if not os.path.isdir(args.dir):
+        print("[qa_ledger] bench: no directory %s" % args.dir, file=sys.stderr)
+        sys.exit(2)
+    entries = sorted(d for d in os.listdir(args.dir)
+                     if os.path.isfile(os.path.join(args.dir, d, IR_FILE)))
+    if not entries:
+        print("[qa_ledger] bench: no entries under %s (an entry is a subdir with %s)"
+              % (args.dir, IR_FILE), file=sys.stderr)
+        sys.exit(2)
+    recs = [_bench_entry(os.path.join(args.dir, e), e) for e in entries]
+    models = sorted({i["model"] for r in recs for i in r["compilations"] if i.get("model")})
+    anon = {m: "M%d" % (k + 1) for k, m in enumerate(models)}
+    table = []
+    for r in recs:
+        cols = ", ".join("%s %d/%d" % (anon.get(i["model"], "?"), i["oracle"]["passed"],
+                                       i["oracle"]["total"]) for i in r["compilations"])
+        table.append({"archetype": r["archetype"], "verdict": r["verdict"],
+                      "compilers": cols or "(none yet)",
+                      "distinct": (r["variance"] or {}).get("all_distinct"),
+                      "oracle_cases": r["oracle_cases"], "reason": r["reason"]})
+    md = _render_bench_md(table, anon, recs)
+    if args.out:
+        with open(args.out, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(md)
+    if args.json:
+        print(json.dumps({"entries": len(recs), "model_map": anon, "table": table,
+                          "raw": recs}, indent=2, ensure_ascii=False))
+    else:
+        print("BENCH: %d entries" % len(recs))
+        for t in table:
+            dist = "" if t["distinct"] is None else (" | distinct" if t["distinct"]
+                                                     else " | CONVERGED")
+            print("  %-14s %-8s | %s%s" % (t["archetype"], t["verdict"], t["compilers"], dist))
+        if args.out:
+            print("  -> %s" % args.out)
+    sys.exit(0)
+
+
 # --------------------------------------------------------------------------- #
 # facts  (T0 / SYSTEM-FACTS: public claims become compiled artifacts of repo
 # facts -- Diamond applied to Diamond. ADR-012.)
@@ -9390,6 +9746,37 @@ def build_parser():
     pcmi.add_argument("--json", action="store_true")
     pcmi.set_defaults(func=cmd_compile_ingest)
 
+    pbo = sub.add_parser(
+        "bootstrap-oracle",
+        help="run a WITHHELD oracle suite against a compiled implementation (ADR-017); exit 0 "
+             "iff every case matches its expected exit -- the maker!=checker wall, executable")
+    pbo.add_argument("--impl", required=True, help="the compiled implementation to run")
+    pbo.add_argument("--oracle", required=True, help="the withheld ORACLE.json case suite")
+    pbo.add_argument("--ledger", default=None, help="optional: persist the measured result")
+    pbo.add_argument("--repo", default=None, help="repo scope when --ledger is given")
+    pbo.add_argument("--json", action="store_true")
+    pbo.set_defaults(func=cmd_bootstrap_oracle)
+
+    pbv = sub.add_parser(
+        "bootstrap-variance",
+        help="structural metrics + pairwise divergence proving independent compilations "
+             "genuinely differ (ADR-017); ADVISORY evidence, never a gate")
+    pbv.add_argument("--impls", required=True, nargs="+",
+                     help="two or more compiled implementations to compare")
+    pbv.add_argument("--json", action="store_true")
+    pbv.set_defaults(func=cmd_bootstrap_variance)
+
+    pbn = sub.add_parser(
+        "bench",
+        help="the Diamond Bench (ADR-018): per-archetype verdict table over a set of bounded "
+             "systems, aggregating compile-validate + bootstrap-oracle + bootstrap-variance; "
+             "model identities anonymized in the headline; deterministic, no LLM")
+    pbn.add_argument("--dir", required=True,
+                     help="the bench directory; each subdir with an IR.json is an entry")
+    pbn.add_argument("--out", default=None, help="write DIAMOND-BENCH.md here")
+    pbn.add_argument("--json", action="store_true")
+    pbn.set_defaults(func=cmd_bench)
+
     pcr = sub.add_parser("cleanroom",
                          help="run a command against a CLEAN checkout of one commit in a throwaway worktree (ADR-008)")
     pcr.add_argument("--ledger", default="QA-LEDGER.json")

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

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.73.0",
+  "version": "1.75.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, 44 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
+  "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, 47 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",
     "url": "https://github.com/andresmassello"

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

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.73.0",
+  "version": "1.75.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.73.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.75.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.73.0
+uscha-kit 1.75.0

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

@@ -0,0 +1 @@
+{"AC-DB-01": true, "AC-DB-02": true, "AC-DB-03": true, "AC-DB-05": true, "AC-DB-04": true, "AC-DB-06": true}

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

@@ -0,0 +1 @@
+{"AC-BS-01": true, "AC-BS-02": true, "AC-BS-03": true, "AC-BS-04": true, "AC-BS-05": true, "AC-BS-06": true}

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

@@ -5298,6 +5298,362 @@ def cmd_compile_ingest(args):
     sys.exit(0)
 
 
+# --------------------------------------------------------------------------- #
+# bootstrap  (Diamond M4: a bounded subsystem's identity is carried by its
+# canonical package + a WITHHELD oracle, not by its implementation. The oracle
+# runner is a measured fact and decides "same system"; variance is advisory
+# evidence that the implementations genuinely differ. ADR-017.)
+# --------------------------------------------------------------------------- #
+_BOOTSTRAP_CASE_TIMEOUT = 15                        # a compiled hook must decide fast
+
+
+def _run_oracle_case(impl_path, case):
+    """Run ONE withheld oracle case against a compiled implementation: feed the case's stdin
+    (raw_stdin verbatim if present, else json.dumps(payload)) to `python <impl>`, and check its
+    result against whichever expectations the case declares. Deterministic execution -- the
+    oracle is a `measured` fact, never an LLM judgment. Returns a per-case result dict.
+
+    A case may assert any of: `expected_exit` (process exit code -- the M4 guard's contract),
+    `expected_stdout` (the program's stdout, compared stripped -- for archetypes that COMPUTE an
+    output, e.g. a parser or transformer), and `expected_json` (stdout parsed as JSON and
+    compared structurally, so an output whose formatting is free but whose value is fixed is not
+    penalised for whitespace or key order). The case passes iff EVERY declared expectation holds;
+    a case that declares none proves nothing and fails."""
+    if "raw_stdin" in case:
+        stdin = case["raw_stdin"]
+    else:
+        stdin = json.dumps(case.get("payload"))
+    try:
+        r = subprocess.run([sys.executable, impl_path], input=stdin, capture_output=True,
+                           text=True, encoding="utf-8", errors="replace",
+                           timeout=_BOOTSTRAP_CASE_TIMEOUT)
+        got, out, err = r.returncode, r.stdout, None
+    except subprocess.TimeoutExpired:
+        got, out, err = None, "", "timeout"
+    except OSError as exc:
+        got, out, err = None, "", "could not run impl: %s" % exc
+    want = case.get("expected_exit")
+    asserted = [k for k in ("expected_exit", "expected_stdout", "expected_json") if k in case]
+    ok = err is None and bool(asserted)
+    if ok and "expected_exit" in case:
+        ok = got == want
+    if ok and "expected_stdout" in case:
+        ok = (out or "").strip() == str(case["expected_stdout"]).strip()
+    if ok and "expected_json" in case:
+        try:
+            ok = json.loads(out) == case["expected_json"]
+        except (ValueError, TypeError):
+            ok = False
+    return {"name": case.get("name"), "expected": want, "got": got, "ok": ok, "error": err}
+
+
+def cmd_bootstrap_oracle(args):
+    """Run a WITHHELD oracle suite (ADR-017) against a compiled implementation. The oracle
+    predates and is physically separate from every compiler input; this runner is the
+    maker!=checker wall made executable. Exit 0 iff every case matches its expected exit,
+    else 1 -- a measured behavioural fact about whether this implementation is the same
+    system. It runs the implementation as a subprocess and consults no model."""
+    try:
+        with open(args.oracle, encoding="utf-8-sig") as fh:
+            oracle = json.load(fh)
+    except (OSError, ValueError) as exc:
+        print("[qa_ledger] bootstrap-oracle: unreadable oracle %s: %s" % (args.oracle, exc),
+              file=sys.stderr)
+        sys.exit(2)
+    cases = oracle.get("cases")
+    if not isinstance(cases, list) or not cases:
+        print("[qa_ledger] bootstrap-oracle: oracle has no cases", file=sys.stderr)
+        sys.exit(2)
+    if not os.path.isfile(args.impl):
+        print("[qa_ledger] bootstrap-oracle: no implementation at %s" % args.impl,
+              file=sys.stderr)
+        sys.exit(2)
+    results = [_run_oracle_case(args.impl, c) for c in cases]
+    passed = sum(1 for r in results if r["ok"])
+    failed = [r for r in results if not r["ok"]]
+    report = {"impl": args.impl, "oracle": args.oracle, "total": len(results),
+              "passed": passed, "failed": len(failed),
+              "oracle_green": not failed, "results": results}
+    if args.ledger and args.repo:
+        ledger = _load(args.ledger)
+        _repo_node(ledger, args.repo)
+        rec = {"impl": os.path.basename(args.impl), "oracle": os.path.basename(args.oracle),
+               "total": len(results), "passed": passed, "failed": len(failed),
+               "oracle_green": not failed,
+               "failing": [r["name"] for r in failed], "at": _now()}
+        ledger.setdefault("bootstrap_oracle", []).append(rec)
+        _save(args.ledger, ledger)
+    if args.json:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+    else:
+        print("BOOTSTRAP-ORACLE %s: %d/%d cases pass -- %s"
+              % (os.path.basename(args.impl), passed, len(results),
+                 "ORACLE GREEN (same system on this suite)" if not failed
+                 else "ORACLE RED (%d divergence(s))" % len(failed)))
+        for r in failed:
+            print("  x %s: expected exit %s, got %s%s"
+                  % (r["name"], r["expected"], r["got"],
+                     " (%s)" % r["error"] if r["error"] else ""))
+    sys.exit(0 if not failed else 1)
+
+
+def _impl_metrics(path):
+    """Structural fingerprint of one implementation: physical LOC, AST node count, function
+    and class counts, and the set of imported top-level modules. Deterministic; no judgment."""
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            src = fh.read()
+    except OSError as exc:
+        return {"path": path, "error": "unreadable: %s" % exc}
+    loc = sum(1 for ln in src.splitlines() if ln.strip())
+    try:
+        tree = ast.parse(src)
+    except SyntaxError as exc:
+        return {"path": path, "loc": loc, "error": "unparseable: %s" % exc}
+    funcs = classes = nodes = 0
+    imports = set()
+    for nd in ast.walk(tree):
+        nodes += 1
+        if isinstance(nd, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            funcs += 1
+        elif isinstance(nd, ast.ClassDef):
+            classes += 1
+        elif isinstance(nd, ast.Import):
+            for a in nd.names:
+                imports.add(a.name.split(".")[0])
+        elif isinstance(nd, ast.ImportFrom):
+            if nd.module:
+                imports.add(nd.module.split(".")[0])
+    return {"path": path, "loc": loc, "ast_nodes": nodes, "functions": funcs,
+            "classes": classes, "imports": sorted(imports),
+            "sha256": hashlib.sha256(src.encode("utf-8")).hexdigest()}
+
+
+def cmd_bootstrap_variance(args):
+    """Prove independent compilations of the same canonical package genuinely DIFFER (ADR-017).
+    Reports per-implementation structural metrics and pairwise divergence. ADVISORY: variance
+    is evidence the implementations differ, never a certificate of 'same system' (only the
+    oracle certifies that) and never a gate -- it cannot change an exit code."""
+    metrics = [_impl_metrics(p) for p in args.impls]
+    pairs = []
+    good = [m for m in metrics if "error" not in m]
+    for i in range(len(good)):
+        for j in range(i + 1, len(good)):
+            a, b = good[i], good[j]
+            ia, ib = set(a["imports"]), set(b["imports"])
+            jac = (len(ia & ib) / len(ia | ib)) if (ia or ib) else 1.0
+            pairs.append({"a": os.path.basename(a["path"]), "b": os.path.basename(b["path"]),
+                          "byte_identical": a["sha256"] == b["sha256"],
+                          "loc_delta": abs(a["loc"] - b["loc"]),
+                          "ast_node_delta": abs(a["ast_nodes"] - b["ast_nodes"]),
+                          "function_delta": abs(a["functions"] - b["functions"]),
+                          "import_jaccard": round(jac, 3)})
+    all_distinct = all(not p["byte_identical"] for p in pairs) if pairs else None
+    report = {"implementations": metrics, "pairs": pairs, "all_distinct": all_distinct,
+              "advisory": True}
+    if args.json:
+        print(json.dumps(report, indent=2, ensure_ascii=False))
+    else:
+        for m in metrics:
+            if "error" in m:
+                print("VARIANCE %s: %s" % (os.path.basename(m["path"]), m["error"]))
+            else:
+                print("VARIANCE %s: %d loc, %d ast-nodes, %d fn, %d cls, imports=%s"
+                      % (os.path.basename(m["path"]), m["loc"], m["ast_nodes"],
+                         m["functions"], m["classes"], ",".join(m["imports"]) or "-"))
+        for p in pairs:
+            print("  %s vs %s: %s | dloc=%d dnodes=%d import_jaccard=%.2f"
+                  % (p["a"], p["b"], "IDENTICAL" if p["byte_identical"] else "distinct",
+                     p["loc_delta"], p["ast_node_delta"], p["import_jaccard"]))
+        if all_distinct is not None:
+            print("  all implementations distinct: %s (advisory, never gates)"
+                  % ("yes" if all_distinct else "NO -- convergence, a weak result"))
+    sys.exit(0)
+
+
+# --------------------------------------------------------------------------- #
+# bench  (Diamond M5: the Diamond Bench aggregates the M3/M4 primitives over a
+# set of bounded systems and emits a per-archetype verdict table. It measures
+# REGENERATION FIDELITY of canonical representations, not "which model codes
+# better" -- model identities are anonymized in the headline. Deterministic, no
+# LLM. ADR-018.)
+# --------------------------------------------------------------------------- #
+# min oracle pass-rate for a non-green compilation to still count as PARTIAL (core identity).
+_BENCH_PARTIAL_FLOOR = 0.8
+
+
+def _bench_oracle_all(impl_path, cases):
+    results = [_run_oracle_case(impl_path, c) for c in cases]
+    passed = sum(1 for r in results if r["ok"])
+    return {"passed": passed, "total": len(results), "green": passed == len(results),
+            "failing": [r["name"] for r in results if not r["ok"]]}
+
+
+def _bench_entry(entry_dir, name):
+    """Run compile-validate + the withheld oracle + variance over ONE bench entry and compute
+    its verdict. Reuses the M3/M4 organs unchanged; consults no model. A PASS is >=3 oracle-green
+    compilations that genuinely differ; PARTIAL is core identity with the divergence isolated;
+    FAIL is no green, convergence to near-identical code, or an oracle a degenerate stub can
+    satisfy (non-discriminating); PENDING is an entry not yet fully compiled."""
+    ir_graph, ir_errors = _load_ir_at(os.path.join(entry_dir, IR_FILE))
+    try:
+        with open(os.path.join(entry_dir, "oracle", "ORACLE.json"), encoding="utf-8-sig") as fh:
+            cases = (json.load(fh) or {}).get("cases") or []
+    except (OSError, ValueError):
+        cases = []
+    rec = {"archetype": name, "oracle_cases": len(cases), "compilations": [],
+           "variance": None, "discrimination": None, "verdict": "PENDING", "reason": None}
+    if ir_graph is None or ir_errors or not cases:
+        rec["reason"] = "entry incomplete (missing/invalid IR or oracle)"
+        return rec
+    comp_dirs = sorted(d for d in os.listdir(entry_dir)
+                       if d.startswith("c-") and
+                       os.path.isfile(os.path.join(entry_dir, d, "COMPILATION.json")))
+    for d in comp_dirs:
+        cd = os.path.join(entry_dir, d)
+        cj = os.path.join(cd, "COMPILATION.json")
+        errors, _adv = _validate_compilation(cj, ir_graph)
+        unit, model = None, None
+        try:
+            with open(cj, encoding="utf-8-sig") as fh:
+                c = json.load(fh)
+            src = c.get("source") or []
+            unit = src[0].get("unit") if src else None
+            model = (c.get("compilation_report") or {}).get("model")
+        except (OSError, ValueError, AttributeError, IndexError):
+            pass
+        impl = os.path.join(cd, unit.replace("/", os.sep)) if unit else None
+        ores = (_bench_oracle_all(impl, cases) if impl and os.path.isfile(impl)
+                else {"passed": 0, "total": len(cases), "green": False, "failing": ["<no impl>"]})
+        rec["compilations"].append({"dir": d, "model": model, "impl": impl,
+                                    "compile_valid": not errors, "oracle": ores})
+    impls = rec["compilations"]
+    impl_paths = [i["impl"] for i in impls if i["impl"] and os.path.isfile(i["impl"])]
+    if len(impl_paths) >= 2:
+        metrics = [_impl_metrics(p) for p in impl_paths]
+        shas = [m.get("sha256") for m in metrics if "error" not in m and m.get("sha256")]
+        rec["variance"] = {"all_distinct": len(set(shas)) == len(shas) and len(shas) >= 2,
+                           "metrics": metrics}
+    stub_dir = os.path.join(entry_dir, "stub")
+    stub_green = False
+    if os.path.isdir(stub_dir):
+        stubs = sorted(f for f in os.listdir(stub_dir) if f.endswith(".py"))
+        if stubs:
+            sres = _bench_oracle_all(os.path.join(stub_dir, stubs[0]), cases)
+            stub_green = sres["green"]
+            rec["discrimination"] = {"stub_passed": sres["passed"], "total": sres["total"],
+                                     "stub_green": stub_green}
+    n = len(impls)
+    if n == 0:
+        rec["reason"] = "no compilations yet"
+        return rec                                  # PENDING
+    all_valid = all(i["compile_valid"] for i in impls)
+    greens = sum(1 for i in impls if i["oracle"]["green"])
+    min_rate = min((i["oracle"]["passed"] / i["oracle"]["total"]) if i["oracle"]["total"]
+                   else 0.0 for i in impls)
+    distinct = rec["variance"]["all_distinct"] if rec["variance"] else (n == 1)
+    if stub_green:
+        rec["verdict"], rec["reason"] = "FAIL", ("oracle satisfied by a degenerate stub -- not "
+                                                 "discriminating; the entry proves nothing")
+    elif not all_valid:
+        rec["verdict"], rec["reason"] = "FAIL", "a compilation does not validate against the pinned IR"
+    elif n < 3:
+        rec["verdict"], rec["reason"] = "PENDING", "fewer than 3 compilations (have %d)" % n
+    elif not distinct:
+        rec["verdict"], rec["reason"] = "FAIL", ("implementations converged to a byte-identical "
+                                                 "pair -- a disguised implementation")
+    elif greens == n:
+        rec["verdict"], rec["reason"] = "PASS", ("all %d compilations oracle-green and genuinely "
+                                                 "different -- the same system" % n)
+    elif min_rate >= _BENCH_PARTIAL_FLOOR:
+        rec["verdict"], rec["reason"] = "PARTIAL", ("core identity (min %.0f%% of cases); "
+                                                    "divergence isolated" % (min_rate * 100))
+    else:
+        rec["verdict"], rec["reason"] = "FAIL", ("a compilation below the core-identity floor "
+                                                 "(min %.0f%%)" % (min_rate * 100))
+    return rec
+
+
+def _render_bench_md(table, anon, recs):
+    lines = ["<!-- GENERATED by qa_ledger.py bench (ADR-018) -- every number is a measured run; "
+             "do not hand-edit. -->", "", "# DIAMOND-BENCH", "",
+             "Regeneration fidelity of canonical representations across archetypes. Each row is a "
+             "bounded system compiled blind by independent models through the M3 contract and "
+             "judged by a WITHHELD oracle (M4). Model identities are anonymized here; the mapping "
+             "is published below.", "",
+             "| Archetype | Verdict | Compilers (oracle pass / total) | Distinct | Oracle cases |",
+             "|-----------|---------|--------------------------------|----------|--------------|"]
+    for t in table:
+        dist = "—" if t["distinct"] is None else ("yes" if t["distinct"] else "NO")
+        lines.append("| %s | %s | %s | %s | %d |" % (t["archetype"], t["verdict"],
+                     t["compilers"], dist, t["oracle_cases"]))
+    counts = {}
+    for t in table:
+        counts[t["verdict"]] = counts.get(t["verdict"], 0) + 1
+    lines += ["", "**Coverage:** " + ", ".join("%d %s" % (v, k) for k, v in sorted(counts.items()))
+              + " (of %d entries)." % len(table), "",
+              "**Model map (published, not the headline):** "
+              + (", ".join("%s = %s" % (a, m) for m, a in sorted(anon.items(), key=lambda x: x[1]))
+                 or "none yet") + ".", "",
+              "## Per-entry detail", ""]
+    for r in recs:
+        lines.append("### %s — %s" % (r["archetype"], r["verdict"]))
+        lines.append("*%s*" % (r["reason"] or ""))
+        if r["compilations"]:
+            for i in r["compilations"]:
+                lines.append("- `%s` (%s): oracle %d/%d%s%s" % (
+                    i["dir"], anon.get(i["model"], i["model"] or "?"),
+                    i["oracle"]["passed"], i["oracle"]["total"],
+                    " GREEN" if i["oracle"]["green"] else "",
+                    "" if i["compile_valid"] else " [does not compile-validate]"))
+        if r["discrimination"]:
+            dsc = r["discrimination"]
+            lines.append("- discrimination stub: %d/%d (%s)" % (
+                dsc["stub_passed"], dsc["total"],
+                "NON-DISCRIMINATING" if dsc["stub_green"] else "oracle rejects the stub"))
+        lines.append("")
+    return "\n".join(lines)
+
+
+def cmd_bench(args):
+    if not os.path.isdir(args.dir):
+        print("[qa_ledger] bench: no directory %s" % args.dir, file=sys.stderr)
+        sys.exit(2)
+    entries = sorted(d for d in os.listdir(args.dir)
+                     if os.path.isfile(os.path.join(args.dir, d, IR_FILE)))
+    if not entries:
+        print("[qa_ledger] bench: no entries under %s (an entry is a subdir with %s)"
+              % (args.dir, IR_FILE), file=sys.stderr)
+        sys.exit(2)
+    recs = [_bench_entry(os.path.join(args.dir, e), e) for e in entries]
+    models = sorted({i["model"] for r in recs for i in r["compilations"] if i.get("model")})
+    anon = {m: "M%d" % (k + 1) for k, m in enumerate(models)}
+    table = []
+    for r in recs:
+        cols = ", ".join("%s %d/%d" % (anon.get(i["model"], "?"), i["oracle"]["passed"],
+                                       i["oracle"]["total"]) for i in r["compilations"])
+        table.append({"archetype": r["archetype"], "verdict": r["verdict"],
+                      "compilers": cols or "(none yet)",
+                      "distinct": (r["variance"] or {}).get("all_distinct"),
+                      "oracle_cases": r["oracle_cases"], "reason": r["reason"]})
+    md = _render_bench_md(table, anon, recs)
+    if args.out:
+        with open(args.out, "w", encoding="utf-8", newline="\n") as fh:
+            fh.write(md)
+    if args.json:
+        print(json.dumps({"entries": len(recs), "model_map": anon, "table": table,
+                          "raw": recs}, indent=2, ensure_ascii=False))
+    else:
+        print("BENCH: %d entries" % len(recs))
+        for t in table:
+            dist = "" if t["distinct"] is None else (" | distinct" if t["distinct"]
+                                                     else " | CONVERGED")
+            print("  %-14s %-8s | %s%s" % (t["archetype"], t["verdict"], t["compilers"], dist))
+        if args.out:
+            print("  -> %s" % args.out)
+    sys.exit(0)
+
+
 # --------------------------------------------------------------------------- #
 # facts  (T0 / SYSTEM-FACTS: public claims become compiled artifacts of repo
 # facts -- Diamond applied to Diamond. ADR-012.)
@@ -9390,6 +9746,37 @@ def build_parser():
     pcmi.add_argument("--json", action="store_true")
     pcmi.set_defaults(func=cmd_compile_ingest)
 
+    pbo = sub.add_parser(
+        "bootstrap-oracle",
+        help="run a WITHHELD oracle suite against a compiled implementation (ADR-017); exit 0 "
+             "iff every case matches its expected exit -- the maker!=checker wall, executable")
+    pbo.add_argument("--impl", required=True, help="the compiled implementation to run")
+    pbo.add_argument("--oracle", required=True, help="the withheld ORACLE.json case suite")
+    pbo.add_argument("--ledger", default=None, help="optional: persist the measured result")
+    pbo.add_argument("--repo", default=None, help="repo scope when --ledger is given")
+    pbo.add_argument("--json", action="store_true")
+    pbo.set_defaults(func=cmd_bootstrap_oracle)
+
+    pbv = sub.add_parser(
+        "bootstrap-variance",
+        help="structural metrics + pairwise divergence proving independent compilations "
+             "genuinely differ (ADR-017); ADVISORY evidence, never a gate")
+    pbv.add_argument("--impls", required=True, nargs="+",
+                     help="two or more compiled implementations to compare")
+    pbv.add_argument("--json", action="store_true")
+    pbv.set_defaults(func=cmd_bootstrap_variance)
+
+    pbn = sub.add_parser(
+        "bench",
+        help="the Diamond Bench (ADR-018): per-archetype verdict table over a set of bounded "
+             "systems, aggregating compile-validate + bootstrap-oracle + bootstrap-variance; "
+             "model identities anonymized in the headline; deterministic, no LLM")
+    pbn.add_argument("--dir", required=True,
+                     help="the bench directory; each subdir with an IR.json is an entry")
+    pbn.add_argument("--out", default=None, help="write DIAMOND-BENCH.md here")
+    pbn.add_argument("--json", action="store_true")
+    pbn.set_defaults(func=cmd_bench)
+
     pcr = sub.add_parser("cleanroom",
                          help="run a command against a CLEAN checkout of one commit in a throwaway worktree (ADR-008)")
     pcr.add_argument("--ledger", default="QA-LEDGER.json")

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.73.0",
+  "version": "1.75.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,