# Предлагаемый формат спецификации и проверка артефакта

**Статус: авторская гипотеза стандарта, частично проверенная программная реализация.** Это не опубликованный отраслевой стандарт и не доказательство, что полевое задание было исполнено. Схема и пример записаны в JSON; семантический валидатор проверен на контролируемых синтетических вариантах. Полная валидация Draft 2020-12 в доступной среде не выполнена из-за недоступной реализации зависимости `jsonschema`.

## Файлы

| Файл | Назначение |
|---|---|
| `specification.schema.json` | Структура Draft 2020-12: обязательные поля, типы, перечисления, запрет неизвестных полей, локальные определения |
| `specification.example.json` | Иллюстративный task brief для сотрудника в поле: 12 точек поливной линии K01–K12, карта route-v3, закрытая K07, критерии и синтетическая приёмка отчёта |
| `validate_spec.py` | Сначала полная проверка через `jsonschema.Draft202012Validator`, затем проверки связей и условий приёмки |
| `schema-check.json` | Реальный результат прогона: 20 семантических тестов выполнены, 2 структурных пропущены; полная валидация недоступна |

**Наблюдение среды.** `importlib.util.find_spec('jsonschema')` обнаруживает namespace package, но импорт `Draft202012Validator` завершается `ImportError: cannot import name 'Draft202012Validator' from 'jsonschema' (unknown location)`. Начальное обнаружение имени пакета поэтому не считалось достаточным. Ничего не устанавливалось и не скачивалось для обхода ограничения.

## Структура и смысл полей

| Блок | Поля и назначение |
|---|---|
| Идентичность | `id` — стабильный ID; `schema_version` — версия формата, здесь `1.0`; `revision` — версия содержания, здесь `r1` |
| Классификация | `kind`: product / technical / task / service; `audience`: agent / developer / employee / contractor / client |
| Статус документа | `status`: draft / in_review / approved / superseded / retired |
| Ответственность | `owner`, `executor`, `acceptor` — ID назначенных ролей или лиц; назначение и полномочия проверяются внешней системой |
| Предмет | `goal`; `scope.included`, `scope.excluded` |
| Входы | `inputs`: ID, ссылка, зафиксированная revision, текстовое описание access |
| Требования | `requirements`: ID, текст, must/should, `source_ref` на ID входа, факт подтверждения `confirmed` |
| Критерии | `criteria`: ID, ссылки на требования, метод, процедура, ожидаемый результат, `evidence_required` |
| Декомпозиция | `tasks`: ID и ссылки на требования/критерии; задачи могут отсутствовать, если дальнейшая декомпозиция не нужна |
| Неизвестное | `open_questions`: ID, вопрос, блокирующий ли он, разрешён ли |
| Выполнение | `execution.status`: not_started / in_progress / submitted / changes_requested / accepted / rejected; ссылка и revision результата |
| Доказательства | `evidence`: ID, criterion_id, версии спецификации и результата, pass/fail/not_run, ссылка, checker |
| Приёмка | `acceptance`: pending / accept / return / reject, actor, reason, выбранные evidence IDs, версии, timestamp |
| Изменения | `change_log`: revision, причина, затронутые IDs |
| Полномочия | `authority`: разрешённые и запрещённые действия, условия остановки |

**Пустое состояние представлено явно.** Пока решение pending, actor, версии решения и decided_at могут быть null. До представления результата artifact_ref и artifact_revision могут быть null. Для принятого результата эти значения необходимы. Ревизии сравниваются на точное равенство строк; лексикографический или числовой порядок версий не предполагается.

**Полевой пример описывает отдельный результат.** Запись отчёта содержит point_id, observed_at со смещением, status, photo_ref, note и location_or_marker. Категории: problem / no_visible_problem / inaccessible; доступной точке необходимо фото и GPS либо маркер, недоступной — причина, фото не обязательно. Сам семантический валидатор проверяет граф связей и версии спецификации, а не эти данные отчёта, наличие фото или состояние поливной линии.

## Реализованные семантические правила

- ID спецификации и ID записей входов, требований, критериев, задач, вопросов и evidence уникальны в документе. Повторение ID одного человека в owner и acceptor допустимо.
- `source_ref` ссылается на вход. Критерии и задачи ссылаются на существующие требования; задачи — на существующие критерии; evidence — на критерии; приёмка — на evidence.
- Для каждого критерия задачи все `criterion.requirement_ids` входят в `task.requirement_ids`: задача явно знает все требования своей проверки. Ссылка на существующий критерий другого требования вызывает `TASK_CRITERION_MISMATCH`.
- Каждое must-требование связано хотя бы с одним критерием. Все критерии, связанные хотя бы с одним must, считаются обязательными для принятия.
- `approved` запрещает неподтверждённые must и неразрешённые blocking questions. Эти же условия проверяются при принятом результате независимо от статуса документа.
- Submitted, changes_requested, accepted и rejected требуют ссылки и версии представленного результата. Это проверка полей снимка, а не доказательство исторического перехода через submitted.
- `execution.status = accepted` и `acceptance.decision = accept` должны присутствовать вместе. Принятие не разрешено для draft/in_review. Исторически принятый результат может сохраняться у superseded/retired документа.
- Решение `return` требует текущего статуса выполнения `changes_requested`, а `reject` — `rejected`; нарушение вызывает `DECISION_STATE_MISMATCH`. Проверяется согласованность снимка, не история переходов.
- При принятии actor должен совпадать с acceptor. Версии приёмки должны совпадать с текущим снимком спецификации и результата.
- При принятии evidence и список выбранных evidence непусты; выбранные доказательства относятся к текущим версиям. Каждый обязательный критерий имеет выбранное текущее pass-доказательство.
- Текущее fail-доказательство обязательного критерия блокирует принятие, даже если его не включили в список приёмки. Для устранения конфликта предусмотрена новая версия результата; полноценная модель аннулирования ошибочного evidence в этом компактном формате отсутствует.
- У необязательного should допускаются отсутствие критерия, отсутствие подтверждения и failed evidence. Они не блокируют принятие, если не связаны также с must. Если should становится обязательным условием, его следует явно повысить до must.
- Ревизии журнала изменений уникальны, текущая revision имеет запись. `affected_ids` текущей записи разрешаются в текущем снимке; исторические IDs старых записей могут относиться к удалённым объектам и здесь не проверяются.

**`evidence_required` не отключает доказательство обязательного критерия.** Это метаданные требований к оформлению проверки. Правило данного профиля требует evidence для каждого must-критерия даже при false. Поле не следует использовать как скрытый обход приёмки.

## Что фактически проверено

**Проведено 20 семантических тестов, все с ожидаемым результатом: 5 положительных и 15 отрицательных.** Тестовый стенд напрямую вызывает семантическую функцию только на контролируемых авторских fixtures; он не подменяет полноценный schema validator для произвольного документа. В отчёте каждое такое испытание помечено `semantic_only_not_document_validation`, а `full_validation_complete` и `all_passed` остаются false.

| Случай | Ожидаемый семантический результат | Фактический результат |
|---|---|---|
| Принятый пример с неподтверждённым should без критерия | Допустить | Допущен |
| Draft с открытым blocking question | Допустить | Допущен |
| Принятый пример с отдельным failed should | Допустить | Допущен |
| Return со статусом changes_requested | Допустить | Допущен |
| Reject со статусом rejected | Допустить | Допущен |
| Ссылка критерия на отсутствующее требование | Отклонить | Отклонён |
| Существующий критерий с требованием вне requirement_ids задачи | Отклонить | Отклонён |
| Дублирующийся ID | Отклонить | Отклонён |
| Evidence старой версии спецификации | Отклонить | Отклонён |
| Evidence старой версии результата | Отклонить | Отклонён |
| Accepted без evidence | Отклонить | Отклонён |
| Открытый blocker в approved/accepted | Отклонить | Отклонён |
| Неподтверждённый must | Отклонить | Отклонён |
| Must без критерия | Отклонить | Отклонён |
| Actor отличается от acceptor | Отклонить | Отклонён |
| Accepted без представленного результата | Отклонить | Отклонён |
| Скрытое текущее fail для обязательного критерия | Отклонить | Отклонён |
| Accepted при статусе draft | Отклонить | Отклонён |
| Return со статусом submitted | Отклонить | Отклонён |
| Reject со статусом submitted | Отклонить | Отклонён |

**Две структурные проверки не выполнены:** некорректный date-time и неизвестное поле. JSON-файлы успешно разобраны стандартным JSON parser, но это не проверка их соответствия Draft 2020-12. После появления работоспособного `jsonschema` тот же стенд автоматически выполнит полную схему и семантику для всех 22 случаев.

## Запуск и ограничение зависимости

```powershell
python validate_spec.py specification.example.json
python validate_spec.py --self-test --output schema-check.json
```

**Требуемая зависимость:** Python-пакет `jsonschema` с `Draft202012Validator` и работающим `FormatChecker` для date-time. Скрипт не устанавливает пакет. При недоступности зависимости обычная проверка документа возвращает `valid: null`, `stage: dependency`, `full_schema_validation: false` и код завершения 2; принятие не разрешается. Режим self-test в этой ситуации выдаёт результаты отдельных семантических unit tests и также сигнализирует о незавершённой полной проверке.

**Формат даты проверяется синтаксически.** При наличии зависимости используется явно включённый FormatChecker; имеется контроль, что он отклоняет заведомо неверную дату. Правильный timestamp не доказывает момент события, подпись, полномочия или отсутствие последующего редактирования.

## Что не реализовано и не доказано

- Аутентификация, цифровая подпись, подлинность actor/checker, права доступа, разделение обязанностей. Сравнение двух строк не подтверждает личность и полномочия.
- Загрузка и проверка ссылок, доступность inputs исполнителю, содержимое артефактов, подлинность evidence. Синтетический пример намеренно проходит семантику с помеченными EXAMPLE-ссылками: валидатор не подтверждает реальную работу.
- Полнота бизнес-требований, достаточность критерия, смысловое соответствие источнику, противоречия свободного текста, измеримость формулировок. Здесь нужны предметное review и реальные проверки.
- Исполнение authority, автоматическое прекращение опасного действия, конфиденциальность и защита от prompt injection. Эти поля описывают правила; механизм принуждения остаётся вне формата.
- Полная машина переходов, неизменяемый журнал событий, подписи approved, аудит истории, обнаружение изменения текста без повышения revision, вычисление хеша версии и история исключений.
- Подтверждение реального поля: 12 точек K01–K12, карта route-v3, закрытая K07, timestamp, результаты pass и приёмка — явно обозначенная иллюстрация. Полевая работа не проводилась; приёмка отчёта не подтверждает исправность всех узлов.

**Граница применения:** артефакт пригоден как проверяемое предложение формы и демонстрация семантических правил. Для production-приёмки нужны полная schema validation, внешняя проверка полномочий и доказательств, управление версиями и проверка на реальных исполнителях.
