@andresmassello/uscha 1.94.0 → 1.95.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.94.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.95.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)
 
@@ -85,7 +85,7 @@ automatic tool can perform: a human verdict.
    from the compiled code: 0.828 measured (12 archetypes) — names AND behaviour
 ```
 
-**What each arrow is, in the engine (kit 1.94.0, 53 subcommands, all measured):**
+**What each arrow is, in the engine (kit 1.95.0, 53 subcommands, all measured):**
 
 | Leg | Subcommands | What it establishes |
 |---|---|---|

package/package.json

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

@@ -206,17 +206,51 @@ def _repo_cfg(ledger, name):
 # measurement: coverage
 # --------------------------------------------------------------------------- #
 def _jacoco_line_counter(xml_path):
-    """Return (missed, covered) for the report-level LINE counter."""
+    """Return (missed, covered) for the report-level LINE counter, or None when the report
+    could not be READ. The distinction is the whole point: a report that measured nothing
+    must never be summed as (0, 0) — that is an invented number, and with one module's XML
+    truncated mid-write it made the surviving modules' percentage look like the project's
+    (audit 1.94.1). Absence is never invented as a number — the rule `cobertura_coverage`
+    already states, applied to the JaCoCo readers too. A report with no LINE counter at all
+    is a real, readable zero and stays (0, 0)."""
     try:
         root = _parse_xml(xml_path).getroot()
-    except ET.ParseError:
-        return 0, 0
+    except (ET.ParseError, OSError, ReportTooLarge):
+        return None
     for c in root.findall("counter"):
         if c.get("type") == "LINE":
-            return int(c.get("missed", 0)), int(c.get("covered", 0))
+            try:
+                return int(c.get("missed", 0)), int(c.get("covered", 0))
+            except (TypeError, ValueError):
+                return None          # a counter that is not a number measured nothing
     return 0, 0
 
 
+def _jacoco_result(files):
+    """Sum the LINE counters of `files`, or report the WHOLE reading unmeasured. Shared by
+    maven/gradle/ant: three hand-copied versions of this sum is how one of them would drift.
+
+    ONE unreadable report makes the reading unmeasured, and an unmeasured reading is
+    (0, 0, 0.0) -- not the survivors' percentage with a false flag beside it. Every other
+    reader in this file returns pct 0.0 whenever report_found is False, and readers of the
+    result rely on it: `readiness` scores coverage as pct/threshold WITHOUT consulting
+    report_found, and `snapshot` prints and persists the pct next to the flag. Handing them
+    the surviving modules' number would score a project on a question nobody asked
+    (audit 1.94.1). The report paths are still listed -- the operator needs to know which
+    files were looked at."""
+    parsed = [_jacoco_line_counter(f) for f in files]
+    reports = [f.replace("\\", "/") for f in files]
+    if not files or any(p is None for p in parsed):
+        return {"covered": 0, "missed": 0, "pct": 0.0, "report_found": False,
+                "reports": reports}
+    missed = sum(p[0] for p in parsed)
+    covered = sum(p[1] for p in parsed)
+    total = missed + covered
+    pct = round(covered / total * 100, 2) if total else 0.0
+    return {"covered": covered, "missed": missed, "pct": pct,
+            "report_found": True, "reports": reports}
+
+
 def maven_coverage(repo_path):
     """
     Prefer an aggregate report if present, else sum per-module reports.
@@ -231,16 +265,7 @@ def maven_coverage(repo_path):
         files = glob.glob(os.path.join(repo_path, "**", "target", "site",
                                        "jacoco", "jacoco.xml"),
                           recursive=True)
-    missed = covered = 0
-    for f in files:
-        m, c = _jacoco_line_counter(f)
-        missed += m
-        covered += c
-    total = missed + covered
-    pct = round(covered / total * 100, 2) if total else 0.0
-    return {"covered": covered, "missed": missed, "pct": pct,
-            "report_found": bool(files),
-            "reports": [f.replace("\\", "/") for f in files]}
+    return _jacoco_result(files)
 
 
 def flutter_coverage(repo_path):
@@ -343,16 +368,7 @@ def gradle_coverage(repo_path):
     if not files:
         files = glob.glob(os.path.join(repo_path, "**", "build", "reports",
                                        "jacoco", "jacoco.xml"), recursive=True)
-    missed = covered = 0
-    for f in files:
-        m, c = _jacoco_line_counter(f)
-        missed += m
-        covered += c
-    total = missed + covered
-    pct = round(covered / total * 100, 2) if total else 0.0
-    return {"covered": covered, "missed": missed, "pct": pct,
-            "report_found": bool(files),
-            "reports": [f.replace("\\", "/") for f in files]}
+    return _jacoco_result(files)
 
 
 def ant_coverage(repo_path):
@@ -360,16 +376,7 @@ def ant_coverage(repo_path):
     report task writes wherever the build file says -- so the report is discovered
     RECURSIVELY by name instead of guessing one convention."""
     files = _ant_reports(repo_path, "jacoco.xml")
-    missed = covered = 0
-    for f in files:
-        m, c = _jacoco_line_counter(f)
-        missed += m
-        covered += c
-    total = missed + covered
-    pct = round(covered / total * 100, 2) if total else 0.0
-    return {"covered": covered, "missed": missed, "pct": pct,
-            "report_found": bool(files),
-            "reports": [f.replace("\\", "/") for f in files]}
+    return _jacoco_result(files)
 
 
 def coverage(repo_path, repo_type):
@@ -1276,7 +1283,15 @@ def _mk_id(tool, rule, fname, line, granularity):
 
 def _find_all(base, patterns, explicit):
     if explicit:
-        return [explicit] if os.path.exists(explicit) else []
+        if not os.path.exists(explicit):
+            # An EXPLICIT path is a claim the operator made about where the report is. When
+            # it is not there, the honest reading is a typo or a build that never wrote it --
+            # not "this linter has no findings". Returning [] made ingest-gate log nothing
+            # and exit 0, so a mistyped --ruff read as a clean gate (audit 1.94.1). Same
+            # fail-closed exit an unparseable report already gets, with the path named.
+            _invalid_static_report(explicit, "linter",
+                                   "no such file (explicit path given, nothing to ingest)")
+        return [explicit]
     found = []
     for pat in patterns:
         found += glob.glob(os.path.join(base, pat), recursive=True)
@@ -3107,7 +3122,7 @@ def cmd_fastpath_eval(args):
         sig("configured", False, "defaults.fast_path present and enabled",
             "config.defaults.fast_path", False)
     else:
-        repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+        repo_path = _scope_path(ledger, args.repo)
         base, base_src = args.base, "--base"
         if base:
             probe = subprocess.run(["git", "rev-parse", "--verify", base + "^{commit}"],
@@ -3694,7 +3709,7 @@ def cmd_cleanroom(args):
     import time
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
-    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    repo_path = _scope_path(ledger, args.repo)
 
     def git(*a, **kw):
         cwd = kw.pop("cwd", repo_path)
@@ -7038,11 +7053,10 @@ def _struct_distance(a, b):
 
 
 def _oracle_hash(arm_dir):
-    try:
-        with open(os.path.join(arm_dir, "oracle", "ORACLE.json"), "rb") as fh:
-            return hashlib.sha256(fh.read()).hexdigest()
-    except OSError:
-        return None
+    # the arm's withheld oracle, hashed by exact bytes -- an arm whose oracle differs by one
+    # byte is a different experiment (cmd_lang_compare refuses the pair). Same rule, and now the
+    # same code, as a manifest unit: `_sha256_file`.
+    return _sha256_file(os.path.join(arm_dir, "oracle", "ORACLE.json"))
 
 
 def cmd_lang_compare(args):
@@ -7533,11 +7547,18 @@ DEFAULT_STATIC_ZERO_AT = 10  # gated-open count at which the static dimension hi
 BANDS = [(95, "READY"), (80, "RELEASE CANDIDATE"), (50, "IN PROGRESS"), (0, "NOT READY")]
 
 
-def _band(score):
-    for floor, label in BANDS:
+def _banded(score, bands):
+    """The label of the highest floor the score reaches. Every band table ends at floor 0, so
+    the last row IS the default -- named once here instead of being restated as a trailing
+    `return` in four callers, where it read as a fifth band nobody could reach (1.95.0)."""
+    for floor, label in bands:
         if score >= floor:
             return label
-    return "NOT READY"
+    return bands[-1][1]
+
+
+def _band(score):
+    return _banded(score, BANDS)
 
 
 _AC_ID = re.compile(r"(?i)^[*_`]*\s*AC[-_]?0*(\d+)\b[*_`]*[\s.:—–·-]*")
@@ -9201,7 +9222,9 @@ def cmd_top(args):
 
     total = len(obligations)
     done, fail, quar = _n("MEASURED_PASS"), _n("MEASURED_FAIL"), _n("QUARANTINE")
-    unmeasured = _n("UNMEASURED") + _n("TRACED")
+    # TRACED/TAGGED are declared in TOP_STATES for the renderer and NEVER assigned above
+    # (v0.1 has no source for either), so only UNMEASURED can carry a count here.
+    unmeasured = _n("UNMEASURED")
     pct = _top_pct(done, total)
     # INV-TOP-06 (ADR-038): DONE never publishes 100% while the seal is MEASURED broken --
     # every criterion green against evidence that no longer belongs to this code state is
@@ -9765,17 +9788,11 @@ _FUNC_RE = re.compile(
 
 
 def _simplicity_band(score):
-    for floor, label in SIMPLICITY_BANDS:
-        if score >= floor:
-            return label
-    return "OVERBUILT"
+    return _banded(score, SIMPLICITY_BANDS)
 
 
 def _rebuild_band(score):
-    for floor, label in REBUILD_BANDS:
-        if score >= floor:
-            return label
-    return "DIVERGE"
+    return _banded(score, REBUILD_BANDS)
 
 
 def _test_file_set(repo_path, repo_type):
@@ -10334,10 +10351,7 @@ _WASTE_COMMENT = ("//", "#", "*", "--", "/*", "*/", '"""', "'''", ";;", "<!--")
 
 
 def _waste_band(score):
-    for floor, label in WASTE_BANDS:
-        if score >= floor:
-            return label
-    return "WASTEFUL"
+    return _banded(score, WASTE_BANDS)
 
 
 def _path_allowed(rel, allow_paths):

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.94.0",
+  "version": "1.95.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, 53 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.94.0",
+  "version": "1.95.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.94.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.95.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.94.0
+uscha-kit 1.95.0

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

@@ -206,17 +206,51 @@ def _repo_cfg(ledger, name):
 # measurement: coverage
 # --------------------------------------------------------------------------- #
 def _jacoco_line_counter(xml_path):
-    """Return (missed, covered) for the report-level LINE counter."""
+    """Return (missed, covered) for the report-level LINE counter, or None when the report
+    could not be READ. The distinction is the whole point: a report that measured nothing
+    must never be summed as (0, 0) — that is an invented number, and with one module's XML
+    truncated mid-write it made the surviving modules' percentage look like the project's
+    (audit 1.94.1). Absence is never invented as a number — the rule `cobertura_coverage`
+    already states, applied to the JaCoCo readers too. A report with no LINE counter at all
+    is a real, readable zero and stays (0, 0)."""
     try:
         root = _parse_xml(xml_path).getroot()
-    except ET.ParseError:
-        return 0, 0
+    except (ET.ParseError, OSError, ReportTooLarge):
+        return None
     for c in root.findall("counter"):
         if c.get("type") == "LINE":
-            return int(c.get("missed", 0)), int(c.get("covered", 0))
+            try:
+                return int(c.get("missed", 0)), int(c.get("covered", 0))
+            except (TypeError, ValueError):
+                return None          # a counter that is not a number measured nothing
     return 0, 0
 
 
+def _jacoco_result(files):
+    """Sum the LINE counters of `files`, or report the WHOLE reading unmeasured. Shared by
+    maven/gradle/ant: three hand-copied versions of this sum is how one of them would drift.
+
+    ONE unreadable report makes the reading unmeasured, and an unmeasured reading is
+    (0, 0, 0.0) -- not the survivors' percentage with a false flag beside it. Every other
+    reader in this file returns pct 0.0 whenever report_found is False, and readers of the
+    result rely on it: `readiness` scores coverage as pct/threshold WITHOUT consulting
+    report_found, and `snapshot` prints and persists the pct next to the flag. Handing them
+    the surviving modules' number would score a project on a question nobody asked
+    (audit 1.94.1). The report paths are still listed -- the operator needs to know which
+    files were looked at."""
+    parsed = [_jacoco_line_counter(f) for f in files]
+    reports = [f.replace("\\", "/") for f in files]
+    if not files or any(p is None for p in parsed):
+        return {"covered": 0, "missed": 0, "pct": 0.0, "report_found": False,
+                "reports": reports}
+    missed = sum(p[0] for p in parsed)
+    covered = sum(p[1] for p in parsed)
+    total = missed + covered
+    pct = round(covered / total * 100, 2) if total else 0.0
+    return {"covered": covered, "missed": missed, "pct": pct,
+            "report_found": True, "reports": reports}
+
+
 def maven_coverage(repo_path):
     """
     Prefer an aggregate report if present, else sum per-module reports.
@@ -231,16 +265,7 @@ def maven_coverage(repo_path):
         files = glob.glob(os.path.join(repo_path, "**", "target", "site",
                                        "jacoco", "jacoco.xml"),
                           recursive=True)
-    missed = covered = 0
-    for f in files:
-        m, c = _jacoco_line_counter(f)
-        missed += m
-        covered += c
-    total = missed + covered
-    pct = round(covered / total * 100, 2) if total else 0.0
-    return {"covered": covered, "missed": missed, "pct": pct,
-            "report_found": bool(files),
-            "reports": [f.replace("\\", "/") for f in files]}
+    return _jacoco_result(files)
 
 
 def flutter_coverage(repo_path):
@@ -343,16 +368,7 @@ def gradle_coverage(repo_path):
     if not files:
         files = glob.glob(os.path.join(repo_path, "**", "build", "reports",
                                        "jacoco", "jacoco.xml"), recursive=True)
-    missed = covered = 0
-    for f in files:
-        m, c = _jacoco_line_counter(f)
-        missed += m
-        covered += c
-    total = missed + covered
-    pct = round(covered / total * 100, 2) if total else 0.0
-    return {"covered": covered, "missed": missed, "pct": pct,
-            "report_found": bool(files),
-            "reports": [f.replace("\\", "/") for f in files]}
+    return _jacoco_result(files)
 
 
 def ant_coverage(repo_path):
@@ -360,16 +376,7 @@ def ant_coverage(repo_path):
     report task writes wherever the build file says -- so the report is discovered
     RECURSIVELY by name instead of guessing one convention."""
     files = _ant_reports(repo_path, "jacoco.xml")
-    missed = covered = 0
-    for f in files:
-        m, c = _jacoco_line_counter(f)
-        missed += m
-        covered += c
-    total = missed + covered
-    pct = round(covered / total * 100, 2) if total else 0.0
-    return {"covered": covered, "missed": missed, "pct": pct,
-            "report_found": bool(files),
-            "reports": [f.replace("\\", "/") for f in files]}
+    return _jacoco_result(files)
 
 
 def coverage(repo_path, repo_type):
@@ -1276,7 +1283,15 @@ def _mk_id(tool, rule, fname, line, granularity):
 
 def _find_all(base, patterns, explicit):
     if explicit:
-        return [explicit] if os.path.exists(explicit) else []
+        if not os.path.exists(explicit):
+            # An EXPLICIT path is a claim the operator made about where the report is. When
+            # it is not there, the honest reading is a typo or a build that never wrote it --
+            # not "this linter has no findings". Returning [] made ingest-gate log nothing
+            # and exit 0, so a mistyped --ruff read as a clean gate (audit 1.94.1). Same
+            # fail-closed exit an unparseable report already gets, with the path named.
+            _invalid_static_report(explicit, "linter",
+                                   "no such file (explicit path given, nothing to ingest)")
+        return [explicit]
     found = []
     for pat in patterns:
         found += glob.glob(os.path.join(base, pat), recursive=True)
@@ -3107,7 +3122,7 @@ def cmd_fastpath_eval(args):
         sig("configured", False, "defaults.fast_path present and enabled",
             "config.defaults.fast_path", False)
     else:
-        repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+        repo_path = _scope_path(ledger, args.repo)
         base, base_src = args.base, "--base"
         if base:
             probe = subprocess.run(["git", "rev-parse", "--verify", base + "^{commit}"],
@@ -3694,7 +3709,7 @@ def cmd_cleanroom(args):
     import time
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
-    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    repo_path = _scope_path(ledger, args.repo)
 
     def git(*a, **kw):
         cwd = kw.pop("cwd", repo_path)
@@ -7038,11 +7053,10 @@ def _struct_distance(a, b):
 
 
 def _oracle_hash(arm_dir):
-    try:
-        with open(os.path.join(arm_dir, "oracle", "ORACLE.json"), "rb") as fh:
-            return hashlib.sha256(fh.read()).hexdigest()
-    except OSError:
-        return None
+    # the arm's withheld oracle, hashed by exact bytes -- an arm whose oracle differs by one
+    # byte is a different experiment (cmd_lang_compare refuses the pair). Same rule, and now the
+    # same code, as a manifest unit: `_sha256_file`.
+    return _sha256_file(os.path.join(arm_dir, "oracle", "ORACLE.json"))
 
 
 def cmd_lang_compare(args):
@@ -7533,11 +7547,18 @@ DEFAULT_STATIC_ZERO_AT = 10  # gated-open count at which the static dimension hi
 BANDS = [(95, "READY"), (80, "RELEASE CANDIDATE"), (50, "IN PROGRESS"), (0, "NOT READY")]
 
 
-def _band(score):
-    for floor, label in BANDS:
+def _banded(score, bands):
+    """The label of the highest floor the score reaches. Every band table ends at floor 0, so
+    the last row IS the default -- named once here instead of being restated as a trailing
+    `return` in four callers, where it read as a fifth band nobody could reach (1.95.0)."""
+    for floor, label in bands:
         if score >= floor:
             return label
-    return "NOT READY"
+    return bands[-1][1]
+
+
+def _band(score):
+    return _banded(score, BANDS)
 
 
 _AC_ID = re.compile(r"(?i)^[*_`]*\s*AC[-_]?0*(\d+)\b[*_`]*[\s.:—–·-]*")
@@ -9201,7 +9222,9 @@ def cmd_top(args):
 
     total = len(obligations)
     done, fail, quar = _n("MEASURED_PASS"), _n("MEASURED_FAIL"), _n("QUARANTINE")
-    unmeasured = _n("UNMEASURED") + _n("TRACED")
+    # TRACED/TAGGED are declared in TOP_STATES for the renderer and NEVER assigned above
+    # (v0.1 has no source for either), so only UNMEASURED can carry a count here.
+    unmeasured = _n("UNMEASURED")
     pct = _top_pct(done, total)
     # INV-TOP-06 (ADR-038): DONE never publishes 100% while the seal is MEASURED broken --
     # every criterion green against evidence that no longer belongs to this code state is
@@ -9765,17 +9788,11 @@ _FUNC_RE = re.compile(
 
 
 def _simplicity_band(score):
-    for floor, label in SIMPLICITY_BANDS:
-        if score >= floor:
-            return label
-    return "OVERBUILT"
+    return _banded(score, SIMPLICITY_BANDS)
 
 
 def _rebuild_band(score):
-    for floor, label in REBUILD_BANDS:
-        if score >= floor:
-            return label
-    return "DIVERGE"
+    return _banded(score, REBUILD_BANDS)
 
 
 def _test_file_set(repo_path, repo_type):
@@ -10334,10 +10351,7 @@ _WASTE_COMMENT = ("//", "#", "*", "--", "/*", "*/", '"""', "'''", ";;", "<!--")
 
 
 def _waste_band(score):
-    for floor, label in WASTE_BANDS:
-        if score >= floor:
-            return label
-    return "WASTEFUL"
+    return _banded(score, WASTE_BANDS)
 
 
 def _path_allowed(rel, allow_paths):

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.94.0",
+  "version": "1.95.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,