@andresmassello/uscha 1.70.0 → 1.72.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.70.0** <!-- uscha:version --> · [uscha.dev](https://uscha.dev) ·
+**Kit v1.72.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`, 40 subcommands, Python stdlib) that ingests
+**A measurement engine** (`qa_ledger.py`, 42 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.70.0",
+  "version": "1.72.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

@@ -4533,6 +4533,10 @@ def cmd_fidelity(args):
         sys.exit(2)
     obs = (delta.get("observations") or []) if delta else []
     verdicts = _curation_verdicts(ledger, args.repo)
+    # fidelity respects the SAME bound that produced the delta (user decision, FR-001): a
+    # bounded discovery is measured over its own subtree, so unexplained_code and the other
+    # mechanical dimensions never mix the delta's scope with the whole repo's.
+    bound = delta.get("path") if delta else None
     dims = {}
     # traceability: canonical items reachable in code via the uscha-spec id machinery
     canon_items = []
@@ -4543,7 +4547,17 @@ def cmd_fidelity(args):
                 canon_items = json.load(fh).get("items") or []
         except (OSError, ValueError):
             canon_items = []
-    tracked = _tracked_files(repo_path) or []
+    tracked = [f for f in (_tracked_files(repo_path) or []) if _under_bound(f, bound)]
+    _scope = " (bounded to %s)" % bound if bound else ""
+    if bound:
+        # scope the DENOMINATOR too, not just the file scan: promote MERGES into CANONICAL
+        # repo-wide, so an earlier unbounded promote would otherwise count out-of-bound
+        # items as "no longer derives" -- the exact scope-mixing this release kills, half-
+        # done if only the numerator moves (fresh-review LOW). An item is under the bound
+        # when its primary provenance file is.
+        canon_items = [it for it in canon_items
+                       if any(_under_bound(f.split(":")[0].split("#")[0], bound)
+                              for f in (it.get("provenance") or {}).get("files") or [])]
     marked, marker_files = set(), set()
     for f, mid in _scan_spec_markers(repo_path, tracked):
         marked.add(mid)
@@ -4552,8 +4566,8 @@ def cmd_fidelity(args):
         traced = sum(1 for it in canon_items if (it.get("derived_from") or "") in marked)
         dims["traceability"] = _fid_dim(round(traced / len(canon_items), 4),
                                         "uscha-spec marker scan over %d git-tracked "
-                                        "files vs %d canonical item(s)"
-                                        % (len(tracked), len(canon_items)))
+                                        "files%s vs %d canonical item(s)"
+                                        % (len(tracked), _scope, len(canon_items)))
     else:
         dims["traceability"] = _fid_dim(None, "UNMEASURED: no canonical items promoted yet")
     # behavior: the latest ingested golden-diff gate verdict
@@ -4579,13 +4593,30 @@ def cmd_fidelity(args):
         cur_ids = {o["id"] for o in cur_static}
         okc = sum(1 for it in static_canon if it.get("derived_from") in cur_ids)
         dims["contracts"] = _fid_dim(round(okc / len(static_canon), 4),
-                                     "re-ran static extractors; %d/%d canonical static "
+                                     "re-ran static extractors%s; %d/%d canonical static "
                                      "item(s) still derive from the code"
-                                     % (okc, len(static_canon)))
+                                     % (_scope, okc, len(static_canon)))
     else:
         dims["contracts"] = _fid_dim(None, "UNMEASURED: no static-class canonical items")
-    # curation_closure: curated OBS / total OBS in the active delta
-    if obs:
+    # curation_closure: curated OBS / total OBS in the active delta. With --ir (ADR-015) it is
+    # answered as a path query over the graph -- OBS nodes reachable to a CURATION node via an
+    # OBS->CURATION edge / OBS nodes. It reproduces v0 when the graph's OBS set equals the
+    # delta's (the FIELD-RUN-001 case); a canonical carrying OBS beyond the active delta would
+    # widen the denominator, which is the graph's honest answer, not v0's.
+    if args.ir:
+        graph = _extract_ir(repo_path, ledger)
+        obs_nodes = [nd["id"] for nd in graph["nodes"] if nd["type"] == "OBS"]
+        cured = {e["from"] for e in graph["edges"] if e["type"] == "OBS->CURATION"}
+        if obs_nodes:
+            hit = sum(1 for oid in obs_nodes if oid in cured)
+            dims["curation_closure"] = _fid_dim(
+                round(hit / len(obs_nodes), 4),
+                "IR path query: %d/%d OBS node(s) reach a CURATION node (IR v%s)"
+                % (hit, len(obs_nodes), IR_SCHEMA))
+        else:
+            dims["curation_closure"] = _fid_dim(
+                None, "UNMEASURED: no OBS nodes in the IR graph")
+    elif obs:
         cur = sum(1 for o in obs if o["id"] in verdicts)
         dims["curation_closure"] = _fid_dim(round(cur / len(obs), 4),
                                             "%d/%d OBS in %s carry a ledger verdict"
@@ -4616,14 +4647,15 @@ def cmd_fidelity(args):
         unex = [f for f in prod if f not in lineage]
         dims["unexplained_code"] = _fid_dim(
             round(len(unex) / len(prod), 4),
-            "%d/%d tracked prod source file(s) with no path to a canonical item or "
-            "preserved OBS (v0 granularity: FILE)" % (len(unex), len(prod)),
+            "%d/%d tracked prod source file(s)%s with no path to a canonical item or "
+            "preserved OBS (v0 granularity: FILE)" % (len(unex), len(prod), _scope),
             files=unex[:10] + (["(+%d)" % (len(unex) - 10)] if len(unex) > 10 else []))
     else:
         dims["unexplained_code"] = _fid_dim(None, "UNMEASURED: no tracked prod source files")
     dims["semantic"] = _fid_dim(None, "not wired: an LLM-judged comparison enters as "
                                       "advisory only and can NEVER gate (INV-ADVISORY-01)")
     out = {"repo": args.repo,
+           **({"path": bound} if bound else {}),
            "dimensions": {k: dict(dims[k], **{"class": FIDELITY_DIMENSIONS[k]})
                           for k in ("traceability", "behavior", "contracts",
                                     "curation_closure", "unexplained_code", "semantic")}}
@@ -4632,14 +4664,307 @@ def cmd_fidelity(args):
     if args.json:
         print(json.dumps(out, indent=2, ensure_ascii=False))
     else:
-        print("FIDELITY %s (vector -- no blend; each number stands on its own evidence):"
-              % args.repo)
+        print("FIDELITY %s%s (vector -- no blend; each number stands on its own evidence):"
+              % (args.repo, " [bounded to %s]" % bound if bound else ""))
         for k, d in out["dimensions"].items():
             val = "UNMEASURED" if d["value"] is None else "%.2f" % d["value"]
             print("  %-17s %-10s [%s] %s" % (k, val, d["class"], d["provenance"]))
     sys.exit(0)
 
 
+# --------------------------------------------------------------------------- #
+# IR  (Diamond M2: the canonical package extracts into a typed graph. ADR-015.
+# Markdown stays canonical; the IR is a derived index. What cannot be typed
+# deterministically is UNTYPED -- visible, counted, never guessed.)
+# --------------------------------------------------------------------------- #
+
+IR_DIR = "ir"
+IR_FILE = "IR.json"
+IR_TWIN = "IR.md"
+IR_SCHEMA = "0.1"
+IR_NODE_TYPES = ("REQ", "INV", "AC", "CONTRACT", "DECISION", "NFR",
+                 "GOLDEN", "OBS", "CURATION", "EVIDENCE")
+IR_EDGE_TYPES = ("REQ->AC", "AC->EVIDENCE", "DECISION->INV", "OBS->CURATION",
+                 "CURATION->canonical", "supersedes", "derived_from")
+# broader than _AC_ID: the forward package uses sub-namespaced ids (AC-DD-07, AC-FV-06)
+_IR_AC_LINE = re.compile(r"^\s*[-*]\s*\[[ xX]\]\s*(AC-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)\b\s*[-—:]*\s*(.*)$")
+_IR_INV_LINE = re.compile(r"^\s*[-*]\s*\*\*(INV-[A-Za-z0-9-]+)\s*[—-]+\s*(.*?)\*\*")
+_IR_ADR_REF = re.compile(r"\bADR-0*(\d+)\b")
+_IR_INV_REF = re.compile(r"\bINV-[A-Za-z0-9-]+\b")
+_IR_SUPERSEDE = re.compile(r"(?i)supersed\w*\s+(ADR-0*\d+)")
+_IR_BANNER = ("GENERATED by qa_ledger.py ir-extract (ADR-015). Rendered view of "
+              + IR_FILE + " -- hand edits are overwritten on regeneration.")
+
+
+def _ir_node_id(ntype, text, source):
+    """Content-address the ID-less (ADR-015 option B): nodes with a native human id keep it;
+    only nodes with nothing human to anchor to get NODE-sha256(type+text+source)[:12]."""
+    norm = re.sub(r"\s+", " ", (text or "").strip().lower())
+    return "NODE-" + hashlib.sha256(
+        (ntype + "\n" + norm + "\n" + source).encode("utf-8")).hexdigest()[:12]
+
+
+def _ir_read_lines(path):
+    try:
+        with open(path, encoding="utf-8-sig", errors="replace") as fh:
+            return fh.read().splitlines()
+    except OSError:
+        return None
+
+
+def _extract_ir(repo_path, ledger):
+    """Deterministic extraction of the forward canonical package into a typed graph. Every
+    node/edge is derived from an EXISTING structural convention or reference -- nothing is
+    inferred. A line that fills a structural slot but cannot be typed lands in `untyped`."""
+    nodes, edges, untyped = [], [], []
+    seen_ids = set()
+
+    def add(node):
+        if node["id"] not in seen_ids:
+            seen_ids.add(node["id"])
+            nodes.append(node)
+
+    # AC nodes <- ACCEPTANCE.md checkboxes carrying an AC id; a checkbox WITHOUT an id is an
+    # acceptance slot the conventions do not type -> untyped (never a guessed id).
+    acc_lines = _ir_read_lines(os.path.join(repo_path, "ACCEPTANCE.md")) or []
+    for n, ln in enumerate(acc_lines, 1):
+        s = ln.strip()
+        if s[:5].lower() not in ("- [x]", "- [ ]", "* [x]", "* [ ]"):
+            continue
+        m = _IR_AC_LINE.match(ln)
+        src = {"file": "ACCEPTANCE.md", "line": n}
+        if m:
+            add({"id": m.group(1).upper(), "type": "AC",
+                 "statement": m.group(2).strip(), "source": src})
+        else:
+            untyped.append({"text": s[5:].strip(), "source": src,
+                            "reason": "acceptance checkbox without a traceable AC-id"})
+
+    # INV nodes <- CONSTITUTION.md `- **INV-XXX-NN — Title.**` headings
+    con_lines = _ir_read_lines(os.path.join(repo_path, "CONSTITUTION.md")) or []
+    inv_ids = set()
+    for n, ln in enumerate(con_lines, 1):
+        m = _IR_INV_LINE.match(ln)
+        if m:
+            add({"id": m.group(1).upper(), "type": "INV",
+                 "statement": m.group(2).strip().rstrip("."),
+                 "source": {"file": "CONSTITUTION.md", "line": n}})
+            inv_ids.add(m.group(1).upper())
+
+    # DECISION nodes <- docs/adr/*.md (native ADR-NNN id, title, file); edges to the INVs the
+    # ADR governs/states, and supersedes edges -- both from references already in the body.
+    adr_dir = os.path.join(repo_path, "docs", "adr")
+    ac_ids = {nd["id"] for nd in nodes if nd["type"] == "AC"}
+    for row in _mirador_adrs(adr_dir):
+        add({"id": row["id"], "type": "DECISION", "statement": row["t"],
+             "source": {"file": os.path.relpath(row["file"], repo_path).replace(os.sep, "/"),
+                        "line": 1}})
+        body = _ir_read_lines(row["file"]) or []
+        text = "\n".join(body)
+        for inv in set(_IR_INV_REF.findall(text)):
+            if inv.upper() in inv_ids:
+                edges.append({"from": row["id"], "to": inv.upper(), "type": "DECISION->INV"})
+        for sup in set(_IR_SUPERSEDE.findall(text)):
+            edges.append({"from": row["id"],
+                          "to": "ADR-%03d" % int(re.search(r"\d+", sup).group()),
+                          "type": "supersedes"})
+        # an ADR's Verification checklist references its ACs -> REQ->AC is absent here (no REQ
+        # layer yet), but AC nodes referenced by an ADR are real edges DECISION mentions AC:
+        for aid in {m.group(0)[1:-1].upper()
+                    for m in re.finditer(r"\(AC-[A-Za-z0-9-]+\)", text)}:
+            if aid in ac_ids:                       # set(): an AC cited twice is one edge
+                edges.append({"from": row["id"], "to": aid, "type": "REQ->AC"})
+
+    # GOLDEN nodes <- git-tracked approved fixtures (the path is a native, stable id)
+    tracked = _tracked_files(repo_path) or []
+    gold_marker = ".appro" + "ved."
+    for f in tracked:
+        if gold_marker in f:
+            add({"id": f, "type": "GOLDEN", "statement": "approved golden fixture",
+                 "source": {"file": f, "line": 1}})
+
+    # OBS / CURATION <- the active delta's observations (all of them, so curation_closure is
+    # a real path query over the graph) + the ledger's curation records. Absent in a repo
+    # that never ran a field run -> simply no such nodes.
+    delta, derrs = _load_delta(repo_path)
+    if delta and not derrs:
+        for o in delta.get("observations") or []:
+            prov = (o.get("provenance") or {}).get("files") or []
+            add({"id": o["id"], "type": "OBS", "statement": o.get("statement") or "",
+                 "source": {"file": prov[0].split(":")[0] if prov else "delta", "line": 1}})
+    canon_path = os.path.join(repo_path, CANDIDATE_DIR, CANONICAL_FILE)
+    canon_items = []
+    if os.path.isfile(canon_path):
+        try:
+            with open(canon_path, encoding="utf-8-sig") as fh:
+                canon_items = json.load(fh).get("items") or []
+        except (OSError, ValueError):
+            canon_items = []
+    for it in canon_items:
+        oid = it.get("derived_from")
+        if not oid:
+            continue
+        prov = (it.get("provenance") or {}).get("files") or []
+        add({"id": oid, "type": "OBS", "statement": it.get("statement") or "",
+             "source": {"file": prov[0].split(":")[0] if prov else "canonical", "line": 1}})
+    for rec in ledger.get("curation") or []:
+        oid = rec.get("obs_id")
+        if not oid:
+            continue
+        cid = "CUR-" + hashlib.sha256(
+            (oid + "\n" + (rec.get("at") or "")).encode("utf-8")).hexdigest()[:12]
+        add({"id": cid, "type": "CURATION",
+             "statement": "%s: %s" % (rec.get("verdict"), oid),
+             "source": {"file": "QA-LEDGER.json", "line": 0}})
+        if oid in seen_ids:
+            edges.append({"from": oid, "to": cid, "type": "OBS->CURATION"})
+
+    node_ids = {nd["id"] for nd in nodes}
+    kept, dropped = [], 0
+    for e in edges:
+        if e["from"] in node_ids and e["to"] in node_ids:
+            kept.append(e)
+        elif e["type"] == "supersedes" and e["from"] in node_ids:
+            kept.append(e)                          # a superseded ADR may be archived; keep it
+        else:
+            dropped += 1
+    nodes.sort(key=lambda nd: (nd["type"], nd["id"]))
+    kept.sort(key=lambda e: (e["type"], e["from"], e["to"]))
+    untyped.sort(key=lambda u: (u["source"]["file"], u["source"]["line"]))
+    counts = {t: sum(1 for nd in nodes if nd["type"] == t) for t in IR_NODE_TYPES}
+    stats = {"nodes": len(nodes), "edges": len(kept),
+             "edges_dropped": dropped, "untyped": len(untyped),
+             "by_type": {t: c for t, c in counts.items() if c},
+             "untyped_rate": round(len(untyped) / (len(nodes) + len(untyped)), 4)
+             if (nodes or untyped) else 0.0}
+    graph = {"schema_version": IR_SCHEMA,
+             "_generated_by": "qa_ledger.py ir-extract (ADR-015) -- derived index of the "
+                              "canonical package; never hand-edit",
+             "nodes": nodes, "edges": kept, "untyped": untyped, "stats": stats}
+    # the seal covers stats too (fresh-review MEDIUM): a doctored summary that ir-render
+    # would faithfully print must trip the strict loader, not slip past it -- the
+    # derived-but-unsealed lesson, applied a third time (path @1.70, evidence_class @1.69).
+    graph["_integrity"] = _ir_seal(graph)
+    return graph
+
+
+def _ir_seal(graph):
+    return _integrity_hash({k: graph.get(k) for k in
+                            ("schema_version", "nodes", "edges", "untyped", "stats")})
+
+
+def _load_ir(repo_path):
+    """Strict loader: an unknown schema_version or a broken graph is exit-2 class, never
+    mis-read (AC-IR-05). Returns (graph, errors); graph None when absent."""
+    path = os.path.join(repo_path, IR_DIR, IR_FILE)
+    if not os.path.isfile(path):
+        return None, []
+    try:
+        with open(path, encoding="utf-8-sig") as fh:
+            g = json.load(fh)
+    except (OSError, ValueError) as exc:
+        return {}, ["unreadable: %s" % exc]
+    errors = []
+    if g.get("schema_version") != IR_SCHEMA:
+        errors.append("schema_version %r != %r (a version this engine does not know is not "
+                      "read, it is refused)" % (g.get("schema_version"), IR_SCHEMA))
+        return g, errors
+    if not isinstance(g.get("nodes"), list) or not isinstance(g.get("edges"), list):
+        return g, ["nodes/edges missing or not lists"]
+    if g.get("_integrity") != _ir_seal(g):
+        errors.append("integrity seal does not match the graph -- nodes, edges, untyped or "
+                      "stats was hand-edited (regenerate via ir-extract)")
+    return g, errors
+
+
+def _render_ir_md(graph):
+    st = graph.get("stats") or {}
+    lines = ["<!-- %s -->" % _IR_BANNER, "", "# Uscha IR v%s (rendered view)" % IR_SCHEMA, "",
+             "%d nodes · %d edges · %d UNTYPED (rate %.2f)"
+             % (st.get("nodes", 0), st.get("edges", 0), st.get("untyped", 0),
+                st.get("untyped_rate", 0.0)), "",
+             "## Nodes", "", "| id | type | statement | source |",
+             "|----|------|-----------|--------|"]
+    for nd in graph.get("nodes") or []:
+        src = "%s:%s" % (nd["source"]["file"], nd["source"]["line"])
+        stmt = (nd.get("statement") or "").replace("|", "\\|")
+        lines.append("| %s | %s | %s | %s |" % (nd["id"], nd["type"], stmt, src))
+    lines += ["", "## Edges", "", "| from | type | to |", "|------|------|----|"]
+    for e in graph.get("edges") or []:
+        lines.append("| %s | %s | %s |" % (e["from"], e["type"], e["to"]))
+    if graph.get("untyped"):
+        lines += ["", "## UNTYPED (conventions the human layer is missing)", "",
+                  "| text | source | reason |", "|------|--------|--------|"]
+        for u in graph["untyped"]:
+            src = "%s:%s" % (u["source"]["file"], u["source"]["line"])
+            txt = (u.get("text") or "").replace("|", "\\|")[:80]
+            lines.append("| %s | %s | %s |" % (txt, src, u.get("reason", "")))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def cmd_ir_extract(args):
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _scope_path(ledger, args.repo)
+    graph = _extract_ir(repo_path, ledger)
+    ir_dir = os.path.join(repo_path, IR_DIR)
+    os.makedirs(ir_dir, exist_ok=True)
+    with open(os.path.join(ir_dir, IR_FILE), "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(json.dumps(graph, indent=2, ensure_ascii=False) + "\n")
+    twin_path = os.path.join(ir_dir, IR_TWIN)
+    twin = _render_ir_md(graph)
+    prev = None
+    if os.path.isfile(twin_path):
+        try:
+            with open(twin_path, encoding="utf-8-sig") as fh:
+                prev = fh.read()
+        except OSError:
+            prev = None
+    with open(twin_path, "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(twin)
+    if prev is not None and prev != twin:
+        print("[qa_ledger] ir-extract: %s regenerated (rendered view, never a source)"
+              % IR_TWIN, file=sys.stderr)
+    st = graph["stats"]
+    if args.json:
+        print(json.dumps(st, indent=2, ensure_ascii=False))
+    else:
+        print("IR-EXTRACT %s: %d nodes, %d edges -> %s"
+              % (args.repo, st["nodes"], st["edges"],
+                 os.path.join(IR_DIR, IR_FILE)))
+        print("  by type: " + ", ".join("%s=%d" % (t, c)
+                                        for t, c in st["by_type"].items()))
+        print("  UNTYPED: %d (rate %.2f) -- the size of what the conventions cannot yet type"
+              % (st["untyped"], st["untyped_rate"]))
+        if st["edges_dropped"]:
+            print("  %d edge(s) dropped (endpoint not a node) -- counted, never dangling"
+                  % st["edges_dropped"])
+    sys.exit(0)
+
+
+def cmd_ir_render(args):
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _scope_path(ledger, args.repo)
+    graph, errors = _load_ir(repo_path)
+    if graph is None:
+        print("[qa_ledger] ir-render: no %s -- run ir-extract first."
+              % os.path.join(IR_DIR, IR_FILE), file=sys.stderr)
+        sys.exit(2)
+    if errors:
+        for e in errors:
+            print("[qa_ledger] ir-render: %s" % e, file=sys.stderr)
+        sys.exit(2)
+    twin = _render_ir_md(graph)
+    with open(os.path.join(repo_path, IR_DIR, IR_TWIN), "w", encoding="utf-8",
+              newline="\n") as fh:
+        fh.write(twin)
+    print("IR-RENDER %s: %s regenerated from the graph"
+          % (args.repo, os.path.join(IR_DIR, IR_TWIN)))
+    sys.exit(0)
+
+
 # --------------------------------------------------------------------------- #
 # facts  (T0 / SYSTEM-FACTS: public claims become compiled artifacts of repo
 # facts -- Diamond applied to Diamond. ADR-012.)
@@ -8687,9 +9012,29 @@ def build_parser():
     pfv.add_argument("--repo", required=True)
     pfv.add_argument("--config", default="uscha.config.json",
                      help="checked for defaults.fidelity.gate -- advisory there is a refusal")
+    pfv.add_argument("--ir", action="store_true",
+                     help="answer curation_closure as a path query over the IR graph "
+                          "(ADR-015); reproduces v0 from the derived index")
     pfv.add_argument("--json", action="store_true")
     pfv.set_defaults(func=cmd_fidelity)
 
+    pie = sub.add_parser(
+        "ir-extract",
+        help="extract the canonical package into a typed graph (ir/IR.json); what cannot be "
+             "typed deterministically is UNTYPED, counted, never guessed (ADR-015)")
+    pie.add_argument("--ledger", default="QA-LEDGER.json")
+    pie.add_argument("--repo", required=True)
+    pie.add_argument("--json", action="store_true")
+    pie.set_defaults(func=cmd_ir_extract)
+
+    pir = sub.add_parser(
+        "ir-render",
+        help="regenerate the human view (ir/IR.md) from the graph; round-trip content-stable "
+             "for the structured parts (ADR-015)")
+    pir.add_argument("--ledger", default="QA-LEDGER.json")
+    pir.add_argument("--repo", required=True)
+    pir.set_defaults(func=cmd_ir_render)
+
     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-plugin/plugin.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "uscha",
-  "version": "1.70.0",
+  "version": "1.72.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, 40 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, 42 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.70.0",
+  "version": "1.72.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.70.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
+**Kit version:** v1.72.0 <!-- uscha:version --> · **[uscha.dev](https://uscha.dev)**
 
 Spec-driven orchestrator + multi-repo QA for Claude Code, with a deterministic ledger.
 **Nine skills** (`uscha-discovery`, `uscha-adr-refine`, `uscha-devloop`, `uscha-sysdoc`, `uscha-reverse-discovery`,

package/uscha-kit/VERSION

@@ -1 +1 @@
-uscha-kit 1.70.0
+uscha-kit 1.72.0

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

@@ -1 +1 @@
-{"AC-FV-01": true, "AC-FV-02": true, "AC-FV-04": true, "AC-FV-05": true, "AC-FV-03": true, "review-h2": true, "review-m4": true}
+{"AC-FV-01": true, "AC-FV-02": true, "AC-FV-04": true, "AC-FV-05": true, "AC-FV-03": true, "review-h2": true, "AC-FV-06": true, "review-m4": true}

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

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

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

@@ -4533,6 +4533,10 @@ def cmd_fidelity(args):
         sys.exit(2)
     obs = (delta.get("observations") or []) if delta else []
     verdicts = _curation_verdicts(ledger, args.repo)
+    # fidelity respects the SAME bound that produced the delta (user decision, FR-001): a
+    # bounded discovery is measured over its own subtree, so unexplained_code and the other
+    # mechanical dimensions never mix the delta's scope with the whole repo's.
+    bound = delta.get("path") if delta else None
     dims = {}
     # traceability: canonical items reachable in code via the uscha-spec id machinery
     canon_items = []
@@ -4543,7 +4547,17 @@ def cmd_fidelity(args):
                 canon_items = json.load(fh).get("items") or []
         except (OSError, ValueError):
             canon_items = []
-    tracked = _tracked_files(repo_path) or []
+    tracked = [f for f in (_tracked_files(repo_path) or []) if _under_bound(f, bound)]
+    _scope = " (bounded to %s)" % bound if bound else ""
+    if bound:
+        # scope the DENOMINATOR too, not just the file scan: promote MERGES into CANONICAL
+        # repo-wide, so an earlier unbounded promote would otherwise count out-of-bound
+        # items as "no longer derives" -- the exact scope-mixing this release kills, half-
+        # done if only the numerator moves (fresh-review LOW). An item is under the bound
+        # when its primary provenance file is.
+        canon_items = [it for it in canon_items
+                       if any(_under_bound(f.split(":")[0].split("#")[0], bound)
+                              for f in (it.get("provenance") or {}).get("files") or [])]
     marked, marker_files = set(), set()
     for f, mid in _scan_spec_markers(repo_path, tracked):
         marked.add(mid)
@@ -4552,8 +4566,8 @@ def cmd_fidelity(args):
         traced = sum(1 for it in canon_items if (it.get("derived_from") or "") in marked)
         dims["traceability"] = _fid_dim(round(traced / len(canon_items), 4),
                                         "uscha-spec marker scan over %d git-tracked "
-                                        "files vs %d canonical item(s)"
-                                        % (len(tracked), len(canon_items)))
+                                        "files%s vs %d canonical item(s)"
+                                        % (len(tracked), _scope, len(canon_items)))
     else:
         dims["traceability"] = _fid_dim(None, "UNMEASURED: no canonical items promoted yet")
     # behavior: the latest ingested golden-diff gate verdict
@@ -4579,13 +4593,30 @@ def cmd_fidelity(args):
         cur_ids = {o["id"] for o in cur_static}
         okc = sum(1 for it in static_canon if it.get("derived_from") in cur_ids)
         dims["contracts"] = _fid_dim(round(okc / len(static_canon), 4),
-                                     "re-ran static extractors; %d/%d canonical static "
+                                     "re-ran static extractors%s; %d/%d canonical static "
                                      "item(s) still derive from the code"
-                                     % (okc, len(static_canon)))
+                                     % (_scope, okc, len(static_canon)))
     else:
         dims["contracts"] = _fid_dim(None, "UNMEASURED: no static-class canonical items")
-    # curation_closure: curated OBS / total OBS in the active delta
-    if obs:
+    # curation_closure: curated OBS / total OBS in the active delta. With --ir (ADR-015) it is
+    # answered as a path query over the graph -- OBS nodes reachable to a CURATION node via an
+    # OBS->CURATION edge / OBS nodes. It reproduces v0 when the graph's OBS set equals the
+    # delta's (the FIELD-RUN-001 case); a canonical carrying OBS beyond the active delta would
+    # widen the denominator, which is the graph's honest answer, not v0's.
+    if args.ir:
+        graph = _extract_ir(repo_path, ledger)
+        obs_nodes = [nd["id"] for nd in graph["nodes"] if nd["type"] == "OBS"]
+        cured = {e["from"] for e in graph["edges"] if e["type"] == "OBS->CURATION"}
+        if obs_nodes:
+            hit = sum(1 for oid in obs_nodes if oid in cured)
+            dims["curation_closure"] = _fid_dim(
+                round(hit / len(obs_nodes), 4),
+                "IR path query: %d/%d OBS node(s) reach a CURATION node (IR v%s)"
+                % (hit, len(obs_nodes), IR_SCHEMA))
+        else:
+            dims["curation_closure"] = _fid_dim(
+                None, "UNMEASURED: no OBS nodes in the IR graph")
+    elif obs:
         cur = sum(1 for o in obs if o["id"] in verdicts)
         dims["curation_closure"] = _fid_dim(round(cur / len(obs), 4),
                                             "%d/%d OBS in %s carry a ledger verdict"
@@ -4616,14 +4647,15 @@ def cmd_fidelity(args):
         unex = [f for f in prod if f not in lineage]
         dims["unexplained_code"] = _fid_dim(
             round(len(unex) / len(prod), 4),
-            "%d/%d tracked prod source file(s) with no path to a canonical item or "
-            "preserved OBS (v0 granularity: FILE)" % (len(unex), len(prod)),
+            "%d/%d tracked prod source file(s)%s with no path to a canonical item or "
+            "preserved OBS (v0 granularity: FILE)" % (len(unex), len(prod), _scope),
             files=unex[:10] + (["(+%d)" % (len(unex) - 10)] if len(unex) > 10 else []))
     else:
         dims["unexplained_code"] = _fid_dim(None, "UNMEASURED: no tracked prod source files")
     dims["semantic"] = _fid_dim(None, "not wired: an LLM-judged comparison enters as "
                                       "advisory only and can NEVER gate (INV-ADVISORY-01)")
     out = {"repo": args.repo,
+           **({"path": bound} if bound else {}),
            "dimensions": {k: dict(dims[k], **{"class": FIDELITY_DIMENSIONS[k]})
                           for k in ("traceability", "behavior", "contracts",
                                     "curation_closure", "unexplained_code", "semantic")}}
@@ -4632,14 +4664,307 @@ def cmd_fidelity(args):
     if args.json:
         print(json.dumps(out, indent=2, ensure_ascii=False))
     else:
-        print("FIDELITY %s (vector -- no blend; each number stands on its own evidence):"
-              % args.repo)
+        print("FIDELITY %s%s (vector -- no blend; each number stands on its own evidence):"
+              % (args.repo, " [bounded to %s]" % bound if bound else ""))
         for k, d in out["dimensions"].items():
             val = "UNMEASURED" if d["value"] is None else "%.2f" % d["value"]
             print("  %-17s %-10s [%s] %s" % (k, val, d["class"], d["provenance"]))
     sys.exit(0)
 
 
+# --------------------------------------------------------------------------- #
+# IR  (Diamond M2: the canonical package extracts into a typed graph. ADR-015.
+# Markdown stays canonical; the IR is a derived index. What cannot be typed
+# deterministically is UNTYPED -- visible, counted, never guessed.)
+# --------------------------------------------------------------------------- #
+
+IR_DIR = "ir"
+IR_FILE = "IR.json"
+IR_TWIN = "IR.md"
+IR_SCHEMA = "0.1"
+IR_NODE_TYPES = ("REQ", "INV", "AC", "CONTRACT", "DECISION", "NFR",
+                 "GOLDEN", "OBS", "CURATION", "EVIDENCE")
+IR_EDGE_TYPES = ("REQ->AC", "AC->EVIDENCE", "DECISION->INV", "OBS->CURATION",
+                 "CURATION->canonical", "supersedes", "derived_from")
+# broader than _AC_ID: the forward package uses sub-namespaced ids (AC-DD-07, AC-FV-06)
+_IR_AC_LINE = re.compile(r"^\s*[-*]\s*\[[ xX]\]\s*(AC-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)\b\s*[-—:]*\s*(.*)$")
+_IR_INV_LINE = re.compile(r"^\s*[-*]\s*\*\*(INV-[A-Za-z0-9-]+)\s*[—-]+\s*(.*?)\*\*")
+_IR_ADR_REF = re.compile(r"\bADR-0*(\d+)\b")
+_IR_INV_REF = re.compile(r"\bINV-[A-Za-z0-9-]+\b")
+_IR_SUPERSEDE = re.compile(r"(?i)supersed\w*\s+(ADR-0*\d+)")
+_IR_BANNER = ("GENERATED by qa_ledger.py ir-extract (ADR-015). Rendered view of "
+              + IR_FILE + " -- hand edits are overwritten on regeneration.")
+
+
+def _ir_node_id(ntype, text, source):
+    """Content-address the ID-less (ADR-015 option B): nodes with a native human id keep it;
+    only nodes with nothing human to anchor to get NODE-sha256(type+text+source)[:12]."""
+    norm = re.sub(r"\s+", " ", (text or "").strip().lower())
+    return "NODE-" + hashlib.sha256(
+        (ntype + "\n" + norm + "\n" + source).encode("utf-8")).hexdigest()[:12]
+
+
+def _ir_read_lines(path):
+    try:
+        with open(path, encoding="utf-8-sig", errors="replace") as fh:
+            return fh.read().splitlines()
+    except OSError:
+        return None
+
+
+def _extract_ir(repo_path, ledger):
+    """Deterministic extraction of the forward canonical package into a typed graph. Every
+    node/edge is derived from an EXISTING structural convention or reference -- nothing is
+    inferred. A line that fills a structural slot but cannot be typed lands in `untyped`."""
+    nodes, edges, untyped = [], [], []
+    seen_ids = set()
+
+    def add(node):
+        if node["id"] not in seen_ids:
+            seen_ids.add(node["id"])
+            nodes.append(node)
+
+    # AC nodes <- ACCEPTANCE.md checkboxes carrying an AC id; a checkbox WITHOUT an id is an
+    # acceptance slot the conventions do not type -> untyped (never a guessed id).
+    acc_lines = _ir_read_lines(os.path.join(repo_path, "ACCEPTANCE.md")) or []
+    for n, ln in enumerate(acc_lines, 1):
+        s = ln.strip()
+        if s[:5].lower() not in ("- [x]", "- [ ]", "* [x]", "* [ ]"):
+            continue
+        m = _IR_AC_LINE.match(ln)
+        src = {"file": "ACCEPTANCE.md", "line": n}
+        if m:
+            add({"id": m.group(1).upper(), "type": "AC",
+                 "statement": m.group(2).strip(), "source": src})
+        else:
+            untyped.append({"text": s[5:].strip(), "source": src,
+                            "reason": "acceptance checkbox without a traceable AC-id"})
+
+    # INV nodes <- CONSTITUTION.md `- **INV-XXX-NN — Title.**` headings
+    con_lines = _ir_read_lines(os.path.join(repo_path, "CONSTITUTION.md")) or []
+    inv_ids = set()
+    for n, ln in enumerate(con_lines, 1):
+        m = _IR_INV_LINE.match(ln)
+        if m:
+            add({"id": m.group(1).upper(), "type": "INV",
+                 "statement": m.group(2).strip().rstrip("."),
+                 "source": {"file": "CONSTITUTION.md", "line": n}})
+            inv_ids.add(m.group(1).upper())
+
+    # DECISION nodes <- docs/adr/*.md (native ADR-NNN id, title, file); edges to the INVs the
+    # ADR governs/states, and supersedes edges -- both from references already in the body.
+    adr_dir = os.path.join(repo_path, "docs", "adr")
+    ac_ids = {nd["id"] for nd in nodes if nd["type"] == "AC"}
+    for row in _mirador_adrs(adr_dir):
+        add({"id": row["id"], "type": "DECISION", "statement": row["t"],
+             "source": {"file": os.path.relpath(row["file"], repo_path).replace(os.sep, "/"),
+                        "line": 1}})
+        body = _ir_read_lines(row["file"]) or []
+        text = "\n".join(body)
+        for inv in set(_IR_INV_REF.findall(text)):
+            if inv.upper() in inv_ids:
+                edges.append({"from": row["id"], "to": inv.upper(), "type": "DECISION->INV"})
+        for sup in set(_IR_SUPERSEDE.findall(text)):
+            edges.append({"from": row["id"],
+                          "to": "ADR-%03d" % int(re.search(r"\d+", sup).group()),
+                          "type": "supersedes"})
+        # an ADR's Verification checklist references its ACs -> REQ->AC is absent here (no REQ
+        # layer yet), but AC nodes referenced by an ADR are real edges DECISION mentions AC:
+        for aid in {m.group(0)[1:-1].upper()
+                    for m in re.finditer(r"\(AC-[A-Za-z0-9-]+\)", text)}:
+            if aid in ac_ids:                       # set(): an AC cited twice is one edge
+                edges.append({"from": row["id"], "to": aid, "type": "REQ->AC"})
+
+    # GOLDEN nodes <- git-tracked approved fixtures (the path is a native, stable id)
+    tracked = _tracked_files(repo_path) or []
+    gold_marker = ".appro" + "ved."
+    for f in tracked:
+        if gold_marker in f:
+            add({"id": f, "type": "GOLDEN", "statement": "approved golden fixture",
+                 "source": {"file": f, "line": 1}})
+
+    # OBS / CURATION <- the active delta's observations (all of them, so curation_closure is
+    # a real path query over the graph) + the ledger's curation records. Absent in a repo
+    # that never ran a field run -> simply no such nodes.
+    delta, derrs = _load_delta(repo_path)
+    if delta and not derrs:
+        for o in delta.get("observations") or []:
+            prov = (o.get("provenance") or {}).get("files") or []
+            add({"id": o["id"], "type": "OBS", "statement": o.get("statement") or "",
+                 "source": {"file": prov[0].split(":")[0] if prov else "delta", "line": 1}})
+    canon_path = os.path.join(repo_path, CANDIDATE_DIR, CANONICAL_FILE)
+    canon_items = []
+    if os.path.isfile(canon_path):
+        try:
+            with open(canon_path, encoding="utf-8-sig") as fh:
+                canon_items = json.load(fh).get("items") or []
+        except (OSError, ValueError):
+            canon_items = []
+    for it in canon_items:
+        oid = it.get("derived_from")
+        if not oid:
+            continue
+        prov = (it.get("provenance") or {}).get("files") or []
+        add({"id": oid, "type": "OBS", "statement": it.get("statement") or "",
+             "source": {"file": prov[0].split(":")[0] if prov else "canonical", "line": 1}})
+    for rec in ledger.get("curation") or []:
+        oid = rec.get("obs_id")
+        if not oid:
+            continue
+        cid = "CUR-" + hashlib.sha256(
+            (oid + "\n" + (rec.get("at") or "")).encode("utf-8")).hexdigest()[:12]
+        add({"id": cid, "type": "CURATION",
+             "statement": "%s: %s" % (rec.get("verdict"), oid),
+             "source": {"file": "QA-LEDGER.json", "line": 0}})
+        if oid in seen_ids:
+            edges.append({"from": oid, "to": cid, "type": "OBS->CURATION"})
+
+    node_ids = {nd["id"] for nd in nodes}
+    kept, dropped = [], 0
+    for e in edges:
+        if e["from"] in node_ids and e["to"] in node_ids:
+            kept.append(e)
+        elif e["type"] == "supersedes" and e["from"] in node_ids:
+            kept.append(e)                          # a superseded ADR may be archived; keep it
+        else:
+            dropped += 1
+    nodes.sort(key=lambda nd: (nd["type"], nd["id"]))
+    kept.sort(key=lambda e: (e["type"], e["from"], e["to"]))
+    untyped.sort(key=lambda u: (u["source"]["file"], u["source"]["line"]))
+    counts = {t: sum(1 for nd in nodes if nd["type"] == t) for t in IR_NODE_TYPES}
+    stats = {"nodes": len(nodes), "edges": len(kept),
+             "edges_dropped": dropped, "untyped": len(untyped),
+             "by_type": {t: c for t, c in counts.items() if c},
+             "untyped_rate": round(len(untyped) / (len(nodes) + len(untyped)), 4)
+             if (nodes or untyped) else 0.0}
+    graph = {"schema_version": IR_SCHEMA,
+             "_generated_by": "qa_ledger.py ir-extract (ADR-015) -- derived index of the "
+                              "canonical package; never hand-edit",
+             "nodes": nodes, "edges": kept, "untyped": untyped, "stats": stats}
+    # the seal covers stats too (fresh-review MEDIUM): a doctored summary that ir-render
+    # would faithfully print must trip the strict loader, not slip past it -- the
+    # derived-but-unsealed lesson, applied a third time (path @1.70, evidence_class @1.69).
+    graph["_integrity"] = _ir_seal(graph)
+    return graph
+
+
+def _ir_seal(graph):
+    return _integrity_hash({k: graph.get(k) for k in
+                            ("schema_version", "nodes", "edges", "untyped", "stats")})
+
+
+def _load_ir(repo_path):
+    """Strict loader: an unknown schema_version or a broken graph is exit-2 class, never
+    mis-read (AC-IR-05). Returns (graph, errors); graph None when absent."""
+    path = os.path.join(repo_path, IR_DIR, IR_FILE)
+    if not os.path.isfile(path):
+        return None, []
+    try:
+        with open(path, encoding="utf-8-sig") as fh:
+            g = json.load(fh)
+    except (OSError, ValueError) as exc:
+        return {}, ["unreadable: %s" % exc]
+    errors = []
+    if g.get("schema_version") != IR_SCHEMA:
+        errors.append("schema_version %r != %r (a version this engine does not know is not "
+                      "read, it is refused)" % (g.get("schema_version"), IR_SCHEMA))
+        return g, errors
+    if not isinstance(g.get("nodes"), list) or not isinstance(g.get("edges"), list):
+        return g, ["nodes/edges missing or not lists"]
+    if g.get("_integrity") != _ir_seal(g):
+        errors.append("integrity seal does not match the graph -- nodes, edges, untyped or "
+                      "stats was hand-edited (regenerate via ir-extract)")
+    return g, errors
+
+
+def _render_ir_md(graph):
+    st = graph.get("stats") or {}
+    lines = ["<!-- %s -->" % _IR_BANNER, "", "# Uscha IR v%s (rendered view)" % IR_SCHEMA, "",
+             "%d nodes · %d edges · %d UNTYPED (rate %.2f)"
+             % (st.get("nodes", 0), st.get("edges", 0), st.get("untyped", 0),
+                st.get("untyped_rate", 0.0)), "",
+             "## Nodes", "", "| id | type | statement | source |",
+             "|----|------|-----------|--------|"]
+    for nd in graph.get("nodes") or []:
+        src = "%s:%s" % (nd["source"]["file"], nd["source"]["line"])
+        stmt = (nd.get("statement") or "").replace("|", "\\|")
+        lines.append("| %s | %s | %s | %s |" % (nd["id"], nd["type"], stmt, src))
+    lines += ["", "## Edges", "", "| from | type | to |", "|------|------|----|"]
+    for e in graph.get("edges") or []:
+        lines.append("| %s | %s | %s |" % (e["from"], e["type"], e["to"]))
+    if graph.get("untyped"):
+        lines += ["", "## UNTYPED (conventions the human layer is missing)", "",
+                  "| text | source | reason |", "|------|--------|--------|"]
+        for u in graph["untyped"]:
+            src = "%s:%s" % (u["source"]["file"], u["source"]["line"])
+            txt = (u.get("text") or "").replace("|", "\\|")[:80]
+            lines.append("| %s | %s | %s |" % (txt, src, u.get("reason", "")))
+    lines.append("")
+    return "\n".join(lines)
+
+
+def cmd_ir_extract(args):
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _scope_path(ledger, args.repo)
+    graph = _extract_ir(repo_path, ledger)
+    ir_dir = os.path.join(repo_path, IR_DIR)
+    os.makedirs(ir_dir, exist_ok=True)
+    with open(os.path.join(ir_dir, IR_FILE), "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(json.dumps(graph, indent=2, ensure_ascii=False) + "\n")
+    twin_path = os.path.join(ir_dir, IR_TWIN)
+    twin = _render_ir_md(graph)
+    prev = None
+    if os.path.isfile(twin_path):
+        try:
+            with open(twin_path, encoding="utf-8-sig") as fh:
+                prev = fh.read()
+        except OSError:
+            prev = None
+    with open(twin_path, "w", encoding="utf-8", newline="\n") as fh:
+        fh.write(twin)
+    if prev is not None and prev != twin:
+        print("[qa_ledger] ir-extract: %s regenerated (rendered view, never a source)"
+              % IR_TWIN, file=sys.stderr)
+    st = graph["stats"]
+    if args.json:
+        print(json.dumps(st, indent=2, ensure_ascii=False))
+    else:
+        print("IR-EXTRACT %s: %d nodes, %d edges -> %s"
+              % (args.repo, st["nodes"], st["edges"],
+                 os.path.join(IR_DIR, IR_FILE)))
+        print("  by type: " + ", ".join("%s=%d" % (t, c)
+                                        for t, c in st["by_type"].items()))
+        print("  UNTYPED: %d (rate %.2f) -- the size of what the conventions cannot yet type"
+              % (st["untyped"], st["untyped_rate"]))
+        if st["edges_dropped"]:
+            print("  %d edge(s) dropped (endpoint not a node) -- counted, never dangling"
+                  % st["edges_dropped"])
+    sys.exit(0)
+
+
+def cmd_ir_render(args):
+    ledger = _load(args.ledger)
+    _repo_node(ledger, args.repo)
+    repo_path = _scope_path(ledger, args.repo)
+    graph, errors = _load_ir(repo_path)
+    if graph is None:
+        print("[qa_ledger] ir-render: no %s -- run ir-extract first."
+              % os.path.join(IR_DIR, IR_FILE), file=sys.stderr)
+        sys.exit(2)
+    if errors:
+        for e in errors:
+            print("[qa_ledger] ir-render: %s" % e, file=sys.stderr)
+        sys.exit(2)
+    twin = _render_ir_md(graph)
+    with open(os.path.join(repo_path, IR_DIR, IR_TWIN), "w", encoding="utf-8",
+              newline="\n") as fh:
+        fh.write(twin)
+    print("IR-RENDER %s: %s regenerated from the graph"
+          % (args.repo, os.path.join(IR_DIR, IR_TWIN)))
+    sys.exit(0)
+
+
 # --------------------------------------------------------------------------- #
 # facts  (T0 / SYSTEM-FACTS: public claims become compiled artifacts of repo
 # facts -- Diamond applied to Diamond. ADR-012.)
@@ -8687,9 +9012,29 @@ def build_parser():
     pfv.add_argument("--repo", required=True)
     pfv.add_argument("--config", default="uscha.config.json",
                      help="checked for defaults.fidelity.gate -- advisory there is a refusal")
+    pfv.add_argument("--ir", action="store_true",
+                     help="answer curation_closure as a path query over the IR graph "
+                          "(ADR-015); reproduces v0 from the derived index")
     pfv.add_argument("--json", action="store_true")
     pfv.set_defaults(func=cmd_fidelity)
 
+    pie = sub.add_parser(
+        "ir-extract",
+        help="extract the canonical package into a typed graph (ir/IR.json); what cannot be "
+             "typed deterministically is UNTYPED, counted, never guessed (ADR-015)")
+    pie.add_argument("--ledger", default="QA-LEDGER.json")
+    pie.add_argument("--repo", required=True)
+    pie.add_argument("--json", action="store_true")
+    pie.set_defaults(func=cmd_ir_extract)
+
+    pir = sub.add_parser(
+        "ir-render",
+        help="regenerate the human view (ir/IR.md) from the graph; round-trip content-stable "
+             "for the structured parts (ADR-015)")
+    pir.add_argument("--ledger", default="QA-LEDGER.json")
+    pir.add_argument("--repo", required=True)
+    pir.set_defaults(func=cmd_ir_render)
+
     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/uscha.config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.70.0",
+  "version": "1.72.0",
   "project": null,
   "defaults": {
     "coverage_threshold": 60,