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

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.