medsci-skills 5.20.1 → 5.22.0

package/LICENSE

@@ -24,22 +24,61 @@ SOFTWARE.
 
 ## Third-Party Content Licenses
 
-The following reporting guideline checklists are bundled under their original licenses
-(NOT under MIT). See each file for attribution:
-
-- STROBE checklist: CC BY (https://www.strobe-statement.org)
-- STARD 2015 checklist: CC BY 4.0 (https://www.equator-network.org/reporting-guidelines/stard/)
-- TRIPOD+AI checklist: CC BY 4.0 (https://www.tripod-statement.org)
-- PRISMA 2020 checklist: CC BY (https://www.prisma-statement.org)
-- ARRIVE 2.0 checklist: CC0 (https://arriveguidelines.org)
-
-The following checklists are NOT bundled due to license restrictions.
-Users should download them directly from official sources:
-
-- CONSORT 2010: https://www.consort-statement.org (CC BY-NC)
-- CARE: https://www.care-statement.org
-- SPIRIT: https://www.spirit-statement.org (CC BY-NC-ND)
-- CLAIM 2024: https://pubs.rsna.org/doi/10.1148/radiol.2020200267
+Parts of this package are not ours, and are bundled under their own licenses (NOT under MIT).
+This section is the index of them. It is checked against the tree on every build by
+`scripts/check_third_party_index.py` — a license file that describes a package other than the one
+you downloaded is worse than no license file at all.
+
+### Reporting guideline checklists — our summaries (`skills/*/references/checklists/*.md`)
+
+These are educational summaries written in our own words, each citing its source. They do not
+relicense the underlying guideline.
+
+- STROBE: CC BY (https://www.strobe-statement.org)
+- STARD 2015 / STARD-AI: CC BY 4.0 (https://www.equator-network.org/reporting-guidelines/stard/)
+- TRIPOD / TRIPOD+AI: CC BY 4.0 (https://www.tripod-statement.org)
+- PRISMA 2020 / PRISMA-DTA: CC BY (https://www.prisma-statement.org)
+- ARRIVE 2.0: CC0 (https://arriveguidelines.org)
+- CONSORT 2025, SPIRIT 2025: CC BY 4.0 (https://www.consort-spirit.org)
+
+**Non-commercial restrictions.** The following summaries derive from instruments whose materials are
+CC BY-NC, and are therefore free to use and redistribute **for non-commercial purposes with
+attribution**; commercial use requires permission from the rights holders:
+
+- CARE, MI-CLEAR-LLM, DECIDE-AI: CC BY-NC 4.0
+- CLAIM 2024: educational summary of an RSNA open-access checklist (© RSNA)
+
+See `skills/check-reporting/references/LICENSES.md` for the per-file detail.
+
+### Official guideline templates, verbatim (`skills/make-figures/templates/official/`)
+
+These are the guideline authors' own documents, redistributed unmodified:
+
+- CONSORT 2025 checklist + flow diagram (`.docx`): CC BY 4.0.
+  © 2025 Hopewell S et al. *BMJ* 2025;388:e081123. doi:10.1136/bmj-2024-081123
+- SPIRIT 2025 checklist + participant timeline (`.docx`): CC BY 4.0.
+  © 2025 Chan A-W et al. *BMJ* 2025;389:e081477. doi:10.1136/bmj-2024-081477
+- STARD 2015 checklist (`.docx`) and flow diagram (`.pdf`): CC BY 4.0.
+  Bossuyt PM et al. *BMJ* 2015;351:h5527
+- PRISMA 2020 flow diagrams (`.pptx`): built by us with
+  `skills/make-figures/scripts/build_prisma2020_template.py`, reproducing the published layout
+  (Page MJ et al. *BMJ* 2021;372:n71, Fig 1, CC BY 4.0)
+
+The CONSORT and SPIRIT **2025** updates are CC BY 4.0 — "unrestricted use, distribution, and
+reproduction in any medium, provided the original work is properly cited". Their 2010 / 2013
+predecessors were CC BY-NC / CC BY-NC-ND and could not have been bundled; this file said so for a
+long time after the 2025 versions had replaced them.
+
+### Citation styles (`skills/manage-refs/citation_styles/*.csl`)
+
+15 CSL files from the Citation Style Language project: **CC BY-SA 3.0**, unmodified, each retaining
+its own `<rights>` element. See `skills/manage-refs/NOTICE.md`.
+
+### Not bundled — download these yourself
+
+- **European Radiology graphical-abstract template** (`EURA-GA-Jan2025.pptx`):
+  https://www.springer.com/journal/330 — the journal's own file, with no license permitting
+  redistribution. `/make-figures` accepts it via `--template /absolute/path.pptx`.
 
 ## Optional Dependencies
 

package/README.md

@@ -2,14 +2,14 @@
 
 # MedSci Skills
 
-**55 skills that actually work.** Built by a physician-researcher, tested on real publications.
+**56 skills that actually work.** Built by a physician-researcher, tested on real publications.
 
 *MedSci Skills is an end-to-end research tool for physician and medical-engineering researchers — design → scaffold → validate → publish — for the clinical manuscript and the medical-AI model behind it. Its moat is the compliance layer — 46 reporting guidelines and risk-of-bias tools, reference/citation verification, and deterministic integrity gates before peer review — now extended by a model-engineering lane that scaffolds reproducible, leakage-safe training repos and audits model validation. Clinical AI model research engineering is in scope; a general AI-scientist platform is not. It competes on clinical submission reliability, not skill count.*
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Release](https://img.shields.io/github/v/release/Aperivue/medsci-skills?style=flat-square&color=blue)](https://github.com/Aperivue/medsci-skills/releases/latest)
 [![CI](https://img.shields.io/github/actions/workflow/status/Aperivue/medsci-skills/validate.yml?branch=main&style=flat-square&label=CI)](https://github.com/Aperivue/medsci-skills/actions/workflows/validate.yml)
-![Skills](https://img.shields.io/badge/Skills-55-brightgreen?style=flat-square)
+![Skills](https://img.shields.io/badge/Skills-56-brightgreen?style=flat-square)
 [![npm](https://img.shields.io/npm/v/medsci-skills?style=flat-square&label=npm&color=cb3837)](https://www.npmjs.com/package/medsci-skills)
 [![npm downloads](https://img.shields.io/npm/dw/medsci-skills?style=flat-square&label=npm%20downloads&color=cb3837)](https://www.npmjs.com/package/medsci-skills)
 [![Watch the 2-min intro](https://img.shields.io/badge/▶_Watch-2--min_intro-FF0000?style=flat-square&logo=youtube&logoColor=white)](https://youtu.be/MclQ_RIofpE)
@@ -288,6 +288,8 @@ The E2E pipeline (`orchestrate --e2e`) produces everything up to `qc/`. The `sub
 
 ## What's New
 
+**v5.21** — verification-layer batch, mostly promoted from real submission failures. A **marked (tracked-changes) manuscript** is now built by driving Word's Compare from the command line and proved by a **round trip** — accepting every revision must reproduce the revised paper exactly, rejecting every revision must reproduce the original — and the gate is **move-aware**, because Word encodes a relocated paragraph as `w:moveFrom`/`w:moveTo` and an insert-and-delete-only verifier calls a good file corrupt. Every detector's `qc/*.json` now **names the detector that wrote it**, so an artifact can be traced back to the check that produced it (a CI-enforced contract). Two `/verify-refs` precision defects: a Unicode hyphen in a surname fired `MISMATCH` — the verdict that means *fabricated author* — on a correct reference, and a Better BibTeX brace-protected surname was read as a corporate author, **silently skipping** the author check the tool exists to perform. New gates: publisher markup in a `.bib` title (`<scp>WHO</scp>` renders as garbage and no gate looked at the printed title), **complete/quasi separation** before a logistic model is fitted (a pathognomonic sign has an empty cell by construction; `glm` returns OR = 0.00, *p* = 0.99, and an AUC that gets reported), and a probe + gate for manuscripts claiming a system **improved itself** (which rung of the verification hierarchy said so?). `/find-cohort-gap` now accepts a **local codebook** — an institutional registry or EMR export, not only a named public cohort — enumerating variables verbatim with provenance rather than letting a model summarise them. Additive and backward-compatible; **55 skills / 46 guidelines / 61 integrity detectors / 23 domain-probe modules**. (See the [CHANGELOG](CHANGELOG.md) for v5.0–v5.20.)
+
 **v5.20.1** — audit-driven coherence fixes. A real `/orchestrate --e2e` state-transition bug (the pipeline halted at step 3 because it required a DOCX that is only rendered at step 7), all 55 skills made routable from the single entry point with a CI reachability gate, and a README plugin-count that had drifted from the marketplace SSOT (now gated). No skill/detector change.
 
 **v5.20** — reviewer-arithmetic gates. Five deterministic `self-review` detectors promoted from a peer-review cycle, each recomputing what a manuscript already prints: `check_table_percentages` (an `n (%)` cell vs its column denominator), `check_nested_group_comparison` (a P value comparing an analysed subset against the parent cohort that **contains** it — nested, invalid), `check_reported_p_from_counts` (rebuilds each 2×2 row and recomputes Fisher / Pearson χ² ± Yates in **pure stdlib**, calibrating the family on rows that reproduce), `check_dta_denominators` (sensitivity/specificity denominators vs the reference-standard category counts, behind a matching grand total), and `check_paired_difference_estimator` (an odd-n integer-scale median cannot be non-integer; a zero-width CI; an unnamed estimator). Plus `/peer-review` request-type discipline (disclosure vs computation) and impossibility-claim verification. Additive and backward-compatible; **55 skills / 46 guidelines / 57 integrity detectors / 22 domain-probe modules**. (See the [CHANGELOG](CHANGELOG.md) for v5.0–v5.19.)
@@ -714,9 +716,33 @@ Prints a checklist showing which components are present, which are missing, and
 
 ## Requirements
 
+**Python 3.9+ and an agent host. That is the whole hard requirement.** Every integrity detector is
+stdlib-only, and so is drafting, reviewing, and auditing a manuscript. If you have no Python, the
+double-click installer will offer to install it for you (`winget` on Windows, or the official
+download page) rather than leaving you at a dead end.
+
 - An [Agent Skills](https://agentskills.io)-compatible host — [Claude Code](https://claude.ai/code) (primary), or Codex / Cursor / GitHub Copilot (see [`docs/host_compatibility.md`](docs/host_compatibility.md); some live-data workflows rely on Claude MCP servers)
-- Python 3.9+ (for statistical analysis and figure generation)
-- R 4.0+ with `meta` (>=7.0), `metafor` (>=4.0), `mada` (>=0.5.11) packages (for meta-analysis)
+- Python 3.9+ — the floor is CI-enforced (`scripts/check_python_floor.py`). Newer is better; if you are installing Python today, take the latest.
+
+Everything else is needed by *some* skills and not others. Rather than a shopping list of packages
+you have never heard of, ask the toolkit what **this** computer can do:
+
+```bash
+python3 installers/doctor.py          # what works, what does not, and the exact fix for each
+python3 installers/doctor.py --fix    # offers to install what is missing — asking before each one
+```
+(Or double-click `installers/check-setup-macos.command` / `installers/check-setup-windows.cmd`.)
+
+It reports in terms of what you were trying to *do* — "turn your manuscript into a journal-formatted
+Word file" needs **pandoc**; "read and QC submission PDFs" needs **poppler**; "open a .docx at all"
+needs **python-docx** — and installs the small things on request. Large things (a TeX distribution,
+R, PyTorch) are never installed for you: it prints the size and the command and leaves the choice
+alone.
+
+**R is not required.** `/analyze-stats` writes Python by default and only emits R if you ask it to;
+the toolkit itself never executes R. Install R (with `meta`, `metafor`, `mada` for meta-analysis)
+only if you want to run the R code it writes for you. The same is true of PyTorch and
+`/model-scaffold`: writing the training code needs nothing; running it needs torch.
 
 ## Use Cases
 
@@ -786,8 +812,32 @@ Or equivalently: `/write-paper --autonomous` if analysis and figures already exi
 
 ## Contributing
 
-Contributions are welcome — and most are **one small, self-contained file** that a
-template walks you through. You do not need to understand the whole pipeline to add value.
+**If you have already changed something on your own machine, `/contribute` will send it for you.**
+Most people who use this are clinicians, not git users: they add the journal they publish in, fix a
+checklist item that was wrong for their specialty, adapt a skill to their department — and the
+change dies on one laptop.
+
+```
+/contribute
+```
+
+It compares your installed skills against what was shipped, tells you exactly what you changed,
+**scans it for patient data, hospital names, IRB numbers and manuscript IDs** (that scan blocks, and
+it is the reason this is a skill and not a button), shows you every line that would leave your
+machine, and only then opens the pull request — you never type a git command. No GitHub CLI? It
+reaches the project as an issue instead.
+
+The same skill files a **false positive** ("this flagged my paper and it was wrong") or a failed
+step. That is not a lesser contribution: it is the only evidence anyone has of how a detector
+behaves on a real manuscript rather than a synthetic fixture.
+
+**You will not be nagged.** Reminders are off by default; the installer mentions the option once
+and then never again. `/contribute` only ever runs when you run it.
+
+---
+
+Contributions are also welcome the ordinary way — and most are **one small, self-contained file**
+that a template walks you through. You do not need to understand the whole pipeline to add value.
 Pick a [**good first issue**](https://github.com/Aperivue/medsci-skills/contribute), or start
 from one of these:
 
@@ -823,6 +873,24 @@ Community members who have reported, verified, or shaped the project are credite
 
 ## In the Wild
 
+### Cited in the literature
+
+**Chen, Wang & Qu (2026), *Recursive Self-Improvement in AI*** — [arXiv:2607.07663](https://arxiv.org/abs/2607.07663), a
+survey of **1,250 papers** — cites this project's methods paper
+([arXiv:2606.09500](https://arxiv.org/abs/2606.09500)) twice, as the reference for what fails when an AI
+audits its own scientific output, and names the approach taken here as the response:
+
+> "In regulated domains, **deterministic integrity gates are interposed** because 'self-critique
+> inherits the blind spots that produce confident fabrication'."
+> — §6.3 (quoting the methods paper; also cited in §5.3, on the self-confirming loop)
+
+That is the argument this repository is built on: a model asked to check its own work inherits the
+blind spots that produced the error, and a script that **recomputes** the number does not.
+
+Every citation we know of is logged in [`docs/citations.md`](docs/citations.md).
+
+### Adoption
+
 Adoption is tracked openly in [`IMPACT.md`](IMPACT.md) (stars, forks, traffic,
 release downloads — snapshotted weekly into [`metrics/traffic_log.csv`](metrics/traffic_log.csv))
 and academic use is logged in [`docs/citations.md`](docs/citations.md).

package/installers/install-macos.command

@@ -1,4 +1,16 @@
 #!/usr/bin/env bash
+# MedSci Skills — double-click installer for macOS.
+#
+# The person running this is a clinician who double-clicked a file. Every failure must end in a
+# sentence they can act on — never a Python traceback, and never a silent "done" that installed
+# nothing. Two things had to change for that to be true:
+#
+#   * `python` is not necessarily Python 3. Handing the installer to whatever `command -v python`
+#     finds could hand it to a Python 2 that dies on the first f-string.
+#   * Python 3.8 is worse than Python 2, not better: install.py *parses* there, so instead of a
+#     clean "wrong version" it dies halfway through with a wall of traceback.
+#
+# So the interpreter is checked for a real version BEFORE anything runs.
 set -u
 
 cd "$(dirname "$0")/.."
@@ -6,23 +18,82 @@ cd "$(dirname "$0")/.."
 echo "MedSci Skills Installer for macOS"
 echo
 
+MIN_MAJOR=3
+MIN_MINOR=9
+
+usable() {  # true only if $1 is really Python >= 3.9
+  command -v "$1" >/dev/null 2>&1 || return 1
+  "$1" -c "import sys; raise SystemExit(0 if sys.version_info >= ($MIN_MAJOR, $MIN_MINOR) else 1)" \
+    >/dev/null 2>&1
+}
+
 PY=""
-if command -v python3 >/dev/null 2>&1; then
-  PY=python3
-elif command -v python >/dev/null 2>&1; then
-  PY=python
+for candidate in python3 python; do
+  if usable "$candidate"; then
+    PY="$candidate"
+    break
+  fi
+done
+
+if [ -z "$PY" ]; then
+  # "No Python" and "too old a Python" need different actions, and a clinician cannot be expected
+  # to work out which one they have from a version string.
+  if command -v python3 >/dev/null 2>&1 || command -v python >/dev/null 2>&1; then
+    # No pipe to `head` — an installer must not depend on tools that may not be on PATH in a
+    # stripped-down environment. `python --version` prints one line anyway.
+    FOUND="$( python3 --version 2>/dev/null || python --version 2>/dev/null )"
+    echo "The Python on this Mac is too old for MedSci Skills."
+    echo "  Found:  ${FOUND:-an older version}"
+    echo "  Needed: Python ${MIN_MAJOR}.${MIN_MINOR} or newer"
+  else
+    echo "Python was not found on this Mac."
+  fi
+  echo
+  echo "MedSci Skills is written in Python, so Python has to be on the computer first."
+  echo "It is free, official, and takes about two minutes."
+  echo
+  echo "  1. Download the latest Python for macOS  (the page opens by itself in a moment)"
+  echo "  2. Open the file you downloaded and click through the installer"
+  echo "  3. Double-click THIS installer again"
+  echo
+  echo "Nothing has been changed on your computer."
+  echo
+
+  # Open the page for them. Telling a clinician to "go to python.org" is a step they have to
+  # perform; opening it is a step they do not. `open` is standard on macOS, but never let a
+  # convenience break the message they still need to read.
+  if command -v open >/dev/null 2>&1; then
+    read -r -p "Press Enter to open the Python download page..."
+    open "https://www.python.org/downloads/" >/dev/null 2>&1 || \
+      echo "Could not open the page. It is at:  https://www.python.org/downloads/"
+  else
+    echo "The download page is at:  https://www.python.org/downloads/"
+  fi
+
+  echo
+  read -r -p "Press Enter to close..."
+  exit 1
 fi
 
-if [ -n "$PY" ]; then
-  "$PY" installers/install.py --target all --desktop-launcher
-  # Turn on the in-app "update available" reminder for this turnkey install so you are told when a
-  # new version is out (no terminal needed afterward). Best-effort; turn off later with
-  # `install.py --disable-update-notify` or MEDSCI_NO_UPDATE_CHECK=1.
-  "$PY" installers/install.py --enable-update-notify || true
-else
-  echo "Python was not found."
-  echo "Install Python 3 from https://www.python.org/downloads/ and run this installer again."
+"$PY" installers/install.py --target all --desktop-launcher
+STATUS=$?
+
+if [ "$STATUS" -ne 0 ]; then
+  echo
+  echo "The installation did not finish (it stopped with error $STATUS)."
+  echo "Nothing was left half-installed — the installer undoes its own work if it cannot complete."
+  echo
+  echo "If you tell us what the message above said, we can fix it:"
+  echo "  https://github.com/Aperivue/medsci-skills/issues/new"
+  echo
+  read -r -p "Press Enter to close..."
+  exit "$STATUS"
 fi
 
+# Turn on the in-app "update available" reminder for this turnkey install, so you are told when a
+# new version ships instead of staying on this one forever. Best-effort: a failure here is not a
+# failed install. Turn it off later with `install.py --disable-update-notify`.
+"$PY" installers/install.py --enable-update-notify >/dev/null 2>&1 || true
+
 echo
 read -r -p "Press Enter to close..."

package/installers/install-windows.cmd

@@ -1,30 +1,112 @@
 @echo off
-setlocal
+rem MedSci Skills - double-click installer for Windows.
+rem
+rem Windows is where most of these downloads go, and it has a trap the old script fell into.
+rem
+rem   THE MICROSOFT STORE STUB. On a Windows machine with no Python, `python` still EXISTS: it is an
+rem   App Execution Alias that opens the Microsoft Store. So `where python` succeeds, errorlevel is
+rem   0, the script cheerfully runs it -- and a Store page opens, nothing is installed, and the
+rem   installer reports it is done. The clinician is told everything worked and has nothing.
+rem
+rem   A TOO-OLD PYTHON. install.py PARSES on 3.8, so it does not fail cleanly: it dies partway
+rem   through with a traceback instead of saying "wrong version".
+rem
+rem So an interpreter is only accepted after it proves, BY RUNNING, that it is Python 3.9 or newer.
+rem Asking `where` only proves a name exists.
+setlocal EnableDelayedExpansion
 cd /d "%~dp0\.."
 
 echo MedSci Skills Installer for Windows
 echo.
 
-where py >nul 2>nul
-if %errorlevel%==0 (
-  py -3 installers\install.py --target all --desktop-launcher
-  rem Turn on the in-app "update available" reminder for this turnkey install (disable later with --disable-update-notify).
-  py -3 installers\install.py --enable-update-notify
-  goto done
+set "PY="
+
+rem The py launcher is the reliable path when it exists.
+py -3 -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)" >nul 2>nul
+if !errorlevel!==0 set "PY=py -3"
+
+rem Fall back to `python` -- but only if it actually runs. The Store stub fails this test, which is
+rem the entire reason for testing instead of asking `where`.
+if not defined PY (
+  python -c "import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)" >nul 2>nul
+  if !errorlevel!==0 set "PY=python"
 )
 
-where python >nul 2>nul
-if %errorlevel%==0 (
-  python installers\install.py --target all --desktop-launcher
-  rem Turn on the in-app "update available" reminder for this turnkey install (disable later with --disable-update-notify).
-  python installers\install.py --enable-update-notify
-  goto done
+if not defined PY (
+  echo Python 3.9 or newer was not found on this computer.
+  echo.
+  echo MedSci Skills is written in Python, so Python has to be installed first.
+  echo It is free, official, and takes a couple of minutes.
+  echo.
+
+  rem winget ships with Windows 10 ^(1809+^) and Windows 11, so on most hospital machines Python can
+  rem simply be installed for the user -- no admin rights, no download page, no PATH checkbox to
+  rem miss. We ASK first: installing software on someone's computer without asking is not ours to do.
+  where winget >nul 2>nul
+  if !errorlevel!==0 (
+    echo This installer can install Python for you now, from the official Python
+    echo repository, into your own user account ^(no administrator password needed^).
+    echo.
+    set /p "DOIT=Install Python now? [Y/N] "
+    if /i "!DOIT!"=="Y" (
+      echo.
+      echo Installing Python. This takes a couple of minutes...
+      echo.
+      winget install --exact --id Python.Python.3.13 --scope user ^
+        --accept-source-agreements --accept-package-agreements
+      echo.
+      if !errorlevel!==0 (
+        echo Python is installed.
+        echo.
+        echo Windows only notices a new program in NEW windows, so this one cannot use it yet:
+        echo.
+        echo    ^>^>  Close this window and double-click the installer again.  ^<^<
+        echo.
+        echo Nothing else has been changed on your computer.
+        echo.
+        pause
+        exit /b 1
+      )
+      echo Python could not be installed automatically ^(error !errorlevel!^).
+      echo Use the download page instead - it is opening now.
+      echo.
+    )
+  )
+
+  echo   1. Download the latest Python for Windows ^(the page opens by itself in a moment^)
+  echo   2. Run the file you downloaded.
+  echo      IMPORTANT: on the FIRST screen, tick the box "Add python.exe to PATH"
+  echo      before pressing Install. It is easy to miss, and nothing works without it.
+  echo   3. Double-click THIS installer again.
+  echo.
+  echo If a Microsoft Store page opened when you tried Python before, that page is a
+  echo placeholder, not Python. Use python.org instead.
+  echo.
+  echo Nothing has been changed on your computer.
+  echo.
+  start "" "https://www.python.org/downloads/"
+  pause
+  exit /b 1
 )
 
-echo Python was not found.
-echo Please install Python 3 from https://www.python.org/downloads/ and run this installer again.
-echo.
+%PY% installers\install.py --target all --desktop-launcher
+if not !errorlevel!==0 (
+  set "RC=!errorlevel!"
+  echo.
+  echo The installation did not finish ^(it stopped with error !RC!^).
+  echo Nothing was left half-installed - the installer undoes its own work if it cannot complete.
+  echo.
+  echo If you tell us what the message above said, we can fix it:
+  echo   https://github.com/Aperivue/medsci-skills/issues/new
+  echo.
+  pause
+  exit /b !RC!
+)
+
+rem Turn on the in-app "update available" reminder for this turnkey install, so you are told when a
+rem new version ships instead of staying on this one forever. Best-effort: a failure here is not a
+rem failed install.
+%PY% installers\install.py --enable-update-notify >nul 2>nul
 
-:done
 echo.
 pause

package/installers/install.py

@@ -15,6 +15,20 @@ import os
 import sys
 from pathlib import Path
 
+# The floor the README promises. Checked here as well as in the double-click installers, because
+# the failure it prevents is a clinician staring at a Python traceback: on 3.8 this file *parses*
+# (so there is no clean syntax error to explain itself) and then dies somewhere in the middle,
+# leaving a half-explained wall of text and no idea what to do next.
+MIN_PYTHON = (3, 9)
+if sys.version_info < MIN_PYTHON:
+    have = ".".join(str(n) for n in sys.version_info[:3])
+    sys.exit(
+        f"\nMedSci Skills needs Python {MIN_PYTHON[0]}.{MIN_PYTHON[1]} or newer. This computer has {have}.\n\n"
+        "  Install the latest Python from  https://www.python.org/downloads/\n"
+        "  then run this installer again.\n\n"
+        "Nothing has been changed on your computer.\n"
+    )
+
 sys.path.insert(0, str(Path(__file__).resolve().parent))  # allow `import medsci_txn` when run as a script
 import medsci_txn  # noqa: E402
 
@@ -231,6 +245,47 @@ def parse_args() -> argparse.Namespace:
     return parser.parse_args()
 
 
+
+def _offer_contribution_reminders_once(log_lines) -> None:
+    """Mention — once, ever — that the option exists. Then never again, whatever they do.
+
+    A person who ignores the question has answered it. Asking a second time would be the exact
+    nagging this setting exists to prevent, so `asked_once` is recorded whether or not they act.
+    """
+    import json as _json
+    home = medsci_txn.state_home()
+    cfg_path = home / "config.json"
+    try:
+        cfg = _json.loads(cfg_path.read_text(encoding="utf-8")) if cfg_path.is_file() else {}
+    except (ValueError, OSError):
+        cfg = {}
+    if cfg.get("asked_once"):
+        return
+
+    log(
+        "\nTwo things, once — then we will not bring either up again:\n"
+        "\n"
+        "  1. If you ever adapt a skill (add your journal, fix something wrong for your specialty),\n"
+        "     that change can be offered back with /contribute. Reminders are OFF by default, and\n"
+        "     nothing is ever sent without a patient-data scan and your confirmation on every line.\n"
+        "         python3 ~/.claude/skills/contribute/scripts/contribution_prefs.py --on\n"
+        "\n"
+        "  2. If this ends up saving you time, the way to say so is a star on the repository.\n"
+        "     Not applause — it is how the next researcher with your problem finds it, and for\n"
+        "     software with no DOI in anyone's reference list it is the closest thing to a citation.\n"
+        "     Most people who write to say thanks have never done it, because nobody told them.\n"
+        "     One command, no browser:\n"
+        "         python3 ~/.claude/skills/contribute/scripts/star_repo.py --now\n"
+        "     (or one click: https://github.com/Aperivue/medsci-skills)",
+        log_lines,
+    )
+    cfg["asked_once"] = True
+    try:
+        cfg_path.parent.mkdir(parents=True, exist_ok=True)
+        medsci_txn.atomic_write_json(cfg_path, cfg)
+    except OSError:
+        pass  # never fail an install over a preference file
+
 def main() -> int:
     args = parse_args()
     if args.self_test:
@@ -319,6 +374,23 @@ def main() -> int:
         print(f"\nInstall log: {log_path}")
         return 1
 
+    # Say what ELSE this computer needs, while they are still looking at the screen.
+    #
+    # Every integrity detector is stdlib-only, so the install above is enough to use most of the
+    # toolkit. But a few skills need a program we do not ship — pandoc to render a manuscript into
+    # a journal-formatted Word file, poppler to read a submission PDF. Those skills already fail
+    # politely; the problem is that they fail *later*, in the middle of the work, to someone who
+    # will not go and install a package manager at that moment. Tell them now, when the answer is
+    # one command. Read-only, asks nothing, installs nothing, and can never fail the install.
+    if not args.dry_run:
+        try:
+            import doctor  # noqa: PLC0415
+
+            doctor.brief_summary(lambda m: log(m, log_lines))
+        except Exception:  # noqa: BLE001 - a setup *check* must never break an install that worked
+            pass
+
+    _offer_contribution_reminders_once(log_lines)
     log("\nDone. Restart Claude Code, Codex, or Cursor before testing the skills.", log_lines)
     log("First test prompt:", log_lines)
     log("MedSci Skills가 설치됐는지 확인하고, 오늘 실습에 쓸 대표 스킬 5개만 보여줘.", log_lines)

package/installers/medsci_txn.py

@@ -38,6 +38,7 @@ so staging + holding dirs are kept on the destination's filesystem.
 
 from __future__ import annotations
 
+import datetime
 import hashlib
 import json
 import os
@@ -144,6 +145,50 @@ def permanent_backup(skill_path: Path, target: str, home: Path, reason: str, log
     return dest
 
 
+
+# ------------------------------------------------------- contribution reminders (opt-in, off)
+
+def _contrib_config(home: Path) -> Path:
+    return home / "config.json"
+
+
+def _contribution_reminder_wanted(home: Path) -> bool:
+    """Off unless the user explicitly asked to be reminded, and then at most monthly.
+
+    An installer that nags is an installer people stop running, and this audience already
+    under-updates. Defaulting to silence costs a few contributions; defaulting to noise costs
+    the update path itself.
+    """
+    p = _contrib_config(home)
+    if not p.is_file():
+        return False
+    try:
+        cfg = json.loads(p.read_text(encoding="utf-8"))
+    except (ValueError, OSError):
+        return False
+    if cfg.get("contribution_reminders") != "on":
+        return False
+    last = cfg.get("last_reminded")
+    if not last:
+        return True
+    try:
+        y, m, d = (int(x) for x in str(last).split("-"))
+        return (datetime.date.today() - datetime.date(y, m, d)).days >= 30
+    except (ValueError, TypeError):
+        return True
+
+
+def _mark_reminded(home: Path) -> None:
+    p = _contrib_config(home)
+    try:
+        cfg = json.loads(p.read_text(encoding="utf-8")) if p.is_file() else {}
+        cfg["last_reminded"] = datetime.date.today().isoformat()
+        p.parent.mkdir(parents=True, exist_ok=True)
+        atomic_write_json(p, cfg)
+    except OSError:
+        pass  # a reminder is not worth failing an install over
+
+
 # ---------------------------------------------------------------- recovery
 
 def recover_target(target: str, home: Path, log) -> bool:
@@ -256,6 +301,25 @@ def install_target(
             else:
                 permanent_backup(d, target, home, "legacy-collision", log)
 
+    # A user-modified skill is usually a clinician adapting the toolkit to their journal, their
+    # specialty, their department. The backup preserves it; nothing ever read the backup again.
+    #
+    # But the person who installed a research tool did not sign up to be asked for things, and a
+    # physician finishing a paper does not need a lecture on open-source etiquette from their
+    # installer. So this is OPT-IN and OFF BY DEFAULT: we say nothing unless they asked to be
+    # told, and even then not more than once a month. Silence is the default, and it is correct.
+    modified = [
+        name for name in owned_skills
+        if (dest / name).exists()
+        and name in prior_skills
+        and skill_inventory(dest / name) != prior_skills[name].get("inventory", {})
+    ]
+    if modified and _contribution_reminder_wanted(home):
+        log(f"  You had changed {len(modified)} skill(s): {', '.join(sorted(modified))}. Your version")
+        log("  is backed up (above); if the change is worth keeping, /contribute will offer it back")
+        log("  to the project — patient-data scan first, nothing sent without your confirmation.")
+        _mark_reminded(home)
+
     prune = [n for n in prior_skills if n not in set(owned_skills)]
     for name in prune:  # a removed/renamed owned skill: back up before pruning, then remove in txn
         d = dest / name