TRACEABILITY — как будет проверяться связность артефактов¶

Зачем¶

Документация полезна агенту и владельцу, только если её утверждения можно проверить. «Поле marked_at хранится в core» — это не текстовая заметка, а утверждение о контракте, миграции, коде и тесте. Граф трассируемости делает такое утверждение явным и проверяемым.

Кто формирует граф¶

Никто не строит его из догадок. Есть два слоя:

Сканеры извлекают факты: ADR из DECISIONS.md, поля из .proto, колонки из миграций, экспортируемые символы и имена тестов из кода.
Автор изменения добавляет только семантические связи в том же MR: «эта задача реализована этим полем», «эта миграция хранит это поле», «этот тест доказывает это требование». Обычно это делает агент, но связь проверяется в описании MR и не считается истинной, пока валидатор не найдёт оба конца.

Такой подход не позволяет ИИ придумать несуществующее поле: ссылка на него не пройдёт проверку. Но он и не заставляет человека вручную переписывать каталог всех файлов — факты берутся из исходников.

Почему граф распределённый¶

Mybit состоит из отдельных Git-репозиториев. Поэтому один файл в platform не может честно валидировать символы core-service или proto в их собственных CI.

Каждый сервис хранит свой небольшой trace-фрагмент и проверяет локальные пути, символы и тесты в собственном pipeline.
platform хранит связи между репозиториями: issue, ADR, сервис, контракт, владелец данных.
Atlas собирает фрагменты в единый читательский граф. Сломанная ссылка видна и в CI того репозитория, где она появилась, и в Atlas.

Минимальная декларация¶

Для критичных изменений будет использоваться компактный машиночитаемый фрагмент:

id: core-ingest-sets
implements:
  - issue: mybit/platform#13
  - adr: ADR-0027
provides:
  - proto: mybit.core.v1.SetRecord.marked_at
  - database: core.workout_sets.marked_at
  - symbol: internal/ingest.IngestSets
verified_by:
  - test: TestIngestSetsStoresMarkedAt

В первой версии валидатор проверяет существование всех целей. Позже он строит отчёты: сироты, непокрытые требования, поля без тестов и устаревшие связи.

Порядок внедрения¶

Ввести Atlas — сайт, который удобно читать.
Добавить trace-фрагменты и проверки в proto и core-service: это самая ценная граница «контракт → БД → реализация → тест».
Вывести получившийся граф и список сирот в Atlas.
Расширять на остальные сервисы только там, где связь приносит пользу.

Граф не является заменой кода, тестов или ревью. Он делает существующие доказательства легко находимыми и не даёт документации ссылаться на выдуманные.