# ADR: EP-CAP-003 Vocabulary Reference Migration Guard

Status: accepted

Context: approved ability, capability, and feature names are free text in v0.1.
EP-CAP-003 expects a later nullable `vocabulary_ref` column so approved entries
can be anchored to a named vocabulary version after terminology standardises.

Decision: keep the v0.1 approved registry schema ID-based and free of natural-key
constraints on `name`.

The current schema leaves the migration path open:

- `approved_abilities.name`, `approved_capabilities.name`, and
  `approved_features.name` have no `CHECK` constraints.
- There are no unique indexes on `name` alone.
- Approved table foreign keys point to integer row IDs, not name strings.
- `review_decisions` records `repository_id`, optional `analysis_run_id`,
  `action`, and `notes`; it does not reference ability, capability, or feature
  names as durable identifiers.

The guard test in `tests/test_storage_migrations.py` introspects the SQLite
schema and fails if a future migration adds name-only uniqueness, name-based
foreign keys, or review decision name references that would make
`name + vocabulary_ref` a painful future key.

Consequence: no `vocabulary_ref` column is added now. When EP-CAP-003 is
implemented, the expected migration is additive: add nullable vocabulary columns,
backfill where vocabulary mappings exist, then introduce any future composite
constraints deliberately after legacy rows have been reconciled.