docs: scrub marketing language and roadmap-tier prose from public surface

mahdi-shafiei · mahdi-shafiei · commit 2e849a8fc869 · 2026-05-01T21:58:09.000-07:00
Phase A (Rule 5/6 cleanup):
docs/index.md hero: replace 100% Differentiable stat-card with
End-to-End Differentiable
docs/user-guide/operators/singlecell.md, sources.md,
losses/singlecell.md: drop complete / directly /
established
docs/examples/basic/pileup-generation.md,
docs/examples/advanced/multiomics-integration.md: drop
complete
docs/examples/advanced/grn-inference.md: 100% recall -&gt;
recall of 1.0
tests/operators/drug_discovery/test_fingerprint_correctness.py:
drop Complete from module docstring
tests/benchmarks/test_runner.py: all-pass rate -&gt; pass rate
of 1.0

Phase B (Rule 4 cleanup): rename roadmap-tier Phase N labels to
descriptive names while preserving the underlying tier semantics:
stable -&gt; stable
(pre-promotion) -&gt; pre-promotion (scaffold)
DTI benchmarks -&gt; DTI benchmarks
... -&gt; experimental ...

Touches docs/user-guide/operators/{foundation-models,protein,
metabolomics,drug-discovery}.md, docs/development/benchmarks.md,
benchmarks/singlecell/_foundation.py, and the four contract tests
that assert on the documentation prose
(test_genomics_foundation_contract,
test_singlecell_foundation_contract,
test_bench_secondary_structure). All 24 contract tests still
pass after the rename.
diff --git a/benchmarks/singlecell/_foundation.py b/benchmarks/singlecell/_foundation.py
@@ -32,7 +32,7 @@
         "status": "deferred",
         "stable_scope": "excluded",
         "reason": (
-            "Phase 3 stable imported-model claims are benchmarked only for "
+            "Stable imported-model claims are benchmarked only for "
             "cell_annotation and batch_correction."
         ),
         "required_harness": "dedicated_foundation_grn_harness",
diff --git a/docs/development/benchmarks.md b/docs/development/benchmarks.md
@@ -216,7 +216,7 @@ artifact and fails closed unless an existing baseline is available or baseline
 bootstrap is requested explicitly.
 For genomics promotion review, use
 `benchmarks.genomics.foundation_suite.build_genomics_foundation_promotion_report()`;
-it follows the same fail-closed guard path while preserving the current Phase 4
+it follows the same fail-closed guard path while preserving the current pre-promotion
 scaffold provenance boundaries in the stored suite report.
 
 ### Imported Foundation-Model Benchmarks
@@ -240,7 +240,7 @@ at the benchmark layer. In addition to benchmark tags, the promoted
 This keeps artifact identity and benchmark scenario identity on one shared
 schema for comparison, regression, and provenance tooling.
 
-Genomics Phase 4 scaffold reports also carry `dataset_provenance` so synthetic
+Genomics pre-promotion scaffold reports also carry `dataset_provenance` so synthetic
 interface validation cannot be mistaken for biological validation. The
 `synthetic_genomics` scaffold is recorded with:
 
@@ -266,13 +266,13 @@ checkpoint support:
 - supported: explicit scGPT batch-context metadata in comparison reports via
   `requires_batch_context`, `batch_key`, and `context_version`
 - supported: canonical single-cell deferral metadata that keeps
-  `grn_transfer` outside Phase 3 stable promotion until a dedicated
+  `grn_transfer` outside stable promotion until a dedicated
   foundation-aware GRN harness exists
-- Phase 4 scaffold: a shared `SequencePrecomputedAdapter` contract plus a
+- Pre-promotion scaffold: a shared `SequencePrecomputedAdapter` contract plus a
   genomics quick-suite scaffold for promoter, TFBS, and splice-site tasks
-- Phase 4 scaffold: `FrozenSequenceEncoderAdapter` for in-process frozen
+- Pre-promotion scaffold: `FrozenSequenceEncoderAdapter` for in-process frozen
   sequence encoder benchmarking under `adapter_mode=frozen_encoder`
-- Phase 4 scaffold: `DNABERT2PrecomputedAdapter` and
+- Pre-promotion scaffold: `DNABERT2PrecomputedAdapter` and
   `NucleotideTransformerPrecomputedAdapter` for aligned precomputed genomics
   artifacts, pending genomics realism and promotion evidence
 - supported: deterministic DTI source contracts for Davis affinity regression
diff --git a/docs/examples/advanced/grn-inference.md b/docs/examples/advanced/grn-inference.md
@@ -37,7 +37,7 @@ Side-by-side heatmaps of the ground truth regulatory matrix (left, blue) and inf
 
 ![Recall at different thresholds](../../assets/examples/singlecell/grn_threshold_recall.png)
 
-Bar chart of recall across thresholds shows 100% recall at threshold 0.0 (all edges predicted) and 0% at higher thresholds for the untrained model, confirming the need for training to produce meaningful regulatory weights.
+Bar chart of recall across thresholds shows recall of 1.0 at threshold 0.0 (all edges predicted) and 0.0 at higher thresholds for the untrained model, confirming the need for training to produce meaningful regulatory weights.
 
 ```
 Ground truth GRN: 5 TFs x 20 genes
diff --git a/docs/examples/advanced/multiomics-integration.md b/docs/examples/advanced/multiomics-integration.md
@@ -4,7 +4,7 @@ This example demonstrates differentiable multi-omics integration using DiffBio's
 
 ## What is Multi-omics Integration?
 
-Multi-omics integration combines data from multiple biological measurement types (genomics, transcriptomics, epigenomics, proteomics) to gain comprehensive insights into cellular function. Key applications include:
+Multi-omics integration combines data from multiple biological measurement types (genomics, transcriptomics, epigenomics, proteomics) to gain joint insights into cellular function. Key applications include:
 
 - **Spatial transcriptomics**: Mapping gene expression to tissue locations
 - **3D genome organization**: Understanding chromatin folding and gene regulation
diff --git a/docs/examples/basic/pileup-generation.md b/docs/examples/basic/pileup-generation.md
@@ -366,7 +366,7 @@ The small mean change with larger max change is expected behavior:
 ### Visualizing Quality Filtering Effect
 
 ```python
-# Create comprehensive visualization
+# Create full visualization
 fig, axes = plt.subplots(2, 2, figsize=(14, 10))
 
 # Top left: Original pileup
diff --git a/docs/index.md b/docs/index.md
@@ -14,7 +14,7 @@ DiffBio provides differentiable implementations of core bioinformatics algorithm
   <div class="stat-label">GPU-Accelerated</div>
 </div>
 <div class="stat-card">
-  <div class="stat-value">100%</div>
+  <div class="stat-value">End-to-End</div>
   <div class="stat-label">Differentiable</div>
 </div>
 <div class="stat-card">
diff --git a/docs/user-guide/losses/singlecell.md b/docs/user-guide/losses/singlecell.md
@@ -184,7 +184,7 @@ def velocity_model_loss(model, spliced, unspliced):
 
 ## Combining Losses
 
-For comprehensive single-cell analysis:
+For full single-cell analysis:
 
 ```python
 from diffbio.losses.singlecell_losses import (
diff --git a/docs/user-guide/operators/drug-discovery.md b/docs/user-guide/operators/drug-discovery.md
@@ -24,7 +24,7 @@ Drug discovery operators enable gradient-based optimization for chemoinformatics
 The current benchmarked drug-discovery surface has two layers:
 
 - stable property-prediction benchmarking via MoleculeNet BBBP
-- Phase 6 DTI benchmarks for Davis and BioSNAP, using deterministic paired
+- DTI benchmarks for Davis and BioSNAP, using deterministic paired
   protein-plus-drug sources and `DifferentiableDTIPipeline`
 
 The DTI benchmarks are still synthetic-fallback aware, but they now exercise the
diff --git a/docs/user-guide/operators/foundation-models.md b/docs/user-guide/operators/foundation-models.md
@@ -4,7 +4,7 @@ DiffBio provides differentiable foundation-model operators for DNA/RNA
 sequences and single-cell expression. The current stable imported-model surface
 is intentionally narrow: precomputed Geneformer and scGPT artifacts for
 single-cell annotation and batch correction. Sequence/genomics adapters and
-frozen benchmark paths exist as Phase 4 pre-promotion scaffold until genomics
+frozen benchmark paths exist as pre-promotion scaffold until genomics
 realism and promotion evidence is attached.
 
 These operators sit in DiffBio's biology-specific layer and reuse the wider
@@ -37,7 +37,7 @@ profiles into dense embeddings using transformer architectures:
 
 Post-DTI stable boundary: benchmark-backed operator support is separate from imported foundation-model promotion.
 
-For Phase 7 domains, the stable surface is intentionally smaller than the
+For experimental domains, the stable surface is intentionally smaller than the
 available experimental interfaces:
 
 | Domain | Verified Capability | Stable Boundary |
@@ -108,8 +108,8 @@ from intended future scope.
 
 `GRN transfer` remains planned in the single-cell suite scenarios, but it is
 not yet a stable imported-model claim because the imported foundation-model
-path is only benchmarked today on annotation and batch correction. Phase 3
-keeps GRN outside stable imported-model promotion until a dedicated foundation-aware GRN harness exists.
+path is only benchmarked today on annotation and batch correction. The
+stable scope keeps GRN outside imported-model promotion until a dedicated foundation-aware GRN harness exists.
 
 ### Precomputed Adapter Examples
 
@@ -150,7 +150,7 @@ The artifact metadata stays explicit:
 ## Imported Sequence Workflows
 
 DiffBio now also exposes a shared sequence benchmark adapter contract. These
-Phase 4 pre-promotion scaffold integrations are available for interface
+Pre-promotion scaffold integrations are available for interface
 validation and benchmark development:
 
 - `SequencePrecomputedAdapter` for aligned imported artifacts
@@ -172,15 +172,15 @@ This does **not** mean arbitrary DNABERT-2 or Nucleotide Transformer
 checkpoints are already supported in-process, and it does not mean genomics has
 been promoted as a stable imported-model domain. The sequence surface today is
 interface validation over precomputed artifacts plus DiffBio-native frozen
-in-process sequence encoder benchmarking. Phase 4 must attach dataset
+in-process sequence encoder benchmarking. Pre-promotion must attach dataset
 provenance, realism, and promotion evidence before genomics can be described as
 stable.
 
 ## Genomics Scaffold Support Matrix
 
 This scaffold support matrix is derived from the genomics foundation benchmark
 harness and contract tests. It is intentionally not a stable genomics support
-matrix until Phase 4 promotion evidence exists.
+matrix until promotion evidence exists.
 
 | Adapter | Adapter Mode | Verified Scaffold Tasks | Scope Exclusions |
 |---------|--------------|--------------------------|------------------|
@@ -242,7 +242,7 @@ report = build_singlecell_foundation_suite_report(results)
 
 That suite report also carries one canonical `deferred_tasks` block so planned
 but unverified work stays explicit in stored artifacts. Today that means
-`grn_transfer` is marked deferred from Phase 3 stable scope until a dedicated foundation-aware GRN harness exists.
+`grn_transfer` is marked deferred from stable scope until a dedicated foundation-aware GRN harness exists.
 When a stable-scope review is needed, the same suite report can be paired with
 the stored Calibrax regression result to produce one promotion-review artifact
 instead of a benchmark-specific summary path. Use
@@ -260,7 +260,7 @@ promoter classification, TFBS classification, and splice-site classification.
 That suite can run the native DiffBio sequence encoder, a frozen in-process
 DiffBio sequence encoder, and the current precomputed DNABERT-2 and Nucleotide
 Transformer adapters through the same deterministic reporting layer. This is
-Phase 4 scaffold evidence, not a stable genomics promotion claim.
+pre-promotion scaffold evidence, not a stable genomics promotion claim.
 
 The genomics suite reports this boundary as machine-readable
 `dataset_provenance`. The default `synthetic_genomics` scaffold records
diff --git a/docs/user-guide/operators/metabolomics.md b/docs/user-guide/operators/metabolomics.md
@@ -12,7 +12,7 @@ Metabolomics operators enable gradient-based optimization for mass spectrometry
 
 ## Metabolomics expansion scope
 
-Phase 7 adds shared artifact handling for precomputed metabolomics embeddings
+Experimental scope adds shared artifact handling for precomputed metabolomics embeddings
 through `MetabolomicsEmbeddingSource`, which aligns imported spectrum
 embeddings by `spectrum_ids`. This reuses the same indexed embedding substrate
 as other imported artifacts and keeps spectrum-row identity explicit.
diff --git a/docs/user-guide/operators/protein.md b/docs/user-guide/operators/protein.md
@@ -12,7 +12,7 @@ Protein structure operators enable gradient-based optimization for structural bi
 
 ## Protein foundation-model scope
 
-Phase 7 protein foundation-model support is deliberately narrow. DiffBio now
+Experimental protein foundation-model support is deliberately narrow. DiffBio now
 uses the shared sequence foundation substrate for protein sequence context in
 the secondary-structure benchmark and provides a strict adapter contract for
 precomputed protein-LM artifacts. This means exported embedding matrices can be
diff --git a/docs/user-guide/operators/singlecell.md b/docs/user-guide/operators/singlecell.md
@@ -1,6 +1,6 @@
 # Single-Cell Operators
 
-DiffBio provides comprehensive differentiable operators for single-cell analysis, including clustering, batch correction, and RNA velocity.
+DiffBio provides differentiable operators for single-cell analysis, including clustering, batch correction, and RNA velocity.
 
 <span class="operator-singlecell">Single-Cell</span> <span class="diff-high">Fully Differentiable</span>
 
diff --git a/docs/user-guide/sources.md b/docs/user-guide/sources.md
@@ -1,6 +1,6 @@
 # Data Sources
 
-DiffBio provides data source modules that integrate seamlessly with the Datarax framework for loading bioinformatics and drug discovery datasets.
+DiffBio provides data source modules that integrate with the Datarax framework for loading bioinformatics and drug discovery datasets.
 
 <span class="operator-md">Data Loading</span> <span class="diff-structural">Structural Module</span>
 
@@ -26,7 +26,7 @@ DataSourceModule (Datarax)
 
 ## Genomics Sources
 
-DiffBio provides optimized data sources for common genomics file formats, built on state-of-the-art libraries.
+DiffBio provides optimized data sources for common genomics file formats, built on widely used libraries.
 
 ### BAMSource - Aligned Reads
 
diff --git a/tests/benchmarks/test_bench_secondary_structure.py b/tests/benchmarks/test_bench_secondary_structure.py
@@ -251,7 +251,7 @@ def test_foundation_metadata_uses_protein_sequence_substrate(self, result) -> No
 
 
 def test_protein_docs_keep_lm_scope_limited() -> None:
-    """Protein docs should not overstate Phase 7 foundation-model support."""
+    """Protein docs should not overstate experimental foundation-model support."""
     from pathlib import Path
 
     doc = Path("docs/user-guide/operators/protein.md").read_text(encoding="utf-8")
diff --git a/tests/benchmarks/test_genomics_foundation_contract.py b/tests/benchmarks/test_genomics_foundation_contract.py
@@ -142,12 +142,12 @@ def test_docs_keep_genomics_scaffold_outside_stable_promotion(self) -> None:
         )
         benchmark_guide = (repo_root / "docs/development/benchmarks.md").read_text(encoding="utf-8")
 
-        assert "Phase 4 pre-promotion scaffold" in user_guide
+        assert "pre-promotion scaffold" in user_guide
         assert "not a stable genomics promotion claim" in user_guide
         assert "`dataset_provenance`" in user_guide
         assert "`promotion_eligible`: `false`" in user_guide
         assert "stable sequence integrations today" not in user_guide
-        assert "Phase 4 scaffold: `DNABERT2PrecomputedAdapter`" in benchmark_guide
+        assert "Pre-promotion scaffold: `DNABERT2PrecomputedAdapter`" in benchmark_guide
         assert "pending genomics realism and promotion evidence" in benchmark_guide
         assert "`source_type`: `scaffold`" in benchmark_guide
 
diff --git a/tests/benchmarks/test_runner.py b/tests/benchmarks/test_runner.py
@@ -249,7 +249,7 @@ def test_empty_results(self) -> None:
         assert summary.pass_rate == 0.0
 
     def test_all_pass(self) -> None:
-        """All passing results give 100% pass rate."""
+        """All passing results give a pass rate of 1.0."""
         results = [
             EvalResult(
                 problem_id=f"p{i}",
diff --git a/tests/benchmarks/test_singlecell_foundation_contract.py b/tests/benchmarks/test_singlecell_foundation_contract.py
@@ -70,7 +70,7 @@ def test_deferred_tasks_keep_grn_outside_phase_3_stable_scope(self) -> None:
                 "status": "deferred",
                 "stable_scope": "excluded",
                 "reason": (
-                    "Phase 3 stable imported-model claims are benchmarked only for "
+                    "Stable imported-model claims are benchmarked only for "
                     "cell_annotation and batch_correction."
                 ),
                 "required_harness": "dedicated_foundation_grn_harness",
diff --git a/tests/operators/drug_discovery/test_fingerprint_correctness.py b/tests/operators/drug_discovery/test_fingerprint_correctness.py
@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Comprehensive Fingerprint Benchmark for DiffBio.
+"""Fingerprint correctness benchmark for DiffBio.
 
 This benchmark evaluates DiffBio's fingerprint operators including:
 - CircularFingerprintOperator (ECFP4)
