medsci-skills 4.1.0

package/skills/meta-analysis/references/submission_package_drift.md

@@ -0,0 +1,71 @@
+# Submission Package Drift Control
+
+**Applies to**: situations with multiple coexisting journal targets (academic radiology / DIR / BJR / MDPI Diagnostics, etc.).
+
+## The problem
+
+When 4~5 per-journal `SUBMISSION/{journal}/` folders coexist and each holds the full body/supplement/figures, there is a drift risk after rebuilds: it becomes unclear which folder is the master, and a typo fixed in only one folder gets re-propagated to the other targets.
+
+## Rules
+
+### SPD-1. Single master + build script
+- **Rule**: There is exactly one `7_Manuscript/` master. Per-journal conversion is handled by `SUBMISSION/_build.sh`.
+- **Build output**: `SUBMISSION/{journal}/{manuscript.docx, supplement.docx, figures/, tables/}` — these are **build artifacts; do not edit by hand**.
+
+### SPD-2. `DO_NOT_EDIT_HERE.md` gate
+- **Rule**: Place a `DO_NOT_EDIT_HERE.md` file in each per-journal folder. When this file is present, the body/supplement/figure in that directory must not be edited. Allowed exception files:
+  - `cover_letter.docx`
+  - `title_page.docx`
+  - `highlights.txt`
+  - `checklist.md` (journal-specific reporting checklist)
+  - `response_to_reviewers.docx` (during revision)
+- These exception files are needed per-journal, so direct editing is allowed.
+
+### SPD-3. Record build time in `MANIFEST.md`
+- **Rule**: Four lines in each `SUBMISSION/{journal}/MANIFEST.md`:
+  1. `_build.sh` run timestamp
+  2. Source: master manuscript commit / `v{N}`
+  3. List of files allowed to be edited in the journal folder
+  4. Confirmation that all `[VERIFY-CSV]` tags were removed (timestamp of `rg` → 0 hits)
+
+### SPD-4. Handling re-targeting after rejection
+- **Same content → different journal**: `_build.sh --journal {new}` for a new folder. No Zenodo DOI re-issue needed. Move the old journal folder to `_archive/`.
+- **After revision, same journal**: `_build.sh --journal {same} --revision {n}`. Build the Response matrix + the changed manuscript together.
+- **Major revision → different journal**: new folder + new Zenodo version (content changed).
+
+## Templates
+
+### `_build.sh` base structure
+```bash
+#!/bin/bash
+# SUBMISSION/_build.sh
+# Usage: ./_build.sh --journal {academic_radiology|dir|bjr|mdpi_diagnostics|...} [--revision N]
+
+set -euo pipefail
+JOURNAL="$1"
+# Per-journal config: word limit, figure limit, reference style, supplement rules
+source "configs/${JOURNAL}.sh"
+
+# Build manuscript
+pandoc "../7_Manuscript/master.md" \
+    --reference-doc "configs/${JOURNAL}_template.docx" \
+    --citeproc --csl "configs/${JOURNAL}.csl" \
+    -o "${JOURNAL}/manuscript.docx"
+
+# Build supplement
+# ... figures, tables, DO_NOT_EDIT_HERE.md touch, MANIFEST.md update
+```
+
+### `DO_NOT_EDIT_HERE.md` contents
+```
+This directory holds build artifacts from SUBMISSION/_build.sh.
+
+Do not edit the body/supplement/figures here. The master is /7_Manuscript/.
+
+Files allowed to be edited:
+- cover_letter.docx
+- title_page.docx
+- highlights.txt
+- checklist.md
+- response_to_reviewers.docx (during revision)
+```

package/skills/meta-analysis/scripts/check_pool_consistency.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""
+check_pool_consistency.py — Phase 4 entry gate.
+
+Asserts UID-set equality between (a) the frozen `FINAL_POOL_LOCK.yaml`
+and (b) the actual round-3 adjudication TSV that feeds extraction. Blocks
+Phase 4 (data extraction) until the two agree.
+
+Why this gate exists
+====================
+Cross-project precedent (anonymized): an LLM reporting-quality SR carried
+five documents that disagreed on INCLUDE/EXCLUDE counts. Three EXCLUDE
+rows existed in the downstream extraction sheet without matching INCLUDE
+decisions. The drift traced to a post-freeze adjudication change that
+propagated to the extraction TSV but not the lock — or the other way
+around. Either direction is fatal at peer review.
+
+The gate fails CLOSED: if the lock and the extraction sheet disagree on
+even one UID, extraction is blocked.
+
+Inputs
+======
+
+  --lock PATH              FINAL_POOL_LOCK.yaml (Phase 3f.5 artifact)
+  --adjudication-tsv PATH  round3_adjudication.tsv (Phase 3c artifact)
+  --decision-col NAME      column holding the decision label
+                           (default: "round3_decision")
+  --uid-col NAME           column holding the UID (default: "uid")
+  --include-labels LIST    decisions counted as INCLUDE
+                           (default: "INCLUDE,INCLUDE_MIXED")
+  --out PATH               JSON report (default: qc/pool_consistency.json)
+
+Output JSON
+===========
+
+    {
+      "submission_safe": false,
+      "lock_include_n": 42,
+      "tsv_include_n": 43,
+      "in_lock_not_tsv": ["UID_007"],
+      "in_tsv_not_lock": ["UID_055"],
+      "match": false
+    }
+
+Exit codes
+==========
+  0  lock and TSV agree on the UID set
+  1  disagreement (PR T1-5 blocks extraction)
+  2  invocation error (missing files, missing columns)
+
+Read-only script. No file modification.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+
+
+def load_lock_uids(lock_path: Path, label_set: list[str]) -> set[str]:
+    try:
+        import yaml  # type: ignore
+    except ImportError:
+        print(
+            "ERROR: PyYAML required for --lock parsing. pip install PyYAML",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+    data = yaml.safe_load(lock_path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        print(f"ERROR: lock file not a mapping: {lock_path}", file=sys.stderr)
+        sys.exit(2)
+    # INCLUDE_MIXED maps to mixed_uids in the lock template.
+    uids: set[str] = set()
+    if "INCLUDE" in label_set:
+        uids.update(str(u) for u in (data.get("include_uids") or []))
+    if "INCLUDE_MIXED" in label_set:
+        uids.update(str(u) for u in (data.get("mixed_uids") or []))
+    if "MIXED" in label_set:
+        uids.update(str(u) for u in (data.get("mixed_uids") or []))
+    if "EXCLUDE" in label_set:
+        uids.update(str(u) for u in (data.get("exclude_uids") or []))
+    return uids
+
+
+def load_tsv_uids(
+    tsv_path: Path,
+    decision_col: str,
+    uid_col: str,
+    label_set: set[str],
+) -> set[str]:
+    # Allow .tsv or .csv (sniff by extension).
+    delim = "," if tsv_path.suffix.lower() == ".csv" else "\t"
+    with tsv_path.open("r", encoding="utf-8", newline="") as fh:
+        reader = csv.DictReader(fh, delimiter=delim)
+        if reader.fieldnames is None:
+            print(f"ERROR: empty TSV: {tsv_path}", file=sys.stderr)
+            sys.exit(2)
+        if uid_col not in reader.fieldnames:
+            print(
+                f"ERROR: uid column {uid_col!r} not in TSV columns "
+                f"{reader.fieldnames!r}",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+        if decision_col not in reader.fieldnames:
+            print(
+                f"ERROR: decision column {decision_col!r} not in TSV columns "
+                f"{reader.fieldnames!r}",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+        uids: set[str] = set()
+        for row in reader:
+            decision = (row.get(decision_col) or "").strip()
+            if decision in label_set:
+                uid = (row.get(uid_col) or "").strip()
+                if uid:
+                    uids.add(uid)
+        return uids
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Phase 4 entry gate: asserts UID-set equality between the frozen "
+            "FINAL_POOL_LOCK.yaml and the round-3 adjudication TSV."
+        )
+    )
+    parser.add_argument("--lock", type=Path, required=True)
+    parser.add_argument("--adjudication-tsv", type=Path, required=True)
+    parser.add_argument("--decision-col", default="round3_decision")
+    parser.add_argument("--uid-col", default="uid")
+    parser.add_argument(
+        "--include-labels",
+        default="INCLUDE,INCLUDE_MIXED",
+        help="Comma-separated decision labels counted as included.",
+    )
+    parser.add_argument("--out", type=Path, default=Path("qc/pool_consistency.json"))
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args(argv)
+
+    if not args.lock.is_file():
+        print(f"ERROR: lock not found: {args.lock}", file=sys.stderr)
+        return 2
+    if not args.adjudication_tsv.is_file():
+        print(f"ERROR: TSV not found: {args.adjudication_tsv}", file=sys.stderr)
+        return 2
+
+    labels = [s.strip() for s in args.include_labels.split(",") if s.strip()]
+    label_set = set(labels)
+    lock_uids = load_lock_uids(args.lock, labels)
+    tsv_uids = load_tsv_uids(
+        args.adjudication_tsv, args.decision_col, args.uid_col, label_set
+    )
+
+    in_lock_only = sorted(lock_uids - tsv_uids)
+    in_tsv_only = sorted(tsv_uids - lock_uids)
+    match = not in_lock_only and not in_tsv_only
+
+    report = {
+        "submission_safe": match,
+        "match": match,
+        "lock_include_n": len(lock_uids),
+        "tsv_include_n": len(tsv_uids),
+        "in_lock_not_tsv": in_lock_only,
+        "in_tsv_not_lock": in_tsv_only,
+        "include_labels": labels,
+    }
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(json.dumps(report, indent=2), encoding="utf-8")
+
+    if not args.quiet:
+        if match:
+            print(f"PASS: lock and TSV agree ({len(lock_uids)} UIDs).")
+        else:
+            print(
+                f"FAIL: lock includes {len(lock_uids)} UIDs, TSV includes "
+                f"{len(tsv_uids)} UIDs."
+            )
+            if in_lock_only:
+                print(f"  In lock but not TSV ({len(in_lock_only)}):")
+                for u in in_lock_only[:10]:
+                    print(f"    - {u}")
+                if len(in_lock_only) > 10:
+                    print(f"    ... and {len(in_lock_only) - 10} more")
+            if in_tsv_only:
+                print(f"  In TSV but not lock ({len(in_tsv_only)}):")
+                for u in in_tsv_only[:10]:
+                    print(f"    - {u}")
+                if len(in_tsv_only) > 10:
+                    print(f"    ... and {len(in_tsv_only) - 10} more")
+
+    return 0 if match else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/meta-analysis/scripts/cohort_overlap_check.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+"""
+Cohort Overlap Detection — flag included-study pairs sharing same data source.
+
+Motivation: recent SR-MA peer-review cycles found included studies using
+overlapping public ICU/EHR cohorts (MIMIC-IV, eICU, KNHIS, UK Biobank) without
+explicit acknowledgment. Independent-cohort assumption for MA pooling is then
+violated. This script reads a study list with PMID + extracted cohort metadata,
+fetches missing fields from PubMed efetch when needed, and reports clusters by
+(a) shared public database, (b) shared institution + overlapping enrollment
+period, (c) shared author surname + year proximity.
+
+Usage:
+    python3 cohort_overlap_check.py --input studies.csv --out overlap_report.md
+
+Input CSV schema (recommended columns):
+    study_id, pmid, country, institution, database_source, enrollment_period_start,
+    enrollment_period_end, first_author, year, sample_n
+
+`database_source` examples: "MIMIC-IV", "eICU", "KNHIS", "UK Biobank", "institutional",
+"multi-center prospective". Use empty string if unknown — script will attempt PubMed
+fetch to infer.
+
+Outputs a Markdown report listing:
+- HIGH-CONFIDENCE OVERLAP pairs (same database + overlapping period)
+- MEDIUM-CONFIDENCE candidates (same institution OR same author surname + year ±2)
+- UNDETERMINED (insufficient metadata)
+"""
+import argparse
+import csv
+import json
+import sys
+import urllib.parse
+import urllib.request
+import xml.etree.ElementTree as ET
+from collections import defaultdict
+from pathlib import Path
+from typing import Optional
+
+PUBLIC_DBS = [
+    "MIMIC-IV", "MIMIC-III", "eICU", "MIMIC", "MarketScan", "Optum",
+    "NHANES", "KNHANES", "KNHIS", "UK Biobank", "Biobank Japan",
+    "TriNetX", "All of Us", "VA Corporate Data Warehouse", "PCORnet",
+    "SEER", "NSQIP",
+]
+
+
+def fetch_pubmed_affiliation(pmid: str, timeout: int = 10) -> dict:
+    """Fetch first-author affiliation + abstract Methods snippet via efetch."""
+    url = (
+        "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi"
+        f"?db=pubmed&id={pmid}&retmode=xml"
+    )
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:
+            data = resp.read()
+    except Exception as e:
+        return {"pmid": pmid, "error": str(e)}
+
+    root = ET.fromstring(data)
+    art = root.find(".//Article")
+    if art is None:
+        return {"pmid": pmid, "error": "no Article element"}
+
+    title = art.findtext("ArticleTitle", "") or ""
+    aff = root.findtext(".//Author/AffiliationInfo/Affiliation", "") or ""
+    abstract = " ".join(
+        (ab.text or "") for ab in root.findall(".//AbstractText")
+    )
+
+    # Heuristic database detection from abstract
+    db_hit = ""
+    for db in PUBLIC_DBS:
+        if db.lower() in abstract.lower():
+            db_hit = db
+            break
+
+    return {
+        "pmid": pmid,
+        "title": title,
+        "affiliation": aff,
+        "database_hit": db_hit,
+    }
+
+
+def periods_overlap(s1: str, e1: str, s2: str, e2: str) -> Optional[bool]:
+    """Return True/False/None (None = insufficient data). YYYY-MM strings."""
+    if not (s1 and e1 and s2 and e2):
+        return None
+    try:
+        return not (e1 < s2 or e2 < s1)
+    except Exception:
+        return None
+
+
+def cluster_by_db(rows: list[dict]) -> dict[str, list[dict]]:
+    """Group rows by database_source (non-empty)."""
+    clusters = defaultdict(list)
+    for r in rows:
+        db = (r.get("database_source") or "").strip()
+        if db and db.lower() != "institutional":
+            clusters[db].append(r)
+    return {k: v for k, v in clusters.items() if len(v) >= 2}
+
+
+def cluster_by_institution(rows: list[dict]) -> dict[str, list[dict]]:
+    clusters = defaultdict(list)
+    for r in rows:
+        inst = (r.get("institution") or "").strip()
+        if inst:
+            # Normalize: lowercase, strip "Department of X, " prefix
+            key = inst.lower().split(",")[0].strip()
+            clusters[key].append(r)
+    return {k: v for k, v in clusters.items() if len(v) >= 2}
+
+
+def cluster_by_author_year(rows: list[dict]) -> dict[str, list[dict]]:
+    clusters = defaultdict(list)
+    for r in rows:
+        surname = (r.get("first_author") or "").strip().split()[0].lower() if r.get("first_author") else ""
+        if surname:
+            clusters[surname].append(r)
+    return {k: v for k, v in clusters.items() if len(v) >= 2}
+
+
+def write_report(out_path: Path, db_clusters, inst_clusters, author_clusters,
+                 enriched: list[dict]) -> None:
+    lines = ["# Cohort Overlap Report", ""]
+
+    lines.append(f"Total studies analyzed: **{len(enriched)}**")
+    lines.append("")
+
+    lines.append("## HIGH-CONFIDENCE: Same public database")
+    if db_clusters:
+        for db, rows in db_clusters.items():
+            lines.append(f"\n### Database: **{db}** ({len(rows)} studies)")
+            for r in rows:
+                period = (
+                    f"{r.get('enrollment_period_start','?')}"
+                    f"-{r.get('enrollment_period_end','?')}"
+                )
+                lines.append(
+                    f"- {r.get('study_id','?')} (PMID {r.get('pmid','?')}, "
+                    f"N={r.get('sample_n','?')}, period {period})"
+                )
+            # Period overlap check (pairwise)
+            for i in range(len(rows)):
+                for j in range(i + 1, len(rows)):
+                    o = periods_overlap(
+                        rows[i].get("enrollment_period_start", ""),
+                        rows[i].get("enrollment_period_end", ""),
+                        rows[j].get("enrollment_period_start", ""),
+                        rows[j].get("enrollment_period_end", ""),
+                    )
+                    if o is True:
+                        lines.append(
+                            f"  - WARN Period overlap: {rows[i]['study_id']} <-> {rows[j]['study_id']}"
+                        )
+                    elif o is None:
+                        lines.append(
+                            f"  - QUERY Period overlap undetermined: "
+                            f"{rows[i]['study_id']} <-> {rows[j]['study_id']}"
+                        )
+    else:
+        lines.append("None.")
+
+    lines.append("\n## MEDIUM: Same institution (single-center cluster)")
+    if inst_clusters:
+        for inst, rows in inst_clusters.items():
+            lines.append(f"\n### Institution: **{inst}** ({len(rows)} studies)")
+            for r in rows:
+                lines.append(f"- {r.get('study_id','?')} (PMID {r.get('pmid','?')})")
+    else:
+        lines.append("None.")
+
+    lines.append("\n## LOWER: Same author surname +/-2y year")
+    if author_clusters:
+        for surname, rows in author_clusters.items():
+            years = [int(r["year"]) for r in rows if str(r.get("year","")).isdigit()]
+            year_span = max(years) - min(years) if years else None
+            tag = "(within +/-2y)" if year_span is not None and year_span <= 2 else "(>2y span)"
+            lines.append(f"\n### Surname: **{surname}** {tag} - {len(rows)} studies")
+            for r in rows:
+                lines.append(f"- {r.get('study_id','?')} ({r.get('year','?')})")
+    else:
+        lines.append("None.")
+
+    lines.append("\n## Recommendation")
+    lines.append(
+        "- For HIGH-CONFIDENCE overlap pairs: sensitivity analysis excluding one, "
+        "explicit Limitations acknowledgment, cohort-source column in Table 1."
+    )
+    lines.append(
+        "- For MEDIUM: request author institution + ORCID to verify cohort independence."
+    )
+
+    out_path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="Cohort overlap detector for SR-MA")
+    p.add_argument("--input", required=True, type=Path, help="Input CSV")
+    p.add_argument("--out", required=True, type=Path, help="Output Markdown report")
+    p.add_argument("--enrich", action="store_true",
+                   help="Fetch PubMed efetch for missing database/affiliation")
+    args = p.parse_args()
+
+    if not args.input.exists():
+        print(f"ERROR: input not found: {args.input}", file=sys.stderr)
+        return 1
+
+    with args.input.open(newline="", encoding="utf-8") as fin:
+        rows = list(csv.DictReader(fin))
+
+    if args.enrich:
+        for r in rows:
+            if not r.get("database_source") and r.get("pmid"):
+                info = fetch_pubmed_affiliation(r["pmid"])
+                if info.get("database_hit"):
+                    r["database_source"] = info["database_hit"]
+                if not r.get("institution") and info.get("affiliation"):
+                    r["institution"] = info["affiliation"][:80]
+
+    db_clusters = cluster_by_db(rows)
+    inst_clusters = cluster_by_institution(rows)
+    author_clusters = cluster_by_author_year(rows)
+
+    write_report(args.out, db_clusters, inst_clusters, author_clusters, rows)
+
+    n_db = sum(len(v) for v in db_clusters.values())
+    n_inst = sum(len(v) for v in inst_clusters.values())
+    print(
+        f"Cohort overlap: {len(db_clusters)} DB clusters ({n_db} studies), "
+        f"{len(inst_clusters)} institution clusters ({n_inst} studies)"
+    )
+    print(f"Report: {args.out}")
+
+    return 1 if db_clusters else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/meta-analysis/scripts/dta_extraction_qc.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+DTA Extraction QC — cross-check forest plot 2x2 cells against source paper sens/spec.
+
+Motivation: recent SR-MA peer-review cycles found extracted (TP, FN, TN, FP)
+cells with sensitivity/specificity values swapped versus the source paper. In
+single-study k=1 subgroups this can invert reported p-values. This script
+validates extracted cells against source-reported sens/spec with a tolerance and
+FLAGs mismatches for manual review. It does NOT auto-correct.
+
+Usage:
+    python3 dta_extraction_qc.py --input extraction.csv --tolerance 0.02 --out qc_report.tsv
+
+Input CSV schema (required columns):
+    study_id          - e.g., "StudyA_2021_1"
+    source_pmid       - PubMed ID (string)
+    source_sens       - decimal 0-1 (e.g., 0.978)
+    source_spec       - decimal 0-1 (e.g., 0.554)
+    extracted_tp      - int (TP cell)
+    extracted_fn      - int (FN cell)
+    extracted_tn      - int (TN cell)
+    extracted_fp      - int (FP cell)
+    source_cohort     - e.g., "external_test_set" (which cohort the source values come from)
+    source_page_ref   - e.g., "Table 3 page 7" (audit trail)
+
+Output:
+    Tab-separated table with one row per study, columns:
+    study_id | extracted_sens | extracted_spec | source_sens | source_spec
+            | sens_diff | spec_diff | status | swap_suspected | message
+"""
+import argparse
+import csv
+import sys
+from pathlib import Path
+
+
+def compute_sens_spec(tp: int, fn: int, tn: int, fp: int) -> tuple[float, float]:
+    """Return (sensitivity, specificity)."""
+    sens = tp / (tp + fn) if (tp + fn) > 0 else float("nan")
+    spec = tn / (tn + fp) if (tn + fp) > 0 else float("nan")
+    return sens, spec
+
+
+def check_row(row: dict, tol: float) -> dict:
+    """Return augmented row with status/diff fields."""
+    try:
+        tp = int(row["extracted_tp"])
+        fn = int(row["extracted_fn"])
+        tn = int(row["extracted_tn"])
+        fp = int(row["extracted_fp"])
+        source_sens = float(row["source_sens"])
+        source_spec = float(row["source_spec"])
+    except (KeyError, ValueError) as e:
+        return {**row, "status": "PARSE_ERROR", "message": str(e)}
+
+    ext_sens, ext_spec = compute_sens_spec(tp, fn, tn, fp)
+    sens_diff = abs(ext_sens - source_sens)
+    spec_diff = abs(ext_spec - source_spec)
+
+    # Swap detection: extracted_sens ≈ source_spec AND extracted_spec ≈ source_sens
+    swap_sens_match = abs(ext_sens - source_spec) <= tol
+    swap_spec_match = abs(ext_spec - source_sens) <= tol
+    swap_suspected = swap_sens_match and swap_spec_match
+
+    if sens_diff <= tol and spec_diff <= tol:
+        status = "OK"
+        message = "Match within tolerance."
+    elif swap_suspected:
+        status = "FLAG_SWAP"
+        message = (
+            f"Possible sens/spec SWAP. "
+            f"Extracted (sens={ext_sens:.3f}, spec={ext_spec:.3f}) matches "
+            f"source swapped (source_sens={source_sens:.3f}, source_spec={source_spec:.3f})."
+        )
+    else:
+        status = "FLAG_MISMATCH"
+        message = (
+            f"Discrepancy beyond tolerance ({tol:.3f}). "
+            f"Check source_page_ref={row.get('source_page_ref','?')}."
+        )
+
+    return {
+        **row,
+        "extracted_sens": f"{ext_sens:.4f}",
+        "extracted_spec": f"{ext_spec:.4f}",
+        "sens_diff": f"{sens_diff:.4f}",
+        "spec_diff": f"{spec_diff:.4f}",
+        "swap_suspected": "YES" if swap_suspected else "NO",
+        "status": status,
+        "message": message,
+    }
+
+
+def main() -> int:
+    p = argparse.ArgumentParser(description="DTA extraction sens/spec QC")
+    p.add_argument("--input", required=True, type=Path, help="Input CSV file")
+    p.add_argument("--tolerance", type=float, default=0.02,
+                   help="Absolute tolerance for sens/spec match (default 0.02 = 2 percentage points)")
+    p.add_argument("--out", required=True, type=Path, help="Output TSV report")
+    args = p.parse_args()
+
+    if not args.input.exists():
+        print(f"ERROR: input file not found: {args.input}", file=sys.stderr)
+        return 1
+
+    with args.input.open(newline="", encoding="utf-8") as fin:
+        reader = csv.DictReader(fin)
+        rows = [check_row(r, args.tolerance) for r in reader]
+
+    fieldnames = [
+        "study_id", "source_pmid", "source_cohort", "source_page_ref",
+        "extracted_tp", "extracted_fn", "extracted_tn", "extracted_fp",
+        "extracted_sens", "extracted_spec", "source_sens", "source_spec",
+        "sens_diff", "spec_diff", "swap_suspected", "status", "message",
+    ]
+    with args.out.open("w", newline="", encoding="utf-8") as fout:
+        writer = csv.DictWriter(fout, fieldnames=fieldnames, delimiter="\t",
+                                extrasaction="ignore")
+        writer.writeheader()
+        for r in rows:
+            writer.writerow(r)
+
+    # Summary stats
+    n = len(rows)
+    n_ok = sum(1 for r in rows if r.get("status") == "OK")
+    n_swap = sum(1 for r in rows if r.get("status") == "FLAG_SWAP")
+    n_mismatch = sum(1 for r in rows if r.get("status") == "FLAG_MISMATCH")
+    n_err = sum(1 for r in rows if r.get("status") == "PARSE_ERROR")
+
+    print(f"DTA QC: {n} studies | OK={n_ok} | SWAP={n_swap} | MISMATCH={n_mismatch} | PARSE_ERROR={n_err}")
+    print(f"Report: {args.out}")
+
+    return 1 if (n_swap + n_mismatch + n_err) > 0 else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())