PGx phenotypes: pgx phenotype|annotate (PGX-024..028, CLI-034)

CPIC lookups by allele function counts or activity values (duplications N x activity, *5/*0 = 0, total-score
fallback), Indeterminate when feasible solutions disagree or an allele is not in the guideline; per-sample
simurg.pgx/1 JSON and diplotype_annotations.tsv with PGX-026 metadata lines.

docs/messages.md

@@ -45,6 +45,7 @@ Generated from `src/simurg/core/errors.py` — do not edit by hand.
 | `E_PGX_BATCH_TOO_SMALL` | error | Too few (passing) samples in the batch for PGx CN calling | PCN-004 |
 | `E_PGX_CN_FAILED` | error | PGx CN calling failed for the sample | PCN-002 |
 | `E_PGX_CN_MISSING` | error | A sample has no PGx CN VCF (give --no-cn to run without) | PGX-011 |
+| `E_PGX_GUIDELINE` | error | Guideline tables not present in the PGx DB | PGX-025 |
 | `E_PGX_SOURCE` | error | PGx source tables missing; run scripts/pgx/fetch_sources.sh | PGX-001 |
 | `E_PGX_TRAIN_TOO_SMALL` | error | Too few (passing) samples to train a PGx CN model | PCN-005 |
 | `E_PGX_VCF_UNINDEXED` | error | SNV VCFs for PGx must be bgzipped and indexed | PGX-011 |

docs/validation/V2_pgx_star.md

@@ -6,6 +6,10 @@ Status: **implemented for CPIC star-allele genes, interim validation** (2026-09-
 * `simurg pgx db build` → deterministic SQLite: 22 genes, 1354 alleles, 1897 normalised variant rows; GSA v4 PGx
   probe map 5002 links; two builds byte-identical.
 * `simurg pgx star-allele call` → `diplotype_summary.tsv`, `pgx_calls.json` (11 star-allele genes).
+* `simurg pgx phenotype` (alias `annotate`) → per-sample `<sample>.pgx.json` (`simurg.pgx/1`) and
+  `diplotype_annotations.tsv` with `#` metadata lines (PGX-024 … PGX-028); CPIC activity scores (xN = N × activity,
+  *5/*0 = 0) and function-count lookups; disagreeing feasible solutions → `Indeterminate` plus per-solution
+  phenotypes. `tests/unit/test_pgx_phenotype.py`.
 * Unit tests: `tests/unit/test_pgx_db.py`, `tests/unit/test_pgx_star.py`.
 
 ## Data and truth
@@ -54,5 +58,9 @@ so the per-call error is 1e-3 (GS ≥ 0.15) and errors are handled by the probe
 ## Caveats
 
 * 16 individuals, one array type, European (CEPH) only; masks from 14 individuals (spec: ≥ 100 samples).
+* CPIC now defines the GRCh38 reference as its own allele where it differs from *1 (CYP2C19 *38): a sample
+  heterozygous at the *1-defining rs3758581 fits *1/*38 best (raw score 0.98), but *38 has no CPIC frequency, so the
+  prior keeps *1/*1 on top — which is what legacy GeT-RM reports.
 * Not yet: named-haplotype (G6PD), variant-based and tagging genes; CYP2D6 hybrids (*13, *36, *68); PharmVar-only
-  genes (CYP2A6, CYP3A4, CYP1A2, …); phenotype annotation (PGX-025) and the JSON schema (PGX-028).
+  genes (CYP2A6, CYP3A4, CYP1A2, …); DPWG tables; the full per-allele supporting/unresolved-variant detail of
+  PGX-027/028 (`supporting_variants.tsv`, `unresolved_variants.tsv`, `variants_not_covered.tsv`).