medsci-skills 5.25.0 → 5.26.1

package/README.md

@@ -137,6 +137,8 @@ Install a single category and invoke its skills under that namespace:
 
 All nine plugins share the same repository source, so this groups and enables skills by category — it is not a partial download. The marketplace tracks `main`, so a plugin's version is its git commit.
 
+**Note the name.** A skill installed as a plugin is invoked under its plugin's namespace (`/medsci-analysis:analyze-stats`); the same skill installed into the skills folder by the `npx`, `gh skill`, classroom, or manual paths is invoked bare (`/analyze-stats`). Both run the same skill — press `/` and use Tab completion rather than typing the long form.
+
 **Want just one capability?** Two skills are also published as focused standalone repos (generated mirrors; this repo stays the source of truth), each installable on its own with `/plugin marketplace add Aperivue/<repo>`:
 
 - [`Aperivue/verify-refs`](https://github.com/Aperivue/verify-refs) — catch fabricated/mismatched citations (PubMed + CrossRef).
@@ -681,12 +683,31 @@ gh skill install --all Aperivue/medsci-skills            # or install all of the
 
 - Claude Code: skills are copied to `~/.claude/skills/` (also read by GitHub Copilot and Cursor).
 - Codex: skills are copied to `~/.agents/skills/` (also read by Cursor and GitHub Copilot).
-- Cursor: no separate step needed — Cursor reads `~/.claude/skills/` and `~/.agents/skills/` directly. The installer can still write an optional `.cursor/rules/` steering rule with `--cursor-project`.
+- Cursor: no separate step needed — Cursor reads `~/.claude/skills/` and `~/.agents/skills/` directly. The installer can still write an optional `.cursor/rules/` steering rule with `--cursor-project`; it carries no machine-specific path, so it is safe to commit.
 - See [`docs/host_compatibility.md`](docs/host_compatibility.md) for the verified per-host install paths and their official sources.
 - Windows users do not need WSL for the basic classroom workflow. Use WSL only for advanced reproducible Linux toolchains.
 
 See [docs/classroom_distribution_plan.md](docs/classroom_distribution_plan.md) and [docs/classroom_materials.md](docs/classroom_materials.md) for instructor distribution, email templates, and first-class exercises.
 
+### Optional: let plain-language requests find the skills
+
+Typing `/orchestrate` is the reliable way in. If you would rather just describe what you want, the
+installer can write a short routing table into a project's `CLAUDE.md` so Claude Code reaches for
+the right skill on its own whenever you work in that folder:
+
+```bash
+python3 installers/install.py --claude-project ~/research/my-study   # this project only
+python3 installers/install.py --claude-user                          # every project (larger footprint)
+python3 installers/install.py --claude-project ~/research/my-study --remove-routing
+```
+
+Both are **off by default**. The block is ~25 lines between `<!-- BEGIN/END medsci-skills routing -->`
+markers and carries no machine-specific paths. It is spliced in, not written over: an existing
+`CLAUDE.md` keeps its bytes outside the markers — line endings and file permissions included — the
+write is atomic so an interrupted run cannot leave a truncated file, re-running updates the block in
+place, and `--remove-routing` takes it back out. Prefer `--claude-project` — `--claude-user` loads in every project you ever open,
+including work unrelated to research.
+
 > **Tip:** Not sure which skill to use? Start with `/orchestrate` -- it will classify your request and route you to the right tool.
 
 ## Updating

package/installers/install.py

@@ -86,41 +86,229 @@ def copy_skills(target: str, dest: Path, log_lines: list[str], dry_run: bool) ->
 
 
 def install_cursor_rule(project: Path, log_lines: list[str], dry_run: bool) -> None:
-    rules_dir = project / ".cursor" / "rules"
-    rule_path = rules_dir / "medsci-skills.mdc"
-    body = f"""---
+    """Write the optional Cursor steering rule into <project>/.cursor/rules/medsci-skills.mdc.
+
+    Two things this deliberately does NOT do any more:
+
+    * It does not embed the repository path. `.cursor/rules/` is a directory people commit, and the
+      absolute path of a home directory is the installer's name, so it travelled into shared repos.
+      It was also pointing at the wrong place: per docs/host_compatibility.md this rule is legacy
+      for discovery -- Cursor reads `~/.claude/skills/` and `~/.agents/skills/` directly -- so the
+      rule steers, and the skills are found where they are installed rather than in a checkout.
+    * It does not call `Path.write_text`, which opens in "w" mode and truncates before writing. This
+      file is ours to replace, but a half-written one after an interrupt is nobody's.
+    """
+    rule_path = project / ".cursor" / "rules" / "medsci-skills.mdc"
+    body = """---
 description: Use MedSci Skills for medical research writing, literature search, statistics, figures, and submission workflows.
 alwaysApply: false
 ---
 
 # MedSci Skills
 
-When the user asks for medical research workflows, inspect the relevant
-`skills/<skill-name>/SKILL.md` file in this repository before acting.
+This file is written by the MedSci Skills installer and is replaced whenever it runs.
 
-Start with these entry points:
+When the user asks for a medical research workflow, use the installed MedSci skill rather than
+answering from scratch. Cursor reads them from `~/.claude/skills/` and `~/.agents/skills/`; open the
+relevant `<skill-name>/SKILL.md` before acting.
 
-- `skills/search-lit/SKILL.md` for literature search and verified citations
-- `skills/analyze-stats/SKILL.md` for statistical tables and analysis code
-- `skills/make-figures/SKILL.md` for publication figures
-- `skills/write-paper/SKILL.md` for manuscript sections
-- `skills/check-reporting/SKILL.md` for reporting guideline audits
+Start with these entry points:
 
-Use small single-skill tasks first. Avoid running the full end-to-end pipeline
-unless the user explicitly asks and provides the required project files.
+- `orchestrate` — unsure which one fits; it classifies the request and routes
+- `search-lit` — literature search and verified citations
+- `analyze-stats` — statistical tables and analysis code
+- `make-figures` — publication figures
+- `write-paper` — manuscript sections
+- `check-reporting` — reporting-guideline audits
 
-Repository path:
-`{REPO_ROOT}`
+Prefer small single-skill tasks. Do not run the full end-to-end pipeline unless the user asks for it
+and provides the required project files.
 """
     log(f"\n[cursor] writing project rule to {rule_path}", log_lines)
     if dry_run:
         log("  DRY RUN write Cursor rule", log_lines)
         return
-    rules_dir.mkdir(parents=True, exist_ok=True)
-    rule_path.write_text(body, encoding="utf-8")
+    prev_mode = os.stat(rule_path).st_mode & 0o777 if rule_path.is_file() else None
+    medsci_txn.atomic_write_bytes(rule_path, body.encode("utf-8"))
+    if prev_mode is not None:
+        try:
+            os.chmod(rule_path, prev_mode)
+        except OSError:
+            pass
     log("  installed Cursor project rule", log_lines)
 
 
+ROUTING_BEGIN = "<!-- BEGIN medsci-skills routing -->"
+ROUTING_END = "<!-- END medsci-skills routing -->"
+
+# Deliberately carries no local path. The Cursor rule above embeds REPO_ROOT, which is fine for a
+# file nobody shares — but a CLAUDE.md sits in a project folder and gets committed, and the absolute
+# path of a home directory is the installer's name. Nothing here is machine-specific.
+ROUTING_BLOCK = f"""{ROUTING_BEGIN}
+## MedSci Skills
+
+MedSci Skills is installed. When a request matches a row below, invoke that skill rather than
+answering from scratch. When the right one is not obvious, invoke `orchestrate` — it classifies the
+request and routes to the rest.
+
+| Request | Skill |
+|---|---|
+| Find papers; check that a citation is real; build a reference list | `search-lit`, `verify-refs`, `manage-refs` |
+| Plan a study; sample size; define variables; de-identify data | `design-study`, `calc-sample-size`, `define-variables`, `deidentify` |
+| Run statistics; draw a publication figure | `analyze-stats`, `make-figures` |
+| Draft or revise a manuscript; write an IRB protocol | `write-paper`, `revise`, `write-protocol` |
+| Audit against a reporting guideline (STROBE, PRISMA, CONSORT, STARD, TRIPOD) or a risk-of-bias tool | `check-reporting` |
+| Self-review before submitting; answer reviewers; review someone else's paper | `self-review`, `revise`, `peer-review` |
+| Choose a journal; assemble a submission package | `find-journal`, `sync-submission` |
+| Medical-research work that is not obviously one of the above | `orchestrate` |
+
+How a skill is invoked depends on how it was installed: bare (`/write-paper`) for a skills-folder
+install, namespaced (`/medsci-writing:write-paper`) for a plugin install. Skip any skill that is not
+installed, and never invent one.
+
+These skills draft and audit. They do not replace authors, statisticians, reviewers, or an IRB, and
+every output needs human-expert verification.
+
+Everything between the two markers above and below is managed by the MedSci Skills installer and is
+replaced or removed wholesale when it runs. Put your own notes outside them.
+{ROUTING_END}
+"""
+
+
+LF = "\n"
+CRLF = "\r\n"
+
+
+def _dominant_newline(text: str) -> str:
+    """Which line ending this file already uses, so the block matches it instead of mixing."""
+    crlf = text.count(CRLF)
+    return CRLF if crlf > text.count(LF) - crlf else LF
+
+
+def _write_preserving_mode(path: Path, text: str, newline: str) -> None:
+    """Atomically replace `path`, keeping the permissions it already had.
+
+    The mode step mirrors update._write_settings: a user who ran `chmod 600` on their CLAUDE.md
+    should not have it widened to the umask default as a side effect of an install.
+    """
+    prev_mode = os.stat(path).st_mode & 0o777 if path.is_file() else None
+    medsci_txn.atomic_write_bytes(path, text.encode("utf-8"))
+    if prev_mode is not None:
+        try:
+            os.chmod(path, prev_mode)
+        except OSError:
+            pass
+
+
+def apply_routing(md_path: Path, remove: bool, dry_run: bool, log_lines: list[str]) -> str:
+    """Splice the routing block into a CLAUDE.md. Returns: added | updated | unchanged | removed | absent.
+
+    What is actually guaranteed, because the first version of this docstring claimed more than the
+    code delivered and an external review said so:
+
+    * **The write is atomic.** Content goes to a temp file beside the target and is `os.replace`d
+      into position (medsci_txn.atomic_write_bytes), so an interrupted run leaves the previous file
+      intact. The previous version called `Path.write_text`, which opens in "w" mode and therefore
+      truncates before writing -- an interrupt there left a zero-byte CLAUDE.md.
+    * **Bytes outside the two markers are preserved, line endings included.** The file is read with
+      `read_bytes` and decoded here, so nothing on the path performs universal-newline translation;
+      a CRLF file stays CRLF, and the block is emitted with the file's own line ending rather than
+      mixing one in.
+    * **Permissions are preserved.**
+
+    The one thing it does NOT preserve, stated rather than hidden: a file with no trailing newline
+    gains one, and removal does not take it back. The newline is needed to put the block on its own
+    line, and nothing in the file records that it was ours.
+
+    A CLAUDE.md is where a user keeps their own standing instructions. Anything less than the above
+    is a data-loss bug, not an install step.
+    """
+    # A symlinked CLAUDE.md must be edited through to its target: `os.replace` onto the link would
+    # replace the link itself with a regular file, and unlinking it would delete the user's link
+    # while leaving the block sitting in the file it pointed at.
+    linked = md_path.is_symlink()
+    target = md_path.resolve() if linked else md_path
+
+    raw = target.read_bytes() if target.is_file() else None
+    head = raw.decode("utf-8") if raw is not None else ""
+    nl = _dominant_newline(head)
+    block = ROUTING_BLOCK if nl == LF else ROUTING_BLOCK.replace(LF, nl)
+    region = block[: -len(nl)]  # the block without its own trailing newline
+
+    # Count every marker rather than finding the first of each. Reasoning from `find()` alone
+    # gets three cases wrong, and all three were reachable: markers in reverse order spliced a
+    # duplicate of the user's text and left a dangling fence; two blocks in one file never
+    # converged; and `--remove-routing` on two blocks reported "removed" while one survived --
+    # a success message that was not true. Anything other than one clean fence is refused, which
+    # is what the half-marker case already did.
+    n_begin, n_end = head.count(ROUTING_BEGIN), head.count(ROUTING_END)
+    if n_begin != n_end:
+        raise RuntimeError(
+            f"{md_path} has {n_begin} '{ROUTING_BEGIN}' and {n_end} '{ROUTING_END}'; refusing to "
+            f"guess where the block ends. Fix the markers by hand, then re-run."
+        )
+    if n_begin > 1:
+        raise RuntimeError(
+            f"{md_path} contains {n_begin} routing blocks. Refusing to touch it: removing one "
+            f"would leave the rest while reporting success. Delete the extra blocks by hand, "
+            f"then re-run."
+        )
+    begin, end = head.find(ROUTING_BEGIN), head.find(ROUTING_END)
+    if begin != -1 and begin > end:
+        raise RuntimeError(
+            f"{md_path} has the routing markers in reverse order (END before BEGIN). Splicing "
+            f"that would duplicate the text between them. Fix the markers by hand, then re-run."
+        )
+
+    if remove:
+        if begin == -1:
+            return "absent"
+        # Exact slice. The previous version ran rstrip("\n") + "\n" over the head, which silently
+        # collapsed the user's own blank lines: "KEEP\n\n" came back as "KEEP\n".
+        tail = head[end + len(ROUTING_END):]
+        if tail.startswith(nl):
+            tail = tail[len(nl):]
+        rest = head[:begin] + tail
+        if dry_run:
+            return "removed"
+        if rest.strip() or linked or not target.is_file():
+            _write_preserving_mode(target, rest, nl)
+        else:
+            target.unlink()
+        return "removed"
+
+    if begin != -1:
+        if head[begin:end + len(ROUTING_END)] == region:
+            return "unchanged"
+        merged = head[:begin] + region + head[end + len(ROUTING_END):]
+        outcome = "updated"
+    else:
+        merged = (head if not head or head.endswith(nl) else head + nl) + block
+        outcome = "added"
+
+    if not dry_run:
+        _write_preserving_mode(target, merged, nl)
+    return outcome
+
+
+def install_claude_routing(md_path: Path, remove: bool, log_lines: list[str], dry_run: bool) -> None:
+    """Add or remove the routing block in one CLAUDE.md, reporting exactly what happened."""
+    verb = "removing" if remove else "writing"
+    log(f"\n[routing] {verb} the routing block in {md_path}", log_lines)
+    if dry_run:
+        outcome = apply_routing(md_path, remove, True, log_lines)
+        log(f"  DRY RUN would report: {outcome}", log_lines)
+        return
+    outcome = apply_routing(md_path, remove, False, log_lines)
+    log({
+        "added": "  added the routing block (the rest of the file was left as it was)",
+        "updated": "  updated the existing routing block (nothing outside the markers changed)",
+        "unchanged": "  already present and identical; no write",
+        "removed": "  removed the routing block",
+        "absent": "  no routing block was there; nothing to remove",
+    }[outcome], log_lines)
+
+
 def run_self_test() -> int:
     """Simulate installs into throwaway temp dirs, assert every skill is discoverable, and
     prove no real host directory is touched. Returns 0 on pass, 1 on failure. Writes nothing
@@ -215,6 +403,27 @@ def parse_args() -> argparse.Namespace:
         default=None,
         help="Project folder where a .cursor/rules/medsci-skills.mdc rule should be written.",
     )
+    parser.add_argument(
+        "--claude-project",
+        type=Path,
+        default=None,
+        help="Opt in: add a short skill-routing block to <folder>/CLAUDE.md so plain-language "
+             "requests in that project reach the right skill. Scoped to that folder; nothing else "
+             "in the file is touched.",
+    )
+    parser.add_argument(
+        "--claude-user",
+        action="store_true",
+        help="Opt in: add the same routing block to ~/.claude/CLAUDE.md, which Claude Code loads in "
+             "EVERY project. Larger footprint than --claude-project; prefer that one unless you "
+             "want it everywhere.",
+    )
+    parser.add_argument(
+        "--remove-routing",
+        action="store_true",
+        help="Remove the routing block from whichever target you name with --claude-project / "
+             "--claude-user. Leaves the rest of the file alone.",
+    )
     parser.add_argument("--dry-run", action="store_true", help="Print actions without changing files.")
     parser.add_argument(
         "--self-test",
@@ -343,6 +552,25 @@ def main() -> int:
         failures.append("cursor")
         log(f"\n[cursor] FAILED: {exc}", log_lines)
 
+    try:
+        if args.claude_project:
+            install_claude_routing(
+                args.claude_project.expanduser().resolve() / "CLAUDE.md",
+                args.remove_routing, log_lines, args.dry_run,
+            )
+        if args.claude_user:
+            install_claude_routing(
+                Path.home() / ".claude" / "CLAUDE.md",
+                args.remove_routing, log_lines, args.dry_run,
+            )
+        if args.remove_routing and not (args.claude_project or args.claude_user):
+            log("\n[routing] --remove-routing needs a target: pass --claude-project <folder> "
+                "and/or --claude-user.", log_lines)
+    except Exception as exc:  # noqa: BLE001
+        failures.append("routing")
+        log(f"\n[routing] FAILED: {exc}", log_lines)
+        log("  the CLAUDE.md was left exactly as it was.", log_lines)
+
     # Place the one-click updater under ~/.medsci-skills/updater/ so a future update needs no
     # GitHub/terminal even if this download folder is deleted (best-effort; never fatal).
     if not args.dry_run:

package/installers/medsci_txn.py

@@ -84,15 +84,33 @@ def assert_contained(path: Path, container: Path) -> None:
 
 # ---------------------------------------------------------------- json io
 
-def atomic_write_json(path: Path, obj) -> None:
+def atomic_write_bytes(path: Path, data: bytes) -> None:
+    """Replace `path` with `data`, atomically: a reader sees either the old file or the whole new
+    one, never a half-written or truncated file.
+
+    Extracted from `atomic_write_json` so there is one fsync implementation in the repo rather than
+    two. The caller that forced the split writes a user's CLAUDE.md, where the alternative --
+    `Path.write_text`, which opens in "w" mode and truncates before writing -- turns an interrupted
+    install into a lost file.
+
+    Bytes, not text: the caller decides the encoding and the line endings, so nothing here can
+    translate a CRLF file into an LF one on the way through.
+    """
     path.parent.mkdir(parents=True, exist_ok=True)
     tmp = path.with_suffix(path.suffix + f".tmp.{os.getpid()}")
-    data = (json.dumps(obj, indent=2, ensure_ascii=False) + "\n").encode("utf-8")
-    with open(tmp, "wb") as f:
-        f.write(data)
-        f.flush()
-        os.fsync(f.fileno())
-    os.replace(tmp, path)
+    try:
+        with open(tmp, "wb") as f:
+            f.write(data)
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        # Leave nothing behind: the destination is still whatever it was before this call.
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        raise
     # fsync the directory so the rename is durable.
     try:
         dfd = os.open(str(path.parent), os.O_RDONLY)
@@ -104,6 +122,10 @@ def atomic_write_json(path: Path, obj) -> None:
         pass  # directory fsync unsupported (e.g. Windows) — os.replace is still atomic.
 
 
+def atomic_write_json(path: Path, obj) -> None:
+    atomic_write_bytes(path, (json.dumps(obj, indent=2, ensure_ascii=False) + "\n").encode("utf-8"))
+
+
 def read_json_strict(path: Path):
     """Read JSON; raise TxnError on a corrupt/unreadable file (callers fail closed)."""
     try: