docs: sync v2.10 public surface and promotion prep (#25)

Yoojin-nam · web-flow · commit b855b48d0872 · 2026-05-23T15:46:31.000+09:00
* chore(meta-analysis): generalize MA references and blocklist MA0 ids

* docs(readme,changelog,citation): sync v2.10 public surface

* docs(promo,joss): add promotion plan and JOSS prep
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,28 @@
 # Changelog
 
+## [3.1.0] - 2026-05-23
+
+### Added — v2.10 cycle integration
+
+- `/peer-review`: Phase 2A SR-MA 8-probe extension (P1-P8) for systematic review meta-analyses (PR #22).
+- `/verify-refs`: Gate 5 PMID/DOI duplicate detection; `submission_safe` / `fully_verified` synchronous propagation (PR #23).
+- `/meta-analysis`: SR-MA dual-extractor workflow, cohort overlap detection, and supplementary 8-file pack (PR #24).
+
+### Changed
+
+- Validator scope extended to `templates/` and `scripts/` for permanent PII blocklist enforcement.
+- `setup-medsci` skill now reflected in the public skill roster so filesystem, README, and external mirrors can align at 40 skills.
+- `README.md` refreshed with v2.10 public-surface highlights and 40-skill badge/text sync.
+
+### Hygiene
+
+- Generalized legacy non-hyphenated MA project codes in `skills/meta-analysis/SKILL.md`.
+- Added the non-hyphenated MA project-code family to the validator blocklist.
+
+### Stats
+
+- 40 skills (was 39); Zenodo concept DOI `10.5281/zenodo.20155321` preserved.
+
 ## [3.0.1] - 2026-05-13
 
 ### Added — first Zenodo-archived release with DOI
diff --git a/CITATION.cff b/CITATION.cff
@@ -19,14 +19,14 @@ authors:
 repository-code: "https://github.com/Aperivue/medsci-skills"
 url: "https://github.com/Aperivue/medsci-skills"
 license: MIT
-version: "3.0.1"
-date-released: "2026-05-13"
+version: "3.1.0"
+date-released: "2026-05-23"
 doi: "10.5281/zenodo.20155321"
 identifiers:
   - description: "Concept DOI (always points to the latest version)"
     type: doi
     value: "10.5281/zenodo.20155321"
-  - description: "Versioned DOI for v3.0.1"
+  - description: "Previous archived release DOI (v3.0.1)"
     type: doi
     value: "10.5281/zenodo.20155322"
 keywords:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,65 @@
+# Contributing to MedSci Skills
+
+Thank you for helping make medical research workflows more reproducible and less brittle. Contributions are welcome through GitHub issues and pull requests.
+
+## What to Contribute
+
+- New skills for recurring medical research workflows.
+- Improvements to existing skill routing, anti-hallucination checks, or quality gates.
+- Deterministic scripts for checks that should not rely on language-model judgment.
+- Public demo improvements using open or synthetic datasets.
+- Documentation that helps clinicians install, test, or safely adapt the skills.
+
+## Skill Addition Workflow
+
+1. Open an issue describing the workflow, target users, expected artifacts, and safety boundaries.
+2. Add a skill under `skills/<skill-name>/` with a `SKILL.md` file.
+3. Include `skill.yml` when the skill has stable inputs, outputs, downstream consumers, or deterministic scripts.
+4. Keep examples public and anonymized. Use synthetic or public datasets whenever possible.
+5. Add focused tests or validation scripts for deterministic behavior.
+6. Run the repository validators before opening a pull request.
+
+## Pull Request Checklist
+
+- [ ] `bash scripts/validate_skills.sh`
+- [ ] `python3 scripts/validate_skill_contracts.py`
+- [ ] No private project identifiers, manuscript IDs, collaborator names, patient-level examples, or institution-specific hidden context.
+- [ ] No personal absolute paths.
+- [ ] New scripts have a short usage example and deterministic expected behavior.
+- [ ] Documentation states when the skill should not be used.
+- [ ] Public-facing copy is suitable for an open-source repository.
+
+## PII and Publication Hygiene
+
+MedSci Skills is public. Do not include:
+
+- Private manuscript IDs or study-folder names.
+- Unpublished project codes.
+- Real collaborator names in examples.
+- Patient-level clinical vignettes.
+- Screenshots or document metadata with hidden author names.
+- Private emails, home-directory paths, or local institution-only paths.
+
+The validator blocklist is intentionally conservative. If it catches a false positive, explain the case in the pull request rather than bypassing the check silently.
+
+## Code Style
+
+- Prefer small, reviewable changes.
+- Use deterministic scripts for count checks, citation checks, file manifests, and package audits.
+- Keep skill prose procedural and testable.
+- Avoid adding broad orchestration behavior when a narrow skill-level check is enough.
+
+## Review Process
+
+Maintainers may ask for:
+
+- A smaller PR split.
+- More explicit safety boundaries.
+- A public demo or synthetic test case.
+- Stronger validator coverage before merge.
+
+For JOSS readiness, contributions should strengthen open-source practice signals: public issues, pull requests, tests, CI, documentation, release notes, and clear contribution pathways.
+
+## Code of Conduct
+
+Until a repository-specific `CODE_OF_CONDUCT.md` is added, contributors are expected to follow the Contributor Covenant principles: https://www.contributor-covenant.org/
diff --git a/PROMO_PLAN.md b/PROMO_PLAN.md
@@ -0,0 +1,150 @@
+# MedSci Skills Promotion Plan
+
+Status date: 2026-05-23
+
+## Current Snapshot
+
+- GitHub: 105 stars, 30 forks, 9 open issues.
+- Traffic window: 2026-05-08 to 2026-05-21.
+- Views: 2,489 total / 844 unique.
+- Clones: 3,227 total / 456 unique.
+- Top referrers: Threads 402, GitHub 325, Google 288, Reddit 126, ChatGPT 58, Aperivue 28.
+- Current public surface: 40 skills, three public end-to-end demos, Zenodo concept DOI `10.5281/zenodo.20155321`.
+
+## Tier 1: Community Visibility
+
+### Awesome Lists
+
+`awesome-claude-code`: no existing medsci-skills PR found in the checked search. Do not create a PR in this cycle. Next cycle task: re-check the maintainer policy, then submit a small one-line addition with the DOI and demo links.
+
+Candidate lists to inspect before outreach:
+
+| Candidate | URL | Likely route | Fit |
+|---|---|---|---|
+| Awesome Claude | https://github.com/ai-for-developers/awesome-claude | Pull request titled `Add: MedSci Skills` | Good fit for Claude/agent-skill ecosystem visibility. |
+| Awesome LLM Apps | https://github.com/Shubhamsaboo/awesome-llm-apps | Issue or pull request after checking contribution conventions | Possible fit only if framed as runnable research workflow templates, not a generic link. |
+| Awesome Healthcare AI | https://github.com/medtorch/awesome-healthcare-ai | Pull request to relevant tools/resources section | Good medical AI audience fit; emphasize research workflow and reporting compliance. |
+| Awesome AI for Science | https://github.com/ai-boost/awesome-ai-for-science | Pull request to research workbench or medical AI section | Good science-tooling fit; keep entry concise and evidence-backed. |
+
+### Reddit Draft Outlines
+
+PII policy: no manuscript IDs, no unpublished study names, no author names, no project-specific identifiers, and no PMID lists in post bodies or comments. Run the PII gate before posting.
+
+#### r/ClaudeAI
+
+Title: `I built 40 Claude Code skills for medical research workflows, with public demos and validators`
+
+Body outline:
+
+- One-sentence problem: medical research work involves many brittle handoffs from literature search to manuscript and submission.
+- What is shipped: 40 Claude Code skills, three public demo pipelines, validator checks, citation/DOI metadata.
+- Why Claude-specific: skills package repeatable procedures, guardrails, and routing patterns rather than one-off prompts.
+- Invite feedback on install friction, skill structure, and missing workflows.
+
+First comment:
+
+```text
+Repo: https://github.com/Aperivue/medsci-skills
+DOI: https://doi.org/10.5281/zenodo.20155321
+Best starting points: README demos, /setup-medsci, /verify-refs, /meta-analysis, /check-reporting.
+```
+
+#### r/medicalAI
+
+Title: `Open-source medical research workflow skills: references, reporting checks, meta-analysis, and submission hygiene`
+
+Body outline:
+
+- Lead with safety/hygiene: citation checks, reporting guideline checks, PII guard, public datasets only in demos.
+- Show the clinical research workflow: literature search, full-text retrieval, study design, statistics, figures, manuscript, reporting, revision.
+- Ask for feedback on reporting-guideline coverage and external validation expectations.
+
+First comment:
+
+```text
+The demos use public/sample datasets only. I am especially looking for feedback on whether the validator and reporting-check surfaces are useful enough for independent reuse.
+```
+
+#### r/medicine
+
+Title: `I open-sourced a physician-built toolkit for making research manuscripts less brittle`
+
+Body outline:
+
+- Avoid AI hype; frame as workflow documentation and QC automation.
+- Mention that it is not clinical decision support and does not process patient data in demos.
+- Ask for practical feedback from clinicians who write or review manuscripts.
+
+First comment:
+
+```text
+This is aimed at research workflow hygiene, not patient care. The most useful criticism would be: what would make this trustworthy enough to try on a low-risk manuscript draft?
+```
+
+### Hacker News
+
+Candidate title: `Show HN: MedSci Skills, Claude Code workflows for medical research manuscripts`
+
+Timing: weekday morning Pacific Time. Post only after the README/Aperivue sync is live and the repo has no known PII hygiene blockers.
+
+## Tier 3: JOSS Submission Prep
+
+JOSS is a good medium-term target, but the current cycle should stop at prep. The refreshed 2026 criteria emphasize:
+
+- 750-1750 word paper with required sections.
+- Evidence of research impact or credible near-term significance.
+- Six months of public development history before submission.
+- Open-source practice signals: tests, CI, releases, changelog, documentation, contribution pathway.
+- Transparent AI usage disclosure.
+
+This cycle adds `paper.md`, `paper.bib`, and `CONTRIBUTING.md`. Do not submit to JOSS without a user confirmation pass and a fresh criteria check.
+
+### Pre-submission Checklist
+
+- [x] MIT `LICENSE`.
+- [x] `CITATION.cff` refreshed for v3.1.0 date/version.
+- [x] Zenodo concept DOI `10.5281/zenodo.20155321`.
+- [x] README, skill documentation, and three public demos.
+- [x] Validator and contract checks in repository scripts/CI.
+- [x] `CONTRIBUTING.md` added in this cycle.
+- [x] `paper.md` outline and `paper.bib` seed references added in this cycle.
+- [ ] Fresh public-history check: JOSS currently expects more than six months of public development history before submission.
+- [ ] Concrete external adoption/reuse evidence for the research impact statement.
+- [ ] Fresh JOSS criteria review immediately before submission.
+
+## Tier 2: Deferred
+
+- Society newsletter outreach.
+- X/Threads mention strategy beyond current organic traffic.
+- Aperivue blog post.
+- Main page redesign.
+
+## External Maintainer Follow-up Drafts
+
+### OpenClaw Issue #31
+
+Status: opened 2026-05-13; 10 days elapsed as of 2026-05-23; no comments observed in the working plan. Re-ping threshold: 2026-06-12, or earlier only with explicit user approval.
+
+Draft:
+
+```text
+Hi, quick follow-up on this. MedSci Skills has now added the v2.10 public hygiene updates: 40-skill roster sync, expanded PII validator coverage, and refreshed meta-analysis/reference-checking surfaces. If this still fits OpenClaw's scope, I would be happy to adjust the entry format or split the medical-research workflow pieces into a narrower listing.
+```
+
+### PR #18
+
+Action remains separate from this PR. Close only after explicit user confirmation:
+
+```text
+Superseded by #23 -- v1.2.0 full-author cross-check + PubMed efetch authoritative path merged via PR #23 (2026-05-19). Closing this branch.
+```
+
+## PII Gate
+
+Before any external post, PR body, issue comment, or commit message:
+
+```bash
+bash scripts/validate_skills.sh
+```
+
+Also run the publication guard in `~/.claude/rules/oss-publication-pii-guard.md` if available. External copy must have zero manuscript IDs, unpublished project IDs, real collaborator names, patient-level examples, or PMID lists. Keep raw blocklist patterns in validator code only, not in promotional copy.
diff --git a/README.md b/README.md
@@ -2,10 +2,10 @@
 
 # MedSci Skills
 
-**39 skills that actually work.** Built by a physician-researcher, tested on real publications.
+**40 skills that actually work.** Built by a physician-researcher, tested on real publications.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-![Skills](https://img.shields.io/badge/Skills-39-brightgreen?style=flat-square)
+![Skills](https://img.shields.io/badge/Skills-40-brightgreen?style=flat-square)
 ![Platform](https://img.shields.io/badge/Platform-Claude_Code-blueviolet?style=flat-square)
 ![Built by](https://img.shields.io/badge/Built_by-Physician--Researcher-blue?style=flat-square)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20155321.svg)](https://doi.org/10.5281/zenodo.20155321)
@@ -21,6 +21,17 @@
 
 ---
 
+## What's New
+
+The v2.10 cycle expands the public workflow surface while tightening release hygiene:
+
+- `/peer-review` v2.10 adds the Phase 2A SR-MA 8-probe extension (P1-P8) for systematic review meta-analyses (PR #22).
+- `/verify-refs` v1.2.0 adds Gate 5 PMID/DOI duplicate detection plus synchronous `submission_safe` / `fully_verified` propagation (PR #23).
+- `/meta-analysis` adds SR-MA dual-extractor workflow support, cohort overlap detection, and a supplementary 8-file pack (PR #24).
+- Validator coverage now enforces the PII blocklist across `templates/` and `scripts/` as well as skill documentation.
+
+---
+
 ## Live Demos: Three Study Types, Three Full Pipelines
 
 Three public datasets. Three study types. Each produces a complete manuscript, publication-ready figures, reporting compliance audit, and presentation slides.
diff --git a/paper.bib b/paper.bib
@@ -0,0 +1,84 @@
+@misc{anthropic_claude_code,
+  author = {{Anthropic}},
+  title = {{Claude Code Documentation}},
+  year = {2026},
+  url = {https://docs.anthropic.com/en/docs/claude-code},
+  note = {Accessed 2026-05-23}
+}
+
+@misc{model_context_protocol,
+  author = {{Model Context Protocol Contributors}},
+  title = {{Model Context Protocol}},
+  year = {2026},
+  url = {https://modelcontextprotocol.io/},
+  note = {Accessed 2026-05-23}
+}
+
+@article{page2021prisma,
+  author = {Page, Matthew J. and McKenzie, Joanne E. and Bossuyt, Patrick M. and Boutron, Isabelle and Hoffmann, Tammy C. and Mulrow, Cynthia D. and Shamseer, Larissa and Tetzlaff, Jennifer M. and Akl, Elie A. and Brennan, Sue E. and Chou, Roger and Glanville, Julie and Grimshaw, Jeremy M. and Hr{\\'{o}}bjartsson, Asbj{\\o}rn and Lalu, Manoj M. and Li, Tianjing and Loder, Elizabeth W. and Mayo-Wilson, Evan and McDonald, Steve and McGuinness, Luke A. and Stewart, Lesley A. and Thomas, James and Tricco, Andrea C. and Welch, Vivian A. and Whiting, Penny and Moher, David},
+  title = {The PRISMA 2020 statement: an updated guideline for reporting systematic reviews},
+  journal = {BMJ},
+  year = {2021},
+  volume = {372},
+  pages = {n71},
+  doi = {10.1136/bmj.n71}
+}
+
+@article{bossuyt2015stard,
+  author = {Bossuyt, Patrick M. and Reitsma, Johannes B. and Bruns, David E. and Gatsonis, Constantine A. and Glasziou, Paul P. and Irwig, Les M. and Lijmer, Jeroen G. and Moher, David and Rennie, Drummond and de Vet, Henrica C. W. and Kressel, Herbert Y. and Rifai, Nader and Golub, Robert M. and Altman, Douglas G. and Hooft, Lotty and Korevaar, Dani{\\\"e}l A. and Cohen, J{\\'e}r{\\'e}mie F.},
+  title = {STARD 2015: An Updated List of Essential Items for Reporting Diagnostic Accuracy Studies},
+  journal = {BMJ},
+  year = {2015},
+  volume = {351},
+  pages = {h5527},
+  doi = {10.1136/bmj.h5527}
+}
+
+@article{vonelm2007strobe,
+  author = {von Elm, Erik and Altman, Douglas G. and Egger, Matthias and Pocock, Stuart J. and G{\\o}tzsche, Peter C. and Vandenbroucke, Jan P.},
+  title = {The Strengthening the Reporting of Observational Studies in Epidemiology (STROBE) Statement: Guidelines for Reporting Observational Studies},
+  journal = {PLoS Medicine},
+  year = {2007},
+  volume = {4},
+  number = {10},
+  pages = {e296},
+  doi = {10.1371/journal.pmed.0040296}
+}
+
+@article{collins2015tripod,
+  author = {Collins, Gary S. and Reitsma, Johannes B. and Altman, Douglas G. and Moons, Karel G. M.},
+  title = {Transparent Reporting of a multivariable prediction model for Individual Prognosis Or Diagnosis (TRIPOD): The TRIPOD Statement},
+  journal = {Annals of Internal Medicine},
+  year = {2015},
+  volume = {162},
+  number = {1},
+  pages = {55--63},
+  doi = {10.7326/M14-0697}
+}
+
+@article{mongan2020claim,
+  author = {Mongan, John and Moy, Linda and Kahn, Charles E.},
+  title = {Checklist for Artificial Intelligence in Medical Imaging (CLAIM): A Guide for Authors and Reviewers},
+  journal = {Radiology: Artificial Intelligence},
+  year = {2020},
+  volume = {2},
+  number = {2},
+  pages = {e200029},
+  doi = {10.1148/ryai.2020200029}
+}
+
+@misc{equator_network,
+  author = {{EQUATOR Network}},
+  title = {{Enhancing the QUAlity and Transparency Of Health Research}},
+  year = {2026},
+  url = {https://www.equator-network.org/},
+  note = {Accessed 2026-05-23}
+}
+
+@misc{joss_author_guide,
+  author = {{Journal of Open Source Software}},
+  title = {{Submitting a paper to JOSS}},
+  year = {2026},
+  url = {https://joss.readthedocs.io/en/latest/submitting.html},
+  note = {Accessed 2026-05-23}
+}
diff --git a/paper.md b/paper.md
diff --git a/scripts/validate_skills.sh b/scripts/validate_skills.sh
diff --git a/skills/meta-analysis/SKILL.md b/skills/meta-analysis/SKILL.md
