Add 10 FAQ, policy, and writing guides

docs/evidence/FAQ_CONTRIBUTOR.md

@@ -0,0 +1,20 @@
+# Contributor FAQ
+
+## How do I get started?
+Read CONTRIBUTING.md, then QUICKSTART.md. Pick an issue from the open issues list.
+
+## What makes a good first issue?
+Issues labeled `good-first-issue` are ideal. They're small, well-scoped, and don't require deep project knowledge.
+
+## How do I submit a PR?
+1. Create a branch from main.
+2. Make your change and add tests.
+3. Run `python3 -m pytest -q` to verify.
+4. Run `python3 scripts/check_doc_links.py` to check links.
+5. Submit the PR referencing the issue number.
+
+## What if I get stuck?
+Ask in the issue comments. If it's urgent, tag a maintainer.
+
+## Can I contribute without writing code?
+Yes! Documentation improvements, test additions, and issue triage are all valuable.

docs/evidence/FAQ_MAINTAINER.md

@@ -0,0 +1,19 @@
+# Maintainer FAQ
+
+## How do I merge a PR?
+1. Ensure all checks pass.
+2. Request review from at least one other maintainer for non-trivial changes.
+3. Squash-merge with a descriptive commit message.
+4. Delete the branch after merging.
+
+## How do I create a release?
+1. Complete the release readiness checklist.
+2. Create a release branch.
+3. Run `make full-reproducibility-report`.
+4. Tag the release and publish release notes.
+
+## How do I handle a safety issue?
+1. Immediately flag the issue in the decision log.
+2. Notify the project lead.
+3. If needed, revert the unsafe change.
+4. Document the resolution.

docs/evidence/FAQ_PUBLIC.md

@@ -0,0 +1,16 @@
+# Public FAQ for Non-Specialists
+
+## What is OpenAMP Foundry?
+A computational pipeline that ranks antimicrobial peptide candidates before lab testing.
+
+## Does it discover new antibiotics?
+It nominates candidates for testing. Discovery requires wet-lab validation.
+
+## Are the scores reliable?
+They are predictions, not proof. The pipeline is benchmarked against known AMPs but has limitations (charge bias, no wet-lab data).
+
+## Can I use the results for my research?
+Yes, with the understanding that all results are computational predictions.
+
+## Is it safe?
+The pipeline is dry-lab only — no biological experiments are conducted. All code is open source (Apache 2.0).

docs/evidence/GUIDE_ASSUMPTIONS_REGISTER.md

@@ -0,0 +1,22 @@
+# Assumptions Register Guide
+
+How to document and track assumptions.
+
+## What to Record
+- Assumptions about data quality
+- Assumptions about model behavior
+- Assumptions about benchmark validity
+- Assumptions about user environment
+
+## Format
+Each assumption should include:
+- What the assumption is
+- Why it's reasonable
+- What would happen if it's wrong
+- When it should be reviewed
+
+## Example
+| Assumption | Basis | Risk if Wrong | Review Date |
+|-----------|-------|---------------|-------------|
+| AMPs are cationic | Literature consensus | Non-cationic AMPs undervalued | Next benchmark cycle |
+| Swiss-Prot decoys are valid negatives | Standard practice | Benchmark AUROC inflated | Next data refresh |

docs/evidence/GUIDE_CLAIM_WORDING_STYLE.md

@@ -0,0 +1,22 @@
+# Claim Wording Style Guide
+
+How to write about computational results without overclaiming.
+
+## Do Use
+- "Computationally nominated candidate"
+- "Predicted antimicrobial peptide"
+- "Dry-lab candidate"
+- "Selected by reproducible pipeline"
+- "Evidence package"
+- "Benchmark-supported under stated assumptions"
+
+## Don't Use
+- "Drug candidate" — requires wet-lab evidence
+- "Proven antimicrobial" — computation does not prove
+- "Safe in humans" — requires clinical evidence
+- "Validated by computation" — computation triages, doesn't validate
+- "Breakthrough therapy" — requires clinical evidence
+
+## Rule of Thumb
+If you wouldn't say it about a random sequence without running any tests,
+you shouldn't say it about a computationally nominated candidate.

docs/evidence/GUIDE_DATA_SOURCE_DOCS.md

@@ -0,0 +1,24 @@
+# Data Source Documentation Guide
+
+Every dataset used by the pipeline must be documented.
+
+## Required Information
+- Source URL or reference
+- License information
+- Download date
+- Version or release
+- Description of the data
+- Known biases or limitations
+
+## Format
+Use a dataset card in `data/README.md` or in the relevant evidence document.
+
+## Example
+```markdown
+## Dataset: Known AMPs (500)
+- Source: UniProt reviewed + APD6 natural
+- License: CC BY 4.0 (UniProt), academic use (APD6)
+- Downloaded: 2026-07-01
+- Description: 500 antimicrobial peptide sequences, 10-30 AA
+- Known bias: Enriched for helical AMPs; fewer proline-rich and cysteine-rich
+```

docs/evidence/GUIDE_NO_HYPE_WRITING.md

@@ -0,0 +1,11 @@
+# No-Hype Writing Rules
+
+Rules for keeping documentation honest and grounded.
+
+1. **No superlatives without evidence.** Don't say "best" or "first" unless you can prove it.
+2. **No claims about biology without wet-lab data.** Computational results are predictions, not proof.
+3. **State limitations as prominently as findings.** Every claim should be paired with its caveat.
+4. **Use the weakest accurate claim.** If "suggests" is accurate, don't use "demonstrates."
+5. **No future capability as current fact.** "Will be able to" is speculation, not documentation.
+6. **No hidden negatives.** Failed experiments, benchmark weaknesses, and model limitations must be documented.
+7. **Review before publishing.** Run `check_claims.py` on all public-facing text.

docs/evidence/GUIDE_UNCERTAINTY_LANGUAGE.md

@@ -0,0 +1,17 @@
+# Uncertainty Language Guide
+
+How to communicate uncertainty in documentation.
+
+## Strength of Language
+| Certainty | Language | When to Use |
+|-----------|----------|-------------|
+| High | "The pipeline scores candidates based on..." | Documented, verifiable behavior |
+| Medium | "Candidates with high ensemble scores tend to be..." | Benchmark-supported pattern |
+| Low | "This suggests that..." | Single experiment or weak signal |
+| Speculative | "It is possible that..." | No evidence yet |
+
+## Rules
+- Match the language to the evidence level.
+- Avoid false precision ("the candidate is 87.3% likely to be antimicrobial").
+- State uncertainty alongside every prediction.
+- When uncertain, say "we don't know" — it's better than false confidence.

docs/evidence/POLICY_CITATION_SOURCE.md

@@ -0,0 +1,18 @@
+# Citation and Source Policy
+
+How to cite sources in documentation.
+
+## Required Citations
+- All dataset sources (with license information)
+- All algorithms or methods not original to this project
+- All benchmark references
+- All literature claims not supported by project evidence
+
+## Citation Format
+Use inline links for web resources and footnotes for academic references.
+
+## Source Requirements
+- Sources must be publicly accessible where possible.
+- Paywalled sources should be noted as such.
+- Sources must be specific (page number, section, or timestamp).
+- "Personal communication" is not an acceptable citation.

docs/evidence/POLICY_RETENTION.md

@@ -0,0 +1,18 @@
+# Retention Policy Explanation
+
+How long documents and artifacts are retained.
+
+## Retention Periods
+| Type | Retention | Notes |
+|------|-----------|-------|
+| Evidence certificates | Permanent | Historical record |
+| Decision logs | Permanent | Governance record |
+| Benchmark results | Permanent | Scientific record |
+| Policy docs | Permanent | Until superseded |
+| Run manifests | 2 years | Reproducibility |
+| Temporary outputs | 90 days | Outputs/ directory |
+| Discussion comments | 1 year | After issue closes |
+
+## Disposal
+After the retention period, documents are archived. Archived documents
+are never deleted without a decision log entry explaining why.

tests/test_faq_writing_batch.py

@@ -0,0 +1,20 @@
+"""Tests for FAQ and writing guides batch."""
+from pathlib import Path
+
+FILES = [
+    "POLICY_RETENTION.md",
+    "GUIDE_CLAIM_WORDING_STYLE.md",
+    "POLICY_CITATION_SOURCE.md",
+    "GUIDE_ASSUMPTIONS_REGISTER.md",
+    "GUIDE_UNCERTAINTY_LANGUAGE.md",
+    "GUIDE_NO_HYPE_WRITING.md",
+    "FAQ_PUBLIC.md",
+    "FAQ_MAINTAINER.md",
+    "FAQ_CONTRIBUTOR.md",
+    "GUIDE_DATA_SOURCE_DOCS.md",
+]
+
+
+def test_all_exist():
+    for f in FILES:
+        assert Path("docs/evidence", f).exists(), f"Missing: {f}"