Форматы репозитория требований v2

Основной принцип

Авторский материал хранится в Markdown и редактируется непосредственно. Агент проверяет смысл, полноту, противоречия и последствия изменения. Для автоматических проверок выделяется небольшой набор контрольных полей. Порядок разделов, пояснения и дополнительные колонки могут меняться.

Строгий машинный формат вводится, когда данные потребляет программа, проверка повторяется часто или ошибка существенно опасна. Не следует переводить весь документ в JSON ради проверки нескольких полей. Подробный выбор по каждому артефакту: ARTIFACTS.md.

Канонические источники

generated/ содержит только вычисляемые coverage.md и traceability.md. Это необязательные отчёты/кэш; источником требований они не являются. JSON-вывод покрытия создаётся по запросу командой python scripts/reqtool.py coverage --json, отдельно сохранять generated/coverage.json не нужно.

Размещение HLR и материалов

Точка входа — docs/requirements/README.md. Канонические определения HLR находятся в Markdown-файлах предметных пакетов внутри docs/requirements/. В одном файле допускается несколько HLR. Статусы и приоритеты не дублируются в оглавлении; группировка каталогов не создаёт дополнительного уровня требований.

Загрузчик рекурсивно читает *.md в каталоге, исключая assets/, attachments/ и скрытые каталоги. Содержимое приложений не становится требованиями автоматически. При чтении проверяются те же метаданные и глобальная уникальность ID. Прежний docs/requirements.md также поддерживается; в новом комплекте это только ссылка на оглавление. Без прежнего файла каталог продолжает работать.

В assets/README.md обычным Markdown описываются назначение, источник/версия, связанные требования и роль материала. Иллюстрация не вводит нормативных правил. Нормативный источник явно связывается с требованием; существенные обязательства доступны в тексте. Относительные ссылки отсчитываются от документа; поля sources остаются путями от корня репозитория. Нормативные источники в sources участвуют в проверке ссылок и анализе влияния.

Вопросы

Один вопрос — раздел ## Q-AREA-001 — Формулировка. Свободно описывайте контекст, варианты и влияние. Для проверки готовности используются поля:

## Q-AREA-001 — Как обрабатывается частичный ответ?

- Статус: open
- Ответственный: product-owner
- Требования: REQ-AREA-001
- Блокирует: REQ-AREA-001
- Этапы: implementation
- Решение: —
- Рабочее решение: —

### Контекст

Пояснение проблемы и варианты решения.

Статус open/resolved. Блокирует содержит ID требований либо «—». Этапы: implementation/release либо «—». Вопрос со статусом resolved ссылается на DEC; open не содержит финального решения. Необязательное поле «Рабочее решение» содержит один текущий DEC со статусом working; отсутствующее поле эквивалентно «—». Оно не меняет статус вопроса или его блокировки. Рабочий DEC должен быть связан с открытым вопросом; proposed/working не используются как финальный ответ для resolved. Контрольные значения не извлекаются из произвольной прозы: неоднозначная запись должна остановить проверку, а не скрыть блокировку. Владелец, срок ответа, варианты и влияние проверяются агентом.

Решения и допущения

Решение — раздел ## DEC-AREA-001 — Выбранный вариант, поля Статус, Требования, Заменяет и обычные разделы «Обоснование», «Альтернативы», «Последствия», «Источник». Статусы proposed/working/accepted/deprecated/superseded. Working — рабочий вариант, принятый к реализации при открытом вопросе; accepted — окончательно принятый вариант. Для архитектурных решений используйте DEC-ARCH-*. Изменение принятого выбора оформляйте новым решением с ссылкой на замещаемое.

Допущение — раздел ## ASM-AREA-001 — Предположение, поля Статус, Требования и Блокирует; далее основание, риск и способ подтверждения. Статусы unconfirmed/confirmed/rejected. Неподтверждённое допущение блокирует --ready для перечисленных требований. Подтверждение должно объяснять, на каких данных основан вывод; его достаточность оценивает агент.

Не требуется заполнять машинной схемой всю пояснительную часть. Проверяются ID, статусы и выбранные связи; содержательная полнота остаётся предметом ревью.

Применимость

docs/applicability.md — редактируемая таблица. Контрольные колонки: Область, Статус (pending/assessed), Применимо (да/нет), Артефакты. Обоснование пишется свободно. profile/profile.json задаёт список областей проверяемого профиля. Pending означает, что область ещё не рассмотрена; assessed не доказывает полноту её спецификации.

Протяжка и разбор изменения

В impact/stretch-matrix.md правило имеет ID IMPACT, поля «Изменения ID» и «Изменения путей», таблицу «Пересмотреть | Причина». Пути-триггеры — glob относительно корня репозитория. Цель — существующий ID или файл. Пустой список обозначается «—». Это авторские связи влияния; инструмент также находит известные прямые связи требований, проверок, данных и выбранного каталога.

В impact/reviews/*.md один раздел REVIEW, поле «Изменения» и таблица «Правило | Цель | Статус | Вывод | Основание». Статусы pending/updated/checked/not_applicable. Для завершённой позиции нужны вывод и ссылки-основания. Существование основания проверяет скрипт, его достаточность — агент. Если используется автоматически рассчитанный план, старый разбор с пропущенными позициями отклоняется. Это проверка полноты известного списка, а не утверждение, что найдено всё влияние.

Автоматизируемые REQ, проверки и данные

По умолчанию сценарий приёмки — читаемый Markdown с исходной ситуацией, действием и наблюдаемым результатом. JSON вводится для конкретного машинного потребителя. Методическая основа и границы автоматизации описаны в GUIDE.md, раздел «Подход к сценариям приёмки».

Форма JSON-сценария — собственный профиль репозитория, а не общепринятый формат сценариев или штатный формат OpenSpec. JSON Schema задаёт структуру этого профиля, но не проверяет корректность бизнес-смысла или поведение продукта.

Для часто проверяемого покрытия сохраняется прежний блок requirement в Markdown спецификации: id, level, status, owner, parents, sources, questions, required_aspects, verification, risk. HLR имеет пустые parents/aspects; REQ — родителей HLR и аспекты обязательства. Status: draft/agreed/retired. Нормативный текст остаётся обычным Markdown, MUST/SHALL обозначает обязательство. Шаблон: templates/spec.md.

acceptance/scenarios/*.json используется для выбранного автоматического контроля: один CHECK может ссылаться на несколько REQ/aspects, один REQ проверяться многими CHECK. Uses — предусловие и не засчитывается в покрытие. Case_ids ограничивает применимые случаи; oracle должен существовать в expected каждого случая. Implementation=null означает план проверки. Даже заполненная implementation обозначает связь с реализацией проверки, а не успешное исполнение; нужны отдельные результаты испытаний. Человеческие сценарии без такого контроля можно описывать непосредственно в Markdown; не следует объявлять их автоматически покрытыми.

acceptance/datasets/*.json и contracts/*.schema.json содержат машинные входы и эталоны. Valid описывает соответствие входа схеме, а не успешность бизнес-действия. Отказ чужой роли может быть valid=true. Эти форматы оправданы повторяемой валидацией входов и контрактов.

Архитектурные проверки

Представления в architecture/ — авторский Markdown/Mermaid. Каталог architecture/catalog.md задаёт единственные определения элементов, статических связей и владельцев. Для выбранных частых проверок его таблицы имеют контрольные колонки ID/Тип/Родитель, От/К/Доступ/Сущность, владельцы/читатели, распределение REQ и связь ограничения с решением/проверкой.

profile/profile.json / architecture_required=true включает проверки каталога: ссылки, единственного владельца записи, допустимых читателей и значимых архитектурных ограничений. В примере этот контроль выбран из-за риска потери уведомления и раскрытия данных. В стартовом шаблоне он отключён: сначала определите, какие ограничения стоят такой проверки. Порядок и пояснительные колонки свободны; диаграммы, runtime, размещение и достаточность NFR проверяет агент. Каталог не превращает все архитектурные документы в строгую машинную модель.

История и идентификаторы

ID стабилен и уникален в основном снимке. Повтор ссылки допустим; archive и templates не являются новыми декларациями. OpenSpec проверяет текущий снимок отдельно от изменения/архива. Reqtool не применяет deltas автоматически. Ссылки на файлы в Markdown относительны к самому документу; JSON-пути к машинным входам — к корню репозитория.