@diottodev/runic 1.0.0 → 1.1.0

package/research-ops/commands/cs-research-ops.md

@@ -0,0 +1,43 @@
+---
+description: Top-level Research Operations router. Classifies an enterprise research inquiry (clinical study design / R&D finance / market research / product research) and forks context to the right sub-skill via the research-ops-skills orchestrator, returning a ≤200-word digest with a named owner and one grill challenge.
+argument-hint: "<research inquiry: study design, R&D budget, market size, user research, etc.>"
+---
+
+# /cs:research-ops — Research Operations router
+
+Route this inquiry through the `research-ops-skills` orchestrator:
+
+**$ARGUMENTS**
+
+## Routing (deterministic, two-signal threshold)
+
+| Signal class | Keywords | Sub-skill |
+|---|---|---|
+| CLINICAL | clinical trial, study design, protocol, endpoint, sample size, power, phase, biostatistics, feasibility | `clinical-research` |
+| RD_FINANCE | R&D budget, program budget, burn, runway, F&A, indirect rate, capitalize vs expense, portfolio ROI | `research-finance` |
+| MARKET | TAM, SAM, SOM, market sizing, survey, sampling, margin of error, segmentation, competitive intelligence | `market-research` |
+| PRODUCT | user interview, JTBD, usability, concept test, discovery research, research repository, insight, saturation | `product-research` |
+
+1. Explore the workspace first — a resolving filename routes silently.
+2. Single signal or tie → one clarifying question with a recommended answer.
+3. Genuine multi-lane → highest-confidence first, run in fork, ask before chaining. Never silently chain.
+
+## Output (≤200-word digest)
+
+- What was analyzed
+- Top 3 findings, each anchored to a canon citation
+- Top 3 next actions with a named human owner where applicable
+- Artifact path
+- One grill challenge for the user
+
+## Hard rules
+
+- Clinical output is an estimate + named clinical owner — never fact.
+- Finance output surfaces assumptions; capex-vs-opex routes to a named finance owner.
+- Market size shows method (both ways) + assumptions — never a single number.
+- Product insight surfaces confidence + source count; singletons are anecdotes.
+
+## Distinct from
+
+- `research/` (academic) — finds literature/grants/patents. This plans/funds/scopes/synthesizes.
+- `ra-qm-team` — regulatory submission. `finance/` — corporate close. `marketing-skill` — campaign analytics.

package/research-ops/skills/clinical-research/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: clinical-research
+description: Use when designing a prospective clinical study before submission — selecting and classifying endpoints (primary / key-secondary / exploratory, with surrogate-endpoint flagging), estimating sample size and power for two-arm designs (means / proportions / survival), or scoring a study plan for feasibility and a GO / GO-WITH-CONDITIONS / REDESIGN / NO-GO phase-gate decision. Every output is an ESTIMATE plus a named human owner (clinician / biostatistician / regulatory owner) — never clinical fact, never a finished protocol. Distinct from ra-qm-team, which handles the regulatory/QM submission (ISO 13485, EU MDR, FDA 510(k)/PMA/QSR), not the study design.
+version: 2.9.0
+author: claude-code-skills
+license: MIT
+tags: [research-ops, clinical-research, study-design, endpoint, sample-size, power, phase-gate, biostatistics]
+compatible_tools: [claude-code, codex-cli, cursor, antigravity, opencode, gemini-cli]
+---
+
+# clinical-research
+
+Prospective clinical study DESIGN: endpoints, sample size / power, and phase-gate feasibility. Every output is an **estimate with stated assumptions** routed to a **named human owner**. This skill never gives clinical advice as fact and never substitutes for a biostatistician or regulatory affairs.
+
+## Purpose
+
+R&D clinical teams, medical monitors, and biostatistics functions live at the moment between *we-have-a-hypothesis* and *we-have-a-protocol-ready-for-submission*. This skill structures three of the hardest design decisions:
+
+Three deterministic tools:
+
+1. `sample_size_estimator.py` — Closed-form power / sample-size for two-arm **means** (Cohen's d), **proportions** (normal approximation), and **survival** (Schoenfeld events). Inflates for dropout. Prints an "ESTIMATE — confirm with a biostatistician" banner.
+2. `endpoint_selector.py` — Scores candidate endpoints across 5 weighted dimensions (clinical relevance, measurability, regulatory acceptance, sensitivity-to-change, burden) and classifies each as **PRIMARY / KEY-SECONDARY / EXPLORATORY**. Penalizes unvalidated surrogate endpoints.
+3. `phase_gate_scorer.py` — Scores a study plan 0-100 across recruitment feasibility, endpoint readiness, statistical power, operational complexity, and budget fit; returns **GO / GO-WITH-CONDITIONS / REDESIGN / NO-GO** plus the named owners who must sign.
+
+## When to use
+
+Invoke this skill when:
+
+- You are choosing a primary endpoint and need to defend it against surrogate-endpoint scrutiny.
+- You need a defensible first sample-size estimate for a protocol synopsis.
+- A study plan needs a feasibility read before a phase-gate review.
+- You are pressure-testing whether the planned enrollment is achievable given the eligible population and sites.
+
+**Do NOT use this skill to**: prepare a regulatory submission or clinical evaluation report (use `ra-qm-team`), find or position a grant (use `research/grants`), design a live product A/B experiment (use `product-team/experiment-designer`), or replace a biostatistician's final sample-size justification.
+
+## Workflow
+
+1. **Draft the synopsis** — Fill `assets/protocol_synopsis_template.md` (objectives, design, population, endpoints, statistical plan placeholder, owners-to-sign).
+2. **Select the endpoint** — Run `endpoint_selector.py --input endpoints.json --profile {drug|device|biologic|diagnostic|digital-therapeutic}`. Read the classification + surrogate flags. If >1 primary, plan multiplicity control.
+3. **Estimate the sample size** — Run `sample_size_estimator.py --design {means|proportions|survival} ...`. Trace the effect/difference/HR to a published or anchor-based source; inflate for dropout.
+4. **Score feasibility** — Run `phase_gate_scorer.py --input study.json --profile <same> --phase {1|2|3|4}`. Read the verdict + blockers + named owners.
+5. **Route for sign-off** — Assemble the synopsis + estimates into the gate packet. The packet is **a recommendation**; a biostatistician, medical monitor, and regulatory owner sign.
+
+## Scripts
+
+| Script | Purpose | Profiles |
+|---|---|---|
+| `scripts/sample_size_estimator.py` | Power / sample-size for means, proportions, survival | n/a (design-driven) |
+| `scripts/endpoint_selector.py` | 5-dimension endpoint scoring + classification + surrogate flag | drug, device, biologic, diagnostic, digital-therapeutic |
+| `scripts/phase_gate_scorer.py` | Feasibility 0-100 + GO/GO-WITH-CONDITIONS/REDESIGN/NO-GO + owners | drug, device, biologic, diagnostic, digital-therapeutic |
+
+All three: stdlib-only, `--help`, `--sample`, `--output {human,json}`.
+
+## Onboarding & customization
+
+Run the onboarding questionnaire **once before you start** — it captures your defaults and named owners so every tool in this skill is pre-configured. Customization is the point: the answers actually change tool behavior.
+
+```bash
+python3 scripts/onboard.py            # interactive (also: --defaults, --set key=value, --reset)
+python3 scripts/onboard.py --show     # see the questions + current effective config
+```
+
+Answers are saved to `~/.config/research-ops/clinical-research.json` (global) or `./.research-ops/clinical-research.json` (`--scope project`) and are read automatically by `config_loader.py`. They set the default development-area **profile**, default **alpha / power / dropout**, and the named **biostatistician / medical monitor / regulatory owner** printed on outputs. CLI flags always override saved config; `RESEARCH_OPS_NO_CONFIG=1` ignores it entirely.
+
+**The seven questions:** development area · alpha · power · dropout · biostatistician · medical monitor · regulatory owner.
+
+## Optimize with autoresearch (opt-in)
+
+This skill ships an **isolated, opt-in** bridge to `engineering/autoresearch-agent`. Only when you ask to "optimize" / "run a loop" does an autoresearch experiment iteratively improve a study plan against this skill's own feasibility score. `scripts/ar_evaluator.py` is the ground-truth evaluator; it prints `feasibility_composite: <0-100>` (higher is better).
+
+```bash
+/ar:setup --domain custom --name trial-feasibility \
+  --target study.json \
+  --eval "python3 ar_evaluator.py --target study.json" \
+  --metric feasibility_composite --direction higher
+/ar:loop custom/trial-feasibility
+```
+
+Isolated: no hard dependency — autoresearch runs only on demand, and the loop edits `study.json`, never the evaluator (locked ground truth).
+
+## References
+
+- `references/study_design_canon.md` — ICH E8(R1) general considerations; ICH E9 + E9(R1) estimand addendum; CONSORT 2010; SPIRIT 2013; FDA Multiple Endpoints guidance (2022).
+- `references/endpoint_and_power.md` — Cohen *Statistical Power Analysis*; Schoenfeld (1983) survival sample size; FDA Surrogate Endpoint Table / BEST glossary; FDA PRO guidance (2009); Chow, Shao & Wang *Sample Size Calculations in Clinical Research*.
+- `references/trial_operations.md` — ICH E6(R2/R3) GCP; TransCelerate risk-based monitoring; FDA RBM guidance; CTTI recruitment best practices; site-feasibility scoring literature.
+
+## Assumptions
+
+- Sample-size formulas use normal approximations with a built-in z-table. They are first-pass **estimates**; a biostatistician produces the final justification (and may use simulation, adaptive designs, or exact methods).
+- The endpoint scorer applies *customary* regulatory priors per development area via `--profile`. Company- or indication-specific precedent overrides the prior.
+- The phase-gate scorer bakes in a profile cost-per-patient benchmark; pass a real budget to override the default.
+- An unvalidated surrogate cannot anchor a PRIMARY endpoint — the scorer enforces this with a penalty.
+
+## Anti-patterns
+
+- **Presenting a power estimate as fact.** Every output is an estimate with a named owner who must sign.
+- **Powering for a convenience effect size.** The effect must trace to a published or anchor-based MCID, not to the n you can afford.
+- **Anchoring a primary on an unvalidated surrogate.** Surrogate endpoints need validation evidence for the indication.
+- **Ignoring multiplicity.** More than one primary endpoint requires pre-specified alpha allocation.
+- **Skipping dropout inflation.** Raw n undersizes the study; inflate by 1/(1 − dropout).
+
+## Distinct from
+
+| Sibling / neighbor | Scope | Difference |
+|---|---|---|
+| `ra-qm-team` | ISO 13485 QMS, ISO 14971 risk, EU MDR tech docs + clinical evaluation, FDA 510(k)/PMA/De Novo/QSR submission | That is the **submission**; clinical-research designs the **study** beforehand |
+| `research/grants` | NIH funding discovery + positioning | That **finds funding**; this **designs the trial** |
+| `product-team/experiment-designer` | Live product A/B hypothesis + sample size | That is a **product experiment**; this is a **clinical trial** |
+| `research-finance` (sibling) | R&D program budget + burn | That **funds** the program; this **scopes** the study |
+
+## Quick examples
+
+```bash
+python3 scripts/sample_size_estimator.py --sample
+python3 scripts/sample_size_estimator.py --design proportions --p1 0.30 --p2 0.45 --dropout 0.15
+python3 scripts/endpoint_selector.py --sample
+python3 scripts/phase_gate_scorer.py --sample --output json
+```
+
+The sample correctly flags an unvalidated serum-cytokine surrogate (cannot be primary) and ranks PASI-75 as the PRIMARY endpoint; the phase-gate sample returns a verdict with a named owner chain.
+
+## Forcing-question library (Matt Pocock grill discipline)
+
+Walked one at a time by `/cs:grill-research-ops` or the orchestrator. Recommended answer + canon citation per question. Never bundled.
+
+1. **"Is your primary endpoint a clinical outcome or a surrogate — and if surrogate, is it on FDA's validated table?"**
+   Recommended: clinical outcome unless the surrogate is validated for this indication.
+   Canon: FDA Surrogate Endpoint Table; BEST (Biomarkers, EndpointS, and other Tools) glossary.
+
+2. **"What's the minimal clinically important difference you're powering for — and where did that number come from?"**
+   Recommended: a published or anchor-based MCID, cited; never a convenience effect size.
+   Canon: ICH E9; Cohen *Statistical Power Analysis*.
+
+3. **"What dropout rate are you assuming, and is the sample size inflated for it?"**
+   Recommended: inflate n by 1/(1 − dropout) using a justified rate.
+   Canon: Chow, Shao & Wang; ICH E9(R1).
+
+4. **"Single primary endpoint or multiple — and if multiple, what's the multiplicity control?"**
+   Recommended: pre-specify alpha allocation (hierarchical / Bonferroni).
+   Canon: FDA Multiple Endpoints guidance (2022).
+
+5. **"Who is the named biostatistician / medical monitor / regulatory owner signing this synopsis?"**
+   Recommended: name them now — this output is a recommendation, not a protocol.
+   Canon: ICH E6(R2) GCP roles & responsibilities.
+
+Walk depth-first. Lock 1-2 before opening 3-5. After all are answered, invoke `endpoint_selector.py` → `sample_size_estimator.py` → `phase_gate_scorer.py`.

package/research-ops/skills/clinical-research/assets/protocol_synopsis_template.md

@@ -0,0 +1,57 @@
+# Protocol Synopsis — Template
+
+> Fill this before running the tools. This is a synopsis, not a full protocol. Every section
+> ends in a named owner who must sign. Output of this skill is an ESTIMATE — a biostatistician,
+> medical monitor, and regulatory owner sign the final protocol.
+
+## 1. Study identification
+- Study ID:
+- Sponsor / department:
+- Phase: [1 | 2 | 3 | 4]
+- Development area / profile: [drug | device | biologic | diagnostic | digital-therapeutic]
+
+## 2. Objectives
+- Primary objective:
+- Secondary objective(s):
+- Estimand (population, treatment, endpoint, intercurrent-event strategy, summary measure):
+
+## 3. Design
+- Type: [parallel-group RCT | crossover | adaptive | single-arm]
+- Arms & allocation ratio:
+- Randomization & stratification factors:
+- Blinding:
+
+## 4. Population
+- Indication:
+- Key inclusion criteria:
+- Key exclusion criteria:
+- Estimated eligible population:
+- Number of sites / countries:
+
+## 5. Endpoints
+| Endpoint | Type (clinical / surrogate / PRO) | Validated? | Proposed class (PRIMARY / KEY-SECONDARY / EXPLORATORY) |
+|---|---|---|---|
+|  |  |  |  |
+
+- Multiplicity control (if >1 primary):
+
+## 6. Statistical plan (placeholder — biostatistician owns the final)
+- Design for sample size: [means | proportions | survival]
+- Assumed effect size / difference / HR + **source citation**:
+- alpha (two-sided): ___   power: ___   dropout: ___
+- Estimated n (from `sample_size_estimator.py`):
+
+## 7. Feasibility & budget
+- Target enrollment / enrollment months:
+- Visits per patient / invasive procedures:
+- Planned budget (USD):
+- Phase-gate verdict (from `phase_gate_scorer.py`):
+
+## 8. Owners to sign (named, not roles)
+- Principal Investigator:
+- Medical Monitor:
+- Biostatistician:
+- Regulatory Owner:
+
+## 9. Assumptions register
+- (List every assumption behind the effect size, dropout, eligible pool, and budget. Each must trace to a source or be flagged as an unverified planning assumption.)

package/research-ops/skills/clinical-research/references/endpoint_and_power.md

@@ -0,0 +1,37 @@
+# Endpoints and Statistical Power
+
+Reference for endpoint selection and sample-size estimation. Pairs with `endpoint_selector.py` and `sample_size_estimator.py`.
+
+## Endpoint hierarchy
+
+- **Clinical outcome** — directly measures how a patient feels, functions, or survives (mortality, stroke, symptom resolution). Strongest regulatory standing.
+- **Surrogate endpoint** — a biomarker intended to substitute for a clinical outcome (LDL cholesterol, viral load, tumor response). Only acceptable if **validated** for the specific indication. FDA maintains a public Surrogate Endpoint Table listing surrogates that have supported approvals; the BEST glossary defines the validation hierarchy (candidate → reasonably likely → validated).
+- **Patient-reported outcome (PRO)** — measured directly from the patient via a validated instrument. FDA's 2009 PRO guidance sets the bar for instrument validity, reliability, and content validity.
+
+The tool penalizes an **unvalidated surrogate** so it cannot anchor a PRIMARY endpoint — this mirrors the regulatory reality that an unvalidated surrogate carries approval risk.
+
+## Choosing the effect size (the hardest input)
+
+The single most consequential — and most abused — input is the assumed effect size. It must be **clinically meaningful** and **externally justified**, never reverse-engineered from the n you can afford.
+
+- For **means**, the effect is Cohen's d (standardized mean difference). Cohen's conventional small/medium/large (0.2 / 0.5 / 0.8) are last resorts, not anchors — prefer a published or anchor-based MCID.
+- For **proportions**, specify the control and treatment rates from prior data; the absolute difference drives n.
+- For **survival**, specify the target hazard ratio; required *events* (not patients) drive power via Schoenfeld's approximation, then n follows from the overall event probability.
+
+## Power formulas the tool implements
+
+- **Two-sample means:** n_per_arm = 2·((z_α + z_β)/d)², adjusted for allocation ratio k.
+- **Two-sample proportions:** n = [z_α·√(2·p̄·q̄) + z_β·√(p₁q₁ + p₂q₂)]² / (p₁ − p₂)².
+- **Survival (Schoenfeld):** required events E = 4·(z_α + z_β)² / (ln HR)²; n = E / P(event).
+
+All inflate for dropout by 1/(1 − dropout). These are estimates; a biostatistician produces the binding justification, possibly via simulation.
+
+## Sources
+
+1. Cohen, J., *Statistical Power Analysis for the Behavioral Sciences*, 2nd ed. (1988).
+2. Schoenfeld, D., *Sample-size formula for the proportional-hazards regression model* — Biometrics 1983;39:499-503.
+3. Chow, Shao, Wang & Lokhnygina, *Sample Size Calculations in Clinical Research*, 3rd ed. (CRC, 2017).
+4. FDA, *Surrogate Endpoint Resources for Drug and Biologic Development* (public Surrogate Endpoint Table).
+5. FDA-NIH BEST (Biomarkers, EndpointS, and other Tools) Resource glossary (2016, updated).
+6. FDA, *Patient-Reported Outcome Measures: Use in Medical Product Development* (2009).
+7. Fleming & DeMets, *Surrogate end points in clinical trials: are we being misled?* — Ann Intern Med 1996;125:605-613.

package/research-ops/skills/clinical-research/references/study_design_canon.md

@@ -0,0 +1,36 @@
+# Study Design Canon
+
+Reference knowledge base for prospective clinical study design. Use this when filling the protocol synopsis and defending design choices at a phase gate.
+
+## The estimand-first mindset (ICH E9(R1))
+
+Before choosing an endpoint or a sample size, define the **estimand**: the precise treatment effect the trial will estimate. ICH E9(R1) defines five attributes — population, treatment, endpoint (variable), intercurrent-event handling strategy, and population-level summary. Skipping the estimand is the most common cause of a trial that "succeeds" statistically but answers the wrong question. Intercurrent events (treatment discontinuation, rescue medication, death) must have a pre-specified strategy (treatment-policy, hypothetical, composite, while-on-treatment, principal-stratum).
+
+## Design selection
+
+- **Parallel-group RCT** — the default for confirmatory efficacy. Two or more arms, randomized, concurrent controls.
+- **Crossover** — each subject is their own control; only valid for chronic, stable, reversible conditions with adequate washout.
+- **Adaptive designs** — pre-planned modifications (sample-size re-estimation, arm dropping, seamless phase 2/3). Powerful but require simulation and regulatory pre-agreement (FDA Adaptive Designs guidance, 2019).
+- **Single-arm** — only defensible with a well-characterized natural history / external control, common in rare disease and oncology early phases.
+
+## Randomization & blinding
+
+Randomization removes selection bias; stratify on strong prognostic factors (and always on site in multicenter trials). Blinding (single / double / triple) removes ascertainment and analysis bias. Document the unblinding plan and the DSMB charter for any interim looks.
+
+## Multiplicity
+
+Any trial with more than one primary endpoint, more than two arms, or interim analyses inflates the family-wise type-I error. Pre-specify the control strategy: hierarchical (fixed-sequence) testing, Bonferroni / Holm, or a graphical (Bretz-Maurer) approach. The FDA Multiple Endpoints guidance (2022) is the operative reference.
+
+## Reporting standards as design checklists
+
+CONSORT 2010 (parallel-group RCT reporting) and SPIRIT 2013 (protocol content) are reporting standards — but used proactively they are design checklists. If you cannot fill a SPIRIT item, the design has a gap.
+
+## Sources
+
+1. ICH E8(R1), *General Considerations for Clinical Studies* (2021) — quality-by-design, fit-for-purpose study design.
+2. ICH E9, *Statistical Principles for Clinical Trials* (1998) and the **E9(R1) Addendum on Estimands and Sensitivity Analysis** (2019).
+3. Schulz, Altman & Moher, *CONSORT 2010 Statement* — BMJ 2010;340:c332.
+4. Chan et al., *SPIRIT 2013 Statement: defining standard protocol items for clinical trials* — Ann Intern Med 2013;158:200-207.
+5. FDA, *Multiple Endpoints in Clinical Trials: Guidance for Industry* (2022).
+6. FDA, *Adaptive Designs for Clinical Trials of Drugs and Biologics* (2019).
+7. Friedman, Furberg, DeMets, *Fundamentals of Clinical Trials*, 5th ed. (Springer, 2015).

package/research-ops/skills/clinical-research/references/trial_operations.md

@@ -0,0 +1,33 @@
+# Trial Operations and Feasibility
+
+Reference for study feasibility and the phase-gate decision. Pairs with `phase_gate_scorer.py`.
+
+## Feasibility is the silent killer
+
+Most trials that fail do not fail on science — they fail on **enrollment**. A study powered for 240 patients across 18 sites assumes a recruitment rate per site per month that is often optimistic by 2-3×. The feasibility scorer enforces two reality checks: the **eligible pool ratio** (eligible population ÷ target enrollment should comfortably exceed 3×, ideally 10×) and **site capacity** (sites × nominal enroll rate × duration vs target). The "enrolling funnel" loses patients at screening, eligibility, and consent — Lasagna's Law (clinicians overestimate the eligible pool the moment a trial opens) is the operative caution.
+
+## Good Clinical Practice (GCP)
+
+ICH E6(R2) — and the in-progress E6(R3) — define the responsibilities of sponsors, investigators, and monitors; informed consent; protocol adherence; and the trial master file. A study design that cannot satisfy GCP roles is not gate-ready. Name the Principal Investigator, Medical Monitor, and Biostatistician before the gate.
+
+## Risk-based monitoring (RBM)
+
+Centralized, risk-based monitoring (FDA's 2013 guidance, expanded 2023; TransCelerate's RBM methodology) replaces 100% source-data verification with targeted monitoring of the data and processes that most affect patient safety and data integrity. Building RBM into the design lowers operational complexity (a scored dimension).
+
+## Operational complexity drivers
+
+Visits per patient, invasive procedures, central-lab logistics, imaging adjudication, and the number of countries all raise operational complexity and recruitment difficulty. The scorer inverts complexity (simpler design → higher score) because every added visit or procedure raises dropout and cost-per-patient.
+
+## Budget reality
+
+Cost-per-patient varies enormously by area (a digital-therapeutic at ~$6k/patient vs a biologic at ~$50k+/patient). The scorer compares planned budget to a profile benchmark and flags under-funding below 75% of benchmark. Research-finance (the sibling skill) owns the full program budget; this scorer only checks gate-level adequacy.
+
+## Sources
+
+1. ICH E6(R2), *Good Clinical Practice* (2016); ICH E6(R3) draft (2023).
+2. FDA, *A Risk-Based Approach to Monitoring of Clinical Investigations* (2013; Q&A revision 2023).
+3. TransCelerate BioPharma, *Risk-Based Monitoring Methodology* position papers.
+4. CTTI (Clinical Trials Transformation Initiative), *Recruitment* and *Feasibility* recommendations.
+5. Lasagna, L. — "Lasagna's Law" on the overestimation of eligible patients (clinical-trials folklore widely cited in feasibility literature).
+6. Treweek et al., *Strategies to improve recruitment to randomised trials* — Cochrane Database Syst Rev 2018.
+7. Getz & Campo, *Trial complexity and protocol design* — Tufts CSDD impact reports.

package/research-ops/skills/clinical-research/scripts/ar_evaluator.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+"""ar_evaluator.py - Autoresearch evaluator for the clinical-research skill (OPT-IN).
+
+Stdlib-only. This is the ISOLATED bridge to engineering/autoresearch-agent. It does
+NOT call autoresearch; it is the ground-truth evaluator that an autoresearch loop runs
+after editing the target study plan. It reads a study-plan JSON (the file the loop
+optimizes), scores it with phase_gate_scorer, and prints ONE metric line to stdout:
+
+    feasibility_composite: <0-100>   (higher is better)
+
+Usage inside autoresearch (the user opts in explicitly):
+    /ar:setup --domain custom --name trial-feasibility \\
+      --target study.json --eval "python3 ar_evaluator.py --target study.json" \\
+      --metric feasibility_composite --direction higher
+
+Direct use:
+    python3 ar_evaluator.py --sample
+    python3 ar_evaluator.py --target study.json --profile drug
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import config_loader as cfg  # noqa: E402
+import phase_gate_scorer as pgs  # noqa: E402
+
+METRIC = "feasibility_composite"
+
+
+def evaluate_target(study: dict, profile: str, phase: int) -> float:
+    result = pgs.evaluate(study, profile, phase)
+    return float(result["composite"])
+
+
+def main(argv: list[str] | None = None) -> int:
+    c = cfg.load_config()
+    p = argparse.ArgumentParser(description="Autoresearch evaluator: study-plan feasibility composite.")
+    p.add_argument("--target", help="path to study-plan JSON (or env AR_TARGET)")
+    p.add_argument("--profile", default=None, help="overrides onboarding default_profile")
+    p.add_argument("--phase", type=int, default=2, choices=[1, 2, 3, 4])
+    p.add_argument("--sample", action="store_true", help="evaluate the embedded sample plan")
+    args = p.parse_args(argv)
+
+    profile = args.profile or c.get("default_profile", "drug")
+    if args.sample:
+        study = pgs.SAMPLE
+    else:
+        target = args.target or os.environ.get("AR_TARGET")
+        if not target:
+            print("error: provide --target <study.json> or set AR_TARGET", file=sys.stderr)
+            return 2
+        try:
+            with open(target) as f:
+                study = json.load(f)
+        except (OSError, json.JSONDecodeError) as e:
+            # autoresearch treats a crash as DISCARD; emit N/A and non-zero.
+            print(f"{METRIC}: N/A")
+            print(f"error: {e}", file=sys.stderr)
+            return 1
+
+    phase = study.get("phase", args.phase)
+    value = evaluate_target(study, profile, phase)
+    # The single machine-readable metric line autoresearch parses:
+    print(f"{METRIC}: {value}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/research-ops/skills/clinical-research/scripts/config_loader.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""config_loader.py - Customization loader for the clinical-research skill.
+
+Stdlib-only. Importable from the skill's other scripts. Precedence (highest wins):
+  1. Project config:  <cwd>/.research-ops/clinical-research.json
+  2. Global config:   ~/.config/research-ops/clinical-research.json
+  3. Built-in DEFAULTS
+
+The onboarding answers (written by onboard.py) live in these files and are read
+here so every tool in this skill picks up the user's customization automatically.
+Set RESEARCH_OPS_NO_CONFIG=1 (or pass --no-config to a tool) to ignore saved config.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+SKILL = "clinical-research"
+
+GLOBAL_CONFIG_DIR = Path.home() / ".config" / "research-ops"
+GLOBAL_CONFIG_PATH = GLOBAL_CONFIG_DIR / f"{SKILL}.json"
+PROJECT_CONFIG_DIRNAME = ".research-ops"
+
+DEFAULTS: dict[str, Any] = {
+    "version": 1,
+    "skill": SKILL,
+    "default_profile": "drug",
+    "default_alpha": 0.05,
+    "default_power": 0.80,
+    "default_dropout": 0.15,
+    "owners": {
+        "biostatistician": None,
+        "medical_monitor": None,
+        "regulatory_owner": None,
+    },
+    "setup_completed_at": None,
+}
+
+
+def project_config_path(cwd: Path | None = None) -> Path:
+    cwd = cwd or Path.cwd()
+    return cwd / PROJECT_CONFIG_DIRNAME / f"{SKILL}.json"
+
+
+def _read_json(path: Path) -> dict[str, Any] | None:
+    try:
+        with path.open(encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else None
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def _deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for k, v in override.items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = _deep_merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def load_config(cwd: Path | None = None) -> dict[str, Any]:
+    """Effective config = DEFAULTS <- global <- project. Honors RESEARCH_OPS_NO_CONFIG."""
+    config = dict(DEFAULTS)
+    if os.environ.get("RESEARCH_OPS_NO_CONFIG") == "1":
+        return config
+    global_cfg = _read_json(GLOBAL_CONFIG_PATH)
+    if global_cfg:
+        config = _deep_merge(config, global_cfg)
+    project_cfg = _read_json(project_config_path(cwd))
+    if project_cfg:
+        config = _deep_merge(config, project_cfg)
+    return config
+
+
+def setup_completed() -> bool:
+    cfg = _read_json(GLOBAL_CONFIG_PATH) or _read_json(project_config_path())
+    return bool(cfg and cfg.get("setup_completed_at"))
+
+
+def write_config(config: dict[str, Any], scope: str = "global", cwd: Path | None = None) -> Path:
+    if scope == "project":
+        path = project_config_path(cwd)
+    else:
+        path = GLOBAL_CONFIG_PATH
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8") as f:
+        json.dump(config, f, indent=2, sort_keys=True)
+    return path
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=f"Inspect {SKILL} customization config.")
+    p.add_argument("--show", action="store_true", help="Print the effective config")
+    p.add_argument("--status", action="store_true", help="Print setup status + paths")
+    p.add_argument("--sample", action="store_true", help="Print the built-in defaults")
+    args = p.parse_args(argv)
+
+    if args.sample:
+        print(json.dumps(DEFAULTS, indent=2, sort_keys=True))
+    elif args.status:
+        print(json.dumps({
+            "skill": SKILL,
+            "global_config_path": str(GLOBAL_CONFIG_PATH),
+            "global_config_exists": GLOBAL_CONFIG_PATH.exists(),
+            "project_config_path": str(project_config_path()),
+            "project_config_exists": project_config_path().exists(),
+            "setup_completed": setup_completed(),
+        }, indent=2))
+    else:
+        print(json.dumps(load_config(), indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())