vocabulary ref and schema guard test

docs/adr-ep-cap-003-vocabulary-ref-guard.md

@@ -0,0 +1,30 @@
+# 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.