@andresmassello/uscha 1.63.0 → 1.65.0

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

@@ -2634,6 +2634,29 @@ def _derive_phase(ledger, name, node, k, qa_order):
     # 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
@@ -3510,6 +3533,320 @@ def cmd_cleanroom(args):
 
 
 
+# --------------------------------------------------------------------------- #
+# 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_roundtrip(args):
+    """Advisory spec-id coverage (ADR-009 slice 2, v1): which PROMOTED candidates are
+    traceable in the code via an embedded `uscha-spec: <candidate>` marker. Coverage by id,
+    deliberately NOT semantic matching -- that stays out of scope until it can be measured
+    (ADR-011). Advisory end to end: exit 0 always, a report, never a gate."""
+    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:
+        print("ROUNDTRIP %s: no %s/ directory -- feature unused, nothing to trace."
+              % (args.repo, CANDIDATE_DIR))
+        sys.exit(0)
+    promoted = sorted(st["promote_as_is"] + st["promote_with_declared_divergence"])
+    ls = subprocess.run(["git", "ls-files"], cwd=repo_path, capture_output=True,
+                        text=True, encoding="utf-8", errors="replace")
+    tracked = [l.strip() for l in ls.stdout.splitlines()
+               if ls.returncode == 0 and l.strip()
+               and not l.strip().startswith(CANDIDATE_DIR + "/")
+               and os.path.basename(l.strip()) != BEHAVIOR_LEDGER_FILE]
+    found = set()
+    pat = re.compile(r"uscha-spec:\s*([\w.\-]+)")
+    ROUNDTRIP_MAX_BYTES = 2 * 1024 * 1024
+    for f in tracked:
+        full = os.path.join(repo_path, f)
+        try:
+            if os.path.getsize(full) > ROUNDTRIP_MAX_BYTES:
+                continue    # a 2MB+ tracked file is not where a spec-id marker lives; an
+                            # unbounded full-tree read is the T112 lesson, applied here
+            with open(full, encoding="utf-8", errors="replace") as fh:
+                body = fh.read()
+        except OSError:
+            continue
+        for m in pat.finditer(body):
+            mid = m.group(1)
+            found.add(mid if mid.endswith(".md") else mid + ".md")
+    covered = [c for c in promoted if c in found]
+    missing = [c for c in promoted if c not in found]
+    out = {"repo": args.repo, "promoted": len(promoted), "covered": len(covered),
+           "missing": missing, "advisory": True,
+           "coverage_pct": round(100.0 * len(covered) / len(promoted), 1) if promoted else None}
+    if args.json:
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        if not promoted:
+            print("ROUNDTRIP %s: no promoted candidates yet -- nothing to trace (advisory)."
+                  % args.repo)
+        else:
+            print("ROUNDTRIP %s: %d/%d promoted candidate(s) traceable by uscha-spec id "
+                  "(advisory)" % (args.repo, len(covered), len(promoted)))
+            for mss in missing:
+                print("  .. %s: no uscha-spec marker found in the code" % mss)
+    sys.exit(0)
+
+
+
+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)
@@ -6652,6 +6989,34 @@ def _golden_approved_path(rec):
 
 
 GOLDEN_SCRUB_FILE = "golden.scrub.json"
+GOLDEN_DIVERGENCES_FILE = "golden.divergences.json"
+
+
+def _load_golden_divergences(root):
+    """Expected divergences for `fix` verdicts (ADR-009 slice 2): a golden that MUST differ
+    because its ADR says the behavior was corrected. Shape:
+    {"divergences": {"<fixture basename>": {"adr": "ADR-RD-NNN", "reason": "..."}}}.
+    Strict like the scrub rules: a typo must not degrade into "no declarations" -- that
+    silence would turn every expected divergence back into a blocker, or worse, hide a
+    declared one behind a malformed file. Absent file -> {} (nothing declared)."""
+    path = os.path.join(root, GOLDEN_DIVERGENCES_FILE)
+    if not os.path.isfile(path):
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            spec = json.load(fh)
+        if not isinstance(spec, dict) or not isinstance(spec.get("divergences"), dict):
+            raise TypeError('expected {"divergences": {"<fixture>": {"adr":..., "reason":...}}}')
+        for k, v in spec["divergences"].items():
+            if (not isinstance(v, dict) or not re.match(r"^ADR-\S+$", str(v.get("adr", "")))
+                    or not str(v.get("reason", "")).strip()):
+                raise TypeError("divergence %r needs adr (ADR-...) and a reason" % k)
+        return spec["divergences"]
+    except (json.JSONDecodeError, TypeError, KeyError) as exc:
+        print("[qa_ledger] %s invalid (%s) - declared divergences are not skipped in "
+              "silence: fix the file or delete it." % (path, exc), file=sys.stderr)
+        sys.exit(2)
+
 
 
 def _load_scrub_rules(root):
@@ -6769,6 +7134,9 @@ def cmd_golden_diff(args):
     received = [p for p in sorted(hits) if os.path.isfile(p)]   # skip dirs matched by glob
     rules = _load_scrub_rules(root)
     labels = _load_golden_labels(getattr(args, "labels", None))
+    divergences = _load_golden_divergences(root)
+    expected_diverged = 0
+    consumed_declarations = set()
     scrub_counts = {}
     diverged = []   # (received_path, reason)
     fixtures = []
@@ -6797,21 +7165,60 @@ def cmd_golden_diff(args):
             fixture["result"] = "read_error"
             diverged.append((rec, f"could not read: {exc}"))
             continue
+        decl, decl_key = None, None
+        for cand_key in (os.path.relpath(app, root).replace(os.sep, "/"),
+                         os.path.relpath(rec, root).replace(os.sep, "/"),
+                         os.path.basename(app), os.path.basename(rec)):
+            # relpath first (the _golden_label pattern: nested suites share basenames and a
+            # declaration must not launder an unrelated module\x27s divergence -- fresh-review
+            # finding); basename stays as the flat-layout convenience.
+            if cand_key in divergences:
+                decl, decl_key = divergences[cand_key], cand_key
+                break
+        if decl:
+            consumed_declarations.add(decl_key)   # only what MATCHED: an unexercised twin
+                                                  # key must still show as unconsumed
         if rb == ab:
+            if decl:
+                # a `fix` verdict DECLARED this golden must differ -- identical bytes mean
+                # the corrected behavior never landed. An expected divergence that is not
+                # observed is a red finding, not a quiet pass (ADR-010: fix cases must
+                # diverge exactly as their ADR describes; identical is not that).
+                fixture["result"] = "declared_divergence_not_observed"
+                diverged.append((rec, "declared divergent (%s) but IDENTICAL -- the fix "
+                                      "this declaration describes is not in the output"
+                                      % decl["adr"]))
+                continue
             fixture["result"] = "matched"
             matched += 1
         # el conteo reportado es del lado RECEIVED (la captura fresca) — sumar
         # ambos lados duplicaria cada volatil enmascarado en el reporte.
         elif rules and (_scrub(rb, rules, scrub_counts)
                         == _scrub(ab, rules, {})):
+            if decl:
+                # scrub-equal IS "not observed": once declared volatiles are masked the
+                # outputs are behaviorally identical, so the fix this declaration
+                # describes is absent -- and letting the scrub branch swallow it hid the
+                # case from every signal (fresh-review HIGH: untested interaction).
+                fixture["result"] = "declared_divergence_not_observed"
+                diverged.append((rec, "declared divergent (%s) but scrub-equal -- "
+                                      "identical once volatiles are masked; the declared "
+                                      "fix is not in the output" % decl["adr"]))
+                continue
             # matchea SOLO tras enmascarar volatiles declarados — cuenta como
             # pass pero se reporta APARTE: el masking jamas es invisible.
             fixture["result"] = "matched_scrubbed"
             matched_scrubbed += 1
+        elif decl:
+            # diverges AND a fix verdict declared it would: expected, named, never silent.
+            fixture["result"] = "expected_divergence"
+            fixture["divergence_adr"] = decl["adr"]
+            expected_diverged += 1
         else:
             fixture["result"] = "diverged"
             diverged.append((rec, "diff NO aprobado contra .approved"))
 
+    unconsumed = sorted(k for k in divergences if k not in consumed_declarations)
     passed = len(diverged) == 0
     # zero fixtures is NOT-RUN, never CLEAN: a comparison that had nothing to
     # compare is absent evidence — log it as not-run (absence advises, a present
@@ -6833,6 +7240,8 @@ def cmd_golden_diff(args):
             "scrub_rules": len(rules),
             "scrub_substitutions": scrub_counts,
             "golden_labels": _golden_label_counts(fixtures),
+            "expected_diverged": expected_diverged,
+            "unconsumed_declarations": unconsumed,
             "fixtures": fixtures,
             "diverged": [{"file": f, "reason": r} for f, r in diverged],
         }, indent=2, ensure_ascii=False))
@@ -7263,6 +7672,20 @@ 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)
+
+    prt = sub.add_parser("roundtrip",
+                         help="advisory: which promoted candidates are traceable in code via uscha-spec ids (ADR-009 slice 2)")
+    prt.add_argument("--ledger", default="QA-LEDGER.json")
+    prt.add_argument("--repo", required=True)
+    prt.add_argument("--json", action="store_true")
+    prt.set_defaults(func=cmd_roundtrip)
+
     pcr = sub.add_parser("cleanroom",
                          help="run a command against a CLEAN checkout of one commit in a throwaway worktree (ADR-008)")
     pcr.add_argument("--ledger", default="QA-LEDGER.json")

package/uscha-kit/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()`

package/uscha-kit/templates/BEHAVIOR-LEDGER.md

@@ -0,0 +1,13 @@
+# Behavior Ledger
+
+The append-only audit trail of every verdict on the legacy system's observed behavior
+(ADR-009/010). Rules the engine enforces (`qa_ledger.py curation-check`):
+
+- Exactly six columns per row. Verdict is one of `preserve` / `fix` / `undefined` — anything
+  else is malformation, not a fourth state.
+- Every verdict names its ADR (`ADR-RD-NNN`): no verdict without its why.
+- Append-only, verified against git: reverting a verdict is a NEW row plus a new ADR, never
+  an edit. The LATEST row for a candidate wins.
+
+| # | candidate | evidence | confidence | verdict | adr |
+|---|-----------|----------|------------|---------|-----|

package/uscha-kit/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.63.0",
+  "version": "1.65.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,