medsci-skills 4.1.0

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

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""Fail-fast guard for /check-reporting checklist routing.
+
+The /check-reporting skill assesses a manuscript against a vendored reporting
+guideline checklist (references/checklists/*.md). Historically, when a routed
+checklist file was absent the skill silently fell back to constructing the
+checklist "from its knowledge of the guideline" — a fabrication path that is
+exactly what the rest of the skill exists to prevent. This guard makes that
+case loud:
+
+  - The requested guideline resolves to a vendored file that exists  -> exit 0.
+  - It resolves to a known guideline whose file is ABSENT            -> exit 1,
+    prints MISSING_CHECKLIST_CONTRACT_VIOLATION.
+  - The name is not a recognised guideline                           -> exit 2,
+    prints UNKNOWN_GUIDELINE.
+
+`--allow-from-memory` is the single explicit opt-in escape hatch: it downgrades
+exit 1/2 to exit 0 but always emits a NON-AUTHORITATIVE warning, so a
+construct-from-memory assessment can never happen silently.
+
+Source of truth for "what is vendored" is the checklists directory on disk, not
+this file — the alias map only translates display names to filename stems.
+
+Stdlib-only.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+
+# Display/guideline name (normalised) -> checklist filename stem.
+# Keys are normalised by _norm(): lowercased, with spaces/hyphens/dots/plus/
+# underscores and a trailing 4-digit year stripped. The stem is the expected
+# file under references/checklists/<stem>.md. A stem whose file is absent is a
+# contract violation, surfaced loudly rather than silently fabricated.
+ALIAS_TO_STEM = {
+    "strobe": "STROBE",
+    "consort": "CONSORT",
+    "consortai": "CONSORT_AI",
+    "stard": "STARD",
+    "stardai": "STARD_AI",
+    "tripod": "TRIPOD",
+    "tripodai": "TRIPOD_AI",
+    "prisma": "PRISMA_2020",
+    "prismadta": "PRISMA_DTA",
+    "prismap": "PRISMA_P",
+    "arrive": "ARRIVE_2",
+    "care": "CARE",
+    "spirit": "SPIRIT",
+    "spiritai": "SPIRIT_AI",
+    "claim": "CLAIM_2024",
+    "miclearllm": "MI_CLEAR_LLM",
+    "squire": "SQUIRE_2",
+    "clear": "CLEAR",
+    "moose": "MOOSE",
+    "grras": "GRRAS",
+    "swim": "SWiM",
+    "amstar": "AMSTAR2",
+    "amstar2": "AMSTAR2",
+    "quadas": "QUADAS2",
+    "quadas2": "QUADAS2",
+    "quadasc": "QUADAS_C",
+    "rob2": "RoB2",
+    "robinsi": "ROBINS_I",
+    "robinse": "ROBINS_E",
+    "robis": "ROBIS",
+    "robme": "ROB_ME",
+    "robnma": "RoB_NMA",
+    "probast": "PROBAST",
+    "probastai": "PROBAST_AI",
+    "nos": "NOS",
+    "cosmin": "COSMIN_RoB",
+    "cosminrob": "COSMIN_RoB",
+}
+
+EXIT_OK = 0
+EXIT_MISSING = 1
+EXIT_UNKNOWN = 2
+
+
+def _norm(name: str) -> str:
+    """Normalise a guideline name to an alias key.
+
+    Lowercase, drop a trailing 4-digit year, then strip spaces/hyphens/dots/
+    plus/underscores. "STARD-AI" -> "stardai"; "AMSTAR 2" -> "amstar2";
+    "CONSORT 2010" -> "consort"; "TRIPOD+AI" -> "tripodai".
+    """
+    n = name.strip().lower()
+    n = re.sub(r"\b(19|20)\d{2}\b", "", n)          # drop version year
+    n = re.sub(r"[\s\-_.+]", "", n)                 # strip spaces/-/_/./+
+    return n
+
+
+def checklist_dir(skill_dir: Path) -> Path:
+    return skill_dir / "references" / "checklists"
+
+
+def resolve_stem(guideline: str) -> str | None:
+    return ALIAS_TO_STEM.get(_norm(guideline))
+
+
+def available_stems(cdir: Path) -> list[str]:
+    if not cdir.is_dir():
+        return []
+    return sorted(p.stem for p in cdir.glob("*.md"))
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Fail-fast guard: confirm a routed reporting-guideline checklist is vendored."
+    )
+    parser.add_argument("--guideline", help="Guideline name, e.g. 'STROBE', 'STARD-AI', 'CONSORT 2010'.")
+    parser.add_argument(
+        "--skill-dir",
+        default=str(Path(__file__).resolve().parent.parent),
+        help="check-reporting skill root (default: inferred from this script).",
+    )
+    parser.add_argument(
+        "--allow-from-memory",
+        action="store_true",
+        help="Explicit opt-in: downgrade a missing/unknown checklist to exit 0 with a "
+             "NON-AUTHORITATIVE warning instead of failing. Never silent.",
+    )
+    parser.add_argument(
+        "--simulate-missing-checklist",
+        action="store_true",
+        help="Force the missing-file path (for contract tests).",
+    )
+    parser.add_argument("--list", action="store_true", help="List vendored checklist files and exit.")
+    args = parser.parse_args()
+
+    skill_dir = Path(args.skill_dir).resolve()
+    cdir = checklist_dir(skill_dir)
+
+    if args.list:
+        stems = available_stems(cdir)
+        print(f"{len(stems)} vendored checklists in {cdir}:")
+        for s in stems:
+            print(f"  {s}")
+        return EXIT_OK
+
+    if args.simulate_missing_checklist:
+        print("MISSING_CHECKLIST_CONTRACT_VIOLATION: simulated missing checklist "
+              "(guideline routed but no vendored file).", file=sys.stderr)
+        if args.allow_from_memory:
+            print("WARNING: --allow-from-memory set; a from-memory (NON-AUTHORITATIVE) "
+                  "assessment would proceed. The report MUST be marked non-vendored.")
+            return EXIT_OK
+        return EXIT_MISSING
+
+    if not args.guideline:
+        parser.error("--guideline is required (or use --list / --simulate-missing-checklist)")
+
+    stem = resolve_stem(args.guideline)
+    if stem is None:
+        print(f"UNKNOWN_GUIDELINE: '{args.guideline}' is not a recognised reporting guideline.",
+              file=sys.stderr)
+        if args.allow_from_memory:
+            print("WARNING: --allow-from-memory set; proceeding from memory for an unrecognised "
+                  "guideline (NON-AUTHORITATIVE). The report MUST be marked non-vendored.")
+            return EXIT_OK
+        return EXIT_UNKNOWN
+
+    path = cdir / f"{stem}.md"
+    if path.is_file():
+        print(f"OK: {args.guideline} -> references/checklists/{stem}.md")
+        return EXIT_OK
+
+    print(f"MISSING_CHECKLIST_CONTRACT_VIOLATION: '{args.guideline}' resolves to "
+          f"'{stem}.md' which is not vendored under {cdir}.", file=sys.stderr)
+    if args.allow_from_memory:
+        print(f"WARNING: --allow-from-memory set; proceeding from memory for '{args.guideline}' "
+              f"(NON-AUTHORITATIVE). The report MUST be marked non-vendored.")
+        return EXIT_OK
+    return EXIT_MISSING
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""
+check_checklist_version.py — detect a reporting checklist that is stale relative
+to the current manuscript (A4b).
+
+A reporting checklist is frequently generated against an *older* manuscript
+version: its section/line references and version label no longer match the
+submitted manuscript, and a reviewer who cross-checks the line numbers sees the
+mismatch. This detector compares an existing checklist's target metadata against
+the current manuscript and flags a regenerate-needed condition.
+
+It reads the version contract emitted by check-reporting (v1.1+):
+`target_manuscript`, `target_version`, `source_sha256` — from a JSON checklist
+(`qc/reporting_checklist.json`) or from the text header / embedded JSON of a
+Markdown report. Comparison precedence:
+
+  1. `source_sha256` present and != current manuscript hash  → STALE (content changed)
+  2. else `target_version` present and != current version    → STALE (version bump)
+  3. else `target_manuscript` present and != current filename → STALE (different file)
+  4. no version metadata at all                               → UNVERIFIABLE (regen w/ v1.1)
+
+Exit: 0 = in sync, 1 = stale / unverifiable, 2 = usage/error. Stdlib-only.
+
+Usage:
+    python3 check_checklist_version.py --checklist qc/reporting_checklist.json \
+        --manuscript manuscript_v8.md [--manuscript-version v8] \
+        [--out qc/checklist_version.json] [--quiet]
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+from pathlib import Path
+
+FILENAME_VERSION_RE = re.compile(r"[_\-.]v(\d{1,3})\b", re.IGNORECASE)
+HEADER_TARGET_FILE_RE = re.compile(r"Target manuscript file:\s*([^\n]+)", re.IGNORECASE)
+HEADER_TARGET_VER_RE = re.compile(r"Target version:\s*v?(\d{1,3})\b", re.IGNORECASE)
+JSON_BLOCK_RE = re.compile(r"```json\s*(\{.*?\})\s*```", re.DOTALL)
+
+
+def manuscript_identity(path: Path, explicit_version: str | None) -> dict:
+    data = path.read_bytes()
+    sha = hashlib.sha256(data).hexdigest()[:12]
+    version = None
+    if explicit_version:
+        m = re.search(r"\d+", explicit_version)
+        version = int(m.group(0)) if m else None
+    if version is None:
+        m = FILENAME_VERSION_RE.search(path.name)
+        version = int(m.group(1)) if m else None
+    return {"file": path.name, "version": version, "sha256": sha}
+
+
+def parse_checklist(path: Path) -> dict:
+    """Extract target_manuscript / target_version / source_sha256 from a JSON or
+    Markdown checklist. Returns a dict with those keys (values may be None)."""
+    text = path.read_text(encoding="utf-8", errors="replace")
+    out = {"target_manuscript": None, "target_version": None, "source_sha256": None}
+
+    obj = None
+    if path.suffix.lower() == ".json":
+        try:
+            obj = json.loads(text)
+        except Exception:
+            obj = None
+    if obj is None:
+        m = JSON_BLOCK_RE.search(text)
+        if m:
+            try:
+                obj = json.loads(m.group(1))
+            except Exception:
+                obj = None
+    if isinstance(obj, dict):
+        out["target_manuscript"] = obj.get("target_manuscript")
+        out["source_sha256"] = obj.get("source_sha256")
+        tv = obj.get("target_version")
+        if tv is not None:
+            mm = re.search(r"\d+", str(tv))
+            out["target_version"] = int(mm.group(0)) if mm else None
+
+    # Markdown header fallbacks (only fill what JSON did not provide)
+    if out["target_manuscript"] is None:
+        m = HEADER_TARGET_FILE_RE.search(text)
+        if m:
+            out["target_manuscript"] = m.group(1).strip()
+    if out["target_version"] is None:
+        m = HEADER_TARGET_VER_RE.search(text)
+        if m:
+            out["target_version"] = int(m.group(1))
+    return out
+
+
+def evaluate(current: dict, checklist: dict) -> list[dict]:
+    findings: list[dict] = []
+    ck_sha = checklist.get("source_sha256")
+    ck_ver = checklist.get("target_version")
+    ck_file = checklist.get("target_manuscript")
+
+    if ck_sha and current["sha256"] and ck_sha != current["sha256"]:
+        findings.append({
+            "type": "checklist_content_stale", "severity": "stale",
+            "detail": f"checklist source_sha256 {ck_sha} != current {current['sha256']} "
+                      "— manuscript content changed since the checklist was generated"})
+    elif ck_ver is not None and current["version"] is not None and ck_ver != current["version"]:
+        findings.append({
+            "type": "checklist_version_stale", "severity": "stale",
+            "detail": f"checklist targets v{ck_ver} but current is v{current['version']}"})
+    elif ck_file and ck_file != current["file"]:
+        findings.append({
+            "type": "checklist_file_mismatch", "severity": "stale",
+            "detail": f"checklist targets '{ck_file}' but current is '{current['file']}'"})
+
+    if ck_sha is None and ck_ver is None and ck_file is None:
+        findings.append({
+            "type": "checklist_no_version_metadata", "severity": "unverifiable",
+            "detail": "checklist carries no target_manuscript/target_version/source_sha256 "
+                      "(pre-v1.1 contract) — cannot verify; regenerate with current check-reporting"})
+    return findings
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        description="Flag a reporting checklist that is stale vs the current manuscript.")
+    ap.add_argument("--checklist", type=Path, required=True,
+                    help="qc/reporting_checklist.json or the .md report.")
+    ap.add_argument("--manuscript", type=Path, required=True, help="Current manuscript file.")
+    ap.add_argument("--manuscript-version", default=None,
+                    help="Current version token (else inferred from filename).")
+    ap.add_argument("--out", type=Path, default=None, help="Write JSON report here.")
+    ap.add_argument("--quiet", action="store_true", help="Suppress stdout summary.")
+    args = ap.parse_args(argv)
+
+    if not args.checklist.is_file():
+        print(f"ERROR: --checklist not a file: {args.checklist}", file=sys.stderr)
+        return 2
+    if not args.manuscript.is_file():
+        print(f"ERROR: --manuscript not a file: {args.manuscript}", file=sys.stderr)
+        return 2
+
+    current = manuscript_identity(args.manuscript, args.manuscript_version)
+    checklist = parse_checklist(args.checklist)
+    findings = evaluate(current, checklist)
+    safe = not findings
+
+    report = {"submission_safe": safe, "current": current,
+              "checklist": checklist, "findings": findings}
+    if args.out is not None:
+        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 safe:
+            print(f"PASS: checklist matches current manuscript (v{current['version']}, "
+                  f"{current['sha256']}).")
+        else:
+            print("FAIL: checklist is stale or unverifiable:")
+            for f in findings:
+                print(f"  - [{f['severity']}] {f['type']}: {f['detail']}")
+
+    return 0 if safe else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,206 @@
+#!/usr/bin/env python3
+"""Reporting-framework naming discipline audit (check-reporting Step 4e).
+
+A base reporting tool and its AI/extension are distinct instruments with separate
+citations. Manuscripts routinely (a) invoke an extension (PROBAST+AI, STARD-AI,
+TRIPOD+AI, PRISMA-DTA) without ever naming or citing the base instrument it
+extends, (b) mix hyphenation for the same family within one document (PROBAST+AI
+13x next to PROBAST-AI 2x), (c) coin item labels like "12-AI", or (d) wave at
+"recent guidance" instead of naming the framework. Each is a reviewer red flag and
+each is a deterministic grep.
+
+INPUTS
+  --manuscript  manuscript markdown/text (required).
+
+CHECKS
+  BASE_MISSING       (Major) an extension is used but its base instrument name never
+                     appears standalone in the document.
+  HYPHEN_MIX         (Minor) both "<FAMILY>+AI" and "<FAMILY>-AI" occur — inconsistent.
+  CITE_MISSING       (Minor) the sentence first invoking an extension carries no
+                     citation marker.
+  SELF_COINED_LABEL  (Minor) a self-coined "<digits>-AI" item label.
+  VAGUE_GUIDANCE     (Minor) "adapted per recent guidance"-style wording with no
+                     named framework.
+
+OUTPUT
+  A reconciliation table (stdout) and, with --out, a JSON artifact:
+    {manuscript, claims[{verdict, severity, detail, where}], summary}
+  Exit 1 (with --strict) when any Major-severity claim exists.
+
+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
+
+# Extension regex -> base instrument name. The base must appear standalone (not as a
+# prefix of the extension) somewhere in the document.
+EXT_TO_BASE = [
+    (r"PROBAST\s*\+\s*AI", "PROBAST"),
+    (r"PROBAST-AI", "PROBAST"),
+    (r"TRIPOD\s*\+\s*AI", "TRIPOD"),
+    (r"TRIPOD-AI", "TRIPOD"),
+    (r"TRIPOD-LLM", "TRIPOD"),
+    (r"STARD-AI", "STARD"),
+    (r"STARD\s*\+\s*AI", "STARD"),
+    (r"CONSORT-AI", "CONSORT"),
+    (r"SPIRIT-AI", "SPIRIT"),
+    (r"PRISMA-DTA", "PRISMA"),
+    (r"QUADAS-C", "QUADAS"),
+]
+
+HYPHEN_FAMILIES = ("PROBAST", "TRIPOD", "STARD", "CONSORT", "SPIRIT", "QUADAS", "DECIDE")
+
+CITE_MARKER = re.compile(r"\[\d|\[@|\bet al\.?|\(\s*[A-Z][A-Za-z]+,?\s+\d{4}|\b\d{4}[a-z]?\)")
+SELF_COINED = re.compile(r"\b\d{1,2}-AI\b")
+VAGUE = re.compile(
+    r"\b(?:adapted|adjusted|modified|aligned|updated|following|per|in line with)\b"
+    r"[\w\s,]{0,20}?"
+    r"\b(?:recent|current|emerging|latest|evolving)\b\s+"
+    r"(?:best[- ]practice|guidance|practice|recommendations?|standards?|guidelines?)",
+    re.I)
+
+
+def _sentences(text: str) -> list[str]:
+    units = []
+    for para in re.split(r"\n[ \t]*\n", text):
+        flat = re.sub(r"\s*\n\s*", " ", para).strip()
+        units.extend(re.split(r"(?<=[.;])\s+", flat))
+    return [u for u in units if u.strip()]
+
+
+def check(text: str) -> list[dict]:
+    claims = []
+
+    # BASE_MISSING + first-use CITE_MISSING
+    flagged_base = set()
+    for ext_re, base in EXT_TO_BASE:
+        m = re.search(ext_re, text, re.I)
+        if not m:
+            continue
+        standalone = re.search(rf"\b{base}\b(?!\s*[-+]\s*(?:AI|LLM))(?!-(?:AI|LLM|DTA|C\b))",
+                               text, re.I)
+        if not standalone and base not in flagged_base:
+            flagged_base.add(base)
+            claims.append({
+                "verdict": "BASE_MISSING",
+                "severity": "Major",
+                "detail": (f"the extension '{m.group(0)}' is used but the base instrument "
+                           f"'{base}' is never named standalone (name and cite both)"),
+                "where": m.group(0),
+            })
+        # citation near first use
+        sent = next((s for s in _sentences(text) if re.search(ext_re, s, re.I)), "")
+        if sent and not CITE_MARKER.search(sent):
+            claims.append({
+                "verdict": "CITE_MISSING",
+                "severity": "Minor",
+                "detail": (f"first use of '{m.group(0)}' has no citation marker in its "
+                           f"sentence"),
+                "where": sent.strip()[:160],
+            })
+
+    # HYPHEN_MIX
+    for fam in HYPHEN_FAMILIES:
+        plus = len(re.findall(rf"{fam}\s*\+\s*AI", text, re.I))
+        hyph = len(re.findall(rf"{fam}-AI", text, re.I))
+        if plus and hyph:
+            claims.append({
+                "verdict": "HYPHEN_MIX",
+                "severity": "Minor",
+                "detail": (f"'{fam}+AI' ({plus}x) and '{fam}-AI' ({hyph}x) both used — "
+                           f"pick one hyphenation"),
+                "where": fam,
+            })
+
+    # SELF_COINED_LABEL
+    for m in dict.fromkeys(SELF_COINED.findall(text)):
+        claims.append({
+            "verdict": "SELF_COINED_LABEL",
+            "severity": "Minor",
+            "detail": f"self-coined AI item label '{m}' — use the framework's own item numbering",
+            "where": m,
+        })
+
+    # VAGUE_GUIDANCE
+    for m in VAGUE.finditer(text):
+        claims.append({
+            "verdict": "VAGUE_GUIDANCE",
+            "severity": "Minor",
+            "detail": (f"vague wording '{m.group(0).strip()}' — name the specific framework "
+                       f"and cite it"),
+            "where": m.group(0).strip()[:80],
+        })
+
+    return claims
+
+
+def analyze(manuscript: str) -> dict:
+    p = Path(manuscript)
+    if not p.is_file():
+        sys.stderr.write(f"ERROR: manuscript not found: {manuscript}\n")
+        sys.exit(2)
+    claims = check(p.read_text(encoding="utf-8"))
+    n_major = sum(1 for c in claims if c["severity"] == "Major")
+    return {
+        "manuscript": str(p),
+        "claims": claims,
+        "summary": {
+            "n_claims": len(claims),
+            "n_major": n_major,
+            "n_flag": len(claims) - n_major,
+            "verdict": "MAJOR_CANDIDATE" if n_major else ("FLAG" if claims else "OK"),
+        },
+    }
+
+
+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) | — | reporting-framework naming is disciplined |")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Reporting-framework naming audit (Step 4e).")
+    ap.add_argument("--manuscript", required=True, help="manuscript markdown/text")
+    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.manuscript)
+
+    if not args.quiet:
+        print("=" * 41)
+        print(" Framework Naming (Step 4e)")
+        print("=" * 41)
+        print(render(result))
+        print()
+        s = result["summary"]
+        if s["n_major"]:
+            print(f"MAJOR candidate: {s['n_major']} base-instrument naming gap(s).")
+        elif s["n_flag"]:
+            print(f"FLAG: {s['n_flag']} naming/citation inconsistency(ies).")
+        else:
+            print("OK: reporting-framework naming is disciplined.")
+
+    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())