@andresmassello/uscha 1.86.0 → 1.87.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.86.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.87.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.062 measured (12 archetypes) — names, not yet semantics
 ```
 
-**What each arrow is, in the engine (kit 1.86.0, 52 subcommands, all measured):**
+**What each arrow is, in the engine (kit 1.87.0, 52 subcommands, all measured):**
 
 | Leg | Subcommands | What it establishes |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andresmassello/uscha",
-  "version": "1.86.0",
+  "version": "1.87.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/SKILL.md

@@ -535,7 +535,10 @@ once logged it caps readiness ≤65 and blocks convergence until resolved with
 criterion carries a stable ID: `- [ ] AC-01 — when X then Y`. A criterion counts as
 CLOSED only when ≥1 GREEN testcase whose name carries the tag (`test_ac1_x`,
 `testAC01X`, `"AC-01: ..."` — IDs normalize by number, `AC-01 == AC_1 == ac1`) exists
-in the ingested JUnit reports AND no tagged testcase is red. The checkbox is the
+in the ingested JUnit reports AND no tagged testcase is red. Since kit 1.87.0 (ADR-036)
+a FAMILY prefix is read the same way: `- [ ] AC-BC-07 — ...` closes on `AC-BC-07_x`,
+`test_ac_bc_7_y` or `AC_BC_7` (normalized to `AC-BC-7`; the family needs a separator on
+both sides — camelCase `testACBC07` is NOT a tag, and `AC-7-x` is still the bare `AC-7`). The checkbox is the
 NARRATIVE; the testcase is the FACT — a checked box without a green tagged test shows
 up as `narrated_only` and does NOT close (measured beats narrated, per criterion).
 A JUnit report older than the repo's source code is treated as STALE (the code changed

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

@@ -142,7 +142,7 @@ def _integrity_hash(data):
     return hashlib.sha256(blob.encode("utf-8")).hexdigest()
 
 
-def _load(path):
+def _load(path, what="ledger", flag="--ledger"):
     """Carga blindada (kit 1.13.0, Topic 34: los recursos compartidos mutables
     incluyen ARCHIVOS). JSON corrupto/truncado = hecho bloqueante con mensaje
     de recuperacion, no un traceback. Si el archivo trae campo integrity
@@ -153,6 +153,12 @@ def _load(path):
     try:
         with open(path, "r", encoding="utf-8") as fh:
             data = json.load(fh)
+    except FileNotFoundError:
+        # what/flag name the file kind and the flag that points at it (1.86.1 re-judge: a
+        # hardcoded "ledger ... --ledger" misled the very first command of a fresh clone,
+        # init --config, and rebuild --baseline).
+        hint = " -- run the dev loop first, or pass --ledger" if what == "ledger" else f" -- pass {flag}"
+        raise SystemExit(f"[qa_ledger] {what} '{path}' not found here{hint}")
     except json.JSONDecodeError as exc:
         raise SystemExit(
             f"[qa_ledger] {path} corrupto (JSON invalido: {exc}). Es un artefacto "
@@ -758,11 +764,43 @@ def _test_evidence_provenance(repo_path, repo_type):
 _AC_TAG = re.compile(
     r"(?:(?<![A-Za-z0-9])[Aa][Cc]|(?<=[a-z])AC)[-_]?0*(\d+)(?!\d)")
 
+# kit 1.87.0 (ADR-036): the FAMILY grammar 'AC-<FAMILY>-<n>' (AC-BC-07, AC-T-24,
+# ac_dd_3). Same explicit boundaries as the bare form, plus a MANDATORY separator
+# on BOTH sides of the family — 'AC-BC-07', 'ac_bc_7', 'AC_T_1'. camelCase families
+# are deliberately NOT supported: 'testACBC07' has no honest split into family +
+# number and stays unmatched.
+# Kept as its OWN pattern so the bare pattern above (and every tag it already
+# produced) stays byte-identical. The two are disjoint by construction: a family
+# must start with a LETTER, so 'AC-01' can never match this one, and the digits of
+# 'AC-BC-07' do not follow 'AC', so it can never match the bare one.
+_AC_TAG_FAM = re.compile(
+    r"(?:(?<![A-Za-z0-9])[Aa][Cc]|(?<=[a-z])AC)"
+    r"[-_]([A-Za-z][A-Za-z0-9]*)[-_]0*(\d+)(?!\d)")
+
+
+def _ac_canon(family, num):
+    """Canonical criterion id for both grammars (ADR-036): 'AC-<int>' for the bare
+    form (AC-01 == AC_1 == ac1) and 'AC-<FAMILY>-<int>' for the family form
+    (AC-T-01 == AC-T-1 == ac_t_1) — python/go test names cannot carry '-', so the
+    separator and the zero padding are never part of the identity."""
+    if family:
+        return "AC-%s-%d" % (family.upper(), int(num))
+    return "AC-%d" % int(num)
+
+
+def _ac_tag_ids(name):
+    """Every criterion id a testcase NAME tags, normalized. Family form first, then
+    bare; the two patterns are disjoint, so the order fixes only the output order."""
+    ids = [_ac_canon(fam, num) for fam, num in _AC_TAG_FAM.findall(name)]
+    ids.extend(_ac_canon(None, num) for num in _AC_TAG.findall(name))
+    return ids
+
 
 def _ac_tags(repo_path, repo_type):
     """Tags AC-n leidos de los NOMBRES de testcase en los reportes JUnit que el
     engine ya ingiere. Devuelve (tags, stale) donde tags = {'AC-n': {'green': x,
-    'red': y}} y stale = [rutas de reportes descartados por viejos]. Un criterio
+    'red': y}} (o 'AC-FAM-n' para la forma con familia, ADR-036 / kit 1.87.0)
+    y stale = [rutas de reportes descartados por viejos]. Un criterio
     cierra MEDIDO solo con >=1 testcase verde y 0 rojos (evidencia roja veta:
     fail-closed). Testcases skipped no cuentan para ningun lado.
 
@@ -806,9 +844,8 @@ def _ac_tags(repo_path, repo_type):
             # cuyo nombre matchea 'ACn' por coincidencia (test_ac3_flow.py) no
             # debe taggear los OTROS tests del mismo archivo/clase.
             blob = tc.get("name") or ""
-            for num in _AC_TAG.findall(blob):
-                d = tags.setdefault(f"AC-{int(num)}",
-                                    {"green": 0, "red": 0, "cases": []})
+            for cid in _ac_tag_ids(blob):
+                d = tags.setdefault(cid, {"green": 0, "red": 0, "cases": []})
                 d[status] += 1
                 # RECEIPT (kit 1.50.0): keep WHICH testcase in WHICH report backed the
                 # verdict -- the name and path were always in scope here and were being
@@ -820,6 +857,24 @@ def _ac_tags(repo_path, repo_type):
     return tags, stale
 
 
+def _sum_ac_tags(ledger):
+    """One derivation of "how many green/red JUnit testcases does AC-n have, summed across
+    every configured repo" -- shared by cmd_readiness (which also keeps up to 8 example case
+    receipts per AC and the combined stale-report list) and cmd_top (which only needs
+    green/red). One place, so the two readouts of the same fact cannot silently disagree."""
+    ac_tags = {}
+    stale_reports = []
+    for rcfg in (ledger.get("config") or {}).get("repos", []):
+        rtags, rstale = _ac_tags(rcfg.get("path", "."), rcfg.get("type", "maven"))
+        for cid, v in rtags.items():
+            d = ac_tags.setdefault(cid, {"green": 0, "red": 0, "cases": []})
+            d["green"] += v["green"]
+            d["red"] += v["red"]
+            d["cases"] = (d["cases"] + v.get("cases", []))[:8]
+        stale_reports.extend(rstale)
+    return ac_tags, sorted(set(stale_reports))
+
+
 def junit_test_count(repo_path, extra_files=None):
     """JUnit-family XML: `pytest --junitxml=...` (python) and jest-junit /
     vitest --reporter=junit (node). Modern emitters WRAP the root:
@@ -1832,7 +1887,7 @@ def _validate_log_step_counts(args):
 
 
 def cmd_init(args):
-    cfg = _load(args.config)
+    cfg = _load(args.config, what="config", flag="--config")
     _validate_init_config(cfg)
     defaults = cfg.get("defaults", {})
     ledger = {
@@ -4189,15 +4244,20 @@ def _canonical_ids(repo_path, acceptance_file):
     except Exception:
         return {}
     for it in items or []:
-        if it.get("id"):                          # normalized "AC-<n>" (numeric ids only)
-            ids[int(it["id"].split("-")[1])] = it["id"]
+        if it.get("id"):
+            # normalized id of EITHER grammar (ADR-036): "AC-<n>" or "AC-<FAMILY>-<n>". Keyed by
+            # the canonical id itself; a bare and a family id can never collide.
+            ids[it["id"]] = it["id"]
     return ids
 
 
 def _match_canonical(statement, canon_ids):
-    m = re.search(r"(?i)\bAC[-_]?0*(\d+)\b", statement)
-    if m and int(m.group(1)) in canon_ids:
-        return canon_ids[int(m.group(1))]
+    """The canonical id an observation's statement names, if any -- read with the same
+    grammar as ACCEPTANCE.md and the JUnit tags (ADR-036), so a statement that mentions
+    'AC-DD-07' anchors the criterion AC-DD-7 exactly as one that mentions 'AC-7' anchors AC-7."""
+    for cid in _ac_tag_ids(statement or ""):
+        if cid in canon_ids:
+            return canon_ids[cid]
     return None
 
 
@@ -6892,6 +6952,9 @@ def cmd_facts(args):
             except OSError as exc:
                 problems.append((path, 0, "file", "unreadable: %s" % exc, ""))
                 continue
+            in_table = False
+            table_names = []
+            table_start = 0
             for n, line in enumerate(lines, 1):
                 # an HTML comment is not a published claim -- the first live run flagged a
                 # section marker (a comment reading "2 Skills") as a drifted count
@@ -6905,6 +6968,28 @@ def cmd_facts(args):
                         actual = _fact_value(facts, key)
                         if claimed != actual:
                             problems.append((path, n, key, claimed, actual))
+                # the parser-surface table (Subcommand/Subcomando header, one `<td class="t">`
+                # row per subcommand) is a claim too, just not a numeric one -- a row can go
+                # missing while the count beside it stays correct (the `top` row did, once).
+                if not in_table:
+                    if re.search(r"<th>Sub ?comm?ando?s?</th>", line, re.I):
+                        in_table, table_names, table_start = True, [], n
+                    continue
+                if "</table>" in line:
+                    in_table = False
+                    want = set(facts["subcommands"]["list"])
+                    got = set(table_names)
+                    for name in sorted(want - got):
+                        problems.append((path, table_start,
+                                         "subcommand table: %s" % name,
+                                         "absent", "present (engine subcommand list)"))
+                    for name in sorted(got - want):
+                        problems.append((path, table_start,
+                                         "subcommand table: %s" % name,
+                                         "present", "absent (not an engine subcommand)"))
+                    continue
+                for m in re.finditer(r'<td class="t">([^<]+)</td>', line):
+                    table_names.append(m.group(1).strip())
         if problems:
             print("FACTUAL DRIFT: %d claim(s) disagree with the derived facts"
                   % len(problems))
@@ -7126,12 +7211,34 @@ def _band(score):
 
 _AC_ID = re.compile(r"(?i)^[*_`]*\s*AC[-_]?0*(\d+)\b[*_`]*[\s.:—–·-]*")
 
+# kit 1.87.0 (ADR-036): the family grammar, same tolerated wrappers/separators.
+# A family starts with a LETTER, so a numeric "family" is not one: '- [ ] AC-7-x'
+# falls through to the bare pattern and reads as AC-7 followed by the text 'x' (the
+# trailing-separator class eats the hyphen, exactly as before ADR-036).
+_AC_ID_FAM = re.compile(
+    r"(?i)^[*_`]*\s*AC[-_]([A-Za-z][A-Za-z0-9]*)[-_]0*(\d+)\b[*_`]*[\s.:—–·-]*")
+
+
+def _ac_id_of(body):
+    """(canonical id, end offset) of the leading AC id of a checkbox body, or
+    (None, 0). The FAMILY form is tried first; the bare form is the fallback, so
+    every id the engine read before ADR-036 still reads exactly the same."""
+    m = _AC_ID_FAM.match(body)
+    if m:
+        return _ac_canon(m.group(1), m.group(2)), m.end()
+    m = _AC_ID.match(body)
+    if m:
+        return _ac_canon(None, m.group(1)), m.end()
+    return None, 0
+
 
 def _parse_acceptance_items(path, section=None):
     """Checkboxes markdown de ACCEPTANCE, con ID trazable opcional por criterio
     ('- [ ] AC-01 — cuando X entonces Y'). Los IDs se normalizan por numero
-    (AC-01 == AC_1 == ac1 — los nombres de test de python/go no admiten '-').
-    Devuelve (items, found); item = {'id': 'AC-n'|None, 'checked', 'text'}."""
+    (AC-01 == AC_1 == ac1 — los nombres de test de python/go no admiten '-') y,
+    desde kit 1.87.0 (ADR-036), tambien por FAMILIA ('- [ ] AC-BC-07 — ...',
+    AC-T-01 == AC-T-1 == ac_t_1). Devuelve (items, found);
+    item = {'id': 'AC-n'|'AC-FAM-n'|None, 'checked', 'text'}."""
     if not path or not os.path.exists(path):
         return [], False
     items = []
@@ -7154,10 +7261,10 @@ def _parse_acceptance_items(path, section=None):
                 else:
                     continue
                 body = s[5:].strip()
-                m = _AC_ID.match(body)
-                items.append({"id": f"AC-{int(m.group(1))}" if m else None,
+                cid, end = _ac_id_of(body)
+                items.append({"id": cid,
                               "checked": checked,
-                              "text": body[m.end():].strip() if m else body})
+                              "text": body[end:].strip()})
     except OSError:
         return [], False
     return items, True
@@ -8108,12 +8215,21 @@ def _top_pct(done, total):
     return 99 if (done < total and pct >= 100) else pct
 
 
-def _top_ac_num(cid):
-    """Stable numeric order for the normalized 'AC-<n>' ids _parse_acceptance_items emits."""
+def _top_ac_key(cid):
+    """Stable order for the normalized ids _parse_acceptance_items emits: the BARE
+    'AC-<n>' criteria first by number, then each letter FAMILY alphabetically and by
+    number inside it (ADR-036). An id in neither shape sorts last instead of raising —
+    the board must still render when the acceptance file carries something unexpected."""
+    parts = str(cid).split("-")
+    if len(parts) >= 3:
+        try:
+            return (1, parts[1].upper(), int(parts[2]))
+        except ValueError:
+            return (2, str(cid), 0)
     try:
-        return int(str(cid).split("-")[1])
+        return (0, "", int(parts[1]))
     except (IndexError, ValueError):
-        return 0
+        return (2, str(cid), 0)
 
 
 def cmd_top(args):
@@ -8133,16 +8249,10 @@ def cmd_top(args):
     acc_path = args.acceptance or (cfg.get("defaults") or {}).get("acceptance_file")
     acc_items, _acc_found = _parse_acceptance_items(acc_path, args.section)
 
-    # measured evidence: the SAME helper readiness closes criteria with (_ac_tags), summed
-    # across repos exactly as cmd_readiness sums it. Re-deriving it here would be the 1.48.1
-    # mirador sin (two derivations of one number, free to disagree).
-    ac_tags = {}
-    for rcfg in cfg.get("repos", []):
-        rtags, _stale = _ac_tags(rcfg.get("path", "."), rcfg.get("type", "maven"))
-        for cid, v in rtags.items():
-            d = ac_tags.setdefault(cid, {"green": 0, "red": 0})
-            d["green"] += v.get("green", 0)
-            d["red"] += v.get("red", 0)
+    # measured evidence: the SAME helper readiness closes criteria with (_ac_tags via
+    # _sum_ac_tags), summed across repos exactly as cmd_readiness sums it. Re-deriving it
+    # here would be the 1.48.1 mirador sin (two derivations of one number, free to disagree).
+    ac_tags, _stale = _sum_ac_tags(ledger)
 
     # quarantine: UNCURATED observations whose statement literally names an AC id. The link
     # is `canonical_match`, a heuristic TEXT match (_match_canonical) -- not a designed
@@ -8191,7 +8301,7 @@ def cmd_top(args):
             seen.add(it["id"])
             ids.append(it["id"])
     obligations = []
-    for cid in sorted(ids, key=_top_ac_num):
+    for cid in sorted(ids, key=_top_ac_key):
         tag, obs = ac_tags.get(cid), quarantine.get(cid)
         # red evidence VETOES (fail-closed, the same rule _ac_closed applies). Measured
         # evidence outranks the lateral QUARANTINE rung so the four buckets partition the
@@ -8213,7 +8323,10 @@ def cmd_top(args):
             "cases_pass": (tag or {}).get("green", 0),
             "cases_total": (tag or {}).get("green", 0) + (tag or {}).get("red", 0),
             "trace": [],                  # no general AC->implementation map yet (ADR-035/5)
-            "quarantine_obs": obs,
+            # red/green evidence outranks the lateral QUARANTINE rung (the state ladder just
+            # above), so an OBS that merely NAMES this AC must not travel into the JSON once
+            # the criterion is already measured -- only a state of QUARANTINE ever carries it.
+            "quarantine_obs": obs if state == "QUARANTINE" else None,
             "ac": None,                   # contract slot with no second honest meaning here
             "age_hours": None})           # no first-seen timestamp exists (ADR-035/1)
 
@@ -8291,18 +8404,7 @@ def cmd_readiness(args):
     # cierra solo con >=1 testcase verde taggeado en los reportes JUnit ya
     # ingeridos (y 0 rojos). El checkbox es RELATO; el testcase es HECHO.
     ac_ids = [i for i in acc_items if i["id"]]
-    ac_tags = {}
-    stale_reports = []
-    for rcfg in ledger["config"].get("repos", []):
-        rtags, rstale = _ac_tags(rcfg.get("path", "."),
-                                 rcfg.get("type", "maven"))
-        for cid, v in rtags.items():
-            d = ac_tags.setdefault(cid, {"green": 0, "red": 0, "cases": []})
-            d["green"] += v["green"]
-            d["red"] += v["red"]
-            d["cases"] = (d["cases"] + v.get("cases", []))[:8]
-        stale_reports.extend(rstale)
-    stale_reports = sorted(set(stale_reports))
+    ac_tags, stale_reports = _sum_ac_tags(ledger)
 
     def _ac_closed(cid):
         d = ac_tags.get(cid)
@@ -8311,13 +8413,13 @@ def cmd_readiness(args):
     # IDs duplicados (ACCEPTANCE mal numerado) cuentan UNA sola vez — si no,
     # un solo test verde cierra "medido" tantos criterios como copias del ID.
     id_list = [i["id"] for i in ac_ids]
-    dupe_ids = sorted({cid for cid in id_list if id_list.count(cid) > 1})
-    unique_ids = sorted(set(id_list))
+    dupe_ids = sorted({cid for cid in id_list if id_list.count(cid) > 1}, key=_top_ac_key)
+    unique_ids = sorted(set(id_list), key=_top_ac_key)
     measured_closed = [cid for cid in unique_ids if _ac_closed(cid)]
     narrated_only = sorted({i["id"] for i in ac_ids
-                            if i["checked"] and not _ac_closed(i["id"])})
+                            if i["checked"] and not _ac_closed(i["id"])}, key=_top_ac_key)
     measured_unchecked = sorted({i["id"] for i in ac_ids
-                                 if not i["checked"] and _ac_closed(i["id"])})
+                                 if not i["checked"] and _ac_closed(i["id"])}, key=_top_ac_key)
     ac_untagged = total - len(ac_ids)
     acc_traceable = bool(ac_ids)
     if acc_traceable:
@@ -8592,8 +8694,9 @@ def cmd_readiness(args):
               f"(--section {args.section!r} matched nothing in the file?) — "
               f"adr/acceptance dimensions at 0")
     if acc_found and total and not acc_traceable:
-        print("  ! acceptance has no traceable IDs ('- [ ] AC-01 — ...') — the "
-              "acceptance dimension falls back to the checkbox ratio (NARRATED, not measured)")
+        print("  ! acceptance has no traceable IDs ('- [ ] AC-01 — ...' or "
+              "'- [ ] AC-BC-01 — ...') — the acceptance dimension falls back to the "
+              "checkbox ratio (NARRATED, not measured)")
     if dupe_ids:
         print(f"  ! duplicate IDs in acceptance (normalized): {', '.join(dupe_ids)} "
               f"— each ID counts ONCE in the acceptance dimension")
@@ -8827,7 +8930,7 @@ def cmd_rebuild(args):
 
 
 def _rebuild_baseline(args):
-    cfg = _load(args.config)
+    cfg = _load(args.config, what="config", flag="--config")
     defaults = cfg.get("defaults", {})
     acc_default = args.acceptance or defaults.get("acceptance_file")
     tol = (args.coverage_tolerance if args.coverage_tolerance is not None
@@ -8853,7 +8956,7 @@ def _rebuild_baseline(args):
 
 
 def _rebuild_compare(args):
-    base = _load(args.baseline)
+    base = _load(args.baseline, what="baseline", flag="--baseline")
     tol = base.get("coverage_tolerance", DEFAULT_COVERAGE_TOLERANCE)
     acc_path = args.acceptance or base.get("acceptance_file")
     section = args.section if args.section is not None else base.get("section")
@@ -10067,8 +10170,9 @@ def _spec_check_text(text):
 def _acceptance_traceability(path):
     """Trazabilidad del ACCEPTANCE (kit 1.10.0): estructura = FACT.
     Bloquea: archivo ausente, cero criterios, CERO criterios con AC-ID, IDs
-    duplicados (tras normalizar: AC-01 == AC-1). Aconseja: criterios sueltos
-    sin ID (no podran cerrar MEDIDO)."""
+    duplicados (tras normalizar: AC-01 == AC-1, y desde kit 1.87.0 / ADR-036
+    AC-BC-07 == AC-BC-7). Aconseja: criterios sueltos sin ID (no podran cerrar
+    MEDIDO)."""
     blockers, advisory = [], []
     items, found = _parse_acceptance_items(path)
     if not found:
@@ -10080,7 +10184,8 @@ def _acceptance_traceability(path):
     ids = [i["id"] for i in items if i["id"]]
     if not ids:
         blockers.append("cero criterios trazables — cada criterio lleva ID "
-                        "estable: '- [ ] AC-01 — cuando X entonces Y'")
+                        "estable: '- [ ] AC-01 — cuando X entonces Y' "
+                        "(o con familia: '- [ ] AC-BC-01 — ...')")
         return blockers, advisory
     dupes = sorted({x for x in ids if ids.count(x) > 1})
     if dupes:
@@ -10800,7 +10905,8 @@ def cmd_doctor(args):
                 elif items:
                     warn(f"ACCEPTANCE without traceable AC-IDs ({len(items)} criterion(s))",
                          "generate it with /uscha-discovery or /uscha-adr-refine "
-                         "(format '- [ ] AC-01 - ...') - without IDs the dominant readiness "
+                         "(format '- [ ] AC-01 - ...', or with a family "
+                         "'- [ ] AC-BC-01 - ...') - without IDs the dominant readiness "
                          "dimension falls back to the checkbox ratio")
                 else:
                     warn(f"ACCEPTANCE {acc} has no criteria (zero checkboxes)")

package/uscha-kit/.claude/skills/uscha-devloop/uscha_top.py

@@ -27,7 +27,6 @@ import subprocess
 import sys
 
 DEFAULT_LEDGER = "QA-LEDGER.json"
-DEFAULT_SIZE = (100, 32)
 FALLBACK_SIZE = (100, 32)
 
 # Lines the board always spends on chrome: the title, 3 rules, 4 KPI lines, the table
@@ -257,6 +256,9 @@ def load_state(state_path=None, ledger=DEFAULT_LEDGER, engine=None):
     if state_path:
         with open(state_path, "r", encoding="utf-8") as fh:
             return json.load(fh)
+    if not os.path.isfile(ledger):
+        raise RuntimeError("ledger '%s' not found here -- run the dev loop first, or pass "
+                           "--ledger" % ledger)
     eng = engine or engine_path()
     if not eng:
         raise RuntimeError("qa_ledger.py not found next to uscha_top.py")

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.86.0",
+  "version": "1.87.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, 52 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.86.0",
+  "version": "1.87.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.86.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.87.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.86.0
+uscha-kit 1.87.0

package/uscha-kit/install-uscha.py

@@ -758,10 +758,12 @@ def _open_best_effort(path):
         pass  # the renderer already printed the absolute path
 
 
-def _mirador_render_path():
-    """The mirador renderer inside this kit (either skill-tree layout)."""
-    for rel in (("skills", "uscha-mirador", "mirador-render.py"),
-                (".claude", "skills", "uscha-mirador", "mirador-render.py")):
+def _kit_script_path(skill_dir, filename):
+    """A script inside this kit, in either skill-tree layout (`skills/<skill_dir>/` or
+    `.claude/skills/<skill_dir>/`) -- the one resolution every sibling script lookup in this
+    file shares, and the same both-layouts precedent `uscha_top.py::engine_path()` uses on
+    its own side of the lookup."""
+    for rel in (("skills", skill_dir, filename), (".claude", "skills", skill_dir, filename)):
         candidate = KIT_ROOT.joinpath(*rel)
         if candidate.is_file():
             return candidate
@@ -772,7 +774,7 @@ def cmd_mirador(args):
     """`uscha mirador` — one command to render + open the project's dashboard.
     No paths, no python: the renderer self-resolves its engine/template siblings, and the
     ledger defaults to the QA-LEDGER.json convention in the current directory."""
-    render = _mirador_render_path()
+    render = _kit_script_path("uscha-mirador", "mirador-render.py")
     if render is None:
         print("[uscha mirador] mirador-render.py not found in the kit", file=sys.stderr)
         raise SystemExit(1)
@@ -807,26 +809,6 @@ def cmd_mirador(args):
         print("\n[uscha mirador] stopped")
 
 
-def _uscha_top_path():
-    """The `uscha top` renderer inside this kit (either skill-tree layout)."""
-    for rel in (("skills", "uscha-devloop", "uscha_top.py"),
-                (".claude", "skills", "uscha-devloop", "uscha_top.py")):
-        candidate = KIT_ROOT.joinpath(*rel)
-        if candidate.is_file():
-            return candidate
-    return None
-
-
-def _qa_ledger_path():
-    """The engine inside this kit (either skill-tree layout)."""
-    for rel in (("skills", "uscha-devloop", "qa_ledger.py"),
-                (".claude", "skills", "uscha-devloop", "qa_ledger.py")):
-        candidate = KIT_ROOT.joinpath(*rel)
-        if candidate.is_file():
-            return candidate
-    return None
-
-
 def cmd_top(args):
     """`uscha top` — the live terminal board of the project's ledger (ADR-031).
     Wired exactly like `mirador`: resolve the sibling script inside the kit and exec it with
@@ -837,7 +819,7 @@ def cmd_top(args):
               "--ledger" % args.ledger, file=sys.stderr)
         raise SystemExit(1)
     if args.json:
-        engine = _qa_ledger_path()
+        engine = _kit_script_path("uscha-devloop", "qa_ledger.py")
         if engine is None:
             print("[uscha top] qa_ledger.py not found in the kit", file=sys.stderr)
             raise SystemExit(1)
@@ -846,7 +828,7 @@ def cmd_top(args):
         if rc:
             raise SystemExit(rc)
         return
-    renderer = _uscha_top_path()
+    renderer = _kit_script_path("uscha-devloop", "uscha_top.py")
     if renderer is None:
         print("[uscha top] uscha_top.py not found in the kit", file=sys.stderr)
         raise SystemExit(1)

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

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

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

@@ -1 +1 @@
-{"AC-T-01": true, "AC-T-02": true, "AC-T-03": true, "AC-T-10": true, "AC-T-04": true, "AC-T-05": true, "AC-T-06": true, "AC-T-09": true, "AC-T-24": true, "AC-T-19": true, "AC-T-23": true, "AC-T-21": true, "AC-T-08": true, "AC-T-07": true, "AC-T-18": true, "AC-T-20": true, "AC-T-22": true}
+{"AC-T-01": true, "AC-T-02": true, "AC-T-03": true, "AC-T-10": true, "AC-T-04": true, "AC-T-05": true, "AC-T-06": true, "AC-T-09": true, "AC-T-24": true, "reg-quarantine-obs-null-on-measured": true, "reg-spec-pin-null-outside-worktree": true, "reg-unreachable-repo-named-not-silent": true, "AC-T-19": true, "reg-empty-project-honest": true, "AC-T-23": true, "AC-T-21": true, "AC-T-08": true, "AC-T-07": true, "AC-T-18": true, "AC-T-20": true, "AC-T-22": true, "reg-ledger-not-found": true}

package/uscha-kit/skills/uscha-devloop/SKILL.md

@@ -535,7 +535,10 @@ once logged it caps readiness ≤65 and blocks convergence until resolved with
 criterion carries a stable ID: `- [ ] AC-01 — when X then Y`. A criterion counts as
 CLOSED only when ≥1 GREEN testcase whose name carries the tag (`test_ac1_x`,
 `testAC01X`, `"AC-01: ..."` — IDs normalize by number, `AC-01 == AC_1 == ac1`) exists
-in the ingested JUnit reports AND no tagged testcase is red. The checkbox is the
+in the ingested JUnit reports AND no tagged testcase is red. Since kit 1.87.0 (ADR-036)
+a FAMILY prefix is read the same way: `- [ ] AC-BC-07 — ...` closes on `AC-BC-07_x`,
+`test_ac_bc_7_y` or `AC_BC_7` (normalized to `AC-BC-7`; the family needs a separator on
+both sides — camelCase `testACBC07` is NOT a tag, and `AC-7-x` is still the bare `AC-7`). The checkbox is the
 NARRATIVE; the testcase is the FACT — a checked box without a green tagged test shows
 up as `narrated_only` and does NOT close (measured beats narrated, per criterion).
 A JUnit report older than the repo's source code is treated as STALE (the code changed

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

@@ -142,7 +142,7 @@ def _integrity_hash(data):
     return hashlib.sha256(blob.encode("utf-8")).hexdigest()
 
 
-def _load(path):
+def _load(path, what="ledger", flag="--ledger"):
     """Carga blindada (kit 1.13.0, Topic 34: los recursos compartidos mutables
     incluyen ARCHIVOS). JSON corrupto/truncado = hecho bloqueante con mensaje
     de recuperacion, no un traceback. Si el archivo trae campo integrity
@@ -153,6 +153,12 @@ def _load(path):
     try:
         with open(path, "r", encoding="utf-8") as fh:
             data = json.load(fh)
+    except FileNotFoundError:
+        # what/flag name the file kind and the flag that points at it (1.86.1 re-judge: a
+        # hardcoded "ledger ... --ledger" misled the very first command of a fresh clone,
+        # init --config, and rebuild --baseline).
+        hint = " -- run the dev loop first, or pass --ledger" if what == "ledger" else f" -- pass {flag}"
+        raise SystemExit(f"[qa_ledger] {what} '{path}' not found here{hint}")
     except json.JSONDecodeError as exc:
         raise SystemExit(
             f"[qa_ledger] {path} corrupto (JSON invalido: {exc}). Es un artefacto "
@@ -758,11 +764,43 @@ def _test_evidence_provenance(repo_path, repo_type):
 _AC_TAG = re.compile(
     r"(?:(?<![A-Za-z0-9])[Aa][Cc]|(?<=[a-z])AC)[-_]?0*(\d+)(?!\d)")
 
+# kit 1.87.0 (ADR-036): the FAMILY grammar 'AC-<FAMILY>-<n>' (AC-BC-07, AC-T-24,
+# ac_dd_3). Same explicit boundaries as the bare form, plus a MANDATORY separator
+# on BOTH sides of the family — 'AC-BC-07', 'ac_bc_7', 'AC_T_1'. camelCase families
+# are deliberately NOT supported: 'testACBC07' has no honest split into family +
+# number and stays unmatched.
+# Kept as its OWN pattern so the bare pattern above (and every tag it already
+# produced) stays byte-identical. The two are disjoint by construction: a family
+# must start with a LETTER, so 'AC-01' can never match this one, and the digits of
+# 'AC-BC-07' do not follow 'AC', so it can never match the bare one.
+_AC_TAG_FAM = re.compile(
+    r"(?:(?<![A-Za-z0-9])[Aa][Cc]|(?<=[a-z])AC)"
+    r"[-_]([A-Za-z][A-Za-z0-9]*)[-_]0*(\d+)(?!\d)")
+
+
+def _ac_canon(family, num):
+    """Canonical criterion id for both grammars (ADR-036): 'AC-<int>' for the bare
+    form (AC-01 == AC_1 == ac1) and 'AC-<FAMILY>-<int>' for the family form
+    (AC-T-01 == AC-T-1 == ac_t_1) — python/go test names cannot carry '-', so the
+    separator and the zero padding are never part of the identity."""
+    if family:
+        return "AC-%s-%d" % (family.upper(), int(num))
+    return "AC-%d" % int(num)
+
+
+def _ac_tag_ids(name):
+    """Every criterion id a testcase NAME tags, normalized. Family form first, then
+    bare; the two patterns are disjoint, so the order fixes only the output order."""
+    ids = [_ac_canon(fam, num) for fam, num in _AC_TAG_FAM.findall(name)]
+    ids.extend(_ac_canon(None, num) for num in _AC_TAG.findall(name))
+    return ids
+
 
 def _ac_tags(repo_path, repo_type):
     """Tags AC-n leidos de los NOMBRES de testcase en los reportes JUnit que el
     engine ya ingiere. Devuelve (tags, stale) donde tags = {'AC-n': {'green': x,
-    'red': y}} y stale = [rutas de reportes descartados por viejos]. Un criterio
+    'red': y}} (o 'AC-FAM-n' para la forma con familia, ADR-036 / kit 1.87.0)
+    y stale = [rutas de reportes descartados por viejos]. Un criterio
     cierra MEDIDO solo con >=1 testcase verde y 0 rojos (evidencia roja veta:
     fail-closed). Testcases skipped no cuentan para ningun lado.
 
@@ -806,9 +844,8 @@ def _ac_tags(repo_path, repo_type):
             # cuyo nombre matchea 'ACn' por coincidencia (test_ac3_flow.py) no
             # debe taggear los OTROS tests del mismo archivo/clase.
             blob = tc.get("name") or ""
-            for num in _AC_TAG.findall(blob):
-                d = tags.setdefault(f"AC-{int(num)}",
-                                    {"green": 0, "red": 0, "cases": []})
+            for cid in _ac_tag_ids(blob):
+                d = tags.setdefault(cid, {"green": 0, "red": 0, "cases": []})
                 d[status] += 1
                 # RECEIPT (kit 1.50.0): keep WHICH testcase in WHICH report backed the
                 # verdict -- the name and path were always in scope here and were being
@@ -820,6 +857,24 @@ def _ac_tags(repo_path, repo_type):
     return tags, stale
 
 
+def _sum_ac_tags(ledger):
+    """One derivation of "how many green/red JUnit testcases does AC-n have, summed across
+    every configured repo" -- shared by cmd_readiness (which also keeps up to 8 example case
+    receipts per AC and the combined stale-report list) and cmd_top (which only needs
+    green/red). One place, so the two readouts of the same fact cannot silently disagree."""
+    ac_tags = {}
+    stale_reports = []
+    for rcfg in (ledger.get("config") or {}).get("repos", []):
+        rtags, rstale = _ac_tags(rcfg.get("path", "."), rcfg.get("type", "maven"))
+        for cid, v in rtags.items():
+            d = ac_tags.setdefault(cid, {"green": 0, "red": 0, "cases": []})
+            d["green"] += v["green"]
+            d["red"] += v["red"]
+            d["cases"] = (d["cases"] + v.get("cases", []))[:8]
+        stale_reports.extend(rstale)
+    return ac_tags, sorted(set(stale_reports))
+
+
 def junit_test_count(repo_path, extra_files=None):
     """JUnit-family XML: `pytest --junitxml=...` (python) and jest-junit /
     vitest --reporter=junit (node). Modern emitters WRAP the root:
@@ -1832,7 +1887,7 @@ def _validate_log_step_counts(args):
 
 
 def cmd_init(args):
-    cfg = _load(args.config)
+    cfg = _load(args.config, what="config", flag="--config")
     _validate_init_config(cfg)
     defaults = cfg.get("defaults", {})
     ledger = {
@@ -4189,15 +4244,20 @@ def _canonical_ids(repo_path, acceptance_file):
     except Exception:
         return {}
     for it in items or []:
-        if it.get("id"):                          # normalized "AC-<n>" (numeric ids only)
-            ids[int(it["id"].split("-")[1])] = it["id"]
+        if it.get("id"):
+            # normalized id of EITHER grammar (ADR-036): "AC-<n>" or "AC-<FAMILY>-<n>". Keyed by
+            # the canonical id itself; a bare and a family id can never collide.
+            ids[it["id"]] = it["id"]
     return ids
 
 
 def _match_canonical(statement, canon_ids):
-    m = re.search(r"(?i)\bAC[-_]?0*(\d+)\b", statement)
-    if m and int(m.group(1)) in canon_ids:
-        return canon_ids[int(m.group(1))]
+    """The canonical id an observation's statement names, if any -- read with the same
+    grammar as ACCEPTANCE.md and the JUnit tags (ADR-036), so a statement that mentions
+    'AC-DD-07' anchors the criterion AC-DD-7 exactly as one that mentions 'AC-7' anchors AC-7."""
+    for cid in _ac_tag_ids(statement or ""):
+        if cid in canon_ids:
+            return canon_ids[cid]
     return None
 
 
@@ -6892,6 +6952,9 @@ def cmd_facts(args):
             except OSError as exc:
                 problems.append((path, 0, "file", "unreadable: %s" % exc, ""))
                 continue
+            in_table = False
+            table_names = []
+            table_start = 0
             for n, line in enumerate(lines, 1):
                 # an HTML comment is not a published claim -- the first live run flagged a
                 # section marker (a comment reading "2 Skills") as a drifted count
@@ -6905,6 +6968,28 @@ def cmd_facts(args):
                         actual = _fact_value(facts, key)
                         if claimed != actual:
                             problems.append((path, n, key, claimed, actual))
+                # the parser-surface table (Subcommand/Subcomando header, one `<td class="t">`
+                # row per subcommand) is a claim too, just not a numeric one -- a row can go
+                # missing while the count beside it stays correct (the `top` row did, once).
+                if not in_table:
+                    if re.search(r"<th>Sub ?comm?ando?s?</th>", line, re.I):
+                        in_table, table_names, table_start = True, [], n
+                    continue
+                if "</table>" in line:
+                    in_table = False
+                    want = set(facts["subcommands"]["list"])
+                    got = set(table_names)
+                    for name in sorted(want - got):
+                        problems.append((path, table_start,
+                                         "subcommand table: %s" % name,
+                                         "absent", "present (engine subcommand list)"))
+                    for name in sorted(got - want):
+                        problems.append((path, table_start,
+                                         "subcommand table: %s" % name,
+                                         "present", "absent (not an engine subcommand)"))
+                    continue
+                for m in re.finditer(r'<td class="t">([^<]+)</td>', line):
+                    table_names.append(m.group(1).strip())
         if problems:
             print("FACTUAL DRIFT: %d claim(s) disagree with the derived facts"
                   % len(problems))
@@ -7126,12 +7211,34 @@ def _band(score):
 
 _AC_ID = re.compile(r"(?i)^[*_`]*\s*AC[-_]?0*(\d+)\b[*_`]*[\s.:—–·-]*")
 
+# kit 1.87.0 (ADR-036): the family grammar, same tolerated wrappers/separators.
+# A family starts with a LETTER, so a numeric "family" is not one: '- [ ] AC-7-x'
+# falls through to the bare pattern and reads as AC-7 followed by the text 'x' (the
+# trailing-separator class eats the hyphen, exactly as before ADR-036).
+_AC_ID_FAM = re.compile(
+    r"(?i)^[*_`]*\s*AC[-_]([A-Za-z][A-Za-z0-9]*)[-_]0*(\d+)\b[*_`]*[\s.:—–·-]*")
+
+
+def _ac_id_of(body):
+    """(canonical id, end offset) of the leading AC id of a checkbox body, or
+    (None, 0). The FAMILY form is tried first; the bare form is the fallback, so
+    every id the engine read before ADR-036 still reads exactly the same."""
+    m = _AC_ID_FAM.match(body)
+    if m:
+        return _ac_canon(m.group(1), m.group(2)), m.end()
+    m = _AC_ID.match(body)
+    if m:
+        return _ac_canon(None, m.group(1)), m.end()
+    return None, 0
+
 
 def _parse_acceptance_items(path, section=None):
     """Checkboxes markdown de ACCEPTANCE, con ID trazable opcional por criterio
     ('- [ ] AC-01 — cuando X entonces Y'). Los IDs se normalizan por numero
-    (AC-01 == AC_1 == ac1 — los nombres de test de python/go no admiten '-').
-    Devuelve (items, found); item = {'id': 'AC-n'|None, 'checked', 'text'}."""
+    (AC-01 == AC_1 == ac1 — los nombres de test de python/go no admiten '-') y,
+    desde kit 1.87.0 (ADR-036), tambien por FAMILIA ('- [ ] AC-BC-07 — ...',
+    AC-T-01 == AC-T-1 == ac_t_1). Devuelve (items, found);
+    item = {'id': 'AC-n'|'AC-FAM-n'|None, 'checked', 'text'}."""
     if not path or not os.path.exists(path):
         return [], False
     items = []
@@ -7154,10 +7261,10 @@ def _parse_acceptance_items(path, section=None):
                 else:
                     continue
                 body = s[5:].strip()
-                m = _AC_ID.match(body)
-                items.append({"id": f"AC-{int(m.group(1))}" if m else None,
+                cid, end = _ac_id_of(body)
+                items.append({"id": cid,
                               "checked": checked,
-                              "text": body[m.end():].strip() if m else body})
+                              "text": body[end:].strip()})
     except OSError:
         return [], False
     return items, True
@@ -8108,12 +8215,21 @@ def _top_pct(done, total):
     return 99 if (done < total and pct >= 100) else pct
 
 
-def _top_ac_num(cid):
-    """Stable numeric order for the normalized 'AC-<n>' ids _parse_acceptance_items emits."""
+def _top_ac_key(cid):
+    """Stable order for the normalized ids _parse_acceptance_items emits: the BARE
+    'AC-<n>' criteria first by number, then each letter FAMILY alphabetically and by
+    number inside it (ADR-036). An id in neither shape sorts last instead of raising —
+    the board must still render when the acceptance file carries something unexpected."""
+    parts = str(cid).split("-")
+    if len(parts) >= 3:
+        try:
+            return (1, parts[1].upper(), int(parts[2]))
+        except ValueError:
+            return (2, str(cid), 0)
     try:
-        return int(str(cid).split("-")[1])
+        return (0, "", int(parts[1]))
     except (IndexError, ValueError):
-        return 0
+        return (2, str(cid), 0)
 
 
 def cmd_top(args):
@@ -8133,16 +8249,10 @@ def cmd_top(args):
     acc_path = args.acceptance or (cfg.get("defaults") or {}).get("acceptance_file")
     acc_items, _acc_found = _parse_acceptance_items(acc_path, args.section)
 
-    # measured evidence: the SAME helper readiness closes criteria with (_ac_tags), summed
-    # across repos exactly as cmd_readiness sums it. Re-deriving it here would be the 1.48.1
-    # mirador sin (two derivations of one number, free to disagree).
-    ac_tags = {}
-    for rcfg in cfg.get("repos", []):
-        rtags, _stale = _ac_tags(rcfg.get("path", "."), rcfg.get("type", "maven"))
-        for cid, v in rtags.items():
-            d = ac_tags.setdefault(cid, {"green": 0, "red": 0})
-            d["green"] += v.get("green", 0)
-            d["red"] += v.get("red", 0)
+    # measured evidence: the SAME helper readiness closes criteria with (_ac_tags via
+    # _sum_ac_tags), summed across repos exactly as cmd_readiness sums it. Re-deriving it
+    # here would be the 1.48.1 mirador sin (two derivations of one number, free to disagree).
+    ac_tags, _stale = _sum_ac_tags(ledger)
 
     # quarantine: UNCURATED observations whose statement literally names an AC id. The link
     # is `canonical_match`, a heuristic TEXT match (_match_canonical) -- not a designed
@@ -8191,7 +8301,7 @@ def cmd_top(args):
             seen.add(it["id"])
             ids.append(it["id"])
     obligations = []
-    for cid in sorted(ids, key=_top_ac_num):
+    for cid in sorted(ids, key=_top_ac_key):
         tag, obs = ac_tags.get(cid), quarantine.get(cid)
         # red evidence VETOES (fail-closed, the same rule _ac_closed applies). Measured
         # evidence outranks the lateral QUARANTINE rung so the four buckets partition the
@@ -8213,7 +8323,10 @@ def cmd_top(args):
             "cases_pass": (tag or {}).get("green", 0),
             "cases_total": (tag or {}).get("green", 0) + (tag or {}).get("red", 0),
             "trace": [],                  # no general AC->implementation map yet (ADR-035/5)
-            "quarantine_obs": obs,
+            # red/green evidence outranks the lateral QUARANTINE rung (the state ladder just
+            # above), so an OBS that merely NAMES this AC must not travel into the JSON once
+            # the criterion is already measured -- only a state of QUARANTINE ever carries it.
+            "quarantine_obs": obs if state == "QUARANTINE" else None,
             "ac": None,                   # contract slot with no second honest meaning here
             "age_hours": None})           # no first-seen timestamp exists (ADR-035/1)
 
@@ -8291,18 +8404,7 @@ def cmd_readiness(args):
     # cierra solo con >=1 testcase verde taggeado en los reportes JUnit ya
     # ingeridos (y 0 rojos). El checkbox es RELATO; el testcase es HECHO.
     ac_ids = [i for i in acc_items if i["id"]]
-    ac_tags = {}
-    stale_reports = []
-    for rcfg in ledger["config"].get("repos", []):
-        rtags, rstale = _ac_tags(rcfg.get("path", "."),
-                                 rcfg.get("type", "maven"))
-        for cid, v in rtags.items():
-            d = ac_tags.setdefault(cid, {"green": 0, "red": 0, "cases": []})
-            d["green"] += v["green"]
-            d["red"] += v["red"]
-            d["cases"] = (d["cases"] + v.get("cases", []))[:8]
-        stale_reports.extend(rstale)
-    stale_reports = sorted(set(stale_reports))
+    ac_tags, stale_reports = _sum_ac_tags(ledger)
 
     def _ac_closed(cid):
         d = ac_tags.get(cid)
@@ -8311,13 +8413,13 @@ def cmd_readiness(args):
     # IDs duplicados (ACCEPTANCE mal numerado) cuentan UNA sola vez — si no,
     # un solo test verde cierra "medido" tantos criterios como copias del ID.
     id_list = [i["id"] for i in ac_ids]
-    dupe_ids = sorted({cid for cid in id_list if id_list.count(cid) > 1})
-    unique_ids = sorted(set(id_list))
+    dupe_ids = sorted({cid for cid in id_list if id_list.count(cid) > 1}, key=_top_ac_key)
+    unique_ids = sorted(set(id_list), key=_top_ac_key)
     measured_closed = [cid for cid in unique_ids if _ac_closed(cid)]
     narrated_only = sorted({i["id"] for i in ac_ids
-                            if i["checked"] and not _ac_closed(i["id"])})
+                            if i["checked"] and not _ac_closed(i["id"])}, key=_top_ac_key)
     measured_unchecked = sorted({i["id"] for i in ac_ids
-                                 if not i["checked"] and _ac_closed(i["id"])})
+                                 if not i["checked"] and _ac_closed(i["id"])}, key=_top_ac_key)
     ac_untagged = total - len(ac_ids)
     acc_traceable = bool(ac_ids)
     if acc_traceable:
@@ -8592,8 +8694,9 @@ def cmd_readiness(args):
               f"(--section {args.section!r} matched nothing in the file?) — "
               f"adr/acceptance dimensions at 0")
     if acc_found and total and not acc_traceable:
-        print("  ! acceptance has no traceable IDs ('- [ ] AC-01 — ...') — the "
-              "acceptance dimension falls back to the checkbox ratio (NARRATED, not measured)")
+        print("  ! acceptance has no traceable IDs ('- [ ] AC-01 — ...' or "
+              "'- [ ] AC-BC-01 — ...') — the acceptance dimension falls back to the "
+              "checkbox ratio (NARRATED, not measured)")
     if dupe_ids:
         print(f"  ! duplicate IDs in acceptance (normalized): {', '.join(dupe_ids)} "
               f"— each ID counts ONCE in the acceptance dimension")
@@ -8827,7 +8930,7 @@ def cmd_rebuild(args):
 
 
 def _rebuild_baseline(args):
-    cfg = _load(args.config)
+    cfg = _load(args.config, what="config", flag="--config")
     defaults = cfg.get("defaults", {})
     acc_default = args.acceptance or defaults.get("acceptance_file")
     tol = (args.coverage_tolerance if args.coverage_tolerance is not None
@@ -8853,7 +8956,7 @@ def _rebuild_baseline(args):
 
 
 def _rebuild_compare(args):
-    base = _load(args.baseline)
+    base = _load(args.baseline, what="baseline", flag="--baseline")
     tol = base.get("coverage_tolerance", DEFAULT_COVERAGE_TOLERANCE)
     acc_path = args.acceptance or base.get("acceptance_file")
     section = args.section if args.section is not None else base.get("section")
@@ -10067,8 +10170,9 @@ def _spec_check_text(text):
 def _acceptance_traceability(path):
     """Trazabilidad del ACCEPTANCE (kit 1.10.0): estructura = FACT.
     Bloquea: archivo ausente, cero criterios, CERO criterios con AC-ID, IDs
-    duplicados (tras normalizar: AC-01 == AC-1). Aconseja: criterios sueltos
-    sin ID (no podran cerrar MEDIDO)."""
+    duplicados (tras normalizar: AC-01 == AC-1, y desde kit 1.87.0 / ADR-036
+    AC-BC-07 == AC-BC-7). Aconseja: criterios sueltos sin ID (no podran cerrar
+    MEDIDO)."""
     blockers, advisory = [], []
     items, found = _parse_acceptance_items(path)
     if not found:
@@ -10080,7 +10184,8 @@ def _acceptance_traceability(path):
     ids = [i["id"] for i in items if i["id"]]
     if not ids:
         blockers.append("cero criterios trazables — cada criterio lleva ID "
-                        "estable: '- [ ] AC-01 — cuando X entonces Y'")
+                        "estable: '- [ ] AC-01 — cuando X entonces Y' "
+                        "(o con familia: '- [ ] AC-BC-01 — ...')")
         return blockers, advisory
     dupes = sorted({x for x in ids if ids.count(x) > 1})
     if dupes:
@@ -10800,7 +10905,8 @@ def cmd_doctor(args):
                 elif items:
                     warn(f"ACCEPTANCE without traceable AC-IDs ({len(items)} criterion(s))",
                          "generate it with /uscha-discovery or /uscha-adr-refine "
-                         "(format '- [ ] AC-01 - ...') - without IDs the dominant readiness "
+                         "(format '- [ ] AC-01 - ...', or with a family "
+                         "'- [ ] AC-BC-01 - ...') - without IDs the dominant readiness "
                          "dimension falls back to the checkbox ratio")
                 else:
                     warn(f"ACCEPTANCE {acc} has no criteria (zero checkboxes)")

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

@@ -27,7 +27,6 @@ import subprocess
 import sys
 
 DEFAULT_LEDGER = "QA-LEDGER.json"
-DEFAULT_SIZE = (100, 32)
 FALLBACK_SIZE = (100, 32)
 
 # Lines the board always spends on chrome: the title, 3 rules, 4 KPI lines, the table
@@ -257,6 +256,9 @@ def load_state(state_path=None, ledger=DEFAULT_LEDGER, engine=None):
     if state_path:
         with open(state_path, "r", encoding="utf-8") as fh:
             return json.load(fh)
+    if not os.path.isfile(ledger):
+        raise RuntimeError("ledger '%s' not found here -- run the dev loop first, or pass "
+                           "--ledger" % ledger)
     eng = engine or engine_path()
     if not eng:
         raise RuntimeError("qa_ledger.py not found next to uscha_top.py")

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

@@ -20,7 +20,12 @@ CONFIG = ROOT / "uscha.config.json"
 OUT = ROOT / ".claude" / "uscha-progress.json"
 
 # tolerant of bold/plain AC ids -- mirrors qa_ledger.py:_AC_ID (AC-01, **AC-01**, `AC_1`)
-_AC = r"[*_`]*\s*AC[-_]?\d+[*_`]*"
+# and, since kit 1.87.0 (ADR-036), the FAMILY form too (AC-BC-07, AC-T-24, `ac_dd_3`).
+# A family starts with a LETTER, so 'AC-7-x' stays the bare AC-7 followed by text --
+# the same fallback order the engine applies. The statusline must never count a
+# criterion the ledger cannot see, nor miss one it can.
+_AC_CORE = r"AC(?:[-_][A-Za-z][A-Za-z0-9]*[-_]|[-_]?)\d+"
+_AC = r"[*_`]*\s*" + _AC_CORE + r"[*_`]*"
 
 
 def _statusline_repo(cfg):
@@ -91,7 +96,8 @@ def _acceptance(state, cfg):
         # a narrated number with the same face as a measured one is the exact dishonesty
         # this kit exists to remove (kit 1.48.1).
         state["acceptance_source"] = "narrated"
-    m = re.search(r"- \[ \]\s*[*_`]*\s*(AC[-_]?\d+)[*_`]*\s*[—–-]\s*(.+)", text, re.IGNORECASE)
+    m = re.search(r"- \[ \]\s*[*_`]*\s*(" + _AC_CORE + r")[*_`]*\s*[—–-]\s*(.+)",
+                  text, re.IGNORECASE)
     if m:
         nxt = re.sub(r"[*_`]", "", m.group(2)).strip()
         state["next"] = f"{m.group(1)}: {nxt[:44]}"

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.86.0",
+  "version": "1.87.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,