@andresmassello/uscha 1.62.0 → 1.64.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.62.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.64.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`, 32 subcommands, Python stdlib) that ingests
+**A measurement engine** (`qa_ledger.py`, 34 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.62.0",
+  "version": "1.64.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

@@ -2629,6 +2629,58 @@ def _derive_phase(ledger, name, node, k, qa_order):
         reasons.append("la evidencia medida no contiene tests ejecutados")
     _go, sev = _gate_open_and_sev(node)
     blk = sev.get("BLOCKER", 0) + sev.get("CRITICAL", 0)
+    # clean-room gate (ADR-008). OPT-IN: no clean_room block, or mode "off", and this does not
+    # exist -- behavior identical to earlier releases. Declared "final": pr-ready additionally
+    # requires clean-room evidence that is GREEN and pinned to the CURRENT HEAD. A new commit
+    # makes the previous run stale for the gate, the same staleness posture the rest of the
+    # engine takes: evidence certifies the thing it was measured against, nothing later.
+    # curation gate (ADR-009, INV-CURATION-01). In use the moment discovery/ exists --
+    # creating candidates IS the opt-in. Fail-closed both ways: an unjudged candidate blocks,
+    # and a malformation blocks too, because "could not validate" must never read as judged.
+    _cu_cfg = (_repo_cfg(ledger, name) if name != "integration"
+               else {"path": "."})               # synthetic scope: never in config["repos"]
+    _cu = _curation_state(_cu_cfg.get("path", "."))
+    if _cu is not None:
+        if _cu["malformed"] or _cu["ledger_errors"] or _cu["append_only"] == "violation":
+            _bits = [m["candidate"] for m in _cu["malformed"][:3]]
+            if _cu["ledger_errors"]:
+                _bits.append(BEHAVIOR_LEDGER_FILE + " malformado")
+            if _cu["append_only"] == "violation":
+                _bits.append(BEHAVIOR_LEDGER_FILE + " editado (append-only)")
+            reasons.append("curation invalida: " + "; ".join(_bits)
+                           + " -- corregir antes de avanzar")
+            conv = False
+        elif _cu["unjudged"]:
+            reasons.append("candidata(s) sin veredicto humano: "
+                           + ", ".join(_cu["unjudged"][:3])
+                           + (" (+%d)" % (len(_cu["unjudged"]) - 3)
+                              if len(_cu["unjudged"]) > 3 else "")
+                           + " -- INV-CURATION-01: sin juicio no hay promocion")
+            conv = False
+    _cr = _cr_cfg(ledger)
+    if _cr and _cr.get("mode") == "final":
+        _head = None
+        _hr = None
+        _crcfg = (_repo_cfg(ledger, name) if name != "integration"
+                  else {"path": "."})          # synthetic scope: never in config["repos"]
+        try:
+            _hr = subprocess.run(["git", "rev-parse", "HEAD"],
+                                 cwd=_crcfg.get("path", "."),
+                                 capture_output=True, text=True, encoding="utf-8",
+                                 errors="replace")
+        except OSError:
+            _hr = None
+        if _hr is not None and _hr.returncode == 0:
+            _head = _hr.stdout.strip()
+        _run = _cr_latest(ledger, name, _head) if _head else None
+        if not _head:
+            reasons.append("clean-room declarado pero no se pudo resolver HEAD "
+                           "(no se mide, no se aprueba)")
+            conv = False
+        elif not _run or not _run.get("ok"):
+            reasons.append("falta clean-room verde para %s (evidencia del arbol no "
+                           "certifica el commit)" % _head[:8])
+            conv = False
     if conv and tests_measured_green and not tests_red and blk == 0:
         evidence = ["ciclo de agente limpio", "tests verdes (medidos)",
                     "0 BLOCKER/CRITICAL abiertos"]
@@ -3355,6 +3407,390 @@ def cmd_golden_coverage(args):
 
 
 
+# --------------------------------------------------------------------------- #
+# cleanroom  (ADR-008: verify the COMMIT, not the tree -- opt-in, human-supplied command)
+# --------------------------------------------------------------------------- #
+
+CLEAN_ROOM_KEY = "clean_room"
+
+
+def _cr_cfg(ledger):
+    cfg = ledger["config"].get("defaults", {}).get(CLEAN_ROOM_KEY)
+    return cfg if isinstance(cfg, dict) else None
+
+
+def _cr_latest(ledger, repo, ref=None):
+    """Latest clean-room record for a repo, optionally pinned to one ref."""
+    runs = [e for e in ledger.get(CLEAN_ROOM_KEY, [])
+            if e.get("repo") == repo and (ref is None or e.get("ref") == ref)]
+    return runs[-1] if runs else None
+
+
+def cmd_cleanroom(args):
+    """Run a command against a CLEAN CHECKOUT of one commit, in a throwaway worktree.
+
+    Evidence produced in the maker's tree is true of the TREE; this produces evidence true
+    of the COMMIT. As a side effect maker != checker becomes physical: the worktree cannot
+    see uncommitted state.
+
+    The engine does NOT decide what to run. The command arrives explicitly via --run, the
+    same contract golden-coverage uses for --harness: the engine owns what it can guarantee
+    (isolation, the SHA binding, cleanup) and never guesses what a project's suite is.
+    Reading test_command_* from config and executing it would make the engine an executor
+    of config-supplied shell, which it is not (ADR-008)."""
+    import time
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+
+    def git(*a, **kw):
+        cwd = kw.pop("cwd", repo_path)
+        try:
+            return subprocess.run(["git"] + list(a), cwd=cwd, capture_output=True,
+                                  text=True, encoding="utf-8", errors="replace")
+        except OSError:
+            return None
+
+    rev = git("rev-parse", "--verify", (args.ref or "HEAD") + "^{commit}")
+    if rev is None or rev.returncode != 0 or not rev.stdout.strip():
+        print("[qa_ledger] cannot resolve ref %r in %s - nothing to verify."
+              % (args.ref or "HEAD", repo_path), file=sys.stderr)
+        sys.exit(2)
+    sha = rev.stdout.strip()
+
+    wt = tempfile.mkdtemp(prefix="uscha-cleanroom-")
+    target = os.path.join(wt, "tree")
+    started = time.time()
+    record = {"repo": args.repo, "ref": sha, "at": _now(), "ok": False,
+              "status": None, "wall_ms": None, "worktree_sha": None}
+    keep = bool((_cr_cfg(ledger) or {}).get("keep_worktree_on_failure"))
+    try:
+        add = git("worktree", "add", "--detach", target, sha)
+        if add is None or add.returncode != 0:
+            record["status"] = "WORKTREE_FAILED"
+            print("[qa_ledger] git worktree add failed:\n%s"
+                  % ((add.stderr if add else "git unavailable") or "")[-800:], file=sys.stderr)
+        else:
+            # a worktree of a commit must be clean by construction; if it is not, something
+            # (a smudge filter, a hook, a stale index) intervened and the isolation claim is
+            # already false. Say so rather than measure in it.
+            st = git("status", "--porcelain", cwd=target)
+            if st is None or st.returncode != 0 or st.stdout.strip():
+                record["status"] = "WORKTREE_DIRTY"
+            else:
+                record["worktree_sha"] = sha
+                if args.setup:
+                    r = subprocess.run(args.setup, cwd=target, shell=True,
+                                       capture_output=True, text=True,
+                                       encoding="utf-8", errors="replace")
+                    if r.returncode != 0:
+                        record["status"] = "SETUP_FAILED"
+                        print((r.stderr or "")[-800:], file=sys.stderr)
+                if record["status"] is None:
+                    r = subprocess.run(args.run, cwd=target, shell=True,
+                                       capture_output=True, text=True,
+                                       encoding="utf-8", errors="replace")
+                    record["exit_code"] = r.returncode
+                    record["status"] = "GREEN" if r.returncode == 0 else "RED"
+                    record["ok"] = r.returncode == 0
+                    if r.returncode != 0:
+                        print((r.stdout or "")[-1500:], file=sys.stderr)
+    finally:
+        record["wall_ms"] = int((time.time() - started) * 1000)
+        # Cleanup is unconditional unless the human asked to inspect a FAILURE: a zombie
+        # worktree is a defect, and `git worktree remove` alone leaves the admin entry behind.
+        if record["ok"] or not keep:
+            git("worktree", "remove", "--force", target)
+            git("worktree", "prune")
+            shutil.rmtree(wt, ignore_errors=True)
+            # VERIFY the removal instead of assuming it. rmtree(ignore_errors=True) and a
+            # discarded git return code can both fail in silence -- typically on Windows,
+            # where a handle the caller's command left open blocks removal.
+            if os.path.exists(target):
+                record["cleanup_failed"] = True
+                record["worktree_kept_at"] = target
+                print("[qa_ledger] WARNING: the clean-room worktree could not be removed and "
+                      "is still at %s (a process may still hold a handle). Remove it with: "
+                      "git worktree remove --force %s && git worktree prune"
+                      % (target, target), file=sys.stderr)
+        else:
+            record["worktree_kept_at"] = target
+
+    ledger.setdefault(CLEAN_ROOM_KEY, []).append(record)
+    ledger["step_counter"] += 1
+    ledger["steps"].append({"n": ledger["step_counter"], "at": _now(),
+                            "kind": "cleanroom", "repo": args.repo})
+    _save(args.ledger, ledger)
+
+    if args.json:
+        print(json.dumps(record, indent=2, ensure_ascii=False))
+    else:
+        print("CLEANROOM %s @ %s: %s (%.1fs)"
+              % (args.repo, sha[:8], record["status"], (record["wall_ms"] or 0) / 1000.0))
+        if record.get("worktree_kept_at"):
+            print("  worktree kept for inspection: " + record["worktree_kept_at"])
+    sys.exit(0 if record["ok"] else 1)
+
+
+
+# --------------------------------------------------------------------------- #
+# curation  (ADR-009/010: candidates in quarantine, verdicts in the behavior
+# ledger, and a promotion gate the ENGINE measures -- INV-CURATION-01)
+# --------------------------------------------------------------------------- #
+
+BEHAVIOR_LEDGER_FILE = "BEHAVIOR-LEDGER.md"
+CANDIDATE_DIR = "discovery"
+_BL_VERDICTS = ("preserve", "fix", "undefined")
+
+
+def _parse_candidate(path):
+    """Parse one candidate's frontmatter. Returns (data, errors); a candidate with errors
+    is INVALID and named -- never silently skipped, because a skipped candidate would walk
+    past the promotion gate unjudged."""
+    errors = []
+    try:
+        # utf-8-sig: a BOM-adding editor must not turn a well-formed candidate into a
+        # false "no frontmatter" (fresh-review LOW)
+        with open(path, encoding="utf-8-sig", errors="replace") as fh:
+            lines = fh.read().splitlines()
+    except OSError as exc:
+        return None, ["unreadable: %s" % exc]
+    if not lines or lines[0].strip() != "---":
+        return None, ["no frontmatter (evidence/confidence are mandatory, ADR-009)"]
+    fm, i = [], 1
+    while i < len(lines) and lines[i].strip() != "---":
+        fm.append(lines[i]); i += 1
+    if i >= len(lines):
+        return None, ["frontmatter never closes"]
+    etype, refs, conf, in_refs, in_evidence = None, [], None, False, False
+    for ln in fm:
+        s = ln.strip()
+        indented = ln.startswith((" ", "\t"))
+        if s.startswith("evidence:") and not indented:
+            in_evidence = True; in_refs = False
+        elif s.startswith("type:"):
+            # scope + duplicates are MALFORMATION, not last-value-wins: a stray top-level
+            # type:/confidence: after the evidence block silently overrode the nested one
+            # and walked straight past the inference->low invariant (fresh-review HIGH).
+            if not (in_evidence and indented):
+                errors.append("type: outside the evidence block")
+            elif etype is not None:
+                errors.append("duplicate type: declaration")
+            else:
+                etype = s[len("type:"):].strip().strip("\x27\x22")
+            in_refs = False
+        elif s.startswith("refs:"):
+            if not (in_evidence and indented):
+                errors.append("refs: outside the evidence block")
+            in_refs = in_evidence and indented
+        elif s.startswith("confidence:") and not indented:
+            if conf is not None:
+                errors.append("duplicate confidence: declaration")
+            else:
+                conf = s[len("confidence:"):].strip().strip("\x27\x22")
+            in_refs = False; in_evidence = False
+        elif in_refs and s.startswith("- "):
+            refs.append(s[2:].strip().strip("\x27\x22"))
+        elif s and not indented:
+            in_refs = False; in_evidence = False
+    if etype not in ("test", "code", "inference"):
+        errors.append("evidence.type %r (expected test|code|inference)" % etype)
+    if not refs:
+        errors.append("evidence.refs is empty (a candidate without evidence is a guess)")
+    if conf not in ("high", "medium", "low"):
+        errors.append("confidence %r (expected high|medium|low)" % conf)
+    if etype == "inference" and conf != "low":
+        errors.append("inference is ALWAYS low confidence (ADR-009); %r declared" % conf)
+    return {"type": etype, "refs": refs, "confidence": conf}, errors
+
+
+def _resolve_ref(repo_path, ref):
+    """A ref must point at something REAL: `path`, `path:N`, `path:N-M` or `path#name`.
+    Returns None when it resolves, else the reason."""
+    frag = None
+    if "#" in ref:
+        ref, frag = ref.split("#", 1)
+    span = None
+    m = re.match(r"^(.*?):(\d+)(?:-(\d+))?$", ref)
+    if m:
+        ref = m.group(1)
+        span = (int(m.group(2)), int(m.group(3) or m.group(2)))
+    full = os.path.join(repo_path, ref.replace("/", os.sep))
+    if _gc_rel(full, repo_path) is None:
+        # an absolute path makes os.path.join DISCARD repo_path entirely, and ../ walks
+        # out -- either way the "evidence" would point outside the legacy tree it claims
+        # to evidence (fresh-review HIGH). Confinement is part of resolution.
+        return "ref escapes the repo tree: %s" % ref
+    if not os.path.isfile(full):
+        return "file not found: %s" % ref
+    if span or frag:
+        try:
+            with open(full, encoding="utf-8", errors="replace") as fh:
+                body = fh.read()
+        except OSError as exc:
+            return "unreadable: %s" % exc
+        if span:
+            n = body.count("\n") + 1
+            if span[0] < 1 or span[1] > n or span[0] > span[1]:
+                return "lines %d-%d out of range (file has %d)" % (span[0], span[1], n)
+        if frag and frag not in body:
+            return "fragment %r not found in %s" % (frag, ref)
+    return None
+
+
+def _load_behavior_ledger(path):
+    """Strict parse of the verdict table. Returns (rows, errors). Malformed is an ERROR,
+    never a degrade: under the promotion gate, a silent "no verdicts" would UNBLOCK exactly
+    what the gate guards (same posture as golden.scrub.json)."""
+    rows, errors = [], []
+    try:
+        with open(path, encoding="utf-8", errors="replace") as fh:
+            lines = fh.read().splitlines()
+    except OSError as exc:
+        return [], ["unreadable: %s" % exc]
+    for n, ln in enumerate(lines, 1):
+        s = ln.strip()
+        if not s.startswith("|"):
+            continue
+        cells = [c.strip() for c in s.strip("|").split("|")]
+        if cells and all(c and set(c) <= set("-: ") for c in cells):
+            continue                                    # separator row (empty cells are NOT)
+        low = [c.lower() for c in cells]
+        if "candidate" in low and "verdict" in low:
+            continue                                    # header row
+        if len(cells) != 6:
+            errors.append("line %d: %d cells, expected 6 (# | candidate | evidence | "
+                          "confidence | verdict | adr)" % (n, len(cells)))
+            continue
+        _, cand, _ev, _conf, verdict, adr = cells
+        if verdict not in _BL_VERDICTS:
+            errors.append("line %d: verdict %r is not one of %s -- a fourth state is "
+                          "malformation, not an option" % (n, verdict, "/".join(_BL_VERDICTS)))
+        if not re.match(r"^ADR-\S+$", adr):
+            errors.append("line %d: adr ref %r -- no verdict without its why (ADR-010)"
+                          % (n, adr))
+        if not cand:
+            errors.append("line %d: empty candidate" % n)
+        rows.append({"candidate": cand, "verdict": verdict, "adr": adr, "line": n})
+    return rows, errors
+
+
+def _bl_append_only(repo_path, rel):
+    """The rows in HEAD must be a byte-identical prefix of the working file. Deliberately
+    blunt (ADR-010): an audit trail that tolerates rewriting is not an audit trail.
+    Returns "ok" | "new" | "violation" | "unmeasured"."""
+    try:
+        # probe the repo FIRST: "git failed entirely" and "file not in HEAD yet" are
+        # different answers, and conflating them turned no-git into a silent "new"
+        # (caught by T120's AC-RD-05 -- unmeasured must never be mistaken for anything).
+        probe = subprocess.run(["git", "rev-parse", "HEAD"], cwd=repo_path,
+                               capture_output=True)
+        if probe.returncode != 0:
+            return "unmeasured"
+        r = subprocess.run(["git", "show", "HEAD:" + rel.replace(os.sep, "/")],
+                           cwd=repo_path, capture_output=True)
+    except OSError:
+        return "unmeasured"
+    if r.returncode != 0:
+        return "new"                                   # not in HEAD yet
+    try:
+        with open(os.path.join(repo_path, rel), "rb") as fh:
+            cur = fh.read()
+    except OSError:
+        return "violation"                             # in HEAD but gone from the tree
+    # normalize line endings on BOTH sides: with core.autocrlf, git stores LF and checks out
+    # CRLF, so a raw byte compare reads that translation as tampering on every Windows box
+    # (found by the first probe). Git itself treats line endings as non-content; so do we.
+    # A verdict edit still cannot hide in a CRLF flip.
+    cur_n = cur.replace(b"\r\n", b"\n")
+    head_n = r.stdout.replace(b"\r\n", b"\n")
+    return "ok" if cur_n.startswith(head_n) else "violation"
+
+
+def _curation_state(repo_path):
+    """Everything the gate needs, from one scan. None = feature unused (no discovery/):
+    behavior identical to a release where this code does not exist (AC-RD-07)."""
+    disc = os.path.join(repo_path, CANDIDATE_DIR)
+    if not os.path.isdir(disc):
+        return None
+    cands = sorted(f for f in os.listdir(disc) if f.lower().endswith(".md"))
+    state = {"candidates": [], "malformed": [], "ledger_errors": [],
+             "append_only": None, "unjudged": [], "promote_as_is": [],
+             "promote_with_declared_divergence": [], "excluded": []}
+    for f in cands:
+        data, errs = _parse_candidate(os.path.join(disc, f))
+        if data:
+            for ref in data["refs"]:
+                bad = _resolve_ref(repo_path, ref)
+                if bad:
+                    errs.append("ref %r: %s" % (ref, bad))
+        if errs:
+            state["malformed"].append({"candidate": f, "errors": errs})
+        else:
+            state["candidates"].append(f)
+    lpath = os.path.join(repo_path, BEHAVIOR_LEDGER_FILE)
+    verdicts = {}
+    if os.path.isfile(lpath):
+        rows, lerrs = _load_behavior_ledger(lpath)
+        state["ledger_errors"] = lerrs
+        state["append_only"] = _bl_append_only(repo_path, BEHAVIOR_LEDGER_FILE)
+        for row in rows:
+            verdicts[row["candidate"]] = row["verdict"]   # append-only: the LATEST row wins
+    for f in state["candidates"]:
+        v = verdicts.get(f)
+        if v is None:
+            state["unjudged"].append(f)
+        elif v == "preserve":
+            state["promote_as_is"].append(f)
+        elif v == "fix":
+            state["promote_with_declared_divergence"].append(f)
+        else:
+            state["excluded"].append(f)
+    return state
+
+
+def cmd_curation_check(args):
+    """The INV-CURATION-01 gate, measured. Exit 2: malformation or tampering (config-error
+    class -- candidates that cannot be validated, a ledger that cannot be trusted). Exit 1:
+    valid candidates awaiting a human verdict (the quarantine holding). Exit 0: every
+    candidate judged, or the feature unused."""
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _repo_cfg(ledger, args.repo).get("path", ".")
+    st = _curation_state(repo_path)
+    if st is None:
+        if args.json:
+            print(json.dumps({"repo": args.repo, "in_use": False}))
+        else:
+            print("CURATION %s: no %s/ directory -- feature unused, nothing to gate."
+                  % (args.repo, CANDIDATE_DIR))
+        sys.exit(0)
+    out = dict(st)
+    out.update({"repo": args.repo, "in_use": True})
+    hard = bool(st["malformed"] or st["ledger_errors"]
+                or st["append_only"] == "violation")
+    if args.json:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        print("CURATION %s: %d candidate(s), %d judged, %d awaiting verdict"
+              % (args.repo, len(st["candidates"]) + len(st["malformed"]),
+                 len(st["promote_as_is"]) + len(st["promote_with_declared_divergence"])
+                 + len(st["excluded"]), len(st["unjudged"])))
+        for m in st["malformed"]:
+            print("  !! %s: %s" % (m["candidate"], "; ".join(m["errors"])))
+        for e in st["ledger_errors"]:
+            print("  !! %s: %s" % (BEHAVIOR_LEDGER_FILE, e))
+        if st["append_only"] == "violation":
+            print("  !! %s: existing rows were EDITED -- append-only violated; revert and "
+                  "add a new row + ADR instead" % BEHAVIOR_LEDGER_FILE)
+        elif st["append_only"] == "unmeasured":
+            print("  -- append-only: UNMEASURED (no git) -- reported, never claimed as pass")
+        for f in st["unjudged"]:
+            print("  .. %s: awaiting human verdict (blocks forward)" % f)
+    sys.exit(2 if hard else (1 if st["unjudged"] else 0))
+
+
+
 def cmd_escalate(args):
     ledger = _load(args.ledger)
     _repo_node(ledger, args.repo)
@@ -4401,6 +4837,9 @@ def cmd_dashboard(args):
             _org[_rn] = _snaps[-1]["origin"]
     if _org:
         out["evidence_origin"] = _org
+    if ledger.get(CLEAN_ROOM_KEY):
+        out["clean_room"] = {r: [e for e in ledger[CLEAN_ROOM_KEY] if e.get("repo") == r][-1]
+                             for r in {e.get("repo") for e in ledger[CLEAN_ROOM_KEY]}}
     if getattr(args, "json", False):
         print(json.dumps(out, indent=2, ensure_ascii=False))
         return
@@ -7105,6 +7544,24 @@ def build_parser():
     pfp.add_argument("--json", action="store_true")
     pfp.set_defaults(func=cmd_fastpath_eval)
 
+    pcu = sub.add_parser("curation-check",
+                         help="the INV-CURATION-01 gate: candidates, verdicts, append-only ledger (ADR-009/010)")
+    pcu.add_argument("--ledger", default="QA-LEDGER.json")
+    pcu.add_argument("--repo", required=True)
+    pcu.add_argument("--json", action="store_true")
+    pcu.set_defaults(func=cmd_curation_check)
+
+    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")
+    pcr.add_argument("--repo", required=True)
+    pcr.add_argument("--ref", default=None, help="commit to verify; default HEAD")
+    pcr.add_argument("--run", required=True,
+                     help="the command to run inside the worktree; the engine never guesses it")
+    pcr.add_argument("--setup", default=None, help="optional bootstrap before --run (e.g. npm ci)")
+    pcr.add_argument("--json", action="store_true")
+    pcr.set_defaults(func=cmd_cleanroom)
+
     pgc = sub.add_parser("golden-coverage",
                          help="record the MEASURED source files a golden's harness exercises (ADR-006)")
     pgc.add_argument("--harness", required=True, help="script that drives the subject")

package/uscha-kit/.claude/skills/uscha-reverse-discovery/SKILL.md

@@ -5,8 +5,10 @@ description: >
   inverse of discovery: the system already exists and its behavior IS the truth, so you
   EXTRACT facts instead of proposing shape. Produce ONLY facts — a system map (endpoints,
   contracts, dependency graph, module candidates via static analysis) and a golden suite
-  captured mechanically at the boundaries. NEVER author an inferred SPEC or ADR of the old
-  system; the human writes those reading your facts. Invoke for "reverse-discovery",
+  captured mechanically at the boundaries — plus CANDIDATE specs in quarantine
+  (discovery/, evidence + confidence mandatory), which NEVER promote without a human
+  verdict in BEHAVIOR-LEDGER.md (ADR-009, INV-CURATION-01: the engine measures the gate).
+  Invoke for "reverse-discovery",
   "migrar/modernizar este sistema", "caracterizar el sistema viejo antes de tocarlo".
 allowed-tools: Read, Write, Glob, Grep, Bash
 disable-model-invocation: false
@@ -15,8 +17,9 @@ disable-model-invocation: false
 # reverse-discovery — extract the facts of an existing system before migrating it
 
 `uscha-discovery` is greenfield: you only have an idea, so you PROPOSE the shape. This is the
-opposite. The system already runs; its observable behavior is the ground truth. **You do
-not invent anything — you characterize what is already there, as facts.**
+opposite. The system already runs; its observable behavior is the ground truth. **Facts
+first, always — and what cannot be fact yet becomes a CANDIDATE in quarantine: evidenced,
+confidence-tagged, and promoted to the contract only by a human verdict (ADR-009).**
 
 ## First contact (show ONCE, then never again)
 
@@ -29,11 +32,11 @@ breadcrumb. Repeating it every run would be exactly the ceremony the method forb
 [uscha · reverse-discovery · START]
 Method: you bring the idea, the method builds the rest. Facts block, guesses advise;
         nothing closes on a checkbox, and the human approves the merge.
-Here:   I EXTRACT facts from the system that already exists. I never invent its spec -- you write that reading my facts.
+Here:   I EXTRACT facts and CANDIDATES from the system that already exists. Candidates stay quarantined until YOUR verdict promotes them.
 Output: SYSTEM-MAP.md · DISCOVERY-SUMMARY.md -- endpoints, contracts, dependency graph,
-        module candidates. Facts only: the SPEC and the ADRs are yours to write.
+        module candidates + discovery/ candidates + BEHAVIOR-LEDGER.md. The verdicts are yours.
 Next:   `/uscha-characterize` freezes current behavior and a HUMAN approves the golden;
-        only then do you write the migration SPEC, reading these facts + that golden.
+        only judged candidates reach the migration SPEC; the golden stays the oracle.
 Stop:   say so at any point -- whatever is already written stays.
 ```
 
@@ -88,17 +91,30 @@ and say exactly what unblocks it.
 Keep the CONTENT in the conversation's language, but keep the labels (`CLOSED`, `Produced`,
 `Blocks`, `Next`, `Run`) verbatim — they are the method's vocabulary and the smoke checks them.
 
-## The one non-negotiable: produce ONLY facts
+## The one non-negotiable: quarantine, not judgment (ADR-009)
 
 A system map (from static analysis) and a golden suite (byte-captured) are FACTS —
-verifiable, not opinions. **You do NOT author a SPEC of "what it does" or ADRs of "why it
-is built this way."** Those are inference, and if the agent writes them it encodes its own
-(mis)reading of the code — the exact blind spot the golden exists to counter. The golden
-is field truth; a SPEC the agent writes about legacy code is a claim. So this skill emits
-facts, and the human infers meaning from them.
-
-If you catch yourself writing a requirement or a rationale, stop: that belongs to the human
-(and to `/uscha-adr-refine` for the FORWARD decisions), not here.
+verifiable, not opinions. What you read out of the code beyond that is a CLAIM, and an
+LLM's claim about legacy code is plausible on the surface and divergent from reality —
+the exact blind spot the golden exists to counter. The old rule banned authoring such
+claims outright; ADR-009 renegotiated it: **you may author them as CANDIDATES, in
+quarantine, and you may NEVER judge or promote them.**
+
+- Every candidate lives in `discovery/`, with mandatory frontmatter: `evidence.type`
+  (`test | code | inference`), `evidence.refs` (real `file:line(s)` — the engine resolves
+  them; a ref that does not resolve makes the candidate invalid, named), and `confidence`
+  (`inference` is ALWAYS `low`).
+- **You capture; you do not judge.** Never decide whether a behavior is bug or feature —
+  that is the verdict (`preserve` / `fix` / `undefined`), it belongs to the human, and it
+  lands in `BEHAVIOR-LEDGER.md` with an ADR per verdict. You may present a candidate with
+  its evidence and ASK; you may write the skeleton row once the human decides; the verdict
+  itself is theirs.
+- The gate is MEASURED, not promised: `qa_ledger.py curation-check` blocks the forward flow
+  while any candidate lacks a verdict (INV-CURATION-01) — and a malformed candidate or a
+  tampered ledger blocks harder (`exit 2`), because "could not validate" must never read
+  as judged.
+- The ledger is append-only (verified against git): reverting a verdict is a NEW row plus a
+  new ADR, never an edit.
 
 ## Phase 1 — Map (fact)
 
@@ -127,7 +143,29 @@ Delegate to the `uscha-characterize` skill; if it is not installed, follow its c
   inputs of past bugs. A boundary whose corpus does not exercise its known branches is
   marked **PARTIAL**, never covered.
 
-## Phase 3 — Summary (facts, no opinion)
+## Phase 3 — Candidates (claims, quarantined)
+
+For every observable behavior the map + golden surface, emit one candidate file in
+`discovery/` (`NNN-short-slug.md`): frontmatter per the section above, then a short
+description of the behavior — what it does, not whether it should. Undesigned edge cases
+are captured too, as `inference`/`low`. Then run:
+
+```bash
+python qa_ledger.py curation-check --repo <name>
+```
+
+Echo its output verbatim — it names invalid candidates and everything awaiting verdict.
+The skill wires; the engine measures.
+
+## Phase 4 — Curation (the human's verdicts)
+
+Present one candidate at a time: the behavior, its evidence refs, its confidence. Ask for
+the verdict. On each answer, append the ledger row (`| # | candidate | evidence |
+confidence | verdict | ADR-RD-NNN |`) and write the skeleton `ADR-RD-NNN` (5-10 lines:
+context, evidence, verdict, consequence) for the human to complete. Re-run `curation-check`
+after the pass: exit 0 means every candidate is judged and the quarantine is clear.
+
+## Phase 5 — Summary (facts, no opinion)
 
 Write `DISCOVERY-SUMMARY.md`: the system map + the golden coverage report (which boundaries
 are captured and approved, which are PARTIAL and why). This is the fact base the human reads
@@ -135,8 +173,9 @@ to write the migration SPEC. Do not editorialize.
 
 ## What you do NOT do (the human's job)
 
-- Do NOT write a SPEC of the old system's behavior — the golden IS the executable spec.
-- Do NOT write ADRs of the old system's implicit decisions.
+- Do NOT record a verdict, promote a candidate, or skip the ledger — the quarantine gate
+  is the human's, and the engine measures it (INV-CURATION-01).
+- Do NOT write the migration SPEC — only judged candidates feed it, and the human writes it.
 - Do NOT decide the NEW structure (module boundaries, shared kernel, sync vs events). Those
   are forward decisions → `/uscha-adr-refine`.
 
@@ -150,15 +189,17 @@ to write the migration SPEC. Do not editorialize.
 ## Convergence — finish when
 
 The map is complete (every boundary and dependency accounted for, or explicitly marked
-unknown), the golden is captured and **human-approved**, and the coverage report states
+unknown), the golden is captured and **human-approved**, every candidate has a verdict
+(`curation-check` exits 0 — measured, not remembered), and the coverage report states
 what is covered vs PARTIAL. State plainly that the facts are ready, then hand off.
 
 ## Handoff
 
-> "Read SYSTEM-MAP.md and DISCOVERY-SUMMARY.md, and inspect the approved golden. These are
-> FACTS about the current system. Now write the migration SPEC — behavior == golden,
-> structure == the new module boundaries — and take the partition decisions via /uscha-adr-refine.
-> Do not treat any of my output as a requirement or a rationale; those are yours to decide."
+> "Read SYSTEM-MAP.md, DISCOVERY-SUMMARY.md and BEHAVIOR-LEDGER.md, and inspect the
+> approved golden. The facts are measured; the verdicts are yours and recorded. Now write
+> the migration SPEC from the JUDGED candidates — `preserve` == golden must match, `fix` ==
+> divergence declared by its ADR, `undefined` == out of contract — and take the partition
+> decisions via /uscha-adr-refine."
 
 Flow (migration): `uscha-reverse-discovery` (facts) → human writes SPEC + `/uscha-adr-refine` (forward
 module decisions) → `/uscha-devloop` (restructure; `golden-diff` + `ApplicationModules.verify()`