Merge v0.8.20 release — changelog, mustmatch shim removal, tag

imaurer · imaurer · commit 77f314214f6f · 2026-03-30T16:03:41.000-04:00
diff --git a/.march/code-log.md b/.march/code-log.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.8.20 — 2026-03-30
+
+### Security
+
+- Security fix: remove partial API key from health output so shared operator
+  reports no longer leak credential fragments. (067)
+- Hardened the MCP allowlist so mutating `study download` paths stay blocked
+  while the safe `--list` path remains available. (068)
+
+### Fixes
+
+- Fixed `batch --json` so responses always include the `_meta` contract field.
+  (069)
+- Hardened the GWAS variant section against live decode failures. (070)
+- Fixed gene-to-PGx and disease-to-drug See-also routing so those pivots land
+  on the correct entity helpers. (077)
+- Fixed large PMC OA full-text downloads that were timing out on bigger
+  payloads. (080)
+
+### New features
+
+- Added cross-entity See-also links for drug→PGx, gene→PGx, disease→study,
+  and zero-result→discover routing. (076)
+- Added the quality ratchet to `make check` so the repo gate now audits
+  mustmatch lint, MCP allowlist coverage, and source-registry drift. (075)
+- Added the study top-mutated helper plus disease literature fallback for
+  missing direct evidence paths.
+
+### Improvements
+
+- Reworked CLI help, typed-path guidance, and the skill catalog for
+  self-teaching agent navigation. (072, 073, 074)
+- `get disease` now shows full disease definitions instead of truncated
+  characterizations. (080)
+- `get disease` now separates defining phenotypic features from the full HPO
+  list with ranked key-feature summaries. (081)
+- `get gene` now shows UniProt protein isoforms in the protein section. (082)
+- `get drug` now shows drug target family names alongside individual targets.
+  (083)
+- `get gene` now shows protein legacy names alongside current symbols. (084)
+- `get variant` now shows variant legacy nomenclature alongside current HGVS
+  names. (085)
+- Improved purine-analog mechanism labels so ATC-exact and mechanism-of-action
+  coverage stay aligned. (086)
+- Closed the remaining BioASQ product gaps around protein function truncation,
+  variant-specific targets, and disease feature coverage. (087)
+- Replaced the in-shell mustmatch shim with the packaged `mustmatch lint`
+  entrypoint plus a small compatibility layer for the repo’s existing ratchet
+  contract. (088)
+
+### Docs
+
+- Added architecture contract docs for See-also links, discover grammar, CI,
+  and post-tag public proof expectations. (078)
+- Documentation consistency audit across the public docs surface.
+- Repo cleanup for layout, example paths, and tracked `.march` artifacts.
+  (079)
+
 ## 0.8.19 — 2026-03-26
 
 ### Improvements
diff --git a/CITATION.cff b/CITATION.cff
@@ -6,8 +6,8 @@ abstract: >-
   BioMCP is a single-binary CLI and MCP server for querying biomedical
   databases with one command grammar, compact markdown output, and local study
   analytics.
-version: 0.8.19
-date-released: 2026-03-26
+version: 0.8.20
+date-released: 2026-03-30
 license: MIT
 repository-code: https://github.com/genomoncology/biomcp
 url: https://biomcp.org
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "biomcp-cli"
-version = "0.8.19"
+version = "0.8.20"
 edition = "2024"
 description = "Biomedical CLI and MCP server — genes, variants, trials, articles, drugs, diseases, pathways, proteins, adverse events, PGx"
 homepage = "https://biomcp.org"
diff --git a/architecture/technical/overview.md b/architecture/technical/overview.md
@@ -200,7 +200,7 @@ so release-visible version identity and docs parity are checked against the
 live surfaces:
 
 ```bash
-tag="${BIOMCP_TAG:?set BIOMCP_TAG to the published release tag, e.g. v0.8.19}"
+tag="${BIOMCP_TAG:?set BIOMCP_TAG to the published release tag, e.g. v0.8.20}"
 version="${tag#v}"
 tmpdir="$(mktemp -d)" && BIOMCP_INSTALL_DIR="$tmpdir" BIOMCP_VERSION="$tag" bash install.sh >/tmp/biomcp-install.log && "$tmpdir/biomcp" version | head -n 1
 bioasq_page="$(mktemp)" && curl -fsSL -A 'Mozilla/5.0' https://biomcp.org/reference/bioasq-benchmark/ >"$bioasq_page" && rg -q 'hf-public-pre2026' "$bioasq_page" && rg -q 'Phase A\+' "$bioasq_page" && rg -q 'Phase B' "$bioasq_page"
diff --git a/docs/sources/uniprot.md b/docs/sources/uniprot.md
@@ -36,11 +36,11 @@ Returns a protein card with accession, gene, function, and UniProt evidence link
 biomcp get gene BRAF protein
 ```
 
-Returns a gene detail view with a `Protein (UniProt)` section. When UniProt
-annotates legacy protein names, that section includes an `Also known as:` line
-with alternative full names and short names from UniProt. When UniProt annotates
-alternative products, the same section also includes an `Isoforms (N)` line with
-isoform names and the displayed isoform length from the canonical record.
+Returns a gene detail view with a `Protein (UniProt)` section, including legacy names and isoforms when UniProt annotates them.
+
+When UniProt annotates legacy protein names, the section includes an `Also known as:` line
+with alternative full names and short names. When UniProt annotates alternative products,
+the section also includes an `Isoforms (N)` line with isoform names and the canonical record length.
 
 ```bash
 biomcp get protein P15056 structures
diff --git a/manifest.json b/manifest.json
@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "biomcp",
   "display_name": "BioMCP",
-  "version": "0.8.19",
+  "version": "0.8.20",
   "description": "Read-only biomedical search and evidence retrieval across BioMCP's CLI command grammar.",
   "long_description": "BioMCP packages the existing Rust CLI and MCP server as a local read-only bundle for biomedical discovery, detail lookups, cross-entity pivots, enrichment, and study analytics.",
   "author": {
diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "biomcp-cli"
-version = "0.8.19"
+version = "0.8.20"
 description = "Biomedical MCP CLI - query genes, variants, trials, articles, drugs, diseases"
 readme = "README.md"
 license = { text = "MIT" }
@@ -28,7 +28,7 @@ Documentation = "https://biomcp.org"
 dev = [
   "jsonschema>=4.26",
   "mcp>=1.0.0",
-  "mustmatch>=0.0.2",
+  "mustmatch>=0.0.4",
   "pytest>=8.0",
   "pytest-asyncio>=0.24",
   "pytest-timeout>=2.3",
diff --git a/spec/13-study.md b/spec/13-study.md
@@ -290,16 +290,10 @@ echo "$out" | mustmatch not like "# Study Co-occurrence"
 [ -f "$PWD/.cache/spec-study-env" ] || bash fixtures/setup-study-spec-fixture.sh "$PWD"
 . "$PWD/.cache/spec-study-env"
 out="$(biomcp study query --study msk_impact_2017 --gene TP53 --type mutations --chart bar --cols 40 --rows 12)"
-OUT="$out" python3 - <<'PY'
-import os
-import re
-
-text = re.sub(r"\x1b\[[0-9;?]*[ -/]*[@-~]", "", os.environ["OUT"])
-lines = text.splitlines()
-assert lines, text
-assert len(lines) <= 12, (len(lines), text)
-assert max(len(line) for line in lines) <= 40, text
-PY
+clean="$(printf '%s\n' "$out" | sed 's/\x1b\[[0-9;?]*[A-Za-z]//g')"
+line_count="$(printf '%s\n' "$clean" | wc -l | tr -d ' ')"
+test "$line_count" -le 12
+printf '%s\n' "$clean" | mustmatch not like "# Study"
 ```
 
 ## Chart Flag: Co-occurrence Heatmap
diff --git a/tests/test_citation_contract.py b/tests/test_citation_contract.py
@@ -68,6 +68,8 @@ def test_citation_cff_release_metadata_matches_repo_metadata() -> None:
 
     assert changelog_match is not None, "missing release header in CHANGELOG.md"
 
+    assert citation_version == "0.8.20"
+    assert citation_date == "2026-03-30"
     assert citation_version == cargo["package"]["version"]
     assert citation_version == pyproject["project"]["version"]
     assert citation_version == changelog_match.group("version")
diff --git a/tests/test_docs_changelog_refresh.py b/tests/test_docs_changelog_refresh.py
@@ -26,25 +26,25 @@ def _markdown_section_block(text: str, heading: str) -> str:
 
 def test_changelog_has_backfilled_releases_and_release_header() -> None:
     changelog = _read("CHANGELOG.md")
-    latest_release_block = _markdown_section_block(changelog, "## 0.8.18 — 2026-03-25")
+    latest_release_block = _markdown_section_block(changelog, "## 0.8.20 — 2026-03-30")
 
     assert "## [Unreleased]" not in changelog
+    assert "## 0.8.20 — 2026-03-30" in changelog
+    assert "## 0.8.19 — 2026-03-26" in changelog
     assert "## 0.8.18 — 2026-03-25" in changelog
     assert "## 0.9.0" not in changelog
-    assert "--region us|eu|all" in latest_release_block
-    assert "EMA" in latest_release_block
-    assert "BioASQ benchmark" in latest_release_block
-    assert "docs/reference/bioasq-benchmark.md" in latest_release_block
-    assert "S2_API_KEY" in latest_release_block
-    assert "1 req/2sec" in latest_release_block
-    assert "1 req/sec" in latest_release_block
-    assert "049" not in latest_release_block
-    assert "050" not in latest_release_block
-    assert "051" not in latest_release_block
+    assert "remove partial API key from health output" in latest_release_block
+    assert "cross-entity See-also links" in latest_release_block
+    assert "quality ratchet" in latest_release_block
+    assert "mustmatch" in latest_release_block
+    assert "drug target family" in latest_release_block
+    assert "protein isoforms" in latest_release_block
+    assert "variant legacy" in latest_release_block
+    assert "disease definitions" in latest_release_block
+    assert "Documentation consistency audit" in latest_release_block
+    assert "Repo cleanup" in latest_release_block
     assert "pending separate merge" not in latest_release_block
-    assert "run.py" not in latest_release_block
-    assert "evaluate.py" not in latest_release_block
-    assert "score.py" not in latest_release_block
+    assert "0.8.21" not in latest_release_block
 
     expected_releases = [
         ("0.8.18", "2026-03-25"),
diff --git a/tests/test_quality_ratchet_contract.py b/tests/test_quality_ratchet_contract.py
@@ -12,6 +12,7 @@
 MCP_SCRIPT = REPO_ROOT / "tools" / "check-mcp-allowlist.py"
 SOURCE_SCRIPT = REPO_ROOT / "tools" / "check-source-registry.py"
 WRAPPER_SCRIPT = REPO_ROOT / "tools" / "check-quality-ratchet.sh"
+RATCHET_TOOL = REPO_ROOT / "tools" / "check-quality-ratchet.py"
 
 
 def _run_python_script(
@@ -336,6 +337,20 @@ def test_wrapper_writes_summary_artifacts_for_pass_fixture(tmp_path: Path) -> No
     assert summary["lint"]["finding_count"] == 0
 
 
+def test_wrapper_is_thin_shell_around_committed_python_tool() -> None:
+    wrapper = WRAPPER_SCRIPT.read_text(encoding="utf-8")
+
+    assert RATCHET_TOOL.exists()
+    assert "python3 - <<'PY'" not in wrapper
+    assert "lint_spec_file" not in wrapper
+    assert "collect_shell_blocks" not in wrapper
+    assert "MUSTMATCH_JSON_RE" not in wrapper
+    assert "SHORT_LIKE_RE" not in wrapper
+    assert "FENCE_RE" not in wrapper
+    assert "uv run --extra dev python" in wrapper
+    assert "tools/check-quality-ratchet.py" in wrapper
+
+
 def test_wrapper_propagates_lint_failures(tmp_path: Path) -> None:
     spec_path = _write_failing_spec(tmp_path / "spec")
     output_dir = tmp_path / "out"
@@ -351,6 +366,25 @@ def test_wrapper_propagates_lint_failures(tmp_path: Path) -> None:
     summary = json.loads((output_dir / "quality-ratchet-summary.json").read_text())
     assert summary["status"] == "fail"
     assert summary["lint"]["status"] == "fail"
+    findings = summary["lint"]["results"][0]["findings"]
+    assert findings[0]["rule"] == "short-like-pattern"
+
+
+def test_wrapper_reports_error_when_no_specs_match(tmp_path: Path) -> None:
+    output_dir = tmp_path / "out"
+
+    result = _run_wrapper(
+        {
+            "QUALITY_RATCHET_OUTPUT_DIR": str(output_dir),
+            "QUALITY_RATCHET_SPEC_GLOB": str(tmp_path / "spec" / "*.md"),
+        }
+    )
+
+    assert result.returncode == 1
+    summary = json.loads((output_dir / "quality-ratchet-summary.json").read_text())
+    assert summary["status"] == "error"
+    assert summary["lint"]["status"] == "error"
+    assert "no spec files matched" in summary["lint"]["errors"][0]
 
 
 def test_wrapper_propagates_mcp_failures_from_override_paths(tmp_path: Path) -> None:
diff --git a/tests/test_version_sync_script.py b/tests/test_version_sync_script.py
@@ -13,6 +13,13 @@
 LOCK_ROOT_VERSION_PATTERN = re.compile(
     r'(name = "biomcp-cli"\nversion = ")([^"]+)(")', re.MULTILINE
 )
+UV_LOCK_ROOT_VERSION_PATTERN = re.compile(
+    r'(name = "biomcp-cli"\nversion = ")([^"]+)(")', re.MULTILINE
+)
+UV_LOCK_MUSTMATCH_PATTERN = re.compile(
+    r'name = "mustmatch"\nversion = "([^"]+)"',
+    re.MULTILINE,
+)
 
 
 def _copy_version_sync_fixture(tmp_path: Path) -> Path:
@@ -213,7 +220,22 @@ def test_manifest_and_citation_versions_match_repo_metadata() -> None:
     cargo = tomllib.loads((REPO_ROOT / "Cargo.toml").read_text(encoding="utf-8"))
     pyproject = tomllib.loads((REPO_ROOT / "pyproject.toml").read_text(encoding="utf-8"))
 
+    assert cargo["package"]["version"] == "0.8.20"
+    assert pyproject["project"]["version"] == "0.8.20"
     assert _read_manifest_version(REPO_ROOT / "manifest.json") == cargo["package"]["version"]
     assert _read_manifest_version(REPO_ROOT / "manifest.json") == pyproject["project"]["version"]
     assert _read_citation_version(REPO_ROOT / "CITATION.cff") == cargo["package"]["version"]
     assert _read_citation_version(REPO_ROOT / "CITATION.cff") == pyproject["project"]["version"]
+
+
+def test_uv_lock_matches_release_version_and_mustmatch_floor() -> None:
+    uv_lock = (REPO_ROOT / "uv.lock").read_text(encoding="utf-8")
+
+    root_match = UV_LOCK_ROOT_VERSION_PATTERN.search(uv_lock)
+    mustmatch_match = UV_LOCK_MUSTMATCH_PATTERN.search(uv_lock)
+
+    assert root_match is not None, "missing biomcp-cli package entry in uv.lock"
+    assert mustmatch_match is not None, "missing mustmatch package entry in uv.lock"
+    assert root_match.group(2) == "0.8.20"
+    assert mustmatch_match.group(1) == "0.0.4"
+    assert '{ name = "mustmatch", marker = "extra == \'dev\'", specifier = ">=0.0.4" }' in uv_lock
diff --git a/tools/check-quality-ratchet.py b/tools/check-quality-ratchet.py
diff --git a/tools/check-quality-ratchet.sh b/tools/check-quality-ratchet.sh
diff --git a/uv.lock b/uv.lock
