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;
• Honest Demo (make demo-honest): zero-credential tour with intentional failure paths (DID_NOT_FINISH, blocked promotions, unsigned approvals);
• Fabrication Resistance Suite (make frs / docs/FRS.md): public attack cases that must fail closed;
• scientific inference narrow path (make scientific-path): L0 known-answer two-group contrast under production evidence rules (pipelines/sci_contrast_l0);
• Z3 formal verification (python -m graph.formal_verification / docs/formal_verification.md): SMT formal proofs for 11 safety & governance properties (P1~P11), AST code path analyzer, and proof audit reports;
• End-to-end integration tests (tests/test_end_to_end_integration.py / docs/integration_testing.md): 7-stage research loop workflow tests, Red-Team interlocks, and fail-closed gate boundary tests;
• 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 RNA-seq pipeline establishes technical quantification validity only;
• the scientific narrow path is a synthetic known-answer demonstration of governed inference, not a biological discovery about real patients or tissues;
• 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, loop, honest_demo, scientific_path, 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
pipelines/sci_contrast_l0/ L0 scientific_inference known-answer narrow path
docs/DEMO.md            Honest Demo guide
docs/DEMO_STATIONS.md   Three Stations, One Refusal (pitch script)
docs/FAULT_LINE.md      Fault-line tables vs multi-agent omics OS
docs/FRS.md             Fabrication Resistance Suite
docs/scientific_path.md scientific narrow-path guide
docs/formal_verification.md Z3 formal verification guide (P1-P11)
docs/integration_testing.md End-to-end integration test guide
docs/MODEL_ROUTING.md   Claude / Codex / Biomni invocation and config templates
docs/OMICS_FM_BACKEND.md Omics-FM inference backends (none/torch/legacy) and benchmark
provenance/             Agent Run Crate builder
tests/                  safety + FRS regression tests
AGENTS.md               lab constitution and operating rules

Not another multi-agent omics chat

Station	System	Power
Generate	Claude	Proposals only
Refute	Codex	Read-only adversarial review
Tools	Biomni (optional, off until digest-pinned)	Bounded L0/L1 lookups
Execute	Nextflow / worker	Deterministic evidence (WRROC)
Authorize	Human Ed25519	Resume gates; models never self-approve

Every thread writes STATIONS.md + stations.json. Reports force a Methods multi-station disclosure. Pitch script:

python -m graph.demo_stations   # or: make demo-stations

Fault-line tables: docs/FAULT_LINE.md.
Routing: docs/MODEL_ROUTING.md.

.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
python -m pytest -q tests/frs
python -m graph.honest_demo
python -m graph.scientific_path

First-time onboarding (no model keys / Docker):

make demo-honest      # intentional failures included
make frs              # fabrication resistance suite
make scientific-path  # governed scientific inference (synthetic L0)

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

Unified CLI Interface (bioagent / python -m cli)

Bio-Agent-Lab features a unified, production-grade Command-Line Interface (bioagent or python -m cli) tailored for both End Users / Researchers and Bioinformatics Engineers:

# General help and subcommand overview
python -m cli --help

# ------------------------------------------------------------------------------
# 🔬 End-Users & Researchers
# ------------------------------------------------------------------------------
# 1. Run L0 demo governed research loop
python -m cli run --question "TP53 mutation vs wildtype survival in BRCA" --level L0

# 2. Inspect active thread status, checkpoints, or DID_NOT_FINISH reasons
python -m cli status

# 3. Check gate statuses and actionable remedy instructions
python -m cli gates

# 4. Execute reference demo tours
python -m cli demo honest       # Zero-credential tour with intentional failures
python -m cli demo stations     # Three Stations pitch script
python -m cli demo sci-path     # Scientific inference narrow path

# ------------------------------------------------------------------------------
# 🛠️ Bioinformatics Engineers & Systems Integrators
# ------------------------------------------------------------------------------
# 1. Validate Nextflow DSL2 pipeline against G_I gate
python -m cli check --pipeline pipelines/rnaseq_quant/main.nf

# 2. Construct and verify content-addressed data manifests (L0-L3)
python -m cli manifest create --data-dir data/ --level L1 --out .lab/data_manifest.json
python -m cli manifest verify --path .lab/data_manifest.json

# 3. Sign Ed25519 human approval receipts
python -m cli approval sign --request .lab/approval_request.json --out .lab/receipt.json --action approve

# 4. Verify Ed25519 approval receipt signatures against trust store
python -m cli approval verify --receipt .lab/receipt.json

# 5. Export machine-readable RO-Crate v1.3 agent-run provenance package
python -m cli crate --run-dir runs/20260730T010000

# 6. Package code-only outbox for Trusted Research Environment (TRE)
python -m cli submit-tre --script pipelines/rnaseq_quant/main.nf --manifest bridge/tre_endpoint.example.json

# 7. Run Fabrication Resistance Suite (FRS) and full security checks
python -m cli check --frs
python -m cli check --all

# Machine-readable JSON output flag (--json) works across all subcommands
python -m cli status --json
python -m cli gates --json

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.

Governance upgrades — P0 (honest commitments) and P1 (adoption surface)

P0-1 · Harness-agnostic enforcement (python -m graph.enforcement). The constitution's B1–B5 checks now live in one shared, orchestrator-independent layer (graph/enforcement.py) that the loop itself runs at intake, before DAG execution, and before the report — not only inside Claude Code hooks. The hooks under .claude/hooks/ are thin shims over the same logic. The CLI (check-command / check-data-plane / check-small-counts / check-no-fabrication) lets any orchestrator or CI job run the identical checks.

P0-2 · Hardened bypass surface. Path/PHI decisions stay in bridge/security_policy.py with URL-decode + NFKC normalization + resolved-path checks; NUL / zero-width / BOM smuggling is now stripped before matching. Biomni MCP filters tools by capability, not module name. The fuzz suite (tests/test_security_bypass_fuzz.py) covers encoding variants and now also drives the loop-level check_data_plane.

P0-3 · Tamper-evident gate log. Every gate evaluation is chained by SHA-256 into .lab/loops/<thread>/provenance/gates.jsonl (graph/gate_log.py). Production and governed-local execution require a verified chain at G_E — reviewers can now verify the gates ran, not merely that the repo claims they did.

P1-4 · Governed-local tier (--mode governed-local). A middle ground between demo and full production: signed data manifest + enforcement + WRROC + human sign-off, executed on one machine for L0/L1 (aggregate outputs only; L2 still requires TRE). Scientific conclusions are allowed only with the governed_local_signed_manifest evidence class and a verified gate log.

P1-5 · Promotion-event gates (--gate-policy promotion-only). Governed-local defaults to promotion-only: research iteration is not blocked at every loop; the human gates remain at report entry. Per-loop signing stays the default for production / demo (LAB_GATE_POLICY=per-loop).

P1-6 · Conditional heterogeneous review. review_policy.heterogeneous_required in .lab/agent_commands.json (or LAB_REQUIRE_HETEROGENEOUS=1) decides whether G_H / G_V require a heterogeneous (dual-implementation) review. Production scientific claims default to required; governed-local defaults to relaxed, with the decision recorded.

P1-7 · Field-level design sign-off. G_D now produces design/review_checklist.json comparing the LLM-drafted analysis plan, the frozen plan, and the pipeline claim field by field; the human approves or overrides each field instead of signing the whole document. G_D verifies the checklist and rejects placeholders.

License

Apache License 2.0. See LICENSE.