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.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01814GKVzZVL3FuF3DeiZXhv

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`).