AI BioResearch Workflow

A safety-first reference scaffold for agent-assisted computational biology.

The central design rule is:

The verifier is the architecture; the generator is replaceable.

Claude Science, Biomni, Claude Code, and Codex are treated as distinct stations in one governed workflow, not as interchangeable chat assistants. Deterministic gates, human approval, explicit failure states, and machine-readable provenance sit between research stages.

Current status

This repository is an executable engineering reference implementation, not a validated clinical system and not a turnkey production platform.

What is implemented and regression-tested:

• data-plane classification and fail-closed guards for controlled data, PHI-shaped content, NIH grant/review paths, and MCP tool arguments;
• reproducibility guards for container digests, SRA Lite, iGenomes, random seeds, environment locks, and execution evidence;
• a seven-stage Q → H → D → I → E → V → R LangGraph with strict JSON-over-stdio model adapters, deterministic gates, Ed25519-verified human approval receipts, and an explicit DID_NOT_FINISH state;
• write-ahead KG staging (pending → asserted → retracted) and an official-SDK, read-only MCP facade that can expose only asserted;
• signed data/execution attestations, workflow-engine WRROC, and a clearly non-evidentiary Agent Run RO-Crate audit proposal;
• a real FastQC → Salmon → conservation assertions → MultiQC pipeline with synthetic positive-control nf-test coverage;
• a three-process DSL2 example with eight machine-readable implementation checks and a recorded successful L0 Q → H → D → I → E → V → R loop;
• hash-locked Python/Conda runtimes and digest-locked containers;
• deterministic unit and MCP protocol tests plus executable GitHub Actions CI.

What is intentionally not claimed as complete:

• hosted model credentials and commands are deliberately not committed; copy .lab/agent_commands.example.json to the ignored local configuration and provide reviewed argv/model IDs;
• bridge.tre_submit only prepares a code-only manual outbox package; it never performs TRE transport or handles credentials;
• the bundled pipeline establishes technical RNA-seq quantification validity only; it does not perform differential expression or support biological/clinical claims;
• Biomni remains optional and disabled until its image and compatibility are independently pinned and reviewed;
• institutional DUA, IRB, TRE, BAA, credential, and publication-policy review remain human responsibilities.

The loop therefore stops honestly when a required adapter, verified KG path, or approved execution plane is unavailable.

Architecture

Governance and data classification
                │
                ▼
Q ── G_Q ── H ── G_H ── D ── G_D ── I ── G_I
                                             │
                             signed authenticated-human approval
                                             │
                  demo L0 local fixture ◀────┤
        production external worker/TRE ◀─────┘
                                             │
E ── G_E ── V ── G_V ── signed human sign-off ── R
      │          │
      └──────────┴──► DID_NOT_FINISH when evidence or budget is missing

• Q — Question: falsifiable comparison, measurable endpoint, declared data level, and locally verified accession cache.
• H — Hypothesis: asserted KG paths, literature support, and heterogeneous adversarial review.
• D — Design: preregistration plus a machine-readable estimand, population, contrast, outcome, effect measure, multiplicity policy, missing-data strategy, and decision rule.
• I — Implementation: pipeline code, tests, digest-pinned containers, reference versions, locks, and embedded controls.
• E — Execution: only demo L0 fixtures may execute in this process. Every production level requires an independently signed receipt from the selected isolated worker or TRE.
• V — Verification: deterministic checks, claim-to-database checks, and independent recomputation.
• R — Report: only after a second named-human V→R sign-off; produces a draft report plus workflow and agent-run provenance.

Hard boundaries

The full constitution is in AGENTS.md. The most important boundaries are:

1. Controlled-data bytes never leave the approved enclave.
2. PHI never goes through connectors or MCP tools.
3. Production classification and execution decisions require signatures from a digest-pinned public-key trust store outside the agent-writable workspace.
4. Participant counts from 1 through 20 are suppressed for declared restricted projects.
5. Numeric scientific claims require execution evidence; missing evidence produces DID_NOT_FINISH, not synthetic results.

The small-count rule follows the All of Us Data and Statistics Dissemination Policy. These hooks are defense-in-depth and do not replace institutional compliance review.

Repository map

.claude/hooks/          deterministic governance hooks
.claude/skills/         shared research skills
.claude/agents/         specialist agent role descriptions
.github/workflows/      deterministic CI plus optional dual-model review
graph/                  gates, executable loop, agent adapters, KG staging
bridge/                 asserted-only KG MCP and optional Biomni bridge
pipelines/rnaseq_quant/ real digest-pinned RNA-seq integration workflow
pipelines/example_3process/ three-process deterministic teaching and CI fixture
provenance/             Agent Run Crate builder
tests/                  safety and deterministic-core regression tests
AGENTS.md               lab constitution and operating rules

.mcp.json activates the local asserted-only KG server alongside configured remote services. Biomni and ToolUniverse stay in .mcp.optional.json.example until their runtime, digest, and safety boundary are verified.

Validate the scaffold

Linux/macOS:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --require-hashes -r requirements.lock
make init
make check

Windows PowerShell (validation does not require GNU Make):

python -m pip install --require-hashes -r requirements.lock
python -m compileall -q .
python -m pytest -q tests

CLAUDE.md is version-controlled and imports the shared AGENTS.md constitution, then adds the Claude Code/Biomni/Codex routing contract. make init preserves it and creates only the shared skill links.

Run the dependency-light graph wiring check without model calls or data access:

make graph-smoke

For a Conda environment, install the platform-resolved lock:

conda-lock install --name bio-agent-lab conda-lock.yml
conda run -n bio-agent-lab python -m pip install --require-hashes -r requirements.lock

Run the real synthetic pipeline tests with the declared nf-test profile:

make pipeline-test
make pipeline-example-test
make example-gate

Running the governed loop

• configure and locally review every backend in .lab/agent_commands.json;
• declare every data source in .lab/data_sources.json;
• populate .lab/accession_cache.json from authoritative database checks;
• copy .lab/tre_endpoint.example.json to the ignored .lab/tre_endpoint.json, then configure the institution-approved manual TRE handoff for L2 work;
• set LAB_PI_NAME and, if used, LAB_PI_ORCID;
• exercise both the success path and a deliberately failing path;
• obtain human scientific, privacy, security, and institutional review.

make demo is the explicit L0 fixture route. It may use synthetic reviewers, but it still stops at both human gates and still requires the native nf-test and nextflow executables at G_I:

make demo QUESTION="Does the declared L0 control pass?" THREAD=demo-1

The command writes the exact interrupt to .lab/loops/demo-1/approvals/pending_request.json and exits. A human or an external approval service must create a receipt from .lab/approval_receipt.example.json. The receipt must contain the authenticated human subject and be Ed25519-signed outside this repository. Resume one interrupt with a public-key store located outside the workspace and pinned by an out-of-band SHA-256:

make demo QUESTION="Does the declared L0 control pass?" THREAD=demo-1 \
  RESUME=1 APPROVAL=/reviewed/pre-execution-receipt.json \
  TRUST_STORE=/policy/trusted-public-keys.json \
  TRUST_STORE_SHA256=<out-of-band-sha256>

Repeat the receipt-and-resume step for the post-verification gate. A command-line name or unsigned JSON is not approval, and the runner never possesses a private signing key. Any recovery action restarts at intake and invalidates downstream contracts.

make loop is the production route. It rejects fixture backends and requires an explicit pipeline and reviewed backend configuration:

make loop \
  QUESTION="Does the registered public-data contrast satisfy its decision rule?" \
  THREAD=study-1 \
  LEVEL=L1 \
  PIPELINE=pipelines/rnaseq_quant/main.nf \
  PROFILE=apptainer \
  AGENT_COMMANDS=.lab/agent_commands.json \
  DATA_MANIFEST=/classification/study-1.signed.json \
  TRUST_STORE=/policy/trusted-public-keys.json \
  TRUST_STORE_SHA256=<out-of-band-sha256>

python -m graph.first_loop \
  --mode production \
  --question "Does the registered public-data contrast satisfy its decision rule?" \
  --thread study-1 \
  --level L1 \
  --pipeline pipelines/rnaseq_quant/main.nf \
  --profile apptainer \
  --agent-commands .lab/agent_commands.json \
  --data-manifest /classification/study-1.signed.json \
  --trust-store /policy/trusted-public-keys.json \
  --trust-store-sha256 <out-of-band-sha256>

For L0, also provide INPUT_ROOT/--input-root; every local input and related file is re-hashed. L1/L2 manifests must use controlled-plane URIs (s3://, gs://, az://, or tre://; L2 accepts only tre://), so this orchestrator never opens their raw bytes.

Production does not run Nextflow locally. After the authenticated pre-execution approval, an approved worker executes .lab/loops/<thread>/execution/params.json and returns an Ed25519-signed execution receipt. Resume with both the approval and execution receipt:

make loop ... THREAD=study-1 RESUME=1 \
  APPROVAL=/reviewed/pre-execution.json \
  EXECUTION_RECEIPT=/worker/study-1.execution.json \
  EXTERNAL_RUN_ROOT=/worker/runs

Every design, approval request, run, report, and agent-call record is written under .lab/loops/<thread>/. Each pipeline declares a claim contract. The frozen ResearchContract binds its preregistration, machine-readable analysis plan, signed data manifest, pipeline bundle, execution policy, and primary claim ID. These identifiers enter the Nextflow parameter file and must reappear in assertions, claims, command evidence, and all three verification tiers.

The bundled examples are technical_qc contracts with supports_hypothesis: false. They terminate as technical_validation_only; the report says NOT EVALUATED and cannot promote a scientific KG edge. A scientific claim contract must exactly match the analysis plan's population, contrast, outcome, estimand, effect measure, decision rule, multiplicity handling, and missing-data strategy.

The demo runner invokes host-managed Nextflow and never mounts the Docker daemon socket. Production accepts only an externally signed isolation attestation whose artifact hashes match the frozen contract. Missing nf-test or nextflow fails G_I; repository pytest is not a substitute.

The operational key custody, signing, controlled-URI, worker isolation, and receipt requirements are specified in docs/trust_and_execution.md.

Provenance boundary

The Workflow Run RO-Crate produced by nf-prov is execution evidence. Production also requires the independent executor's signed artifact manifest. The Agent Run Crate is generated by the system being audited, is marked audit-only and selfAsserted, and cannot satisfy G_E or support a scientific claim. Its profile remains a local proposal, not a registered standard. Approval, data-classification, and execution-attestation keys are separate duty classes; one public key cannot authorize more than one class.

License

Apache License 2.0. See LICENSE.