medsci-skills 4.1.0

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

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""Reconcile meta-analysis screening ID sets into a canonical JSON artifact."""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import re
+import sys
+from pathlib import Path
+
+
+INCLUDE_VALUES = {"include", "included", "yes", "y", "1", "true", "eligible", "include-qualitative"}
+EXCLUDE_VALUES = {"exclude", "excluded", "no", "n", "0", "false", "ineligible"}
+
+
+def read_table(path: Path) -> list[dict[str, str]]:
+    if not path.exists():
+        raise FileNotFoundError(path)
+    delimiter = "\t" if path.suffix.lower() in {".tsv", ".tab"} else ","
+    with path.open(encoding="utf-8-sig", newline="") as fh:
+        return [{k.strip(): (v or "").strip() for k, v in row.items()} for row in csv.DictReader(fh, delimiter=delimiter)]
+
+
+def find_col(rows: list[dict[str, str]], candidates: list[str]) -> str | None:
+    if not rows:
+        return None
+    lower = {k.lower(): k for k in rows[0].keys()}
+    for cand in candidates:
+        if cand.lower() in lower:
+            return lower[cand.lower()]
+    for key in rows[0].keys():
+        lk = key.lower()
+        if any(cand.lower() in lk for cand in candidates):
+            return key
+    return None
+
+
+def norm_id(value: str) -> str:
+    value = value.strip()
+    if not value:
+        return ""
+    match = re.search(r"\d+", value)
+    return match.group(0) if match else value
+
+
+def decision_kind(value: str) -> str:
+    v = value.strip().lower()
+    if any(token in v for token in INCLUDE_VALUES):
+        return "include"
+    if any(token in v for token in EXCLUDE_VALUES):
+        return "exclude"
+    return "unknown"
+
+
+def ids_from_table(path: Path, id_col_arg: str | None, decision_col_arg: str | None, include_only: bool) -> tuple[set[str], dict[str, str]]:
+    rows = read_table(path)
+    id_col = id_col_arg or find_col(rows, ["id", "record_id", "study_id", "ref_id"])
+    if not id_col:
+        raise ValueError(f"Could not identify ID column in {path}")
+    decision_col = decision_col_arg or find_col(rows, ["decision", "verdict", "include", "screening", "consensus", "outcome"])
+    ids: set[str] = set()
+    decisions: dict[str, str] = {}
+    for row in rows:
+        rid = norm_id(row.get(id_col, ""))
+        if not rid:
+            continue
+        decision = row.get(decision_col, "") if decision_col else ""
+        kind = decision_kind(decision)
+        decisions[rid] = decision
+        if include_only:
+            if kind == "include":
+                ids.add(rid)
+        else:
+            ids.add(rid)
+    return ids, decisions
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Reconcile MA screening ID sets.")
+    parser.add_argument("--screening", required=True, help="TSV/CSV with screening decisions")
+    parser.add_argument("--consensus", help="TSV/CSV with final consensus decisions")
+    parser.add_argument("--table1", help="TSV/CSV containing bivariate/Table 1 study IDs")
+    parser.add_argument("--output", default="2_Screening/screening_consensus.json")
+    parser.add_argument("--screening-id-col")
+    parser.add_argument("--screening-decision-col")
+    parser.add_argument("--consensus-id-col")
+    parser.add_argument("--consensus-decision-col")
+    parser.add_argument("--table1-id-col")
+    args = parser.parse_args()
+
+    screening_path = Path(args.screening)
+    screening_include, screening_decisions = ids_from_table(
+        screening_path, args.screening_id_col, args.screening_decision_col, include_only=True
+    )
+
+    if args.consensus:
+        consensus_ids, consensus_decisions = ids_from_table(
+            Path(args.consensus), args.consensus_id_col, args.consensus_decision_col, include_only=False
+        )
+        consensus_exclude = {rid for rid, dec in consensus_decisions.items() if decision_kind(dec) == "exclude"}
+        consensus_include = {rid for rid, dec in consensus_decisions.items() if decision_kind(dec) == "include"}
+    else:
+        consensus_ids = set()
+        consensus_exclude = set()
+        consensus_include = set()
+
+    if args.table1:
+        table1_ids, _ = ids_from_table(Path(args.table1), args.table1_id_col, None, include_only=False)
+    else:
+        table1_ids = set()
+
+    qualitative = (screening_include - consensus_exclude) | consensus_include
+    bivariate = table1_ids
+    narrative_only = qualitative - bivariate
+
+    payload = {
+        "schema_version": 1,
+        "sources": {
+            "screening": str(screening_path),
+            "consensus": args.consensus,
+            "table1": args.table1,
+        },
+        "sets": {
+            "screening_include": sorted(screening_include, key=lambda x: (len(x), x)),
+            "consensus_exclude": sorted(consensus_exclude, key=lambda x: (len(x), x)),
+            "consensus_include": sorted(consensus_include, key=lambda x: (len(x), x)),
+            "qualitative": sorted(qualitative, key=lambda x: (len(x), x)),
+            "bivariate": sorted(bivariate, key=lambda x: (len(x), x)),
+            "narrative_only": sorted(narrative_only, key=lambda x: (len(x), x)),
+        },
+        "totals": {
+            "k_screening_include": len(screening_include),
+            "k_consensus_exclude": len(consensus_exclude),
+            "k_consensus_include": len(consensus_include),
+            "k_qualitative": len(qualitative),
+            "k_bivariate": len(bivariate),
+            "k_narrative_only": len(narrative_only),
+        },
+        "blocking_issues": [],
+    }
+
+    if bivariate and not bivariate <= qualitative:
+        payload["blocking_issues"].append(
+            {
+                "code": "TABLE1_NOT_IN_QUALITATIVE",
+                "ids": sorted(bivariate - qualitative, key=lambda x: (len(x), x)),
+            }
+        )
+
+    output = Path(args.output)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+    print(json.dumps(payload["totals"], indent=2))
+    return 1 if payload["blocking_issues"] else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/meta-analysis/skill.yml

@@ -0,0 +1,47 @@
+schema_version: 2
+name: meta-analysis
+layer: B
+owner_domain: meta_analysis_integrity
+when_to_use:
+  - Running an end-to-end systematic review or meta-analysis (PROSPERO → search → screen → extract → synthesis → PRISMA)
+  - Diagnostic test accuracy meta-analysis (bivariate / HSROC) or intervention meta-analysis (random-effects)
+  - Screening reconciliation across two reviewers with Cohen's kappa and adjudication round
+  - Risk of bias batch (QUADAS-2 / ROBINS-I) tied to extraction CSV ID receipts
+  - Phase 6b post-analysis source-fidelity audit when CSV ↔ R output ↔ manuscript drift suspected
+when_NOT_to_use:
+  - Single-study analysis (use /analyze-stats)
+  - Topic discovery before a protocol exists (use /ma-scout)
+  - Reporting checklist generation only (use /check-reporting)
+  - Manuscript prose drafting after synthesis (use /write-paper)
+inputs:
+  - protocol/search_strategies.md
+  - screening/*.tsv
+  - extraction/*.csv
+outputs:
+  - 2_Screening/screening_consensus.json
+  - analysis/meta_analysis_outputs.json
+  - manuscript/manuscript.md
+deterministic_scripts:
+  - scripts/screening_reconcile.py
+side_effects:
+  - writes_project_artifacts
+downstream_consumers:
+  - write-paper
+  - self-review
+  - make-figures
+forbidden_actions:
+  - report_counts_without_id_receipts
+  - continue_after_p0_reconciliation_mismatch
+
+# v2.1 quality card
+purpose: "Run the SR/MA pipeline: PROSPERO registration, search, screening, extraction, risk of bias, synthesis (bivariate/HSROC or random-effects), and PRISMA reporting."
+safety_boundaries:
+  - "Study counts are never reported without ID-level receipts; halts on a P0 reconciliation mismatch."
+  - "Pool composition is locked to a single source of truth; downstream counts are re-derived, not copied."
+known_limitations:
+  - "Synthesis validity depends on correct extraction; the skill enforces process, not clinical correctness."
+  - "DTA pooling assumes adequate per-study 2x2 / threshold data."
+validation_commands:
+  - "python3 scripts/screening_reconcile.py"
+  - "python3 scripts/check_pool_consistency.py"
+evidence_surface: demo

package/skills/meta-analysis/templates/FINAL_POOL_LOCK.yaml.template

@@ -0,0 +1,70 @@
+# FINAL_POOL_LOCK.yaml — frozen pool composition for an SR/MA
+#
+# Created at Phase 3f.5 (round-3 adjudication freeze) by /meta-analysis.
+# All downstream artifacts (extraction TSV, manuscript prose counts,
+# PRISMA flow caption, supplementary INDEX, cover letter free-text)
+# must agree with these values exactly. /sync-submission Phase 5
+# `scripts/cross_document_n_check.py --pool-lock` enforces this.
+#
+# Why a lock file
+# ---------------
+# Cross-project precedent (anonymized): an LLM reporting-quality SR carried
+# five documents that disagreed on INCLUDE (63 vs 64) and EXCLUDE
+# (108/109/111). Three EXCLUDE rows existed in the extraction sheet
+# without matching INCLUDE. The drift traced to a late round-3 adjudication
+# whose result was applied to some artifacts and not others.
+#
+# The lock file is the single source of truth. Once the freeze line is
+# crossed, NEVER re-derive the counts from raw artifacts in a downstream
+# script — always reference the lock.
+
+# ---------------------------------------------------------------------------
+# Metadata
+# ---------------------------------------------------------------------------
+
+# ISO-8601 date when the pool was frozen.
+freeze_date: "YYYY-MM-DD"
+
+# Round at which freeze occurred — typically "round_3_adjudication".
+freeze_stage: "round_3_adjudication"
+
+# Freeform note describing which screening sheet anchored this lock.
+provenance:
+  screening_artifact: "2_Screening/round3_adjudication.tsv"
+  adjudicator: "first_reviewer"
+  ai_assisted_round: false   # set true if AI pre-screening was used per SKILL.md Phase 3c
+
+# ---------------------------------------------------------------------------
+# Counts (canonical numbers — NEVER edit without re-freezing)
+# ---------------------------------------------------------------------------
+
+# Studies in the final pool (Phase 4 extraction candidate set).
+final_pool_n: 0
+
+# Total INCLUDE decisions across rounds (post-adjudication).
+include_count: 0
+
+# Total EXCLUDE decisions (full-text excluded).
+exclude_count: 0
+
+# Mixed (eligible for some outcomes, excluded for others).
+mixed_count: 0
+
+# ---------------------------------------------------------------------------
+# Identifier sets
+# ---------------------------------------------------------------------------
+
+# UID lists. Use stable IDs (PMID, DOI, or screening-sheet record ID).
+include_uids: []
+exclude_uids: []
+mixed_uids: []
+
+# ---------------------------------------------------------------------------
+# Integrity hash
+# ---------------------------------------------------------------------------
+
+# SHA-256 of the sorted include_uids + exclude_uids + mixed_uids list,
+# joined with newlines. Provides tamper-evidence: any single UID edit
+# changes the hash. Recompute with:
+#   python -c 'import hashlib; ids = sorted(open("..._uids.txt").read().splitlines()); print(hashlib.sha256("\n".join(ids).encode()).hexdigest())'
+sha256: ""

package/skills/meta-analysis/templates/extraction_form_v2.md

@@ -0,0 +1,129 @@
+# SR-MA Data Extraction Form v2
+
+**Version**: v2.0
+**Motivation**: Recent SR-MA peer-review cycles surfaced three recurring extraction-stage failure modes — diagnostic 2×2 cell sens/spec swap, undisclosed cohort overlap via shared public databases, and undocumented diagnostic vs prognostic subset N. v2 adds three column families to prevent recurrence.
+
+## Coverage
+
+Use this form for any SR-MA with diagnostic accuracy and/or prognostic prediction outcomes. Compatible with QUADAS-AI / PROBAST-AI / METRICS frameworks.
+
+## Column schema (CSV / Google Sheets)
+
+### Identity (always required)
+
+| Column | Description | Example |
+|---|---|---|
+| `study_id` | Internal ID (`<Surname>_<Year>_<seq>`) | `StudyA_2021_1` |
+| `pmid` | PubMed ID | `00000000` |
+| `doi` | DOI | `10.xxxx/example.YYYY.NNNNNN` |
+| `first_author_lastname` | LastName from PubMed | `Surname` |
+| `first_author_forename` | ForeName from PubMed | `Forename` |
+| `year` | Publication year | `2021` |
+| `country` | Per affiliation (use country of cohort, not publisher) | `[Country]` |
+| `journal` | Full journal name | `[Journal Full Title]` |
+| `study_design` | retrospective / prospective / case-control / cross-sectional | `retrospective` |
+
+### Cohort source (NEW in v2 — prevents undisclosed overlap)
+
+| Column | Description | Example |
+|---|---|---|
+| `cohort_source` | One of: `institutional` / `multi-center prospective` / `MIMIC-IV` / `eICU` / `MIMIC-III` / `KNHIS` / `UK Biobank` / `TriNetX` / `Optum` / `MarketScan` / `SEER` / etc. | `MIMIC-IV` |
+| `institution_primary` | Verbatim institution name from corresponding-author affiliation | `Tertiary Academic Medical Center, [City]` |
+| `institutions_additional` | Pipe-separated additional centers | `Other Affiliated Hospital` |
+| `enrollment_period_start` | YYYY-MM | `2017-01` |
+| `enrollment_period_end` | YYYY-MM | `2019-12` |
+| `data_sharing_statement` | Yes / No / NotReported | `NotReported` |
+| `overlap_flag_reviewer1` | Reviewer 1 suspects cohort overlap with which study_id (or empty) | `StudyB_YYYY` |
+| `overlap_flag_reviewer2` | Reviewer 2's overlap flag | `StudyB_YYYY` |
+
+### Sample sizes (diagnostic subset N transparency)
+
+| Column | Description | Example |
+|---|---|---|
+| `sample_n_total` | Total study N | `452` |
+| `sample_n_train` | Training set N | `273` |
+| `sample_n_internal_test` | Internal test N | `68` |
+| `sample_n_external_test` | External test N | `111` |
+| `sample_n_dta_pool` | N contributing to DTA bivariate (sens/spec extraction) | `111` |
+| `sample_n_prognostic_pool` | N contributing to prognostic AUC pool | `0` |
+| `prevalence_in_dta_pool` | (TP+FN) / sample_n_dta_pool | `0.414` |
+
+### DTA outcome extraction (2×2 cell integrity)
+
+For each cohort that contributes to bivariate pool, extract:
+
+| Column | Description | Example |
+|---|---|---|
+| `dta_cohort_label` | Which cohort the values come from (must match `sample_n_external_test` or similar) | `external_test` |
+| `tp` | True positive count | `45` |
+| `fn` | False negative count | `1` |
+| `tn` | True negative count | `36` |
+| `fp` | False positive count | `29` |
+| `extracted_sens` | TP / (TP+FN), decimal | `0.978` |
+| `extracted_spec` | TN / (TN+FP), decimal | `0.554` |
+| **`source_sens_reported`** | Sensitivity as reported in source paper (decimal) | `0.978` |
+| **`source_spec_reported`** | Specificity as reported in source paper (decimal) | `0.554` |
+| **`source_page_ref`** | Page + Table/Figure number in source paper | `Table 3, p.7` |
+| **`source_verbatim_quote`** | Verbatim sentence containing the sens/spec values | `"The deep-integrated model achieved a sensitivity of 0.978..."` |
+| `extractor1_initials` | First extractor | `R1` |
+| `extractor2_initials` | Second extractor | `R2` |
+| `extraction_consensus_status` | Resolved / DiscussNeeded / Conflict | `Resolved` |
+
+**QC**: Run `scripts/dta_extraction_qc.py` with `--tolerance 0.02` after dual-extractor entry. Any FLAG_SWAP or FLAG_MISMATCH requires third-reviewer adjudication.
+
+### Prognostic outcome extraction (PROBAST-AI compatible)
+
+| Column | Description | Example |
+|---|---|---|
+| `prognostic_outcome_type` | mortality / AKI / disease_progression / readmission / etc. | `mortality` |
+| `prognostic_endpoint_definition` | Verbatim definition | `In-hospital all-cause death within index admission` |
+| `auc_point` | Reported AUC, decimal | `0.87` |
+| `auc_ci_lower` | 95% CI lower | `0.83` |
+| `auc_ci_upper` | 95% CI upper | `0.90` |
+| `validation_type` | internal / external / leave-one-out / k-fold | `external` |
+| `calibration_reported` | Yes / No | `No` |
+| `dca_reported` | Decision curve analysis Yes/No | `No` |
+
+### Risk of bias (per-study × per-domain)
+
+QUADAS-AI (for DTA studies):
+
+| Column | Description |
+|---|---|
+| `quadasai_d1_patient_selection` | Low / High / Unclear |
+| `quadasai_d2_index_test` | Low / High / Unclear |
+| `quadasai_d3_reference_standard` | Low / High / Unclear |
+| `quadasai_d4_flow_timing` | Low / High / Unclear |
+| `quadasai_d1_justification` | Verbatim short reason |
+| `quadasai_d2_justification` | ... |
+| ... | (same for D3, D4) |
+| `quadasai_overall` | Low / High / Unclear (consensus) |
+
+PROBAST-AI (for prognostic studies): D1 Participants / D2 Predictors / D3 Outcome / D4 Analysis — same Low/High/Unclear + justification.
+
+METRICS: 4 domains (data, model dev, validation, reporting) per study.
+
+### Authors of extraction record
+
+| Column | Description |
+|---|---|
+| `extraction_date_initial` | YYYY-MM-DD |
+| `extraction_date_consensus` | YYYY-MM-DD |
+| `cohens_kappa_d1` | Pre-adjudication inter-rater κ for domain D1 |
+| ... | (record κ for each pre-adjudication discrepancy domain) |
+
+## Workflow (dual-extractor consensus)
+
+1. Extractor 1 + Extractor 2 independently fill all cells, source_page_ref, source_verbatim_quote
+2. Run `dta_extraction_qc.py --tolerance 0.02` → flag mismatches
+3. Pre-adjudication κ recorded for D1-D4
+4. Discrepancies → third-reviewer adjudication, consensus_status updated
+5. Run `cohort_overlap_check.py --enrich` → populate database_source via PubMed if missing
+6. Manual review of HIGH/MEDIUM clusters → confirm or override
+7. Lock extraction (read-only) before statistical analysis
+
+## Related
+
+- `scripts/dta_extraction_qc.py`
+- `scripts/cohort_overlap_check.py`
+- `templates/supplementary_8file_checklist.md`

package/skills/meta-analysis/templates/supplementary_8file_checklist.md

@@ -0,0 +1,94 @@
+# SR-MA Supplementary Package — 8-File Standard
+
+**Motivation**: Recent SR-MA peer reviews surfaced supplementary packages that contained only figure captions (≈90 lines), missing PRISMA checklist, exclusion list, extraction table, per-study RoB — despite Methods citing "Supplementary Table S1". Below is the minimum package to avoid this pattern.
+
+**Apply to**: every SR-MA submission. Radiology / Radiology-AI / European Radiology / JCSM / Lancet family / JAMA family / BMJ family all expect this level of supplementary.
+
+## 8 mandatory files
+
+### S1 — PRISMA / PRISMA-DTA / PRISMA-S checklist
+
+- 27-item PRISMA 2020 (general) or PRISMA-DTA (diagnostic accuracy SR-MA)
+- Each item filled with main-manuscript page reference (`p.3, lines 45-48`)
+- Use checklist template from your institutional checklist store
+- For pure search reporting: PRISMA-S 16-item additional
+
+### S2 — PROSPERO protocol PDF (snapshot + amendments)
+
+- Download from prospero.york.ac.uk at registration AND at submission
+- Include all amendments with date + rationale
+- **If subgroup analyses changed post-registration**: explicit amendment record with date
+
+### S3 — Full search strategy verbatim (per database)
+
+- Each database (PubMed / Embase / Cochrane / Scopus / Web of Science) with:
+  - Search date (YYYY-MM-DD)
+  - Final string verbatim (copy-paste from interface)
+  - Filter use (date, language, study type)
+  - Number of records retrieved per database
+
+### S4 — Full-text exclusion list with reasons (PRISMA item 16b)
+
+- Every full-text article excluded with:
+  - First author, year, title
+  - PMID / DOI
+  - Exclusion reason (one of pre-specified categories)
+- Use Rayyan export or equivalent
+
+### S5 — Per-study data extraction table
+
+- One row per included study × all extracted variables (use `extraction_form_v2.md` schema)
+- Include `source_page_ref` + `source_verbatim_quote` for outcome cells (DTA 2×2 or AUC)
+- Locked read-only file (CSV + PDF snapshot)
+
+### S6 — Per-study × per-domain risk-of-bias table
+
+- For DTA: QUADAS-AI (4 domains × N_diagnostic studies) + applicability concerns
+- For prognostic: PROBAST-AI (4 domains × N_prognostic studies)
+- Per-cell: Low / High / Unclear + 1-line justification
+- Optionally: METRICS framework parallel column
+- Include pre-adjudication Cohen's κ per domain
+
+### S7 — Subgroup forest plots (all pre-specified + clearly labeled exploratory)
+
+- Each forest plot with:
+  - Subgroup label
+  - "Pre-specified in PROSPERO" or "Exploratory (post-hoc)" tag
+  - Heterogeneity (I², τ²) per stratum
+  - **k=1 strata excluded from formal test OR flagged as descriptive only**
+
+### S8 — Sensitivity analyses + publication bias
+
+- Leave-one-out for primary outcome (forest plot or table)
+- Cohort overlap sensitivity analysis (exclude one of HIGH-confidence overlap pair)
+- Deeks' funnel asymmetry test for DTA studies (mada::funnel)
+- Funnel plot + Egger / Begg for prognostic AUC pooling
+- Trim-and-fill if asymmetry detected
+
+## Submission gate check
+
+Before submitting, verify:
+
+```bash
+ls -la submission/supplementary/
+# Expected: at minimum 8 files (S1-S8)
+
+# Each file size > 5 KB (figure caption only is ~3 KB)
+for f in submission/supplementary/S*.{md,pdf,csv,docx}; do
+  size=$(stat -f%z "$f" 2>/dev/null || stat -c%s "$f" 2>/dev/null)
+  echo "$f: $size bytes"
+done
+```
+
+If any S-file is missing or only contains figure captions → **NOT READY for submission**.
+
+## Cross-link to AI Disclosure (`/sync-submission` gate)
+
+The supplementary checklist should be combined with the AI Disclosure presence check. Most major imaging journals require an affirmative or negative disclosure statement either in manuscript text or in S-file metadata.
+
+## Related
+
+- `templates/extraction_form_v2.md`
+- `scripts/dta_extraction_qc.py`
+- `scripts/cohort_overlap_check.py`
+- `/peer-review` Phase 2A P5 (supplementary completeness probe)

package/skills/meta-analysis/tests/test_pool_consistency.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+# Regression tests for meta-analysis check_pool_consistency.py.
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+SCRIPT="$REPO_ROOT/skills/meta-analysis/scripts/check_pool_consistency.py"
+TMP="$(mktemp -d -t pool_consist.XXXXXX)"
+trap 'rm -rf "$TMP"' EXIT
+
+[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }
+python3 -c "import yaml" 2>/dev/null || { echo "SKIP: pyyaml unavailable"; exit 0; }
+
+fail=0
+ran=0
+assert_exit() {
+    local label="$1" expected="$2" actual="$3"
+    ran=$((ran + 1))
+    if [[ "$expected" == "$actual" ]]; then
+        printf '  PASS  %-50s exit=%s\n' "$label" "$actual"
+    else
+        printf '  FAIL  %-50s expected=%s actual=%s\n' "$label" "$expected" "$actual"
+        fail=$((fail + 1))
+    fi
+}
+
+# --------------------------------------------------------------------------
+# Case 1: lock and TSV agree on 3 UIDs => PASS
+# --------------------------------------------------------------------------
+mkdir -p "$TMP/c1"
+cat > "$TMP/c1/lock.yaml" <<'EOF'
+freeze_date: "2026-01-01"
+final_pool_n: 3
+include_count: 3
+exclude_count: 0
+mixed_count: 0
+include_uids: [UID_001, UID_002, UID_003]
+exclude_uids: []
+mixed_uids: []
+EOF
+cat > "$TMP/c1/r3.tsv" <<'EOF'
+uid	round3_decision	notes
+UID_001	INCLUDE	ok
+UID_002	INCLUDE	ok
+UID_003	INCLUDE	ok
+UID_004	EXCLUDE	out of scope
+EOF
+python3 "$SCRIPT" --lock "$TMP/c1/lock.yaml" \
+    --adjudication-tsv "$TMP/c1/r3.tsv" \
+    --out "$TMP/c1/report.json" --quiet
+assert_exit "case 1: lock and TSV agree" 0 $?
+
+# --------------------------------------------------------------------------
+# Case 2: TSV has extra UID => FAIL
+# --------------------------------------------------------------------------
+mkdir -p "$TMP/c2"
+cat > "$TMP/c2/lock.yaml" <<'EOF'
+include_uids: [UID_001, UID_002]
+exclude_uids: []
+mixed_uids: []
+EOF
+cat > "$TMP/c2/r3.tsv" <<'EOF'
+uid	round3_decision
+UID_001	INCLUDE
+UID_002	INCLUDE
+UID_009	INCLUDE
+EOF
+python3 "$SCRIPT" --lock "$TMP/c2/lock.yaml" \
+    --adjudication-tsv "$TMP/c2/r3.tsv" \
+    --out "$TMP/c2/report.json" --quiet
+assert_exit "case 2: TSV extra UID (FAIL)" 1 $?
+python3 - "$TMP/c2/report.json" <<'PY' || fail=$((fail + 1))
+import json, sys
+with open(sys.argv[1]) as fh: r = json.load(fh)
+assert "UID_009" in r["in_tsv_not_lock"], r
+assert not r["in_lock_not_tsv"], r
+PY
+
+# --------------------------------------------------------------------------
+# Case 3: lock has extra UID => FAIL
+# --------------------------------------------------------------------------
+mkdir -p "$TMP/c3"
+cat > "$TMP/c3/lock.yaml" <<'EOF'
+include_uids: [UID_001, UID_002, UID_999]
+mixed_uids: []
+exclude_uids: []
+EOF
+cat > "$TMP/c3/r3.tsv" <<'EOF'
+uid	round3_decision
+UID_001	INCLUDE
+UID_002	INCLUDE
+EOF
+python3 "$SCRIPT" --lock "$TMP/c3/lock.yaml" \
+    --adjudication-tsv "$TMP/c3/r3.tsv" \
+    --out "$TMP/c3/report.json" --quiet
+assert_exit "case 3: lock extra UID (FAIL)" 1 $?
+python3 - "$TMP/c3/report.json" <<'PY' || fail=$((fail + 1))
+import json, sys
+with open(sys.argv[1]) as fh: r = json.load(fh)
+assert "UID_999" in r["in_lock_not_tsv"], r
+PY
+
+# --------------------------------------------------------------------------
+# Case 4: missing decision column => exit 2
+# --------------------------------------------------------------------------
+mkdir -p "$TMP/c4"
+cat > "$TMP/c4/lock.yaml" <<'EOF'
+include_uids: [UID_001]
+mixed_uids: []
+exclude_uids: []
+EOF
+cat > "$TMP/c4/r3.tsv" <<'EOF'
+uid	notes
+UID_001	whatever
+EOF
+python3 "$SCRIPT" --lock "$TMP/c4/lock.yaml" \
+    --adjudication-tsv "$TMP/c4/r3.tsv" \
+    --out "$TMP/c4/report.json" --quiet 2>/dev/null
+assert_exit "case 4: missing decision col (exit 2)" 2 $?
+
+echo ""
+echo "ran=$ran fail=$fail"
+[[ $fail -eq 0 ]]