medsci-skills 4.1.0

package/skills/analyze-stats/scripts/check_generated_code.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""Generated-code quality gate for analysis scripts (analyze-stats Phase 3.5).
+
+AI-generated analysis code carries a recurring set of reproducibility-hygiene
+"slop" patterns that pass a casual read but break reproducibility or violate
+the data-integrity rules every medsci-skills analysis must follow. This linter
+scans emitted .py / .R scripts before they are reported as final and flags:
+
+  MISSING_SEED            randomness is used (sampling, bootstrap, train/test
+                          split, shuffling, rng) but no seed is set
+                          (np.random.seed / set.seed / random_state= /
+                          default_rng / RandomState). Non-reproducible. (Major)
+  HARDCODED_DATA_LITERAL  a large hand-typed numeric literal that looks like
+                          tabular data — either alongside a real data-file read,
+                          or very large on its own. The data-integrity rule is
+                          "never hand-type CSV data into scripts; use read_csv +
+                          subset." (Major)
+  HARDCODED_ABS_PATH      an absolute filesystem path literal (/Users/, /home/,
+                          C:\\, ~/Documents). Non-portable and a PII risk. (Major)
+  INPLACE_SOURCE_OVERWRITE the same path is both read as input and written as
+                          output — silently overwriting raw source data. The
+                          data-integrity rule is "never modify raw data." (Major)
+  DEBUG_LEFTOVER          a debugger/print artifact left in (breakpoint(),
+                          pdb.set_trace(), browser(), print("debug"...)) or a
+                          TODO/FIXME/XXX marker. (Flag)
+  UNUSED_IMPORT           (Python only) an imported name never referenced again;
+                          dead dependency. (Flag)
+
+The gate is conservative on the Major checks (it fires HARDCODED_DATA_LITERAL
+only on genuinely table-shaped literals, MISSING_SEED only when a real
+randomness call is present) so it stays quiet on legitimate analysis code.
+
+INPUTS
+  positional   one or more .py / .R / .r files.
+  --code-dir   directory to scan recursively for .py / .R / .r files.
+  (at least one source must be provided via either form.)
+
+OUTPUT
+  A findings table (stdout) and, with --out, a JSON artifact:
+    {files[], claims[{verdict, severity, file, line, detail}], summary}
+  Exit 1 (with --strict) when any Major claim exists; exit 2 on input error.
+
+Stdlib-only (ast / 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 ast
+import json
+import re
+import sys
+from pathlib import Path
+
+# --- shared regexes (language-agnostic unless noted) ------------------------
+
+ABS_PATH = re.compile(r"""['"](?:/Users/|/home/|~/Documents|~/Desktop|~/Downloads|[A-Za-z]:\\\\)[^'"]*['"]""")
+
+DEBUG_PY = re.compile(
+    r"\bbreakpoint\s*\(|\bpdb\.set_trace\s*\(|^\s*import\s+pdb\b|"
+    r"\bprint\s*\(\s*['\"](?:debug|here|test|xxx|todo|checkpoint)\b", re.IGNORECASE)
+DEBUG_R = re.compile(
+    r"\bbrowser\s*\(\s*\)|\bdebug(?:once)?\s*\(|"
+    r"\bprint\s*\(\s*paste0?\s*\(\s*['\"](?:debug|here|test)\b|"
+    r"\bcat\s*\(\s*['\"](?:debug|here)\b", re.IGNORECASE)
+TODO_MARKER = re.compile(r"#\s*(?:TODO|FIXME|XXX)\b", re.IGNORECASE)
+
+# randomness signals vs seed signals
+RAND_PY = re.compile(
+    r"np\.random\.|numpy\.random\.|\brandom\.(?:sample|shuffle|choice|random|randint|randrange)\b|"
+    r"\bRandomState\b|\bdefault_rng\b|\btrain_test_split\b|\bKFold\b|\bStratifiedKFold\b|"
+    r"\bShuffleSplit\b|\bresample\s*\(|\bbootstrap\b|\bpermutation\b")
+SEED_PY = re.compile(
+    r"np\.random\.seed\s*\(|numpy\.random\.seed\s*\(|\brandom\.seed\s*\(|"
+    r"\bRandomState\s*\(|\bdefault_rng\s*\(|\brandom_state\s*=")
+RAND_R = re.compile(
+    r"\bsample\s*\(|\bsample\.int\s*\(|\brnorm\s*\(|\brunif\s*\(|\brbinom\s*\(|"
+    r"\brpois\s*\(|\bboot\s*\(|\bcreateDataPartition\s*\(")
+SEED_R = re.compile(r"\bset\.seed\s*\(")
+
+# data-file reads / writes (for INPLACE_SOURCE_OVERWRITE and the DATA_LITERAL gate)
+READ_CALL = re.compile(
+    r"(?:read_csv|read\.csv|read_excel|read\.xlsx|read_parquet|read_table|read\.table|"
+    r"read_csv2|read_tsv|read_sas|read_stata|read_feather|read_json|loadtxt|genfromtxt)"
+    r"\s*\(\s*([^,\)]+)")
+WRITE_FN = re.compile(
+    r"(?:to_csv|write\.csv|write_csv|write_csv2|to_excel|write\.xlsx|to_parquet|"
+    r"write_parquet|to_feather|savetxt|write\.table|write_tsv|fwrite)\s*\(")
+
+STR_LITERAL = re.compile(r"""['"]([^'"]+)['"]""")
+# bracketed/paren literal whose body is mostly comma-separated numbers
+NUM_LITERAL_BODY = re.compile(r"[\[(]([^\[\]()]*?\d[^\[\]()]*?)[\])]")
+NUM_TOKEN = re.compile(r"-?\d+(?:\.\d+)?(?:[eE][-+]?\d+)?")
+
+DATA_LITERAL_MIN = 12       # numbers in one literal to look table-shaped (with a read)
+DATA_LITERAL_STANDALONE = 24  # numbers in one literal to flag even with no read
+
+
+def _first_path_literal(arg: str) -> str | None:
+    m = STR_LITERAL.search(arg)
+    return m.group(1) if m else None
+
+
+def strip_comments(src: str) -> str:
+    """Blank out `#`-to-EOL comments while preserving byte offsets and line count,
+    so seed/randomness detection never matches a mention inside a comment (e.g.
+    '# no set.seed() used') yet reported line numbers stay correct. Runs only for
+    the seed/randomness checks; path/literal checks keep the full source."""
+    out = []
+    for line in src.split("\n"):
+        i = line.find("#")
+        out.append(line if i < 0 else line[:i] + " " * (len(line) - i))
+    return "\n".join(out)
+
+
+def check_text_common(src: str, lang: str) -> list[dict]:
+    claims: list[dict] = []
+    lines = src.splitlines()
+    has_read = bool(READ_CALL.search(src))
+    code = strip_comments(src)  # comment-free copy for seed/randomness logic
+
+    # MISSING_SEED
+    rand, seed = (RAND_PY, SEED_PY) if lang == "py" else (RAND_R, SEED_R)
+    rm = rand.search(code)
+    if rm and not seed.search(code):
+        ln = src[:rm.start()].count("\n") + 1
+        claims.append({
+            "verdict": "MISSING_SEED", "severity": "Major", "line": ln,
+            "detail": (f"randomness ('{rm.group(0).strip()[:30]}') is used but no seed is set "
+                       f"({'np.random.seed/random_state=' if lang == 'py' else 'set.seed()'}); "
+                       f"the result is not reproducible"),
+        })
+
+    # HARDCODED_ABS_PATH
+    am = ABS_PATH.search(src)
+    if am:
+        ln = src[:am.start()].count("\n") + 1
+        claims.append({
+            "verdict": "HARDCODED_ABS_PATH", "severity": "Major", "line": ln,
+            "detail": f"absolute path literal {am.group(0)[:50]} — non-portable and a PII risk",
+        })
+
+    # HARDCODED_DATA_LITERAL
+    for m in NUM_LITERAL_BODY.finditer(src):
+        body = m.group(1)
+        # ignore obvious non-data: ranges, single repeated, function-call args with kwargs
+        nums = NUM_TOKEN.findall(body)
+        if "=" in body:  # kwargs like figsize=(8,6) or linspace(0,1,...) — not table data
+            continue
+        if len(nums) >= DATA_LITERAL_STANDALONE or (len(nums) >= DATA_LITERAL_MIN and has_read):
+            ln = src[:m.start()].count("\n") + 1
+            claims.append({
+                "verdict": "HARDCODED_DATA_LITERAL", "severity": "Major", "line": ln,
+                "detail": (f"a hand-typed numeric literal with {len(nums)} values"
+                           + (" alongside a data-file read" if has_read else "")
+                           + "; load tabular data with read_csv()/read.csv() + subset, "
+                             "never hand-type it into the script"),
+            })
+            break  # one report per file is enough to act on
+
+    # INPLACE_SOURCE_OVERWRITE — a write call writing to a path also read as input.
+    # Reads capture the first call argument; writes scan the call window for any
+    # string literal (the output path is often the 2nd arg, e.g. write.csv(df, "x")).
+    reads = {p for a in READ_CALL.findall(src) if (p := _first_path_literal(a))}
+    writes: set[str] = set()
+    for wm in WRITE_FN.finditer(src):
+        window = src[wm.end():wm.end() + 200]
+        window = window.split(")")[0]  # stay within this call's arg list
+        writes.update(STR_LITERAL.findall(window))
+    overlap = reads & writes
+    if overlap:
+        path = sorted(overlap)[0]
+        idx = src.find(path)
+        ln = src[:idx].count("\n") + 1 if idx >= 0 else 0
+        claims.append({
+            "verdict": "INPLACE_SOURCE_OVERWRITE", "severity": "Major", "line": ln,
+            "detail": (f"'{path}' is both read as input and written as output; writing to the "
+                       f"source path overwrites raw data — write derived outputs to a new path"),
+        })
+
+    # DEBUG_LEFTOVER
+    debug_re = DEBUG_PY if lang == "py" else DEBUG_R
+    for i, line in enumerate(lines, 1):
+        if debug_re.search(line) or TODO_MARKER.search(line):
+            claims.append({
+                "verdict": "DEBUG_LEFTOVER", "severity": "Flag", "line": i,
+                "detail": f"debug/marker leftover: {line.strip()[:60]}",
+            })
+            break  # first occurrence per file
+
+    return claims
+
+
+def check_unused_imports_py(src: str) -> list[dict]:
+    """Python-only, AST-based. An imported name never referenced elsewhere."""
+    try:
+        tree = ast.parse(src)
+    except SyntaxError:
+        return []  # don't guess on unparseable files
+    imported: list[tuple[str, str, int]] = []  # (bound_name, display, lineno)
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                bound = (alias.asname or alias.name).split(".")[0]
+                imported.append((bound, alias.asname or alias.name, node.lineno))
+        elif isinstance(node, ast.ImportFrom):
+            if node.module == "__future__":
+                continue
+            for alias in node.names:
+                if alias.name == "*":
+                    return []  # star import: cannot reason about usage
+                bound = alias.asname or alias.name
+                imported.append((bound, f"{node.module or ''}.{alias.name}", node.lineno))
+    # collect all Name usages outside the import statements
+    used: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name):
+            used.add(node.id)
+        elif isinstance(node, ast.Attribute):
+            pass  # base Name already captured by the Name walk
+    claims = []
+    for bound, display, lineno in imported:
+        if bound not in used:
+            claims.append({
+                "verdict": "UNUSED_IMPORT", "severity": "Flag", "line": lineno,
+                "detail": f"'{display}' is imported but never used; remove the dead import",
+            })
+    return claims
+
+
+def check_file(path: Path) -> list[dict]:
+    lang = "py" if path.suffix.lower() == ".py" else "r"
+    src = path.read_text(encoding="utf-8", errors="replace")
+    claims = check_text_common(src, lang)
+    if lang == "py":
+        claims += check_unused_imports_py(src)
+    for c in claims:
+        c["file"] = str(path)
+    return claims
+
+
+def gather_files(positional: list[str], code_dir: str | None) -> list[Path]:
+    files: list[Path] = []
+    for p in positional:
+        pp = Path(p)
+        if not pp.is_file():
+            sys.stderr.write(f"ERROR: not a file: {p}\n")
+            sys.exit(2)
+        files.append(pp)
+    if code_dir:
+        d = Path(code_dir)
+        if not d.is_dir():
+            sys.stderr.write(f"ERROR: not a directory: {code_dir}\n")
+            sys.exit(2)
+        for ext in ("*.py", "*.R", "*.r"):
+            files.extend(sorted(d.rglob(ext)))
+    # dedupe, preserve order
+    seen, uniq = set(), []
+    for f in files:
+        key = str(f.resolve())
+        if key not in seen:
+            seen.add(key)
+            uniq.append(f)
+    if not uniq:
+        sys.stderr.write("ERROR: no .py/.R source files to scan\n")
+        sys.exit(2)
+    return uniq
+
+
+def analyze(positional: list[str], code_dir: str | None) -> dict:
+    files = gather_files(positional, code_dir)
+    claims: list[dict] = []
+    for f in files:
+        claims += check_file(f)
+    n_major = sum(1 for c in claims if c["severity"] == "Major")
+    return {
+        "files": [str(f) for f in files],
+        "claims": claims,
+        "summary": {
+            "n_files": len(files),
+            "n_claims": len(claims),
+            "n_major": n_major,
+            "n_flag": len(claims) - n_major,
+            "verdict": "MAJOR_CANDIDATE" if n_major else "OK",
+        },
+    }
+
+
+def render(result: dict) -> str:
+    lines = ["| File:Line | Check | Severity | Detail |", "|---|---|---|---|"]
+    for c in result["claims"]:
+        loc = f"{Path(c['file']).name}:{c.get('line', 0)}"
+        lines.append(f"| {loc} | {c['verdict']} | {c['severity']} | {c['detail']} |")
+    if len(lines) == 2:
+        lines.append("| (none) | — | — | scripts are reproducibility-clean |")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Generated-code quality gate (analyze-stats Phase 3.5).")
+    ap.add_argument("files", nargs="*", help=".py / .R source files to scan")
+    ap.add_argument("--code-dir", help="directory to scan recursively for .py/.R files")
+    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.files, args.code_dir)
+
+    if not args.quiet:
+        print("=" * 41)
+        print(" Generated-Code Quality (Phase 3.5)")
+        print("=" * 41)
+        print(render(result))
+        print()
+        s = result["summary"]
+        if s["n_major"]:
+            print(f"MAJOR candidate: {s['n_major']} reproducibility/integrity issue(s) "
+                  f"across {s['n_files']} file(s).")
+        else:
+            print(f"OK: {s['n_files']} file(s) reproducibility-clean "
+                  f"({s['n_flag']} minor flag(s)).")
+
+    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())

package/skills/analyze-stats/skill.yml

@@ -0,0 +1,38 @@
+schema_version: 2
+name: analyze-stats
+layer: B
+owner_domain: statistical_analysis
+
+when_to_use: "Generate reproducible Python/R analysis code with publication-ready tables and figures for a defined study design."
+when_NOT_to_use: "Sample-size planning (use calc-sample-size); figure-only generation (use make-figures)."
+
+inputs:
+  - "analysis dataset (CSV)"
+  - "analysis plan / variable definitions"
+outputs:
+  - "analysis code (Python/R)"
+  - "result tables"
+  - "analysis figures"
+side_effects:
+  - writes_project_artifacts
+  - executes_analysis_code
+downstream_consumers:
+  - write-paper
+  - make-figures
+  - self-review
+forbidden_actions:
+  - fabricate_or_hand_type_numeric_results
+  - report_estimates_without_ci_or_p
+
+# v2.1 quality card
+purpose: "Produce reproducible statistical code and publication-ready output for a specified design (DTA, agreement, survival, regression, survey, etc.)."
+safety_boundaries:
+  - "All numbers come from executed code on the supplied data; never hand-typed (seed-fixed transforms)."
+  - "Primary estimates report effect size with 95% CI and exact p-values."
+known_limitations:
+  - "Correctness depends on a correct analysis plan and clean data (use design-study / clean-data first)."
+  - "Does not adjudicate clinical validity of the chosen test."
+validation_commands:
+  - "re-run the emitted script and diff results"
+  - "/self-review"
+evidence_surface: demo

package/skills/analyze-stats/tests/fixtures/gen_bad.R

@@ -0,0 +1,16 @@
+# Analysis: synthetic BAD fixture (R) for the generated-code quality gate.
+# Date: 2020-01-01
+
+# absolute path literal + source read
+df <- read.csv("/Users/researcher/data/cohort.csv")
+
+# hand-typed tabular data instead of read.csv + subset
+auc <- c(0.81, 0.83, 0.79, 0.88, 0.84, 0.77, 0.82, 0.86, 0.80, 0.85, 0.78, 0.87, 0.83, 0.81)
+
+# randomness with no set.seed() -> non-reproducible
+boot <- sample(df$auc, size = 1000, replace = TRUE)
+
+browser()  # debugger left in
+
+# writes back to the source path -> overwrites raw data
+write.csv(df, "/Users/researcher/data/cohort.csv")

package/skills/analyze-stats/tests/fixtures/gen_bad.py

@@ -0,0 +1,24 @@
+"""
+Analysis: synthetic BAD fixture for the generated-code quality gate.
+Date: 2020-01-01
+Random seed: (intentionally missing)
+"""
+import numpy as np
+import pandas as pd
+import json  # unused import (dead dependency)
+
+# absolute path literal + source read
+df = pd.read_csv("/Users/researcher/data/cohort.csv")
+
+# hand-typed tabular data instead of read_csv + subset
+ref = pd.DataFrame({
+    "auc": [0.81, 0.83, 0.79, 0.88, 0.84, 0.77, 0.82, 0.86, 0.80, 0.85, 0.78, 0.87, 0.83, 0.81],
+})
+
+# randomness with no seed set -> non-reproducible
+boot = np.random.choice(df["auc"].values, size=1000, replace=True)
+
+breakpoint()  # debugger left in
+
+# writes back to the source path -> overwrites raw data
+df.to_csv("/Users/researcher/data/cohort.csv")

package/skills/analyze-stats/tests/fixtures/gen_clean.py

@@ -0,0 +1,21 @@
+"""
+Analysis: synthetic CLEAN fixture for the generated-code quality gate.
+Date: 2026-01-01
+Random seed: 42
+"""
+import numpy as np
+import pandas as pd
+
+np.random.seed(42)
+
+# portable relative path; no hand-typed data
+df = pd.read_csv("cohort.csv")
+
+# seeded randomness -> reproducible
+boot = np.random.choice(df["auc"].values, size=1000, replace=True)
+boot_mean = float(np.mean(boot))
+
+# derived output written to a NEW path, not the source
+summary = df["auc"].describe()
+summary.to_csv("auc_summary.csv")
+print(f"bootstrap mean AUC = {boot_mean:.3f}")

package/skills/analyze-stats/tests/test_generated_code.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Regression test for the generated-code quality gate (analyze-stats Phase 3.5).
+# Synthetic, PII-free fixtures reproduce reproducibility/integrity slop in both
+# Python and R (missing seed, hardcoded absolute path, hand-typed tabular data,
+# in-place source overwrite, debug leftover, unused import) and a clean script.
+# Absolute-path literals use a synthetic /Users/researcher/ that does not match
+# the repo PII blocklist (personal home dirs only).
+# Stdlib-only (python3).
+set -u
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$HERE/../scripts/check_generated_code.py"
+BAD_PY="$HERE/fixtures/gen_bad.py"
+BAD_R="$HERE/fixtures/gen_bad.R"
+CLEAN="$HERE/fixtures/gen_clean.py"
+OUT="$(mktemp -t gencode_XXXX).json"
+trap 'rm -f "$OUT"' EXIT
+
+fail=0
+check() { local label="$1"; shift
+    if "$@" >/dev/null 2>&1; then printf '  PASS  %s\n' "$label"
+    else printf '  FAIL  %s\n' "$label"; fail=$((fail+1)); fi
+}
+has_verdict() { python3 -c "
+import json,sys
+d=json.load(open('$OUT'))
+assert any(c['verdict']=='$1' for c in d['claims']), '$1 not found'
+"; }
+
+[[ -f "$SCRIPT" ]] || { echo "ENV-ERR: script missing" >&2; exit 2; }
+
+# (1) bad Python script -> exit 1 with all four Major verdicts + flags
+python3 "$SCRIPT" "$BAD_PY" --out "$OUT" --strict --quiet >/dev/null 2>&1
+check "exit 1 (bad .py)" test "$?" -eq 1
+check "MISSING_SEED detected" has_verdict MISSING_SEED
+check "HARDCODED_ABS_PATH detected" has_verdict HARDCODED_ABS_PATH
+check "HARDCODED_DATA_LITERAL detected" has_verdict HARDCODED_DATA_LITERAL
+check "INPLACE_SOURCE_OVERWRITE detected" has_verdict INPLACE_SOURCE_OVERWRITE
+check "UNUSED_IMPORT detected" has_verdict UNUSED_IMPORT
+check "DEBUG_LEFTOVER detected" has_verdict DEBUG_LEFTOVER
+
+# (2) bad R script -> exit 1 with R-side Major verdicts
+python3 "$SCRIPT" "$BAD_R" --out "$OUT" --strict --quiet >/dev/null 2>&1
+check "exit 1 (bad .R)" test "$?" -eq 1
+check "MISSING_SEED detected (R)" has_verdict MISSING_SEED
+check "HARDCODED_ABS_PATH detected (R)" has_verdict HARDCODED_ABS_PATH
+check "HARDCODED_DATA_LITERAL detected (R)" has_verdict HARDCODED_DATA_LITERAL
+check "INPLACE_SOURCE_OVERWRITE detected (R)" has_verdict INPLACE_SOURCE_OVERWRITE
+
+# (3) clean Python script -> exit 0
+python3 "$SCRIPT" "$CLEAN" --strict --quiet >/dev/null 2>&1
+check "exit 0 (clean .py)" test "$?" -eq 0
+
+# (4) --code-dir scans the fixtures directory (finds Major issues -> exit 1)
+python3 "$SCRIPT" --code-dir "$HERE/fixtures" --strict --quiet >/dev/null 2>&1
+check "exit 1 (--code-dir scan)" test "$?" -eq 1
+
+echo "fail=$fail"; [[ "$fail" -eq 0 ]] && echo "ALL PASS" || echo "FAILURES: $fail"
+exit "$fail"

package/skills/analyze-stats/tests/test_survival_template.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# Test the survival_analysis.py template hardening (A1):
+#   - median survival reported WITH a 95% CI (not a bare point estimate)
+#   - Cox events-per-variable (EPV) gate
+#   - cluster-robust (sandwich) SE for nested observation units
+# Static assertions always run (CI-safe, no heavy deps). A runtime smoke runs
+# only when lifelines is importable; otherwise it SKIPs (never fails CI).
+set -u
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TPL="$HERE/../references/templates/survival_analysis.py"
+PASS=0
+FAIL=0
+ok()  { echo "  PASS: $1"; PASS=$((PASS+1)); }
+bad() { echo "  FAIL: $1"; FAIL=$((FAIL+1)); }
+
+# --- static: the template must compile + contain the hardened code paths ---
+python3 -m py_compile "$TPL" 2>/dev/null && ok "template compiles" || bad "template syntax error"
+
+grep -q "def median_with_ci" "$TPL" && ok "median_with_ci helper present" || bad "no median_with_ci helper"
+grep -q "median_survival_times" "$TPL" && ok "imports median CI util" || bad "median CI util not imported"
+# no bare median print left behind (the old `Median survival = {med:.1f}` form)
+grep -qE 'Median survival[^\n]*median_survival_time_' "$TPL" && bad "bare median print still present" || ok "no bare median print"
+grep -q "cluster_col" "$TPL" && ok "Cox cluster_col (robust SE) param" || bad "no cluster_col param"
+grep -q -- "--cluster" "$TPL" && ok "--cluster CLI arg" || bad "no --cluster CLI arg"
+grep -qiE "EPV =|EPV <" "$TPL" && ok "Cox EPV gate present" || bad "no Cox EPV gate"
+
+# --- runtime smoke (optional, lifelines required) ---
+if python3 -c "import lifelines" 2>/dev/null; then
+  WORK="$(mktemp -d)"; trap 'rm -rf "$WORK"' EXIT
+  python3 - "$WORK" <<'PY'
+import csv, os, sys, random
+random.seed(0)
+work = sys.argv[1]
+rows = [("t", "e", "g", "age", "pid")]
+for i in range(120):
+    rows.append((round(random.expovariate(1/12), 2), int(random.random() < 0.6),
+                 "A" if i % 2 else "B", round(40 + random.gauss(0, 10), 1), i // 2))
+with open(os.path.join(work, "s.csv"), "w", newline="") as f:
+    csv.writer(f).writerows(rows)
+PY
+  OUT="$(python3 "$TPL" --input "$WORK/s.csv" --time t --event e --group g \
+        --covariates age --cluster pid --output "$WORK/o" 2>&1)"
+  echo "$OUT" | grep -q "95% CI" && ok "runtime: median prints 95% CI" || bad "runtime: median CI missing"
+  echo "$OUT" | grep -q "EPV =" && ok "runtime: EPV line printed" || bad "runtime: EPV missing"
+  echo "$OUT" | grep -q "cluster-sandwich" && ok "runtime: cluster SE applied" || bad "runtime: cluster SE missing"
+else
+  echo "  SKIP: lifelines not installed (static checks only)"
+fi
+
+echo ""
+echo "test_survival_template: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]

package/skills/author-strategy/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: author-strategy
+description: PubMed author profile analysis. Author name → PubMed fetch → study type classification → visualization → strategy report.
+triggers: author-strategy, 저자 분석, publication analysis, 다작 분석, 연구 전략 분석, author profile, reverse engineer strategy
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: inherit
+---
+
+# /author-strategy — PubMed Author Strategy Analysis
+
+## Purpose
+
+Analyze a researcher's PubMed publication portfolio to reverse-engineer their research strategy. Produces a CSV dataset, 7 visualizations, and a strategy report.
+
+## Prerequisites
+
+- Python 3.10+ with `biopython`, `pandas`, `matplotlib`, `seaborn`
+- Scripts: `${CLAUDE_SKILL_DIR}/fetch_pubmed.py`, `${CLAUDE_SKILL_DIR}/analyze_patterns.py`
+
+## Workflow
+
+### Step 1: Gather Input
+
+Ask the user for:
+1. **Author name** (PubMed format, e.g., "Kim DK" or "Lee KS")
+2. **Last name** for position classification (auto-detected if ambiguous)
+3. **Output directory** (default: `~/.local/cache/author-strategy/{AuthorName}/`)
+
+### Step 2: Fetch PubMed Data
+
+```bash
+python "${CLAUDE_SKILL_DIR}/fetch_pubmed.py" "{Author Name}" \
+  --last-name "{LastName}" \
+  --output "{output_dir}/data/{name}_publications.csv" \
+  --email "{user_email}"
+```
+
+Review the console summary (total count, study type distribution, author position).
+If count is 0, suggest alternative name formats (e.g., "Yon DK" vs "Yon D" vs "Yon Dong Keon").
+
+### Step 3: Generate Visualizations and Report
+
+```bash
+python "${CLAUDE_SKILL_DIR}/analyze_patterns.py" "{output_dir}/data/{name}_publications.csv" \
+  --output-dir "{output_dir}/report/" \
+  --author-name "{Author Name}"
+```
+
+This produces:
+- 7 PNG charts (01-07)
+- `analysis_report.md` with strategy breakdown
+
+### Step 4: Interpret and Present
+
+Read `analysis_report.md` and present to the user:
+
+1. **Executive summary**: total publications, growth trajectory, high-tier rate
+2. **Primary strategy**: what study type dominates and why
+3. **Author position analysis**: leadership rate (1st + last) vs middle
+4. **Topic clusters**: research focus areas
+5. **ROI quadrant**: which strategies yield high-tier + leadership vs. volume only
+6. **Replication opportunities**: which patterns are replicable with Claude Code + public databases
+
+### Step 5: Optional — MA Gap Identification
+
+If the user asks "what MA topics are feasible with this professor?":
+- Cross-reference topic clusters with existing MA plans in memory
+- Identify gaps where the professor has domain expertise but no MA published
+- Output a prioritized list of MA proposals
+
+## Study Type Classifier
+
+The classifier is tuned for Korean epidemiology and public health researchers. Categories:
+
+| Type | Detection Pattern |
+|------|------------------|
+| GBD | "global burden" or "gbd" in title/abstract |
+| SR/MA | "systematic review" or "meta-analysis" |
+| NHIS/Claims | "national health insurance", "nhis", "claims database", "nationwide cohort" |
+| Cross-national | Country pairs or "cross-national"/"binational" |
+| National survey | "knhanes", "nhanes", "kchs", "national survey" |
+| Biobank | "biobank" |
+| AI/ML | "machine learning", "deep learning", "artificial intelligence" |
+| Clinical trial | "randomized" or publication type |
+| Case report | "case report" |
+| Letter/Commentary | Publication type = letter/comment/editorial |
+
+**Known limitation**: The classifier may undercount NHIS studies when they appear in Cross-national or Other categories. The report notes this.
+
+## Known Limitations
+
+- The study type classifier is tuned for epidemiology and public health researchers. May undercount specialized study types for other fields.
+- NHIS studies may be undercounted when they appear in cross-national or "other" categories.
+- PubMed search requires an email for NCBI E-utilities (set via `--email` flag).
+
+## Anti-Hallucination
+
+- **Never fabricate publication counts, h-index, or journal metrics.** All numbers must come from PubMed API output.
+- **Never invent study classifications.** If a paper cannot be classified, label it as "Other" rather than guessing.
+- If PubMed returns 0 results, suggest alternative name formats rather than generating fake data.
+
+## Output Structure
+
+```
+{output_dir}/
+  data/
+    {name}_publications.csv
+  report/
+    analysis_report.md
+    01_yearly_stacked.png
+    02_study_type_pie.png
+    03_author_position.png
+    04_journal_tier_heatmap.png
+    05_topic_distribution.png
+    06_growth_curve.png
+    07_strategy_roi.png
+```