medsci-skills 4.1.0

package/skills/self-review/scripts/check_confounding_completeness.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+"""Confounding-completeness gate for observational studies (self-review Phase 2.5e).
+
+The highest-yield observational reviewer finding is also the most mechanical: a
+covariate that was *measured*, is *imbalanced across exposure groups* in the
+baseline table, and is *absent from the adjustment set* is residual confounding
+by a measured variable. A single-pass prose review misses it because the
+manuscript text is internally consistent; only a join of the exposure-stratified
+Table 1 against the Methods adjustment set exposes it. This script is that join
+(probe O1 of observational_confounding.md), backported from the panel so the
+deterministic finding lands without a multi-agent pass.
+
+INPUTS
+  --table1   exposure-stratified baseline table, CSV. One row per covariate.
+             Needs a covariate-name column and a p-value (or SMD) column. Column
+             names are auto-detected (case-insensitive); override with
+             --name-col / --p-col / --smd-col. A file named like
+             `table1_by_<exposure>.csv` is the convention.
+  --adjusted adjustment-set variables. Either a path to a file (one variable per
+             line, or a Methods paragraph the script greps after "adjusted for")
+             or a comma-separated list passed inline with --adjusted-list.
+
+OUTPUT
+  A reconciliation table (stdout) and, with --out, a JSON artifact:
+    {covariate, imbalance_p / smd, in_adjustment_set, verdict}
+  verdict UNADJUSTED_IMBALANCED is the Major candidate. Exit 1 (with --strict)
+  when any UNADJUSTED_IMBALANCED row exists.
+
+Matching the adjustment set to Table-1 covariate labels is fuzzy (a table row
+"Smoking, pack-years" vs an adjustment token "smoking"), so the match is a
+normalized-substring test in both directions; review the reconciliation table
+rather than trusting the count blindly.
+
+Stdlib-only (csv / json / re / argparse). Exit codes: 0 clean (or report-only),
+1 unadjusted-imbalanced rows found (with --strict), 2 input/usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import re
+import sys
+from pathlib import Path
+
+# --- column auto-detection -------------------------------------------------
+
+NAME_HINTS = ("covariate", "variable", "characteristic", "feature", "name", "")
+P_HINTS = ("p_value", "pvalue", "p-value", "p val", "p", "pr")
+SMD_HINTS = ("smd", "std_diff", "standardized", "std. mean", "std mean")
+
+P_THRESHOLD = 0.05
+SMD_THRESHOLD = 0.10
+
+# Header / summary rows that are not covariates (sample-size lines, group totals,
+# trend-p rows). Matched on the whole normalized label, not a substring, so a real
+# covariate like "Total cholesterol" is not swallowed by "total".
+def _is_skip_row(cov: str) -> bool:
+    c = _norm(cov)
+    if c in ("", "total", "overall", "n", "no", "number"):
+        return True
+    if re.match(r"^n\s*[=:]", cov.strip().lower()):     # "N = ...", "n: ..."
+        return True
+    if "p for trend" in c or "p trend" in c or "for trend" in c:
+        return True
+    return False
+
+
+def _norm(s: str) -> str:
+    """Lowercase, drop punctuation/units, collapse whitespace for fuzzy match."""
+    s = s.lower()
+    s = re.sub(r"\(.*?\)", " ", s)            # drop "(mg/dL)", "(%)"
+    s = re.sub(r"[^a-z0-9 ]+", " ", s)        # punctuation -> space
+    s = re.sub(r"\s+", " ", s).strip()
+    return s
+
+
+def _pick_col(header: list[str], hints: tuple[str, ...], override: str | None) -> int | None:
+    if override:
+        for i, h in enumerate(header):
+            if _norm(h) == _norm(override):
+                return i
+        sys.stderr.write(f"ERROR: column '{override}' not found in header {header}\n")
+        return None
+    norm = [_norm(h) for h in header]
+    # exact-ish first
+    for hint in hints:
+        h = _norm(hint)
+        for i, col in enumerate(norm):
+            if col == h and h:
+                return i
+    # then substring
+    for hint in hints:
+        h = _norm(hint)
+        for i, col in enumerate(norm):
+            if h and h in col:
+                return i
+    return None
+
+
+def _parse_p(raw: str) -> float | None:
+    """Parse a p-value cell: '0.001', '<0.001', 'p<0.01', '0.03*', 'NS'."""
+    if raw is None:
+        return None
+    s = raw.strip().lower()
+    if not s or s in ("ns", "na", "n/a", "-", "."):
+        return 1.0 if s == "ns" else None
+    m = re.search(r"<\s*(0?\.[0-9]+|[0-9]+\.?[0-9]*)", s)   # "<0.001", "p<.01"
+    if m:
+        try:                                   # report just under the stated bound
+            return max(float(m.group(1)) - 1e-6, 0.0)
+        except ValueError:
+            return None
+    m = re.search(r"0?\.[0-9]+|[0-9]+\.?[0-9]*", s)
+    if m:
+        try:
+            return float(m.group(0))
+        except ValueError:
+            return None
+    return None
+
+
+def _parse_float(raw: str) -> float | None:
+    if raw is None:
+        return None
+    m = re.search(r"-?[0-9]*\.?[0-9]+", raw.strip())
+    return float(m.group(0)) if m else None
+
+
+# --- adjustment set --------------------------------------------------------
+
+def load_adjustment_set(path: str | None, inline: str | None) -> list[str]:
+    if inline:
+        return [t.strip() for t in inline.split(",") if t.strip()]
+    if not path:
+        return []
+    p = Path(path)
+    if not p.is_file():
+        sys.stderr.write(f"ERROR: adjustment file not found: {path}\n")
+        sys.exit(2)
+    text = p.read_text(encoding="utf-8")
+    # If the file is a Methods paragraph, grep the "adjusted for ..." clause.
+    m = re.search(r"adjust(?:ed|ing)?\s+for\s+(.+?)(?:\.|;|\n\n|$)", text, re.I | re.S)
+    if m:
+        clause = m.group(1)
+        parts = re.split(r",| and | as well as ", clause)
+        return [p2.strip() for p2 in parts if p2.strip()]
+    # Otherwise treat as one variable per line.
+    return [ln.strip() for ln in text.splitlines() if ln.strip() and not ln.startswith("#")]
+
+
+def in_adjustment_set(cov: str, adj_norm: list[str]) -> bool:
+    c = _norm(cov)
+    if not c:
+        return False
+    for a in adj_norm:
+        if not a:
+            continue
+        if a in c or c in a:
+            return True
+        # token overlap on the leading word (smoking ~ "smoking, pack-years")
+        if c.split(" ")[0] == a.split(" ")[0] and len(c.split(" ")[0]) >= 3:
+            return True
+    return False
+
+
+# --- core ------------------------------------------------------------------
+
+def analyze(table1: str, adj: list[str], name_col, p_col, smd_col) -> dict:
+    p = Path(table1)
+    if not p.is_file():
+        sys.stderr.write(f"ERROR: table1 not found: {table1}\n")
+        sys.exit(2)
+    with p.open(encoding="utf-8-sig", newline="") as f:
+        reader = csv.reader(f)
+        rows = [r for r in reader if any(c.strip() for c in r)]
+    if len(rows) < 2:
+        sys.stderr.write("ERROR: table1 has no data rows\n")
+        sys.exit(2)
+    header = rows[0]
+    ni = _pick_col(header, NAME_HINTS, name_col)
+    pi = _pick_col(header, P_HINTS, p_col)
+    si = _pick_col(header, SMD_HINTS, smd_col)
+    if ni is None:
+        ni = 0
+    if pi is None and si is None:
+        sys.stderr.write("ERROR: could not locate a p-value or SMD column; pass --p-col/--smd-col\n")
+        sys.exit(2)
+
+    adj_norm = [_norm(a) for a in adj]
+    findings = []
+    for r in rows[1:]:
+        if ni >= len(r):
+            continue
+        cov = r[ni].strip()
+        if _is_skip_row(cov):
+            continue
+        pval = _parse_p(r[pi]) if (pi is not None and pi < len(r)) else None
+        smd = _parse_float(r[si]) if (si is not None and si < len(r)) else None
+        imbalanced = (pval is not None and pval < P_THRESHOLD) or \
+                     (smd is not None and abs(smd) >= SMD_THRESHOLD)
+        if not imbalanced:
+            continue
+        adjusted = in_adjustment_set(cov, adj_norm)
+        findings.append({
+            "covariate": cov,
+            "imbalance_p": pval,
+            "smd": smd,
+            "in_adjustment_set": adjusted,
+            "verdict": "ADJUSTED" if adjusted else "UNADJUSTED_IMBALANCED",
+        })
+
+    unadjusted = [f for f in findings if f["verdict"] == "UNADJUSTED_IMBALANCED"]
+    return {
+        "table1": str(p),
+        "adjustment_set": adj,
+        "thresholds": {"p": P_THRESHOLD, "smd": SMD_THRESHOLD},
+        "n_imbalanced": len(findings),
+        "n_unadjusted_imbalanced": len(unadjusted),
+        "findings": findings,
+        "verdict": "MAJOR_CANDIDATE" if unadjusted else "OK",
+        "suggested_fix": (
+            "Report an extended-adjustment sensitivity model adding the "
+            "unadjusted imbalanced covariates; keep the original model primary "
+            "only if the extended model agrees."
+        ) if unadjusted else None,
+    }
+
+
+def render_table(result: dict) -> str:
+    lines = [
+        "| Covariate | Imbalance p | SMD | In adjustment set? | Verdict |",
+        "|---|---|---|---|---|",
+    ]
+    for f in result["findings"]:
+        p = "—" if f["imbalance_p"] is None else f"{f['imbalance_p']:.4g}"
+        s = "—" if f["smd"] is None else f"{f['smd']:.3g}"
+        mark = "✗ Major" if f["verdict"] == "UNADJUSTED_IMBALANCED" else "✓"
+        lines.append(
+            f"| {f['covariate']} | {p} | {s} | "
+            f"{'yes' if f['in_adjustment_set'] else 'NO'} | {mark} |"
+        )
+    return "\n".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Observational confounding-completeness gate (O1).")
+    ap.add_argument("--table1", required=True, help="exposure-stratified Table 1 CSV")
+    ap.add_argument("--adjusted", help="adjustment-set file (var-per-line or Methods paragraph)")
+    ap.add_argument("--adjusted-list", help="comma-separated adjustment variables (inline)")
+    ap.add_argument("--name-col", help="override covariate-name column header")
+    ap.add_argument("--p-col", help="override p-value column header")
+    ap.add_argument("--smd-col", help="override SMD column header")
+    ap.add_argument("--out", help="write JSON artifact to this path")
+    ap.add_argument("--strict", action="store_true", help="exit 1 if unadjusted-imbalanced rows exist")
+    args = ap.parse_args()
+
+    adj = load_adjustment_set(args.adjusted, args.adjusted_list)
+    if not adj:
+        sys.stderr.write("WARN: empty adjustment set — every imbalanced covariate will flag.\n")
+
+    result = analyze(args.table1, adj, args.name_col, args.p_col, args.smd_col)
+
+    print("=" * 41)
+    print(" Confounding Completeness (Phase 2.5e / O1)")
+    print("=" * 41)
+    print(f"adjustment set: {', '.join(adj) if adj else '(none)'}")
+    print(render_table(result))
+    print()
+    if result["n_unadjusted_imbalanced"]:
+        print(f"MAJOR candidate: {result['n_unadjusted_imbalanced']} imbalanced covariate(s) "
+              f"absent from the adjustment set.")
+        print(f"Fix: {result['suggested_fix']}")
+    else:
+        print("OK: no measured-but-unadjusted imbalanced covariate.")
+
+    if args.out:
+        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.out).write_text(json.dumps(result, indent=2), encoding="utf-8")
+        print(f"\nwrote {args.out}")
+
+    return 1 if (args.strict and result["n_unadjusted_imbalanced"]) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/self-review/scripts/check_panel_diversity.py

@@ -0,0 +1,336 @@
+#!/usr/bin/env python3
+"""Panel lens-diversity gate (self-review Phase 2.6, --panel).
+
+A multi-agent panel is only worth its cost if its reviewers cover *distinct*
+concern axes. Left unchecked, independent reviewers converge on the same easy
+themes (everyone flags "missing calibration") while whole high-risk axes go
+unprobed — the panel collapses to fewer effective lenses than reviewers, and
+the editor synthesis cannot tell monoculture from genuine consensus. This gate
+post-processes the reviewers' structured output (the panel_review_template
+schema the editor already collects) and reports three diversity failures:
+
+  UNCOVERED_AXIS     an expected high-risk axis for this research type produced
+                     ZERO major findings across the whole panel. Mirrors the
+                     "completeness critic" pattern: name what nobody probed so
+                     the editor can re-probe it before finalizing. (Major)
+  FAMILY_MONOCULTURE the panel's major findings concentrate in ONE concern
+                     family beyond a threshold (one family holds the majority),
+                     a signal the lenses converged rather than spanned the
+                     manuscript. (Major)
+  LENS_COLLAPSE      one reviewer contributed only families that another
+                     reviewer already covered — a fully-redundant lens that
+                     added no independent signal. Distinct from healthy
+                     CONSENSUS (a reviewer agreeing on SOME themes but also
+                     raising at least one family nobody else did). (Flag)
+
+Healthy consensus is preserved: a finding family raised by ≥2 reviewers is a
+strength, not a defect. The gate only fires LENS_COLLAPSE when a reviewer's
+ENTIRE contribution is redundant, and UNCOVERED_AXIS/MONOCULTURE on
+panel-level coverage, never on agreement per se.
+
+INPUTS
+  --panel  JSON file. Either a list of reviewer objects, or an object with a
+           "reviewers" list (and optional "research_type"). Each reviewer
+           object needs reviewer_id, expertise_area, and major[] (with heading
+           and/or comment text); minor[] is ignored for axis coverage.
+  --research-type  one of: survival, sr_ma, radiomics, dta, observational,
+           narrative (synonyms accepted). Overrides any value in the JSON.
+           When unknown/absent, UNCOVERED_AXIS is skipped (cannot know the
+           expected axes) and noted in the summary.
+
+OUTPUT
+  A diversity table (stdout) and, with --out, a JSON artifact:
+    {panel, research_type, claims[{verdict, severity, detail, where}], summary}
+  summary carries the family histogram, concentration index, and the
+  expected/covered/uncovered axes. Exit 1 (with --strict) when any Major claim
+  exists; exit 2 on input error.
+
+Stdlib-only (json / re / argparse / pathlib). Exit codes: 0 clean (or
+report-only), 1 Major claim(s) found (with --strict), 2 input/usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# Concern families, aligned to the panel's per-domain focus checklists and the
+# self-review A–J category system. Each finding is assigned to the FIRST family
+# whose lexicon matches its text; order is most-specific to most-generic so a
+# leakage finding is not swallowed by the generic "statistics" family.
+FAMILY_LEXICON: list[tuple[str, re.Pattern]] = [
+    ("search_screening", re.compile(
+        r"search strateg|screening|eligibilit|inclusion criteri|exclusion criteri|"
+        r"database\b|grey literature|gray literature|duplicate (?:removal|record)|"
+        r"prisma flow|records identified|study selection", re.IGNORECASE)),
+    ("design_leakage", re.compile(
+        r"leakage|data (?:split|leak)|train(?:ing|/test| test)|test set|"
+        r"contaminat|allocation|randomi[sz]|immortal time|time[-\s]?zero|"
+        r"selection bias|spectrum bias|case[-\s]?control selection|"
+        r"reference standard|verification bias", re.IGNORECASE)),
+    ("confounding", re.compile(
+        r"confound|residual confounding|covariate|adjust(?:ment|ed)|mediator|"
+        r"collider|confounding by indication|propensity", re.IGNORECASE)),
+    ("imaging", re.compile(
+        r"acquisition|scanner|sequence|segmentation|voxel|kernel|reconstruction|"
+        r"combat|harmoni[sz]|slice thickness|field strength|radiomic feature|"
+        r"window(?:ing| level)|protocol heterogeneity", re.IGNORECASE)),
+    ("reporting", re.compile(
+        r"strobe|tripod|prisma\b|consort|claim\b|stard|reporting (?:guideline|standard|"
+        r"completeness)|checklist|flow diagram|disclosure|registration|protocol "
+        r"deviation|abstract (?:inconsisten|mismatch)", re.IGNORECASE)),
+    ("reproducibility", re.compile(
+        r"reproducib|code availab|data availab|random seed|\bseed\b|script\b|"
+        r"open (?:data|code)|version pin", re.IGNORECASE)),
+    ("statistics", re.compile(
+        r"calibrat|discriminat|\bauc\b|c[-\s]?statistic|delong|confidence interval|"
+        r"\bci\b|heterogeneit|\bi2\b|i\^?2|pooling|pooled|random[-\s]?effects|"
+        r"multiplicit|multiple compar|\bp[-\s]?value|\bpower\b|sample size|"
+        r"model specif|proportional hazard|missing data|imputation|competing risk|"
+        r"events per variable|overfitting|effect size|subdistribution", re.IGNORECASE)),
+    ("clinical", re.compile(
+        r"clinical|actionab|guideline|management|generali[sz]ab|applicab|"
+        r"external validit|patient[-\s]?care|over(?:reach|claim)|"
+        r"clinical (?:relevance|utility|significance)", re.IGNORECASE)),
+]
+
+# Expected high-risk axes per research type (each SHOULD yield ≥1 major). Mirrors
+# the Phase 2.6 reviewer-set table; optional axes (e.g. imaging when the exposure
+# is non-imaging) are not required and so are omitted here.
+EXPECTED_AXES: dict[str, list[str]] = {
+    "survival": ["statistics", "clinical"],
+    "sr_ma": ["search_screening", "clinical", "statistics"],
+    "radiomics": ["imaging", "statistics", "clinical"],
+    "dta": ["design_leakage", "statistics", "clinical"],
+    "observational": ["confounding", "clinical", "statistics"],
+    "narrative": ["clinical", "reporting"],
+}
+
+RESEARCH_TYPE_SYNONYMS: dict[str, str] = {
+    "survival": "survival", "prognostic": "survival", "cohort": "survival",
+    "sr": "sr_ma", "ma": "sr_ma", "sr_ma": "sr_ma", "sr/ma": "sr_ma",
+    "systematic review": "sr_ma", "meta-analysis": "sr_ma", "meta analysis": "sr_ma",
+    "radiomics": "radiomics", "feature": "radiomics",
+    "dta": "dta", "diagnostic": "dta", "diagnostic-accuracy": "dta", "ai model": "dta",
+    "observational": "observational", "strobe": "observational",
+    "narrative": "narrative", "review article": "narrative", "sanra": "narrative",
+}
+
+MONOCULTURE_MIN_MAJORS = 4   # too few majors to call concentration meaningful
+MONOCULTURE_SHARE = 0.60     # one family holding > this share = monoculture
+
+
+def normalize_research_type(raw: str | None) -> str | None:
+    if not raw:
+        return None
+    key = raw.strip().lower()
+    if key in RESEARCH_TYPE_SYNONYMS:
+        return RESEARCH_TYPE_SYNONYMS[key]
+    for syn, canon in RESEARCH_TYPE_SYNONYMS.items():
+        if syn in key:
+            return canon
+    return None
+
+
+def classify(text: str) -> str:
+    for family, pat in FAMILY_LEXICON:
+        if pat.search(text):
+            return family
+    return "other"
+
+
+def finding_text(major: dict) -> str:
+    parts = [str(major.get(k, "")) for k in ("heading", "comment", "location")]
+    return " ".join(p for p in parts if p)
+
+
+def load_reviewers(obj) -> tuple[list[dict], str | None]:
+    if isinstance(obj, list):
+        return obj, None
+    if isinstance(obj, dict):
+        revs = obj.get("reviewers")
+        if isinstance(revs, list):
+            return revs, obj.get("research_type")
+    raise ValueError("panel JSON must be a list of reviewers or an object with a 'reviewers' list")
+
+
+def check(reviewers: list[dict], research_type: str | None) -> tuple[list[dict], dict]:
+    claims: list[dict] = []
+
+    # Per-reviewer families (set of distinct families this reviewer raised as majors)
+    rev_families: dict[str, set[str]] = {}
+    family_hist: dict[str, int] = {}
+    n_majors = 0
+    for i, rev in enumerate(reviewers):
+        rid = str(rev.get("reviewer_id") or f"R{i + 1}")
+        fams: set[str] = set()
+        for maj in rev.get("major", []) or []:
+            fam = classify(finding_text(maj))
+            fams.add(fam)
+            family_hist[fam] = family_hist.get(fam, 0) + 1
+            n_majors += 1
+        rev_families[rid] = fams
+
+    covered = set(family_hist)
+    covered.discard("other")
+
+    # 1) UNCOVERED_AXIS — only when we know the expected axes
+    expected: list[str] = []
+    uncovered: list[str] = []
+    if research_type and research_type in EXPECTED_AXES:
+        expected = EXPECTED_AXES[research_type]
+        uncovered = [ax for ax in expected if family_hist.get(ax, 0) == 0]
+        for ax in uncovered:
+            claims.append({
+                "verdict": "UNCOVERED_AXIS",
+                "severity": "Major",
+                "detail": (f"no major finding addresses the '{ax}' axis, which a "
+                           f"{research_type} panel is expected to probe; the editor "
+                           f"should re-probe it before finalizing"),
+                "where": f"expected axes for {research_type}: {', '.join(expected)}",
+            })
+
+    # 2) FAMILY_MONOCULTURE — concentration of majors in one family
+    hhi = 0.0
+    top_family = None
+    top_share = 0.0
+    if n_majors:
+        shares = {f: c / n_majors for f, c in family_hist.items() if f != "other"}
+        hhi = sum(s * s for s in shares.values())
+        if shares:
+            top_family, top_share = max(shares.items(), key=lambda kv: kv[1])
+        if n_majors >= MONOCULTURE_MIN_MAJORS and top_share > MONOCULTURE_SHARE:
+            claims.append({
+                "verdict": "FAMILY_MONOCULTURE",
+                "severity": "Major",
+                "detail": (f"{top_share:.0%} of major findings fall in the '{top_family}' "
+                           f"family ({family_hist.get(top_family, 0)}/{n_majors}); the panel "
+                           f"converged on one axis rather than spanning the manuscript"),
+                "where": "family histogram: " + ", ".join(
+                    f"{f}={c}" for f, c in sorted(family_hist.items(), key=lambda kv: -kv[1])),
+            })
+
+    # 3) LENS_COLLAPSE — a reviewer whose every family is also covered by another
+    for rid, fams in rev_families.items():
+        own = {f for f in fams if f != "other"}
+        if not own:
+            continue
+        others = set()
+        for other_rid, other_fams in rev_families.items():
+            if other_rid != rid:
+                others |= {f for f in other_fams if f != "other"}
+        if own and own <= others:  # fully subsumed by other reviewers
+            claims.append({
+                "verdict": "LENS_COLLAPSE",
+                "severity": "Flag",
+                "detail": (f"reviewer {rid} raised only families also covered by other "
+                           f"reviewers ({', '.join(sorted(own))}); this lens added no "
+                           f"independent axis — confirm it is a genuine consensus, not a "
+                           f"redundant reviewer assignment"),
+                "where": f"reviewer {rid}",
+            })
+
+    # 4) THIN_PANEL
+    if len(reviewers) < 2:
+        claims.append({
+            "verdict": "THIN_PANEL",
+            "severity": "Flag",
+            "detail": (f"only {len(reviewers)} reviewer(s); a panel needs ≥2 independent "
+                       f"lenses for diversity to be meaningful"),
+            "where": "panel composition",
+        })
+
+    summary = {
+        "n_reviewers": len(reviewers),
+        "n_majors": n_majors,
+        "family_histogram": family_hist,
+        "concentration_hhi": round(hhi, 3),
+        "top_family": top_family,
+        "top_family_share": round(top_share, 3),
+        "expected_axes": expected,
+        "covered_axes": sorted(covered),
+        "uncovered_axes": uncovered,
+        "research_type_known": bool(research_type and research_type in EXPECTED_AXES),
+    }
+    return claims, summary
+
+
+def analyze(panel: str, research_type_arg: str | None) -> dict:
+    p = Path(panel)
+    if not p.is_file():
+        sys.stderr.write(f"ERROR: panel JSON not found: {panel}\n")
+        sys.exit(2)
+    try:
+        obj = json.loads(p.read_text(encoding="utf-8"))
+        reviewers, rt_in_json = load_reviewers(obj)
+    except (ValueError, json.JSONDecodeError) as exc:
+        sys.stderr.write(f"ERROR: {exc}\n")
+        sys.exit(2)
+
+    research_type = normalize_research_type(research_type_arg) or normalize_research_type(rt_in_json)
+    claims, summary = check(reviewers, research_type)
+    n_major = sum(1 for c in claims if c["severity"] == "Major")
+    summary["n_claims"] = len(claims)
+    summary["n_major"] = n_major
+    summary["n_flag"] = len(claims) - n_major
+    summary["verdict"] = "MAJOR_CANDIDATE" if n_major else "OK"
+    return {
+        "panel": str(p),
+        "research_type": research_type,
+        "claims": claims,
+        "summary": summary,
+    }
+
+
+def render(result: dict) -> str:
+    lines = ["| Check | Severity | Detail |", "|---|---|---|"]
+    for c in result["claims"]:
+        lines.append(f"| {c['verdict']} | {c['severity']} | {c['detail']} |")
+    if len(lines) == 2:
+        lines.append("| (none) | — | panel lenses span distinct axes; no monoculture |")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Panel lens-diversity gate (Phase 2.6, --panel).")
+    ap.add_argument("--panel", required=True, help="reviewers JSON (list or {reviewers:[...]})")
+    ap.add_argument("--research-type", help="survival|sr_ma|radiomics|dta|observational|narrative")
+    ap.add_argument("--out", help="write JSON artifact to this path")
+    ap.add_argument("--strict", action="store_true", help="exit 1 if any Major claim exists")
+    ap.add_argument("--quiet", action="store_true", help="suppress stdout table")
+    args = ap.parse_args()
+
+    result = analyze(args.panel, args.research_type)
+
+    if not args.quiet:
+        print("=" * 41)
+        print(" Panel Lens-Diversity (Phase 2.6)")
+        print("=" * 41)
+        print(render(result))
+        print()
+        s = result["summary"]
+        if not s["research_type_known"]:
+            print("NOTE: research type unknown — UNCOVERED_AXIS skipped "
+                  "(pass --research-type to enable axis-coverage checks).")
+        if s["n_major"]:
+            print(f"MAJOR candidate: {s['n_major']} diversity failure(s); "
+                  f"covered axes: {', '.join(s['covered_axes']) or '(none)'}.")
+        else:
+            print(f"OK: {s['n_reviewers']} reviewers spanning "
+                  f"{len(s['covered_axes'])} distinct axes "
+                  f"(HHI={s['concentration_hhi']}).")
+
+    if args.out:
+        Path(args.out).parent.mkdir(parents=True, exist_ok=True)
+        Path(args.out).write_text(json.dumps(result, indent=2), encoding="utf-8")
+        if not args.quiet:
+            print(f"\nwrote {args.out}")
+
+    return 1 if (args.strict and result["summary"]["n_major"]) else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())