From a6ffc64bf79f5ec20c1cdd34d5e91b66ab661961 Mon Sep 17 00:00:00 2001
From: OpenCode <opencode@example.com>
Date: Tue, 7 Jul 2026 11:18:31 +0700
Subject: [PATCH] Add documentation readiness checklist

Closes #567

- docs/evidence/DOCS_READINESS_CHECKLIST.md -- covers link health,
  freshness, claim wording, quickstart, release, governance
- Blocker vs warning examples
- 5 tests
---
 docs/evidence/DOCS_READINESS_CHECKLIST.md | 57 +++++++++++++++++++++++
 tests/test_docs_readiness_checklist.py    | 26 +++++++++++
 2 files changed, 83 insertions(+)
 create mode 100644 docs/evidence/DOCS_READINESS_CHECKLIST.md
 create mode 100644 tests/test_docs_readiness_checklist.py

diff --git a/docs/evidence/DOCS_READINESS_CHECKLIST.md b/docs/evidence/DOCS_READINESS_CHECKLIST.md
new file mode 100644
index 00000000..d39b4b14
--- /dev/null
+++ b/docs/evidence/DOCS_READINESS_CHECKLIST.md
@@ -0,0 +1,57 @@
+# Documentation Readiness Checklist
+
+Before sharing a project update or preparing a public release, verify
+documentation health with this checklist.
+
+---
+
+## Link Health
+
+- [ ] `python scripts/check_doc_links.py` reports 0 broken links
+- [ ] All cross-references between docs resolve correctly
+- [ ] External links (APD6, DRAMP, UniProt) are still accessible
+
+## Freshness
+
+- [ ] `docs/evidence/METRICS_CURRENT.md` matches current benchmark outputs
+- [ ] `docs/research/ROADMAP.md` reflects completed and in-progress work
+- [ ] `docs/evidence/SIMULATION_BENCHMARK.md` matches current gate verdict
+- [ ] Version numbers in docs match the current pipeline version
+
+## Claim Wording
+
+- [ ] `python scripts/safety/check_claims.py` reports no overclaiming language
+- [ ] No document claims biological validation without wet-lab data
+- [ ] Terms like "proven", "drug candidate", "safe in humans" are absent or quoted
+- [ ] All benchmark claims reference honest limitations (charge-domination, no wet-lab data)
+
+## Quickstart Accuracy
+
+- [ ] `make demo` succeeds
+- [ ] `python3 -m pytest -q` passes
+- [ ] Quickstart instructions match actual commands
+- [ ] Setup steps work from a clean checkout
+
+## Release Readiness
+
+- [ ] `docs/review/PUBLICATION_PACK.md` checklist is complete
+- [ ] `docs/review/RELEASE_DRY_RUN_GUIDE.md` is up to date
+- [ ] `make full-reproducibility-report` succeeds
+
+## Governance
+
+- [ ] `AGENT_TASKS.json` task categories are current
+- [ ] `docs/evidence/SYNTHETIC_DATA_POLICY.md` is referenced where synthetic data is used
+- [ ] `docs/evidence/LIMITATIONS_OVERVIEW.md` is accurate
+
+## Blocker vs Warning
+
+| Severity | Example | Action |
+|----------|---------|--------|
+| 🔴 Blocker | Broken link in quickstart | Fix before sharing |
+| 🔴 Blocker | Overclaiming language in public-facing doc | Rewrite before release |
+| 🟡 Warning | Stale ROADMAP entry | Update when possible |
+| 🟡 Warning | METRICS_CURRENT.md minor version mismatch | Update when possible |
+
+A blocker must be resolved before any public update. A warning should be
+resolved but is not a release gate.
diff --git a/tests/test_docs_readiness_checklist.py b/tests/test_docs_readiness_checklist.py
new file mode 100644
index 00000000..00d4f55b
--- /dev/null
+++ b/tests/test_docs_readiness_checklist.py
@@ -0,0 +1,26 @@
+"""Tests for docs readiness checklist."""
+from pathlib import Path
+
+
+def test_file_exists():
+    assert Path("docs/evidence/DOCS_READINESS_CHECKLIST.md").exists()
+
+
+def test_has_link_health():
+    text = Path("docs/evidence/DOCS_READINESS_CHECKLIST.md").read_text()
+    assert "Link Health" in text
+
+
+def test_has_claim_wording():
+    text = Path("docs/evidence/DOCS_READINESS_CHECKLIST.md").read_text()
+    assert "Claim Wording" in text
+
+
+def test_has_blocker_vs_warning():
+    text = Path("docs/evidence/DOCS_READINESS_CHECKLIST.md").read_text()
+    assert "Blocker" in text and "Warning" in text
+
+
+def test_has_quickstart():
+    text = Path("docs/evidence/DOCS_READINESS_CHECKLIST.md").read_text()
+    assert "Quickstart" in text