@andresmassello/uscha 1.63.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.63.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`, 33 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.63.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

@@ -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,264 @@ 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_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)
@@ -7263,6 +7544,13 @@ 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")

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()`

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

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.63.0",
+  "version": "1.64.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, 33 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
+  "description": "Spec-driven development for LLM coding agents: 9 skills (discovery, adr-refine, reverse-discovery, characterize, devloop, sysdoc, rubric, mirador, status) + a stdlib measurement engine (qa_ledger.py, 34 subcommands + universal installer + npm/npx router). Facts block, guesses advise; the human approves.",
   "author": {
     "name": "Andres Massello",
     "url": "https://github.com/andresmassello"

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

@@ -1,6 +1,6 @@
 {
   "name": "uscha",
-  "version": "1.63.0",
+  "version": "1.64.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.63.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.64.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`,
@@ -178,6 +178,25 @@ Honest limit: this is **not** a substitute for CI. A local worktree runs on your
 OS, your shell - environment variance is invisible to it. Different failure class, different
 instrument.
 
+## Curation (ADR-009/010) - candidates in quarantine, verdicts on the record
+
+Reverse discovery's brownfield entry: the agent may author CANDIDATE specs of a legacy
+system - in `discovery/`, with mandatory `evidence` (`test|code|inference`) and
+`confidence` frontmatter, refs the engine resolves against real files - and **nothing is
+promoted without a human verdict**:
+
+```bash
+python qa_ledger.py curation-check --repo <name> [--json]
+```
+
+Verdicts live in `BEHAVIOR-LEDGER.md` (`preserve` / `fix` / `undefined`, one ADR each) -
+a human-readable table with machine-enforced rules: strict shape (`exit 2` on malformed,
+because under this gate a silent "no verdicts" would UNBLOCK what it guards), append-only
+verified against git (revert = new row + new ADR, never an edit; latest row wins). While
+any candidate lacks a verdict, `pr-ready` is blocked naming it (INV-CURATION-01) - the
+quarantine is measured, not promised. No `discovery/` directory -> the feature does not
+exist and nothing changes.
+
 ## End-to-end flow
 
 `uscha-discovery` is the front for something new (you only have the idea); `uscha-adr-refine` is the front

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.63.0
+uscha-kit 1.64.0

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

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

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,264 @@ 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_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)
@@ -7263,6 +7544,13 @@ 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")

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.64.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,