Единый manifest применимости стандартов¶

Требования применяются к .standards/standards.yaml проекта и охватывают архитектурные компоненты, возможности и цели развёртывания. Уровни обязательности определены в корневом README.md.

В этом документе формальный признак применимости — ссылка применимого документа на объявленный компонент или возможность проекта.

STD-MAN-001. Расположение и схема manifest¶

Уровень: MUST

Применяется к: прикладному проекту, использующему этот репозиторий стандартов

Проект должен хранить manifest в .standards/standards.yaml. Значение schema_version должно быть равно 3, а структура manifest должна соответствовать standards-manifest.schema.json.

Обоснование¶

Стабильное расположение и версия позволяют человеку и ИИ-агенту найти и проверить manifest без эвристик.

Проверка¶

валидация файла по JSON Schema;
запуск scripts/standards.py validate.

Исключения¶

Иное расположение внутри корня проекта требует ADR, исключения STD-MAN-001 в manifest и документированной команды проверки. Хранить manifest вне корня проекта запрещено.

STD-MAN-002. Фиксация версии стандартов¶

Уровень: MUST

Применяется к: каждому manifest

Объект standards должен содержать непустой release-тег в tag и полный 40-символьный Git commit SHA в commit_sha. Оба значения должны обозначать одну версию этого репозитория.

CI прикладного проекта должен получить checkout по tag, сравнить его фактический HEAD с commit_sha и завершиться ошибкой при несовпадении. Checkout должен быть чистым: локально изменённый или добавленный файл стандартов не должен использоваться как содержимое зафиксированного commit. Локальная проверка формата manifest не заменяет эту сверку с Git.

Обоснование¶

Тег удобен человеку, а commit SHA однозначно связывает решение с неизменяемым содержимым.

Проверка¶

проверка формата значений по JSON Schema;
scripts/standards.py verify-version либо scripts/standards.py check;
воспроизведение команд из ненормативного руководства по подключению.

Исключения¶

Значение unreleased MAY использоваться только пока в репозитории стандартов нет ни одного release-тега; полный commit SHA остаётся обязательным. После первого release нетегированный commit стандартов не должен подключаться как unreleased.

STD-MAN-003. Формальные признаки проекта¶

Уровень: MUST

Применяется к: каждому manifest

Массив components должен перечислять запускаемые и публикуемые компоненты проекта. Каждый компонент должен иметь id и один kind из перечня схемы.

Массив capabilities должен перечислять только фактически реализуемые возможности из перечня схемы. Каждая возможность должна иметь id, тип type и хотя бы один непустой массив providers или consumers с ID участвующих компонентов. Все id компонентов и возможностей должны быть уникальны во всём manifest. Компонент, предоставляющий контракт или результат, указывается в providers; использующий его компонент — в consumers. Возможность, отсутствующая в проекте, не должна добавляться «на будущее».

Для возможности без отношения producer/consumer массив providers должен перечислять компоненты, которые реализуют, исполняют или публикуют эту возможность. Значение роли не должно выводиться из имени capability или каталога компонента.

Обоснование¶

Явные факты о составе проекта позволяют определять применимость без вывода из названий каталогов, языка или framework.

Проверка¶

проверка уникальности и ссылочной целостности ID;
сопоставление с deployment-, build- и API-контрактами проекта;
проверка отсутствия несуществующих возможностей.

Исключения¶

Новый тип, отсутствующий в схеме, требует обновления стандарта; свободное строковое значение вместо типа запрещено.

STD-MAN-004. Вычисление применимых документов¶

Уровень: MUST

Применяется к: каждому manifest

Перечень применимых документов должен вычисляться из components, capabilities, ролей providers и consumers, а также из профилей каждой цели targets по каталогам в architecture.json и infrastructure.json. Manifest не должен содержать вручную поддерживаемый массив документов.

Каталог должен соответствовать applicability-catalog.schema.json и реализовывать правила DEV-PROF-001–DEV-PROF-003. Каждый путь каталога должен обозначать существующий нормативный документ.

Обоснование¶

Вычисление устраняет дублирование перечня в manifest и даёт одинаковый результат человеку, CI и ИИ-агенту.

Проверка¶

scripts/standards.py explain;
валидация каталога по JSON Schema;
проверка существования путей каталога.

Исключения¶

Не допускаются для ручного переопределения вычисленного перечня. Исключение из отдельного требования оформляется по STD-MAN-005.

STD-MAN-005. Исключения из требований¶

Уровень: MUST

Применяется к: согласованному исключению из требования

Массив exceptions должен содержать объект с точным requirement_id и относительным путём к ADR в adr. Один объект должен ссылаться на одно требование, а один requirement_id должен встречаться в массиве не более одного раза. Требование должно находиться в документе, вычисленном для этого manifest по STD-MAN-004; неприменимость не оформляется как исключение. При отсутствии исключений поле MAY отсутствовать.

Причины, риски, компенсирующие меры, владелец, срок и условия пересмотра должны находиться в ADR, а не дублироваться в manifest. ADR должен соответствовать DEV-ADR-001, иметь status: accepted, совпадающий requirement_id и неистёкший expires_on.

Обоснование¶

Manifest остаётся кратким индексом, а решение и его жизненный цикл сохраняются в предназначенном для этого документе.

Проверка¶

проверка существования ID в зафиксированной версии стандартов;
проверка принадлежности ID вычисленному перечню документов;
проверка существования ADR;
проверка front matter, статуса, ID и срока ADR командой validate или check;
review содержания ADR по правилам корневого README.md.

Исключения¶

Не допускаются для ссылки на несуществующий ID или ADR.