# Curated annotation rules

Rules written and owned by this project. Each `CR-nnnn.yaml` is a `CuratedRule`
(`src/ai_gene_review/schema/gene_review.yaml`). A rule couples the sequence-feature
logic of an annotation with the taxon or context logic that limits it, in one
auditable record, and names the external source it replaces.

| Rule | Assigns | Conditions | Replaces | Status |
|---|---|---|---|---|
| [CR-0001](CR-0001.yaml) | GO:0007034 vacuolar transport | IPR005024 AND Eukaryota | interpro2go IPR005024 | PROPOSED |
| [CR-0002](CR-0002.yaml) | GO:0061639 Cdv-dependent cytokinesis | IPR053654 OR IPR053492 | (new coverage) | PROPOSED |
| [CR-0003](CR-0003.yaml) | GO:0006511 ubiquitin-dependent protein catabolic process | IPR000426 AND ubiquitin relay module not absent | interpro2go IPR000426 | PROPOSED |
| [CR-0004](CR-0004.yaml) | EC 1.2.1.75 name, RHEA:26446 | FunFam 3.40.50.720:FF:000411 AND MCR-type CDD AND Archaea | ARBA00067001, ARBA00052213 | PROPOSED |
| [CR-0005](CR-0005.yaml) | GO:0044548 S100 protein binding | IPR037893 AND Chordata | interpro2go IPR037893 | PROPOSED |
| [CR-0006](CR-0006.yaml) | GO:0005118 sevenless binding, GO:0045500 sevenless signaling pathway | IPR002956 AND IPR050726 AND Diptera | interpro2go IPR002956 (sevenless binding) | PROPOSED |
| [CR-0007](CR-0007.yaml) | GO:0020037 heme binding, GO:0009055 electron transfer activity | CDD cd21555 | (new coverage; model unintegrated in InterPro) | PROPOSED |

## Semantics

- A rule fires when **any** condition set holds; a set holds when **all** its
  conditions hold. `negated: true` inverts a condition.
- Every set needs at least one non-negated sequence-feature condition (InterPro,
  Pfam, PANTHER, FunFam, CDD, NCBIfam). Taxon and module conditions only restrict.
- `MODULE_CONTEXT` conditions name a module in `modules/` and are
  **exclusion-only**: the condition fails only when the module is evaluated as
  unsatisfiable in the protein's organism or context, and holds when it is
  satisfiable or not evaluated. A missing component may be a detection gap, so
  absence of evidence never blocks an annotation. They cannot be negated.
  This default has a cost where the module is rare in a lineage: CR-0003 keeps 149
  archaeal annotations on unevaluated proteomes although the relay was found in 3 of
  504 complete ones (see its notes). Before choosing a module condition over a taxon
  condition, count what each keeps and what each drops, and record both in
  `validation_runs`.

## When to use which condition

Use the condition that actually separates right from wrong members:

- **Taxon** when a whole lineage lacks the prerequisite and the taxon is an exact
  proxy for it (CR-0001: only eukaryotes have a vacuole).
- **Module context** when the prerequisite is a set of components that a taxon
  only approximates (CR-0003: a ubiquitin conjugation system, which some archaea
  may have).
- **Sequence features** (CDD models, sites, subfamilies) when the problem is
  paralogy or a subfamily with a different function; a taxon cannot help when
  both paralogs sit in the same genome (CR-0004).

If a term is wrong for every member of an entry, no rule is needed: record the
removal in `projects/INTERPRO/interpro2go.sssom.yaml` or the ARBA rule review.

## Relation to other records

- `projects/INTERPRO/interpro2go.sssom.yaml` records what is wrong with a
  mapping; a row that cannot be fixed inside interpro2go names its replacement
  rule ("REPLACE WITH RULE CR-nnnn").
- `rules/arba/<ID>/<ID>-review.yaml` records what is wrong with a UniProt rule;
  the curated rule lists it under `replaces`.
- Modules provide the context layer. Rules whose components are detected by
  other rules must not depend, through a module, on themselves.

## Module-context oracle

`src/ai_gene_review/context_oracle.py` evaluates a `MODULE_CONTEXT` condition for a
UniProt proteome. A detector file in `context/` maps each module step to InterPro
signatures (sensitive on purpose, since the oracle only excludes); the module is
then evaluated with `module_logic`. It returns satisfiable, unsatisfiable (only for
a complete proteome: reference proteome, full assembly, BUSCO at least 95) or not
evaluated. Results are cached in `context/cache/` and summarised in
[context/RESULTS.md](context/RESULTS.md).

## Commands

```bash
just validate-curated-rules           # schema + semantic checks
just count-curated-rules              # UniProtKB match counts (network)
just evaluate-module-context rules/curated/context/ubiquitin_transfer_relay.yaml UP000008243 --rule rules/curated/CR-0003.yaml
```

`count-curated-rules` turns each rule into a UniProt query (module conditions
cannot be queried and are left out, so the count is an upper bound). Record
the result in the rule's `validation_runs`.