medsci-skills 4.1.0

package/skills/check-reporting/scripts/check_prisma_figure.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""PRISMA Figure 1 Arithmetic & Cross-Reference Audit.
+
+Loaded by `/check-reporting prisma` Step 4d.
+
+Inputs:
+  --md         manuscript markdown (body text PRISMA numbers).
+  --figure     Figure 1 source: markdown manifest, caption .md, or text export.
+  --out        output JSON (default: qc/prisma_figure_audit.json).
+
+Outputs:
+  qc/prisma_figure_audit.json + console table.
+
+Exit codes:
+  0  audit_safe (all PRESENT)
+  1  arithmetic or cross-reference MISMATCH / MISSING
+  2  invalid input (file missing, parse failure)
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+KEYWORDS = {
+    "identified": r"(\d[\d,]*)\s+(?:records?|reports?)\s+identified",
+    "duplicates": r"(\d[\d,]*)\s+(?:records?|reports?|duplicates?)\s+(?:duplicates?\s+)?removed",
+    "screened": r"(\d[\d,]*)\s+(?:records?|reports?)\s+screened",
+    # Explicit suffix required to avoid collision with excluded_eligibility.
+    "excluded_screening": r"(\d[\d,]*)\s+(?:records?|reports?)\s+excluded\s+(?:at|after|during)\s+screening",
+    "sought": r"(\d[\d,]*)\s+(?:reports?|records?)\s+sought(?:\s+for\s+retrieval)?",
+    "not_retrieved": r"(\d[\d,]*)\s+(?:reports?|records?)\s+(?:not\s+retrieved|unobtainable)",
+    # Match both "reports retrieved" and "retrieved 186 reports".
+    "retrieved": r"(?:(\d[\d,]*)\s+(?:records?|reports?)\s+retrieved|retrieved\s+(\d[\d,]*)\s+(?:records?|reports?))",
+    "assessed": r"(\d[\d,]*)\s+(?:reports?|records?)\s+assessed(?:\s+for\s+eligibility)?",
+    # Explicit suffix required to avoid collision with excluded_screening.
+    "excluded_eligibility": r"(\d[\d,]*)\s+(?:records?|reports?)\s+excluded\s+with\s+reasons?",
+    "included": r"(\d[\d,]*)\s+(?:studies|records?|reports?)\s+included",
+}
+
+
+def extract_numbers(text: str) -> dict[str, int]:
+    """Return {key: int} for keywords that match. First match wins per key."""
+    out: dict[str, int] = {}
+    for key, pattern in KEYWORDS.items():
+        m = re.search(pattern, text, flags=re.IGNORECASE)
+        if m:
+            num = next((g for g in m.groups() if g), None)
+            if num is None:
+                continue
+            try:
+                out[key] = int(num.replace(",", ""))
+            except ValueError:
+                continue
+    return out
+
+
+def check_arithmetic(n: dict[str, int]) -> list[dict]:
+    eqs = [
+        ("screened = identified - duplicates", "screened", "identified", "duplicates"),
+        ("sought = screened - excluded_screening", "sought", "screened", "excluded_screening"),
+        ("retrieved = sought - not_retrieved", "retrieved", "sought", "not_retrieved"),
+        ("included = assessed - excluded_eligibility", "included", "assessed", "excluded_eligibility"),
+    ]
+    out = []
+    for label, lhs_key, a_key, b_key in eqs:
+        if all(k in n for k in (lhs_key, a_key, b_key)):
+            lhs = n[lhs_key]
+            rhs = n[a_key] - n[b_key]
+            out.append({
+                "eq": label,
+                "lhs": lhs,
+                "rhs": rhs,
+                "status": "PRESENT" if lhs == rhs else "MISMATCH",
+            })
+        else:
+            missing = [k for k in (lhs_key, a_key, b_key) if k not in n]
+            out.append({
+                "eq": label,
+                "lhs": None,
+                "rhs": None,
+                "status": "MISSING",
+                "missing_keys": missing,
+            })
+    return out
+
+
+def cross_reference(body: dict[str, int], figure: dict[str, int]) -> list[dict]:
+    out = []
+    keys = set(body) | set(figure)
+    for key in sorted(keys):
+        b = body.get(key)
+        f = figure.get(key)
+        if b is None and f is None:
+            continue
+        if b is None:
+            status = "MISSING"
+            note = "body lacks number"
+        elif f is None:
+            status = "MISSING"
+            note = "figure lacks number"
+        elif b == f:
+            status = "PRESENT"
+            note = ""
+        else:
+            status = "MISMATCH"
+            note = f"body={b}, figure={f}"
+        out.append({"key": key, "body": b, "figure": f, "status": status, "note": note})
+    return out
+
+
+def render_table(rows: list[dict], cols: list[str]) -> str:
+    if not rows:
+        return "  (none)"
+    widths = {c: max(len(c), max(len(str(r.get(c, ""))) for r in rows)) for c in cols}
+    head = "  " + "  ".join(c.ljust(widths[c]) for c in cols)
+    sep = "  " + "  ".join("-" * widths[c] for c in cols)
+    body = "\n".join(
+        "  " + "  ".join(str(r.get(c, "")).ljust(widths[c]) for c in cols) for r in rows
+    )
+    return "\n".join([head, sep, body])
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--md", required=True, help="manuscript markdown path")
+    ap.add_argument("--figure", required=True, help="Figure 1 source path (.md, .txt)")
+    ap.add_argument("--out", default="qc/prisma_figure_audit.json", help="output JSON path")
+    args = ap.parse_args()
+
+    md_path = Path(args.md)
+    fig_path = Path(args.figure)
+    if not md_path.exists():
+        print(f"ERROR: manuscript not found: {md_path}", file=sys.stderr)
+        return 2
+    if not fig_path.exists():
+        print(f"ERROR: figure source not found: {fig_path}", file=sys.stderr)
+        return 2
+
+    body_text = md_path.read_text(encoding="utf-8")
+    fig_text = fig_path.read_text(encoding="utf-8")
+
+    body_numbers = extract_numbers(body_text)
+    figure_numbers = extract_numbers(fig_text)
+
+    arith_body = check_arithmetic(body_numbers)
+    arith_figure = check_arithmetic(figure_numbers)
+    xref = cross_reference(body_numbers, figure_numbers)
+
+    audit_safe = (
+        all(r["status"] == "PRESENT" for r in arith_body)
+        and all(r["status"] == "PRESENT" for r in arith_figure)
+        and all(r["status"] == "PRESENT" for r in xref)
+    )
+
+    action_items: list[str] = []
+    for r in arith_body:
+        if r["status"] == "MISMATCH":
+            action_items.append(
+                f"[PRISMA-FIGURE] body arithmetic '{r['eq']}' fails: {r['lhs']} vs {r['rhs']}"
+            )
+    for r in arith_figure:
+        if r["status"] == "MISMATCH":
+            action_items.append(
+                f"[PRISMA-FIGURE] figure arithmetic '{r['eq']}' fails: {r['lhs']} vs {r['rhs']}"
+            )
+    for r in xref:
+        if r["status"] == "MISMATCH":
+            action_items.append(
+                f"[PRISMA-FIGURE] cross-ref '{r['key']}' MISMATCH: body={r['body']}, figure={r['figure']}"
+            )
+
+    result = {
+        "manuscript": str(md_path),
+        "figure_source": str(fig_path),
+        "body_numbers": body_numbers,
+        "figure_numbers": figure_numbers,
+        "arithmetic_body": arith_body,
+        "arithmetic_figure": arith_figure,
+        "cross_reference": xref,
+        "audit_safe": audit_safe,
+        "action_items": action_items,
+    }
+
+    out_path = Path(args.out)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(json.dumps(result, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    print(f"== PRISMA Figure Audit — {md_path.name} vs {fig_path.name} ==\n")
+    print("Body arithmetic:")
+    print(render_table(arith_body, ["eq", "lhs", "rhs", "status"]))
+    print("\nFigure arithmetic:")
+    print(render_table(arith_figure, ["eq", "lhs", "rhs", "status"]))
+    print("\nCross-reference (body ↔ figure):")
+    print(render_table(xref, ["key", "body", "figure", "status", "note"]))
+    print(f"\naudit_safe: {audit_safe}")
+    print(f"output: {out_path}")
+    if action_items:
+        print("\nAction items:")
+        for a in action_items:
+            print(f"  - {a}")
+
+    return 0 if audit_safe else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/check-reporting/scripts/prisma_cascade_check.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""
+prisma_cascade_check.py — PRISMA flow cascade arithmetic auto-verify.
+
+PRISMA 2020 flow diagrams chain a cascade of subtractions:
+
+    [identified across databases] → [after dedup]
+    → [title/abstract screened]
+    → [full-text reviewed]
+    → [included in qualitative synthesis]
+    → [included in quantitative synthesis]
+
+Each transition has a corresponding "excluded" count. The arithmetic is
+trivial in principle but reviewers and editors find off-by-one errors at
+high frequency: the prose cascade `151 + 108 + 39 + 1 + 1 + 4 = 304` is
+followed by a prose summary "305" four lines later. The desk-reject
+follows immediately because the prose is presented as fact.
+
+This script:
+
+1. Reads round-by-round screening TSV artifacts
+   (`round1.tsv`, `round2.tsv`, `round3_adjudication.tsv`).
+2. Computes the canonical flow chain from raw decisions.
+3. Optionally cross-checks against a manuscript markdown body and emits
+   a per-stage drift report.
+
+Usage
+=====
+
+    python prisma_cascade_check.py \\
+        --round1 2_Screening/round1.tsv \\
+        --round2 2_Screening/round2.tsv \\
+        --round3 2_Screening/round3_adjudication.tsv \\
+        --out qc/prisma_cascade.json
+
+    python prisma_cascade_check.py \\
+        --round1 ... --round2 ... --round3 ... \\
+        --manuscript manuscript.md \\
+        --out qc/prisma_cascade.json
+
+Decision column defaults:
+    round 1 / round 2: `decision` ∈ {INCLUDE, EXCLUDE, MAYBE}
+    round 3: `round3_decision` ∈ {INCLUDE, EXCLUDE}
+
+Output JSON:
+
+    {
+      "submission_safe": false,
+      "stage_counts": {
+        "round1_total": 458,
+        "round1_include": 220,
+        "round2_include": 87,
+        "round3_include": 42,
+        "round3_exclude": 45
+      },
+      "cascade_arithmetic": {
+        "round1_to_round2": {"excluded": 238, "checked": true},
+        "round2_to_round3": {"excluded": 133, "checked": true}
+      },
+      "manuscript_drift": [
+        {"stage": "round3_include", "computed": 42, "manuscript": 43,
+         "manuscript_line": 67}
+      ]
+    }
+
+Exit codes:
+    0 — no drift (and manuscript agrees if supplied)
+    1 — drift between computed cascade and manuscript prose
+    2 — invocation error
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def count_decisions(tsv_path: Path, decision_col: str) -> dict[str, int]:
+    """Return {decision: count} for the given TSV."""
+    delim = "," if tsv_path.suffix.lower() == ".csv" else "\t"
+    counts: dict[str, int] = {}
+    total = 0
+    with tsv_path.open("r", encoding="utf-8", newline="") as fh:
+        reader = csv.DictReader(fh, delimiter=delim)
+        if reader.fieldnames is None or decision_col not in reader.fieldnames:
+            print(
+                f"ERROR: decision column {decision_col!r} not in {tsv_path}",
+                file=sys.stderr,
+            )
+            sys.exit(2)
+        for row in reader:
+            decision = (row.get(decision_col) or "").strip().upper()
+            if decision:
+                counts[decision] = counts.get(decision, 0) + 1
+                total += 1
+    counts["_total"] = total
+    return counts
+
+
+def search_manuscript_stage(text: str, stage_name: str) -> tuple[int | None, int | None]:
+    """Best-effort grep for a stage count and its line number.
+
+    Stage names map to a small dictionary of cascade phrases. Returns
+    (value, lineno) or (None, None) when no match found.
+    """
+    patterns = {
+        "round1_include": [
+            r"(\d{1,3}(?:,\d{3})*)\s+records?\s+(?:were\s+)?(?:included\s+)?after\s+title.{0,40}abstract",
+            r"(\d{1,3}(?:,\d{3})*)\s+records?\s+screened\s+by\s+title",
+        ],
+        "round2_include": [
+            r"(\d{1,3}(?:,\d{3})*)\s+records?\s+(?:moved\s+forward\s+)?to\s+full.?text",
+            r"(\d{1,3}(?:,\d{3})*)\s+records?\s+(?:were\s+)?retrieved\s+for\s+full.?text",
+        ],
+        "round3_include": [
+            r"(\d{1,3}(?:,\d{3})*)\s+studies?\s+(?:were\s+)?included\s+in\s+(?:the\s+)?(?:final\s+)?(?:qualitative|quantitative)\s+synthesis",
+            r"(\d{1,3}(?:,\d{3})*)\s+studies?\s+(?:were\s+)?included\s+in\s+(?:the\s+)?(?:meta-analysis|review)",
+            r"(?:included|comprised|finally\s+included)\s+(\d{1,3}(?:,\d{3})*)\s+studies?",
+        ],
+    }
+    pats = patterns.get(stage_name)
+    if not pats:
+        return None, None
+    for lineno, line in enumerate(text.splitlines(), start=1):
+        for pat in pats:
+            m = re.search(pat, line, flags=re.IGNORECASE)
+            if m:
+                try:
+                    val = int(m.group(1).replace(",", ""))
+                except ValueError:
+                    continue
+                return val, lineno
+    return None, None
+
+
+@dataclass
+class CascadeReport:
+    submission_safe: bool
+    stage_counts: dict[str, int] = field(default_factory=dict)
+    cascade_arithmetic: dict[str, dict] = field(default_factory=dict)
+    manuscript_drift: list[dict] = field(default_factory=list)
+
+
+def build_report(
+    round1: Path,
+    round2: Path,
+    round3: Path,
+    manuscript: Path | None,
+    r1_col: str,
+    r2_col: str,
+    r3_col: str,
+) -> CascadeReport:
+    r1 = count_decisions(round1, r1_col)
+    r2 = count_decisions(round2, r2_col)
+    r3 = count_decisions(round3, r3_col)
+
+    stage_counts = {
+        "round1_total": r1.get("_total", 0),
+        "round1_include": r1.get("INCLUDE", 0) + r1.get("MAYBE", 0),
+        "round2_include": r2.get("INCLUDE", 0) + r2.get("MAYBE", 0),
+        "round3_include": r3.get("INCLUDE", 0),
+        "round3_exclude": r3.get("EXCLUDE", 0),
+    }
+
+    cascade: dict[str, dict] = {
+        "round1_to_round2": {
+            "excluded": stage_counts["round1_total"] - stage_counts["round2_include"],
+            "checked": True,
+        },
+        "round2_to_round3": {
+            "excluded": (
+                stage_counts["round2_include"]
+                - (stage_counts["round3_include"] + stage_counts["round3_exclude"])
+            ),
+            "checked": True,
+        },
+    }
+
+    drifts: list[dict] = []
+    if manuscript is not None and manuscript.is_file():
+        text = manuscript.read_text(encoding="utf-8")
+        for stage in ("round1_include", "round2_include", "round3_include"):
+            val, lineno = search_manuscript_stage(text, stage)
+            if val is None:
+                continue
+            if val != stage_counts[stage]:
+                drifts.append(
+                    {
+                        "stage": stage,
+                        "computed": stage_counts[stage],
+                        "manuscript": val,
+                        "manuscript_line": lineno,
+                    }
+                )
+
+    submission_safe = not drifts
+    return CascadeReport(
+        submission_safe=submission_safe,
+        stage_counts=stage_counts,
+        cascade_arithmetic=cascade,
+        manuscript_drift=drifts,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="PRISMA flow cascade arithmetic auto-verify.")
+    parser.add_argument("--round1", type=Path, required=True)
+    parser.add_argument("--round2", type=Path, required=True)
+    parser.add_argument("--round3", type=Path, required=True)
+    parser.add_argument("--manuscript", type=Path, default=None)
+    parser.add_argument("--r1-col", default="decision")
+    parser.add_argument("--r2-col", default="decision")
+    parser.add_argument("--r3-col", default="round3_decision")
+    parser.add_argument("--out", type=Path, default=Path("qc/prisma_cascade.json"))
+    parser.add_argument("--quiet", action="store_true")
+    args = parser.parse_args(argv)
+
+    for p, label in (
+        (args.round1, "--round1"),
+        (args.round2, "--round2"),
+        (args.round3, "--round3"),
+    ):
+        if not p.is_file():
+            print(f"ERROR: {label} not a file: {p}", file=sys.stderr)
+            return 2
+
+    report = build_report(
+        args.round1, args.round2, args.round3,
+        args.manuscript, args.r1_col, args.r2_col, args.r3_col,
+    )
+
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(
+        json.dumps(
+            {
+                "submission_safe": report.submission_safe,
+                "stage_counts": report.stage_counts,
+                "cascade_arithmetic": report.cascade_arithmetic,
+                "manuscript_drift": report.manuscript_drift,
+            },
+            indent=2,
+        ),
+        encoding="utf-8",
+    )
+
+    if not args.quiet:
+        if report.submission_safe:
+            print(
+                "PASS: cascade computed. Stages: "
+                + " → ".join(
+                    f"{k}={v}" for k, v in report.stage_counts.items() if not k.startswith("_")
+                )
+            )
+        else:
+            print(
+                f"FAIL: {len(report.manuscript_drift)} manuscript-prose "
+                "drift(s) vs computed cascade."
+            )
+            for d in report.manuscript_drift:
+                print(
+                    f"  {d['stage']}: computed={d['computed']} "
+                    f"manuscript={d['manuscript']} (line {d['manuscript_line']})"
+                )
+
+    return 0 if report.submission_safe else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/check-reporting/skill.yml

@@ -0,0 +1,41 @@
+schema_version: 2
+name: check-reporting
+layer: A
+owner_domain: reporting_compliance
+when_to_use:
+  - Pre-submission item-level checklist run for a target reporting guideline (STROBE / CONSORT / STARD / TRIPOD / PRISMA / ARRIVE / CARE / SPIRIT / CLAIM / SQUIRE 2.0 / etc.)
+  - Risk-of-bias assessment using QUADAS-2 / QUADAS-C / RoB 2 / ROBINS-I / ROBINS-E / ROBIS / PROBAST / NOS / COSMIN / RoB NMA
+  - AI-extension audit (STARD-AI, TRIPOD+AI, PROBAST+AI, CLAIM 2024, MI-CLEAR-LLM, CLEAR)
+  - Reviewer or editor asks the manuscript "to comply with [guideline]" — generate the gap list
+when_NOT_to_use:
+  - Drafting manuscript prose to fill missing items (use /write-paper or /revise)
+  - Inventing checklist items not in the published guideline (forbidden)
+  - Reviewer-style critique of intellectual content (use /peer-review or /self-review)
+inputs:
+  - manuscript/manuscript.md
+outputs:
+  - qc/reporting_checklist.md
+  - qc/reporting_checklist.json
+deterministic_scripts:
+  - none_required
+side_effects:
+  - writes_qc_artifacts
+downstream_consumers:
+  - write-paper
+  - self-review
+forbidden_actions:
+  - invent_reporting_guideline_items
+  - silently_mark_missing_items_present
+
+# v2.1 quality card
+purpose: "Audit a manuscript item-by-item against a chosen reporting guideline (32 supported) with PRESENT/MISSING/PARTIAL status."
+safety_boundaries:
+  - "Checklist items are quoted from the guideline, never invented; missing items are not marked present."
+  - "Fails fast if the requested checklist file is absent rather than generating a guessed checklist."
+known_limitations:
+  - "Item judgements are advisory; a PRESENT mark is a locator, not a quality guarantee."
+  - "Coverage is limited to the bundled checklists."
+validation_commands:
+  - "python3 scripts/check_checklist_exists.py <guideline>"
+  - "python3 scripts/prisma_cascade_check.py"
+evidence_surface: demo

package/skills/check-reporting/tests/fixtures/framework_bad.md

@@ -0,0 +1,8 @@
+# Methods
+
+Risk of bias was assessed with PROBAST+AI. Some studies used PROBAST-AI
+signalling questions instead.
+
+Diagnostic accuracy reporting followed STARD-AI as adapted per recent guidance.
+
+We applied a 12-AI item subset to score the models.

package/skills/check-reporting/tests/fixtures/framework_clean.md

@@ -0,0 +1,7 @@
+# Methods
+
+Risk of bias was assessed using PROBAST (Wolff 2019) together with its PROBAST+AI
+extension (Collins 2024) [12].
+
+Diagnostic accuracy reporting followed STARD 2015 (Bossuyt 2015) and its STARD-AI
+extension (Sounderajah 2025) [13].

package/skills/check-reporting/tests/test_checklist_fail_fast.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# Regression tests for check-reporting check_checklist_exists.py (fail-fast guard).
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../../.." && pwd)"
+SCRIPT="$REPO_ROOT/skills/check-reporting/scripts/check_checklist_exists.py"
+
+[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }
+
+fail=0
+ran=0
+
+assert_exit() {
+    local label="$1" expected="$2" actual="$3"
+    ran=$((ran + 1))
+    if [[ "$expected" == "$actual" ]]; then
+        printf '  PASS  %-52s exit=%s\n' "$label" "$actual"
+    else
+        printf '  FAIL  %-52s expected=%s actual=%s\n' "$label" "$expected" "$actual"
+        fail=$((fail + 1))
+    fi
+}
+
+assert_contains() {
+    local label="$1" needle="$2" haystack="$3"
+    ran=$((ran + 1))
+    if [[ "$haystack" == *"$needle"* ]]; then
+        printf '  PASS  %-52s\n' "$label"
+    else
+        printf '  FAIL  %-52s (missing: %s)\n' "$label" "$needle"
+        fail=$((fail + 1))
+    fi
+}
+
+run() { python3 "$SCRIPT" "$@" >/dev/null 2>&1; echo $?; }
+
+# 1. Vendored checklists that exist on disk -> exit 0.
+assert_exit "STROBE present" 0 "$(run --guideline STROBE)"
+assert_exit "STARD-AI alias present" 0 "$(run --guideline STARD-AI)"
+assert_exit "TRIPOD+AI alias present" 0 "$(run --guideline 'TRIPOD+AI')"
+assert_exit "AMSTAR 2 alias present" 0 "$(run --guideline 'AMSTAR 2')"
+assert_exit "RoB 2 alias present" 0 "$(run --guideline 'RoB 2')"
+assert_exit "QUADAS-C alias present" 0 "$(run --guideline QUADAS-C)"
+
+# 2. Now-vendored guidelines -> exit 0 (CONSORT 2025 / SPIRIT 2025 / CARE / CLAIM
+#    2024 were vendored in PR #43; they must resolve to real files).
+assert_exit "CONSORT now vendored" 0 "$(run --guideline 'CONSORT 2025')"
+assert_exit "CARE now vendored" 0 "$(run --guideline CARE)"
+assert_exit "SPIRIT now vendored" 0 "$(run --guideline 'SPIRIT 2025')"
+assert_exit "CLAIM 2024 now vendored" 0 "$(run --guideline 'CLAIM 2024')"
+
+# 2b. Advertised-but-unvendored guidelines -> exit 1 (contract violation). The AI
+#     extensions are routed in the auto-detect table but ship no checklist file.
+assert_exit "CONSORT-AI unvendored" 1 "$(run --guideline 'CONSORT-AI')"
+assert_exit "SPIRIT-AI unvendored" 1 "$(run --guideline 'SPIRIT-AI')"
+
+# 3. Unrecognised guideline -> exit 2.
+assert_exit "unknown guideline" 2 "$(run --guideline NOT-A-REAL-GUIDELINE)"
+
+# 4. Explicit opt-in downgrades missing/unknown to exit 0 but warns (never silent).
+assert_exit "opt-in unvendored -> 0" 0 "$(run --guideline 'CONSORT-AI' --allow-from-memory)"
+assert_exit "opt-in unknown -> 0" 0 "$(run --guideline NOPE --allow-from-memory)"
+optin_out="$(python3 "$SCRIPT" --guideline 'CONSORT-AI' --allow-from-memory 2>&1)"
+assert_contains "opt-in emits NON-AUTHORITATIVE warning" "NON-AUTHORITATIVE" "$optin_out"
+
+# 5. Contract-test simulation (codex Improvement B "Prove" step).
+sim_out="$(python3 "$SCRIPT" --simulate-missing-checklist 2>&1)"
+assert_exit "simulate-missing-checklist" 1 "$(run --simulate-missing-checklist)"
+assert_contains "simulate emits standard violation code" "MISSING_CHECKLIST_CONTRACT_VIOLATION" "$sim_out"
+
+# 6. Violation message carries the standardized machine-greppable code.
+viol_out="$(python3 "$SCRIPT" --guideline 'CONSORT-AI' 2>&1)"
+assert_contains "missing emits standard violation code" "MISSING_CHECKLIST_CONTRACT_VIOLATION" "$viol_out"
+
+printf '\n%d/%d checks passed\n' "$((ran - fail))" "$ran"
+[[ "$fail" -eq 0 ]] || exit 1