From 2597f4a293e2bde957264a2911dfed01fc1b52ad Mon Sep 17 00:00:00 2001 From: OpenCode Date: Wed, 8 Jul 2026 17:30:15 +0700 Subject: [PATCH] Add 10 newcomer and safety guides Closes #416, Closes #417, Closes #418, Closes #419, Closes #421, Closes #422, Closes #423, Closes #425, Closes #426, Closes #427 --- docs/evidence/GUIDE_EVIDENCE_BOUNDARY.md | 20 ++++++++++++ docs/evidence/GUIDE_FIRST_PR.md | 32 +++++++++++++++++++ docs/evidence/GUIDE_LOCAL_SETUP.md | 27 ++++++++++++++++ docs/evidence/GUIDE_MISUSE_SCENARIOS.md | 16 ++++++++++ .../GUIDE_SAFE_CONTRIBUTION_BOUNDARY.md | 23 +++++++++++++ docs/evidence/GUIDE_TRUST_MODEL.md | 19 +++++++++++ docs/evidence/MAP_READER_BY_PERSONA.md | 18 +++++++++++ docs/evidence/PAGE_NON_GOALS.md | 17 ++++++++++ docs/evidence/SAFETY_CHARTER.md | 22 +++++++++++++ docs/evidence/TOUR_COMMANDS.md | 30 +++++++++++++++++ tests/test_newcomer_guides.py | 20 ++++++++++++ 11 files changed, 244 insertions(+) create mode 100644 docs/evidence/GUIDE_EVIDENCE_BOUNDARY.md create mode 100644 docs/evidence/GUIDE_FIRST_PR.md create mode 100644 docs/evidence/GUIDE_LOCAL_SETUP.md create mode 100644 docs/evidence/GUIDE_MISUSE_SCENARIOS.md create mode 100644 docs/evidence/GUIDE_SAFE_CONTRIBUTION_BOUNDARY.md create mode 100644 docs/evidence/GUIDE_TRUST_MODEL.md create mode 100644 docs/evidence/MAP_READER_BY_PERSONA.md create mode 100644 docs/evidence/PAGE_NON_GOALS.md create mode 100644 docs/evidence/SAFETY_CHARTER.md create mode 100644 docs/evidence/TOUR_COMMANDS.md create mode 100644 tests/test_newcomer_guides.py diff --git a/docs/evidence/GUIDE_EVIDENCE_BOUNDARY.md b/docs/evidence/GUIDE_EVIDENCE_BOUNDARY.md new file mode 100644 index 00000000..29f4a770 --- /dev/null +++ b/docs/evidence/GUIDE_EVIDENCE_BOUNDARY.md @@ -0,0 +1,20 @@ +# Evidence Boundary Explainer + +What counts as evidence in the OpenAMP Foundry pipeline, and what does not. + +## Computational Evidence (Levels 0-4) +- Valid sequence syntax +- Reproducible features +- Baseline heuristic scores +- Multi-model consensus +- Leakage-resistant benchmark results + +## Biological Evidence (Levels 5-6) +- Lab assay results +- Independent replication + +## The Boundary +Computational evidence is sufficient for triage and nomination. +Biological evidence is required for any claim of activity, safety, or efficacy. +Crossing the boundary without wet-lab data is the most common and +most serious form of overclaiming in AI-driven discovery. diff --git a/docs/evidence/GUIDE_FIRST_PR.md b/docs/evidence/GUIDE_FIRST_PR.md new file mode 100644 index 00000000..1b883596 --- /dev/null +++ b/docs/evidence/GUIDE_FIRST_PR.md @@ -0,0 +1,32 @@ +# First Successful PR Guide + +Steps to get your first PR merged. + +## Choose an Issue +Pick an issue labeled `good-first-issue`. These are small, well-scoped tasks. + +## Set Up +```bash +git clone https://github.com/Open-Problem-Lab/OpenAMP-Foundry.git +cd OpenAMP-Foundry +git checkout -b your-branch-name +``` + +## Make Changes +1. Make your change. +2. Add or update tests. +3. Verify: `python3 -m pytest -q` +4. Verify: `python scripts/check_doc_links.py` + +## Submit +```bash +git add -A +git commit -m "Brief description of the change" +git push origin your-branch-name +``` +Then create a PR on GitHub referencing the issue number. + +## After Submission +- Respond to review comments. +- Make requested changes. +- Once approved, your PR will be merged. diff --git a/docs/evidence/GUIDE_LOCAL_SETUP.md b/docs/evidence/GUIDE_LOCAL_SETUP.md new file mode 100644 index 00000000..6a1c12f2 --- /dev/null +++ b/docs/evidence/GUIDE_LOCAL_SETUP.md @@ -0,0 +1,27 @@ +# Local Setup Troubleshooting Guide + +## Quick Check +```bash +python3 --version # Should be 3.11+ +python3 -m venv .venv # Should create a virtual environment +source .venv/bin/activate +pip install -e ".[dev]" # Should install without errors +python3 -m pytest -q # Should pass +``` + +## Common Issues + +### `pip install` fails +- Try: `pip install --upgrade pip setuptools wheel` +- Try: `pip install -e ".[dev]" --no-build-isolation` + +### Tests fail with import error +- Make sure you're in the virtual environment: `source .venv/bin/activate` +- Make sure PYTHONPATH includes `src`: `export PYTHONPATH=src` + +### `make demo` fails +- Check that input files exist: `ls examples/sequences/demo_candidates.csv` +- Check that reference files exist: `ls examples/known_reference/demo_known_amps.csv` + +### Still stuck? +Open an issue with the full error message and your OS/Python version. diff --git a/docs/evidence/GUIDE_MISUSE_SCENARIOS.md b/docs/evidence/GUIDE_MISUSE_SCENARIOS.md new file mode 100644 index 00000000..a7fe95d3 --- /dev/null +++ b/docs/evidence/GUIDE_MISUSE_SCENARIOS.md @@ -0,0 +1,16 @@ +# Misuse Scenarios and Mitigations + +Potential misuse scenarios and how the project mitigates them. + +| Scenario | Risk | Mitigation | +|----------|:----:|------------| +| Overclaiming computational results as biological proof | High | `check_claims.py`, review process, AGENTS.md rules | +| Using pipeline to design toxins | High | No toxicity optimization, safety penalties, safety review | +| Releasing unscreened candidate lists | Medium | Gate process, human review, embargoed release | +| Misinterpreting safety scores as guarantees | Medium | LIMITATIONS_OVERVIEW.md, disclaimer in all outputs | +| Using pipeline without understanding limitations | Low | Honest limitations documented, quickstart guides | + +## Principles +- Mitigations must not rely on users reading all documentation. +- Safety-relevant mitigations should be enforced by code or process. +- When code cannot prevent misuse, documentation and review must. diff --git a/docs/evidence/GUIDE_SAFE_CONTRIBUTION_BOUNDARY.md b/docs/evidence/GUIDE_SAFE_CONTRIBUTION_BOUNDARY.md new file mode 100644 index 00000000..2fde7d99 --- /dev/null +++ b/docs/evidence/GUIDE_SAFE_CONTRIBUTION_BOUNDARY.md @@ -0,0 +1,23 @@ +# Safe Contribution Boundary Guide + +What contributions are safe to make without maintainer discussion, +and what requires discussion first. + +## Safe (No Discussion Needed) +- Typo fixes and formatting improvements +- Adding tests for existing functionality +- Adding documentation for existing features +- Updating example data or demo files + +## Discussion Recommended +- Adding new features or modifying existing behavior +- Adding new documentation categories +- Changing test infrastructure +- Adding new dependencies + +## Discussion Required +- Changes to safety policy +- Changes to scoring weights +- Changes to calibration pipeline +- Any change that affects claims or releases +- Adding new benchmarks that affect the gate diff --git a/docs/evidence/GUIDE_TRUST_MODEL.md b/docs/evidence/GUIDE_TRUST_MODEL.md new file mode 100644 index 00000000..877ed6e8 --- /dev/null +++ b/docs/evidence/GUIDE_TRUST_MODEL.md @@ -0,0 +1,19 @@ +# Trust Model Overview + +How trust is established in the OpenAMP Foundry project. + +## Trust Layers +1. **Code transparency** — all code is open source (Apache 2.0) +2. **Evidence transparency** — all results include caveats and limitations +3. **Process transparency** — decisions are logged in decision logs +4. **Reproducibility** — all outputs can be regenerated from versioned inputs +5. **Review** — expert review is required before release + +## What Trust Does NOT Mean +- Trust in the pipeline does not mean trust in the predictions as biological proof. +- Trust in the code does not mean the code is bug-free. +- Trust in the process does not mean the process guarantees correct results. + +## Related +- `docs/trust/TRUST_CENTER.md` — trust architecture +- `docs/evidence/LIMITATIONS_OVERVIEW.md` — honest limitations diff --git a/docs/evidence/MAP_READER_BY_PERSONA.md b/docs/evidence/MAP_READER_BY_PERSONA.md new file mode 100644 index 00000000..203b7078 --- /dev/null +++ b/docs/evidence/MAP_READER_BY_PERSONA.md @@ -0,0 +1,18 @@ +# Reader Map by Persona + +How different readers should navigate the documentation. + +## Newcomer +Start at README.md → QUICKSTART.md → CONTRIBUTOR_CURRICULUM.md + +## Scientist +Start at LIMITATIONS_OVERVIEW.md → METRICS_CURRENT.md → EVIDENCE_CERTIFICATE.md + +## Engineer +Start at ARCHITECTURE.md → COMMAND_SURFACE.md → src/openamp_foundry/ + +## Reviewer +Start at EXPERT_REVIEW_PACK.md → LIMITATIONS_OVERVIEW.md → PR_REVIEW_RUBRIC.md + +## Agent (AI) +Start at AGENTS.md → AGENT_TASKS.json → CURRICULUM_AGENT.md diff --git a/docs/evidence/PAGE_NON_GOALS.md b/docs/evidence/PAGE_NON_GOALS.md new file mode 100644 index 00000000..17d1025f --- /dev/null +++ b/docs/evidence/PAGE_NON_GOALS.md @@ -0,0 +1,17 @@ +# Non-Goals Page + +What the project explicitly does NOT aim to do. + +## Non-Goals +1. **Replace wet-lab validation** — computational scores are predictions, not proof. +2. **Discover drugs** — the pipeline nominates candidates, not drugs. +3. **Guarantee safety** — safety scores are heuristics, not guarantees. +4. **Replace domain experts** — expert review is required for all releases. +5. **Optimize for toxicity** — that would violate the safety charter. +6. **Operate autonomously** — human review is required for all decisions. + +## Why Document Non-Goals +- Prevents mission creep. +- Sets clear expectations for users and contributors. +- Makes it easier to say no to out-of-scope work. +- Aligns the project with its safety and honesty constraints. diff --git a/docs/evidence/SAFETY_CHARTER.md b/docs/evidence/SAFETY_CHARTER.md new file mode 100644 index 00000000..826b1ae0 --- /dev/null +++ b/docs/evidence/SAFETY_CHARTER.md @@ -0,0 +1,22 @@ +# One-Page Safety Charter + +## Our Commitment +OpenAMP Foundry is a dry-lab computational project. It does not conduct +biological experiments. It does not provide protocols for handling +dangerous organisms. It does not optimize for toxicity or harmful outcomes. + +## Safety Rules +1. No wet-lab protocols in this repository. +2. No optimization for mammalian toxicity. +3. No instructions for pathogen enhancement. +4. No release of unscreened high-risk candidate lists. +5. Human review required before any release or public claim. + +## Enforcement +- `scripts/safety/check_claims.py` scans for overclaiming language. +- All PRs are reviewed for safety implications. +- Safety-critical changes require a designated safety reviewer. + +## Related +- `SAFETY.md` — full safety policy +- `RESPONSIBLE_USE.md` — allowed and forbidden uses diff --git a/docs/evidence/TOUR_COMMANDS.md b/docs/evidence/TOUR_COMMANDS.md new file mode 100644 index 00000000..8258764c --- /dev/null +++ b/docs/evidence/TOUR_COMMANDS.md @@ -0,0 +1,30 @@ +# Command Tour for New Users + +A guided tour of the most important CLI commands. + +## 1. Rank Candidates +```bash +openamp-foundry rank --candidates examples/sequences/demo_candidates.csv \ + --references examples/known_reference/demo_known_amps.csv \ + --out outputs/demo_ranked.jsonl --report outputs/demo_report.md +``` +This scores candidates, ranks them, and generates evidence certificates. + +## 2. Validate Certificates +```bash +openamp-foundry validate --certificate outputs/evidence/AMPF-000001.json \ + --schema schemas/candidate.schema.json +``` +This validates a candidate's evidence certificate against the schema. + +## 3. Build a Lab Pack +```bash +make lab-batch-pack +``` +This creates a zip file with everything a lab partner needs. + +## 4. Check Pipeline Health +```bash +make full-reproducibility-report +``` +This generates a report summarizing pipeline state and readiness. diff --git a/tests/test_newcomer_guides.py b/tests/test_newcomer_guides.py new file mode 100644 index 00000000..05f5e4e4 --- /dev/null +++ b/tests/test_newcomer_guides.py @@ -0,0 +1,20 @@ +"""Tests for newcomer guides batch.""" +from pathlib import Path + +FILES = [ + "MAP_READER_BY_PERSONA.md", + "GUIDE_TRUST_MODEL.md", + "GUIDE_EVIDENCE_BOUNDARY.md", + "SAFETY_CHARTER.md", + "PAGE_NON_GOALS.md", + "GUIDE_MISUSE_SCENARIOS.md", + "GUIDE_SAFE_CONTRIBUTION_BOUNDARY.md", + "GUIDE_FIRST_PR.md", + "GUIDE_LOCAL_SETUP.md", + "TOUR_COMMANDS.md", +] + + +def test_all_exist(): + for f in FILES: + assert Path("docs/evidence", f).exists(), f"Missing: {f}"