{
  "markdown": "# Research Repo Doctor\n\n<!-- mcp-name: io.github.Tom409114/rrdoctor -->\n\nGet your research artifact ready for Artifact Evaluation before the deadline:\nscan the repo, scaffold the easy fixes, verify the run path, and generate the appendix.\n\nWeb demo for public repos: <https://research-repo-doctor-bckncrcwwmg6jrbsrd6btj.streamlit.app/>\nIf the hosted demo is waking up or reinstalling dependencies, the local zero-install\ncommand below is the reliable fallback:\n\n```bash\nuvx rrdoctor scan .\n```\n\nMaintainers can check anonymous demo access with\n`python scripts/check_live_demo.py https://research-repo-doctor-bckncrcwwmg6jrbsrd6btj.streamlit.app/`.\n\n![rrdoctor demo](docs/demo.gif)\n\n[![CI](https://github.com/Tom409114/research-repo-doctor/actions/workflows/ci.yml/badge.svg)](https://github.com/Tom409114/research-repo-doctor/actions/workflows/ci.yml)\n[![rrdoctor readiness](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Tom409114/research-repo-doctor/main/.rrdoctor-badge.json)](https://github.com/Tom409114/research-repo-doctor)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](pyproject.toml)\n\n`rrdoctor` is a local CLI and GitHub Action for research artifact preparation. It audits\nwhether a repo is reviewable, citable, and close to runnable; scaffolds safe mechanical\nfixes; maps findings to an AE-style readiness level; and turns the rest into a checklist\nany coding agent or human can finish.\n\n## Make it a pull-request gate\n\nThe GitHub Action is the main adoption path: run the CLI while preparing the\nartifact, then keep the same deterministic preflight on every pull request.\n\n```yaml\nname: Reproducibility preflight\n\non:\n  pull_request:\n  push:\n    branches: [main]\n\npermissions:\n  contents: read\n\njobs:\n  rrdoctor:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v7\n      - uses: Tom409114/research-repo-doctor@v0.2.24\n        with:\n          profile: standard\n          fail-on: error\n```\n\nThe full [GitHub Action guide](docs/github-action.md) covers sticky PR comments,\nnew-finding baselines, agent plans, appendices, and complete AE prep packets.\n\n## AE deadline loop\n\n```bash\nuvx rrdoctor prepare . --profile acm --out-dir rrdoctor-prep\n\n# Or run the pieces explicitly:\nuvx rrdoctor scan . --profile acm\nuvx rrdoctor fix . --write\nuvx rrdoctor appendix . --profile acm --output ARTIFACT_APPENDIX.md\nuvx rrdoctor verify . --profile acm\nuvx rrdoctor verify . --profile acm --run --timeout 600 --fail-on error  # trusted repos only\n# Or pin the official quickstart command as the dynamic gate:\nuvx rrdoctor verify . --profile acm --command \"python train.py config/default.py\" --run --timeout 600 --fail-on error\n```\n\nFor trusted repositories, `rrdoctor verify --run` can go beyond static checks. For supported\nPython repositories it creates a temporary isolated environment, installs declared\ndependencies, and executes the declared entrypoint there under a timeout. Other ecosystems\nretain an explicit resolver preflight. With the default gate (`--fail-on error`), failed or\nblocked dynamic L2/L3 steps return a nonzero exit code. Use `--command` when the artifact has\na specific smoke-test or quickstart command that reviewers should run. Dynamic mode may run\ndependency build/install hooks as well as the entrypoint, so never use it on untrusted code.\n`rrdoctor prepare` writes the report, agent plan, artifact appendix, and verification ladder\ninto one local evidence directory.\n\nArtifact Evaluation chairs and lab maintainers can use the\n[AE chair guide](docs/ae-chair-guide.md) for optional pre-submission wording and\nCI examples.\n\nFor public calibration evidence, see the\n[80-repository data brief](docs/corpus-data-brief.md) and the\n[nanoGPT first-run regression case study](docs/case-studies/nanogpt.md).\n\n## What it catches\n\n- **\"Your `--seed` flag does nothing.\"** `RRD052` spots code that declares a seed option but\n  never calls `random.seed`, `np.random.seed`, `torch.manual_seed`, `tf.random.set_seed`, or\n  `random_state=seed`.\n- **\"This worked on my laptop.\"** Local-only data paths, missing data provenance, and\n  undocumented retrieval steps.\n- **\"The environment silently changed.\"** Unpinned dependencies, missing runtime versions,\n  undeclared imports, and absent dependency manifests.\n- **\"The notebook lies.\"** Stale outputs, out-of-order execution, checkpoint artifacts, and\n  secret-like notebook output.\n- **\"Reviewers cannot tell how to cite or rerun this.\"** Missing license, citation, CI,\n  tests, changelog, results provenance, or experiment entrypoint.\n\n## Install\n\nRun once, without installing:\n\n```bash\nuvx rrdoctor scan .\n```\n\nAlternatives:\n\n```bash\npipx run rrdoctor scan .\npip install rrdoctor\nrrdoctor scan .\n```\n\nDeveloper install from source:\n\n```bash\ngit clone https://github.com/Tom409114/research-repo-doctor.git\ncd research-repo-doctor\npython -m pip install -e \".[dev]\"\nrrdoctor scan .\n```\n\n## Fix the easy gaps\n\nLet `rrdoctor` create the safe scaffolding for you. It is deterministic, idempotent, and\nnever overwrites existing files.\n\n```bash\nrrdoctor fix . --write\n```\n\nIt can scaffold missing governance docs, citation metadata, data/results provenance notes,\na reproducible-seed helper, changelog entries, and common research `.gitignore` entries.\nThe hard parts become a reviewable plan:\n\n```bash\nrrdoctor plan . --output plan.md\n```\n\n## Use with your coding agent\n\nPaste this into Claude Code, Cursor, GitHub Copilot, or any other coding agent:\n\n```text\nUse rrdoctor as the deterministic, offline, no-API-key grader for this research repo.\n\nRun:\nrrdoctor scan . --format json --output baseline.json\nrrdoctor plan . --output plan.md\n\nWork through plan.md without weakening rrdoctor checks.\n\nDefinition of done:\nrrdoctor scan . --baseline baseline.json --fail-on-new error\n```\n\nThe final command is the objective gate: it verifies the agent's work against the starting\nbaseline and fails only on newly introduced errors.\n\nCopyable agent templates are available for Agent Skills / Claude Code-style workflows and\nCursor project rules under [integrations/](integrations/).\n\nKeywords: research software, reproducibility, artifact evaluation, repository audit, auto-fix,\ncoding agents, AGENTS.md, GitHub Action, notebooks, data availability, citation metadata.\n\n## Help calibrate the rules\n\nThe fastest way to improve rrdoctor is real scan feedback from real research\nrepositories. After one scan, the low-friction\n[10-minute trial report](https://github.com/Tom409114/research-repo-doctor/issues/new?template=trial_report.yml)\nasks only what was useful, wrong or missing, and whether the tool fits a real\ndeadline. For a focused rule report, please open a\n[false-positive](https://github.com/Tom409114/research-repo-doctor/issues/new?template=false_positive.yml),\n[false-negative](https://github.com/Tom409114/research-repo-doctor/issues/new?template=false_negative.yml),\n[scan-case](https://github.com/Tom409114/research-repo-doctor/issues/new?template=scan_case.yml),\nor [new-rule](https://github.com/Tom409114/research-repo-doctor/issues/new?template=rule_request.yml)\nissue. Include the rule ID, command, rrdoctor version, and a sanitized minimal\nrepo shape. See [feedback and calibration](docs/feedback.md) for the short checklist.\n\n## Why this matters\n\nResearch code often lands on GitHub under deadline pressure. A reviewer or future lab\nmember finds a promising repository and then loses hours because the environment is\nunderspecified, data paths are local, notebooks contain stale outputs, dependencies are\nunpinned, or the citation is unclear.\n\nResearch Repo Doctor turns those recurring release blockers into deterministic checks with\nconcrete remediation - and, where it is safe to do so, scaffolds the mechanical starting\npoints. It is built to sit in the ordinary maintenance path: run locally while preparing\na release, then run automatically on pull requests through GitHub Actions.\n\nThe audit runs without an AI API key, network access, or hosted service. That same\ndeterminism makes it an honest grader: it can verify fixes made by a person or a coding\nagent.\n\n```text\naudit -> fix -> plan -> (your coding agent / you) -> verify -> PR\n  |       |       |                                  |\n  |       |       rrdoctor plan                      rrdoctor scan --baseline\n  |       rrdoctor fix --write                       --fail-on-new error\n  rrdoctor scan\n```\n\n## What's new in 0.2.24\n\n- **Better systems-artifact coverage**: existing checks now recognize Cargo,\n  CMake, Meson, container, and Nix evidence plus documented artifact scripts\n  and Cargo commands across entrypoint, test, CI, and release workflows.\n- **Quieter static scans**: target-source `SyntaxWarning` noise is suppressed,\n  and escaped Python exception text no longer looks like a local Windows path.\n- **A rechecked first-run trust case**: public PyPI `rrdoctor==0.2.23` still\n  scores nanoGPT as `Functional` at 76/100 with 0 errors, while the original\n  noisy `RRD050` and `RRD063` findings remain absent.\n- **An explicit JOSS boundary**: the draft-paper notes now separate the\n  more-than-six-month public-history gate from research-use, authorship,\n  conflict-of-interest, and AI-disclosure evidence that maintainers must supply.\n- **A configuration file that actually governs the scan**: CLI and MCP calls\n  load the target repository's `.rrdoctor.yml` from any working directory;\n  profile, report, threshold, failure, include/exclude, and rule settings now\n  work beneath explicit CLI overrides.\n\n## What's new in 0.2.23\n\n- **A safer release path**: the hosted demo can stay pinned to the latest\n  published PyPI package while a new release propagates, avoiding broken\n  Streamlit deployments during Trusted Publishing.\n- **A first-class GitHub Action path**: a compact pull-request workflow now\n  appears near the top of the README and is guarded by public-readiness tests.\n- **A shorter feedback loop**: completed web-demo scans link to a structured\n  10-minute trial report for useful findings, false positives, false negatives,\n  and real deadline fit.\n- **Official MCP Registry distribution**: `v0.2.24` is published as\n  [`io.github.Tom409114/rrdoctor`](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.Tom409114/rrdoctor),\n  with MCP support remaining an optional extra rather than a core scanner\n  dependency. Registry inclusion is distribution metadata, not endorsement or\n  evidence of adoption.\n- **Stronger dynamic verification coverage**: an offline integration test proves\n  L3 can install and import a declared local wheel inside its temporary Python\n  environment.\n\n## What's new in 0.2.22\n\n- **Real Python environment verification**: `rrdoctor verify --run` now creates\n  a temporary isolated venv, installs the repository's declared dependencies,\n  and runs L3 with that interpreter and PATH instead of stopping at a resolver\n  dry run.\n- **Honest execution boundaries**: verification reports disclose dependency\n  build-hook risk, redact machine-specific temporary paths, and remove the\n  temporary environment after the run. Other ecosystems retain an explicit\n  resolver preflight.\n- **Stronger isolation checks**: inherited `PYTHONHOME` and `PYTHONPATH` values\n  are removed, and versioned launchers such as `python3.10` are redirected to\n  the temporary environment.\n\n## What's new in 0.2.21\n\n- **More honest corpus evidence**: the public 80-repository calibration corpus\n  now has 80 focused review notes, 0 repositories awaiting focused review, and\n  a concise data brief that explains what the corpus does and does not prove.\n- **Lower-noise model-release scans**: `RRD050` and `verify` now recognize\n  common model-release entrypoints such as `demo.py`, `inference.py`,\n  `predict.py`, `sample.py`, and `generate.py` in root, `scripts/`, and\n  `tools/` layouts.\n- **Less noisy secret checks**: `RRD063` and `RRD090` now require stronger\n  entropy evidence for generic `api_key`/`token`/`secret`/`password`\n  assignments while still flagging provider-shaped keys.\n- **More agent integrations**: the repository includes copyable GitHub Copilot\n  instructions alongside the existing Agent Skill and Cursor templates for the\n  baseline -> plan -> verify loop.\n- **Clearer launch artifacts**: the JOSS draft now states the evaluation\n  evidence and limitations more explicitly, and the live-demo check now follows\n  Streamlit's anonymous redirect handshake before deciding whether the app is reachable.\n\n## What's new in 0.2.20\n\n- **Lower-noise mature scientific package scans**: `RRD010` now recognizes\n  common license filenames such as `LICENSE.txt`, and `RRD043` ignores\n  CI/devcontainer paths, tests/fixtures, URL path segments, and documented\n  placeholder/example absolute paths.\n- **Lower-noise library and secret heuristics**: `RRD050` no longer treats\n  mature package/library projects, including common nested `package/` layouts,\n  as missing paper experiment entrypoints, and `RRD090` ignores URL query\n  tokens, local function-call or method-call token variables, generic fake\n  tokens in test helpers, and provider-looking substrings embedded inside\n  longer biological/test sequences.\n- **More reviewed corpus evidence**: SciPy is a focused review case and an\n  expected-absent regression gate for `RRD010` and `RRD043`; scikit-image,\n  JAX, NetworkX, Keras, Transformers, PyTorch Lightning, Biopython,\n  torchvision, MDAnalysis, QuTiP, ESM, stable-diffusion, detectron2,\n  DINO, StyleGAN2-ADA PyTorch, instant-ngp, Big Vision, latent-diffusion,\n  taming-transformers, generative-models, pytorch-image-models, Brax, ArviZ,\n  PyMC, Pyro, TensorFlow Probability, statsmodels, Optax, and the remaining\n  corpus entries now add first-run trust gates or focused review evidence. The\n  latest 80-repository corpus gate has 0 expected-absent regressions, 80\n  reviewed notes, and 0 repositories still awaiting focused review.\n- **Less template-like auto-fix output**: `rrdoctor fix --write` can now read\n  simple literal `setup.py` metadata statically, without executing repository\n  code, when generating citation and provenance scaffolds.\n- **More filled Artifact Appendix access notes**: `rrdoctor appendix` reuses the\n  same local metadata inference to pre-fill repository URLs and versions for\n  legacy `setup.py`/`setup.cfg` projects.\n- **More realistic L2 environment checks**: `rrdoctor verify --run` now resolves\n  common nested Python requirement files such as `requirements/base.txt` and\n  `requirements/main.txt`, plus `.yaml` Conda environment files, instead of\n  skipping those repository layouts.\n- **Lower-noise notebook secret checks**: `RRD063` now shares the test/fixture\n  generic fake-token suppression used by `RRD090`, while still flagging\n  standalone provider-style keys.\n\n## What's new in 0.2.19\n\n- **Lower-noise experiment entrypoint detection**: `RRD050` now recognizes\n  package-level research binaries such as `t5x/train.py`, documented\n  `python3 ${T5X_DIR}/t5x/train.py` commands, and notebook-first artifacts with\n  clearly named demo/example/reproduce notebooks such as `graphcast_demo.ipynb`.\n- **More first-run corpus evidence**: focused review notes now cover 32/60 seed\n  corpus repositories. The latest 60-repository static corpus scan has 0\n  expected-absent regressions and keeps t5x and GraphCast as entrypoint\n  regression gates.\n\n## What's new in 0.2.18\n\n- **Lower-noise dependency checks**: `RRD034` now parses Python AST imports\n  instead of regex-matching source text, so comments, docstrings, and prose\n  examples do not look like missing packages.\n- **Runtime-focused dependency signal**: docs, tests, benchmarks, vendored code,\n  maintainer tooling, `conftest.py`, build-system requirements, and local\n  sibling modules are filtered out before dependency-gap reporting.\n- **More corpus review evidence**: focused review notes now cover 30/60 seed\n  corpus repositories, including scikit-learn, Astropy, scvi-tools, and DINOv2\n  checks for dependency-signal noise.\n- **Current install path**: PyPI, GitHub Action examples, demo requirements,\n  citation metadata, and the self-scan report are aligned to this release.\n\n## What's new in 0.2.15\n\n- **Clearer verification evidence**: `rrdoctor verify` reports now lead with\n  the gate outcome, failure threshold, timeout, trust boundary, rerun command,\n  and the source of any L3 dynamic command.\n- **Stronger Artifact Appendix scaffolding**: `rrdoctor appendix` now pre-fills\n  local README/project metadata, dependency manifests, data/results docs,\n  config files, and detected entrypoint commands where available.\n- **More useful generated data notes**: `rrdoctor fix --write` carries over\n  candidate dataset URLs, DOIs, README data commands, and local data scripts\n  when scaffolding `DATA.md`.\n- **Maintainer launch gates**: `python scripts/check.py` and\n  `python scripts/check_public_readiness.py` provide cross-platform local checks\n  for release, JOSS, Artifact Evaluation, and public outreach readiness.\n\n## What's new in 0.2.14\n\n- **One-command AE evidence packet**: `rrdoctor prepare` writes the static\n  report, agent fix plan, Artifact Appendix, and verification ladder into one\n  local directory for deadline handoff.\n- **CI-uploaded AE packet**: the GitHub Action now supports `prepare: \"true\"`\n  and `prepare-output`, so pull requests and release gates can upload the same\n  reviewer-ready packet.\n- **Pinned run-path verification**: `verify --command \"...\"`, the Action\n  `verify-command` input, and the MCP `verify` tool let maintainers pin the\n  official quickstart command and timeout as the L3 gate.\n- **Lower first-run noise**: MAE-style root `main_*.py` scripts, AlphaFold-style\n  `random_seed=` plumbing, test-file randomness, and placeholder absolute paths\n  are handled more conservatively.\n\n## What's new in 0.2.13\n\n- **Scan reports now lead to the AE workflow**: Markdown reports and agent fix\n  plans now include next-step commands for `rrdoctor plan`, `rrdoctor appendix`,\n  static `rrdoctor verify`, and trusted-only dynamic `verify --run`.\n- **Stronger auto-fix scaffolds**: generated `AGENTS.md` files now include the\n  scan -> plan -> baseline verification loop, and generated results-provenance\n  notes include local repository context, current result files, and a structured\n  result inventory table.\n- **Better adoption materials**: public docs now include a feedback/calibration\n  path and an Artifact Evaluation chair guide with optional pre-submission\n  wording and CI examples.\n\n## What's new in 0.2.12\n\n- **Trusted dynamic Action gate**: GitHub Action users can now set\n  `verify-run: \"true\"` plus `verify-fail-on: error` so trusted dynamic\n  verification blocks CI while still uploading the verification report.\n- **Agent distribution templates**: repository Copilot instructions, an Agent\n  Skill template, and a Cursor project rule make the deterministic\n  scan -> plan -> verify loop copyable across coding-agent workflows.\n- **Tighter evidence wording**: corpus and JOSS draft wording now distinguishes\n  focused review notes from full manual repository audits.\n\n## What's new in 0.2.11\n\n- **First-run trust tuning**: README install/run commands, seeded local RNGs,\n  PyTorch parameter initialization, UUID-like identifiers, and classic ML repos\n  now produce fewer false positives.\n- **Real dynamic gate**: `rrdoctor verify --run --fail-on error` now exits\n  nonzero when dependency resolution or the detected run path fails or is blocked.\n- **More calibration evidence**: 22 focused review notes are now committed,\n  including BERT, CLIP, improved-diffusion, MAE, and AlphaFold follow-ups with\n  expected-absent checks for fixed noisy findings.\n\n## What's new in 0.2.10\n\n- **More reliable corpus calibration**: the public evaluation-corpus runner now\n  falls back to GitHub archives when `git clone` times out, keeping first-run\n  trust checks less dependent on flaky transport.\n- **Cleaner maintainer automation**: first-party workflows and documentation\n  examples now use current Node 24-compatible GitHub Actions releases.\n- **Sharper diagnostics**: `rrdoctor doctor` now reports optional MCP\n  integration availability only when the package and import-time dependencies\n  actually load.\n\n## What's new in 0.2.9\n\n- **Clearer first-run CLI behavior**: `rrdoctor --version` now reports the\n  installed package version, and running bare `rrdoctor` prints the root help\n  page successfully.\n\n## What's new in 0.2.8\n\n- **Better README run-path recognition**: README-documented\n  `python -m package.train ...` commands now count as experiment entrypoints\n  when they map to local repository modules.\n- **Stronger dynamic verification for ML launchers**: `rrdoctor verify` now\n  recognizes module-runner commands such as\n  `python -m torch.distributed.run train.py ...` when they include a local\n  Python entrypoint.\n\n## What's new in 0.2.7\n\n- **Better citation scaffolds**: `rrdoctor fix --write` now reads structured\n  PEP 621 and Poetry metadata, preserves multiple authors, normalizes SSH git\n  remotes, and handles git worktree origin URLs when generating `CITATION.cff`.\n- **Lower-noise dependency checks**: `RRD034` now understands PEP 621 environment\n  markers and Poetry dependency groups, reducing undeclared-import false positives.\n\n## What's new in 0.2.6\n\n- **Lower-noise secret checks**: Rcpp `Generator token` markers and public\n  pkgdown `docsearch.api_key` search configuration no longer trigger `RRD090`,\n  while generic credential-like API keys still do.\n- **More reliable corpus scans**: the evaluation runner now falls back to\n  GitHub archive downloads when `git clone` transport is flaky, without\n  installing or executing target repositories.\n- **More manual calibration evidence**: the current public corpus snapshot\n  covers 60/60 successful static scans, 22 focused review notes loaded in that\n  snapshot, and 0 expected-absent regressions.\n\n## What's new in 0.2.5\n\n- **Model-release entrypoints**: README-documented `python scripts/*.py` /\n  `python tools/*.py` commands and pyproject-declared CLI commands now count as\n  experiment entrypoints, reducing first-run false positives on repositories\n  such as Segment Anything and Whisper.\n- **ML tools entrypoints**: common `tools/train.py`, `tools/test.py`, and\n  related ML framework commands now count for `RRD050`.\n- **Seed helper scaffolding**: `rrdoctor fix --write` can scaffold a\n  reproducible `set_global_seed(seed)` helper for `RRD052` without overwriting\n  project code.\n- **Corpus regression gates**: entrypoint fixes are backed by focused review\n  notes and `expected_absent` checks in the public evaluation corpus.\n\n## What's new in 0.2.4\n\n- **First-run trust improvements**: root-level `train.py`/`main.py`/`run.py`,\n  Snakemake/Nextflow workflows, and README run commands count as experiment entrypoints.\n- **Lower-noise security checks**: notebook and repository secret detection now requires\n  high-confidence credential-like values before raising blocking errors.\n- **More realistic README checks**: concrete training, evaluation, benchmark, workflow, or\n  reproduction commands count as evidence for reproducing results.\n- **Corpus-backed rule calibration**: the public evaluation corpus tracks false-positive and\n  false-negative review notes, expected-absent regression gates, and aggregate rule frequencies.\n- **Release hygiene**: citation guidance detection recognizes README Citing sections, BibTeX,\n  DOI links, and \"please cite\" text; local git tags count as deterministic version evidence.\n- **Release polish**: the demo GIF is generated, issue access is open, and the committed\n  self-scan report is 100/100.\n\n## What's new in 0.2.0\n\n- **`rrdoctor fix`** provides deterministic, idempotent auto-fix for common gaps (governance\n  docs, citation metadata, data/results provenance, seed helper scaffolding, changelog, ignore\n  entries). Never overwrites.\n- **`rrdoctor plan`** emits a tool-agnostic fix plan you can hand to any coding agent; every\n  task names the deterministic check that verifies it.\n- **Baseline gating**: `rrdoctor scan --baseline report.json --fail-on-new error` fails only\n  on newly introduced findings, so large repos can adopt the audit incrementally.\n- **`rrdoctor badge`** emits a Shields.io endpoint or SVG artifact-readiness badge.\n- **Artifact readiness labels** map findings to an AE-style level: `Available`,\n  `Functional`, or `Reproduced-ready`. The numeric score remains as a secondary\n  triage signal.\n- **First-class PR automation**: the Action posts a sticky PR comment, writes a job summary,\n  and can attach the fix plan, using only the built-in `GITHUB_TOKEN`.\n- **New rules** include unpinned dependencies, committed notebook checkpoints, pre-commit\n  config, and an AGENTS.md task guide for agent and human contributors.\n\n## Quickstart\n\n```bash\nrrdoctor scan .                   # deterministic audit (Markdown report)\nrrdoctor fix . --write            # apply safe scaffolding for easy gaps\nrrdoctor plan . --output plan.md  # tool-agnostic work order for the rest\nrrdoctor scan . --format json --output baseline.json --fail-on none\nrrdoctor scan . --baseline baseline.json --fail-on-new error  # gate regressions\n```\n\nStricter gate and report file:\n\n```bash\nrrdoctor scan . --profile strict --fail-on warning --output rrdoctor-report.md\n```\n\nMachine-readable and agent output:\n\n```bash\nrrdoctor scan . --format sarif --output rrdoctor.sarif --fail-on none\nrrdoctor scan . --format agent --output fix-plan.md\n```\n\nBefore a submission deadline:\n\n```bash\nrrdoctor prepare . --profile acm --out-dir rrdoctor-prep          # one local AE packet\nrrdoctor appendix . --profile acm --output ARTIFACT_APPENDIX.md   # appendix + checklist mapping\nrrdoctor verify . --profile neurips                               # L1/L2/L3 ladder (static)\nrrdoctor verify . --run --timeout 600 --fail-on error              # build + run gate (trusted repos)\nrrdoctor verify . --command \"python train.py config/default.py\" --run --timeout 600\n```\n\nSubmission profiles: `acm`, `neurips`, `icml`, `ml-paper`, `fair4rs`, `joss` (alongside the\ngeneral `minimal`/`standard`/`strict`/`ml` tiers). Static dependency and runtime checks also\nunderstand R, Julia, Rust/Cargo, CMake-based builds, containers, and Nix environments, not just\nPython and JavaScript.\n\n## The audit -> fix -> verify loop\n\nA deterministic checker is reproducible and trustworthy but cannot write prose or judge\nintent. A coding agent edits well but needs a precise specification and an objective\ndefinition of done. Research Repo Doctor gives you both:\n\n1. **Audit**: `rrdoctor scan` produces deterministic findings.\n2. **Fix the easy ones**: `rrdoctor fix --write` scaffolds governance docs, citation metadata,\n   provenance notes, a seed helper, a changelog, and ignore entries (idempotent, never\n   overwriting).\n3. **Plan the rest**: `rrdoctor plan` emits a tool-agnostic work order. Paste it into the\n   coding agent of your choice, attach it to an issue, or work it by hand.\n4. **Verify**: re-run the audit against a baseline. Because verification is deterministic\n   and key-free, it works as an honest grader for changes from any source.\n\nSee [docs/agent-workflows.md](docs/agent-workflows.md) and [docs/autofix.md](docs/autofix.md).\n\n## GitHub Action\n\nAdd one workflow to many repositories and get consistent reproducibility reports on pull\nrequests and pushes. The Action requires no API key.\n\n```yaml\nname: Reproducibility audit\n\non:\n  pull_request:\n\npermissions:\n  contents: read\n  pull-requests: write\n\njobs:\n  rrdoctor:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v7\n      - uses: Tom409114/research-repo-doctor@v0.2.24\n        with:\n          profile: standard\n          fail-on: none\n          comment-pr: \"true\"     # sticky PR comment with the report\n          step-summary: \"true\"   # report in the job summary\n          plan: \"true\"           # attach an agent-ready fix plan\n          appendix: \"true\"       # attach an Artifact Evaluation appendix\n          verify: \"true\"         # attach the L1/L2/L3 verification ladder\n          prepare: \"true\"        # upload a complete AE prep packet directory\n          # For trusted repos, add verify-run: \"true\" and verify-fail-on: error\n```\n\nFor new-finding gating and a committed baseline, see\n[docs/pull-request-automation.md](docs/pull-request-automation.md).\n\n## Example output\n\n```text\nResearch Repo Doctor Summary\nProfile: standard\nReadiness: Functional\nScore: 64/100\nErrors: 0\nWarnings: 5\nRules evaluated: 32\n\nHow to fix first:\n- RRD030 No dependency manifest found: Add pyproject.toml, requirements.txt, or another manifest.\n- RRD040 Data availability documentation missing: Add DATA.md, docs/data.md, or a README section.\n```\n\nWorked examples live in [examples/reports/](examples/reports/), including a\n[fix plan](examples/reports/fix-plan.md) and a [self-scan report](examples/reports/self-scan-report.md).\n\n## Commands\n\n| Command | Purpose |\n| --- | --- |\n| `rrdoctor scan` | Run the deterministic audit; supports `--baseline` and `--fail-on-new`. |\n| `rrdoctor fix` | Apply safe, idempotent scaffolding for common gaps (`--write` to apply). |\n| `rrdoctor plan` | Emit a tool-agnostic fix plan (Markdown or JSON). |\n| `rrdoctor prepare` | Write a local AE prep packet: report, plan, appendix, and verification. |\n| `rrdoctor verify` | Reproducibility ladder L1/L2/L3; `--command` pins the official quickstart; `--run` actually builds and executes. |\n| `rrdoctor appendix` | Generate an ACM Artifact Appendix + ACM/NeurIPS checklist mapping. |\n| `rrdoctor badge` | Emit an artifact-readiness badge (Shields.io endpoint or SVG). |\n| `rrdoctor mcp` | Run the MCP server (`scan`/`verify`/`appendix` as agent tools). |\n| `rrdoctor init` | Write a documented `.rrdoctor.yml`. |\n| `rrdoctor list-rules` | List all registered rules. |\n| `rrdoctor explain RRD0xx` | Explain a rule and how to remediate it. |\n| `rrdoctor doctor` | Self-diagnostics. |\n| `rrdoctor --version` | Show the installed package version. |\n\n## Rule categories\n\nDocumentation, environment, data, experiments, notebooks, citation, governance, testing,\nCI, security, release, and metadata. The full table is in [docs/checks.md](docs/checks.md);\nauto-fixable rules are marked there.\n\n## Reproducibility stance\n\nResearch Repo Doctor does not claim to prove a paper is reproducible. It checks release\nhygiene that makes reproduction possible to attempt. Reports are heuristic and should be\nreviewed by maintainers. Generated fixes are starting points and contain placeholders to\ncomplete before release.\n\n## Philosophy\n\nDeterministic first. The scanner is understandable, testable, and useful with no network\naccess. The core scanner will not add network calls, require a hosted-service API key, or\nfabricate adoption metrics. AI is something you bring to act on the output - never a\ndependency of the audit itself, and never tied to a single tool.\n\n## Configuration\n\n```yaml\nversion: 1\nprofile: standard\npaths:\n  exclude: [\".git\", \".venv\", \"node_modules\", \"__pycache__\"]\nthresholds:\n  large_file_mb: 50\n  large_notebook_output_kb: 1024\nrules:\n  RRD032:\n    enabled: false\n  RRD042:\n    severity: warning\nfail_on: error\n```\n\nSee [docs/configuration.md](docs/configuration.md).\n\n## Contributing\n\nContributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md),\nopen a rule request or false-positive report, and include a minimal fixture when possible.\n\n## Security\n\nDo not report suspected credential exposure in a public issue. See [SECURITY.md](SECURITY.md).\n\n## Citation\n\nUse the included [CITATION.cff](CITATION.cff) or cite the version DOI for this\nrelease: [10.5281/zenodo.21289885](https://doi.org/10.5281/zenodo.21289885).\nThe stable concept DOI,\n[10.5281/zenodo.21045161](https://doi.org/10.5281/zenodo.21045161), resolves to\nthe latest archived release and preserves the complete version lineage.\n\nA JOSS-style draft manuscript is available in [paper/](paper/) for review. It is\nnot a submitted manuscript and intentionally avoids unverified adoption claims;\nformal submission metadata will be updated only when it is true.\n\n```bibtex\n@software{research_repo_doctor_2026,\n  title = {Research Repo Doctor},\n  author = {{Research Repo Doctor Maintainers}},\n  version = {0.2.24},\n  year = {2026},\n  doi = {10.5281/zenodo.21289885},\n  url = {https://github.com/Tom409114/research-repo-doctor}\n}\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 32523,
  "sha": "ffc5704ca12f177a06f59e7446d11cab1c92596ade61da9bf8cd472633e60cd6",
  "repo_slug": "tom409114/research-repo-doctor",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tom409114_rrdoctor_80e2bed1/readme"
}