From 293df9c59dfb8788e2c7e044c8855146b3c5d03e Mon Sep 17 00:00:00 2001
From: Sergey Krylov <ksv741@mail.ru>
Date: Sun, 23 Aug 2026 21:21:31 +0300
Subject: [PATCH] docs: document local verification workflow

---
 AGENTS.md                                   |  1 +
 development/README.md                       |  1 +
 development/runtime-openapi-verification.md | 47 +++++++++++++++++++++
 3 files changed, 49 insertions(+)
 create mode 100644 development/runtime-openapi-verification.md

diff --git a/AGENTS.md b/AGENTS.md
index da52c62..60e8468 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,6 +8,7 @@
 
 ```bash
 git status --short
+bash ../specs/scripts/verify-runtime-openapi.sh
 ```
 
 ## Границы
diff --git a/development/README.md b/development/README.md
index 7270adf..668c644 100644
--- a/development/README.md
+++ b/development/README.md
@@ -4,3 +4,4 @@
 
 - [Audit remediation registry](audit-remediation.md) — текущий статус findings, следующий OpenSpec change и evidence завершённых улучшений.
 - [OpenSpec authority и lifecycle](openspec-authority-and-lifecycle.md) — единственный SDD store, границы постоянной документации и условия archive.
+- [Проверка runtime OpenAPI](runtime-openapi-verification.md) — отдельный read-only contract gate и его границы.
diff --git a/development/runtime-openapi-verification.md b/development/runtime-openapi-verification.md
new file mode 100644
index 0000000..8c2d7e8
--- /dev/null
+++ b/development/runtime-openapi-verification.md
@@ -0,0 +1,47 @@
+# Проверка runtime OpenAPI
+
+## Назначение
+
+`bash specs/scripts/verify-runtime-openapi.sh` сверяет полный OpenAPI document,
+который отдаёт локально запущенный backend по `/api/docs-json`, с committed
+snapshot `frontend/src/shared/api/spec/openapi.json`.
+
+Это отдельный контрактный gate, а не общий verifier всех репозиториев. Он нужен
+перед изменениями backend API или frontend transport contract и не заменяет
+локальные lint/typecheck команды приложений.
+
+## Запуск
+
+Из корня workspace:
+
+```bash
+node --version # должна быть Node 22
+bash specs/scripts/verify-runtime-openapi.sh
+```
+
+Перед первым запуском в обоих application repositories выполняют `npm ci` под
+Node 22. Команда определяет workspace из собственного пути, поэтому её можно
+запустить и по абсолютному пути из другой текущей директории.
+
+## Границы и результат
+
+Команда:
+
+- временно компилирует backend, создаёт временную SQLite DB и запускает backend
+  только на loopback-порту с детерминированными development values;
+- рекурсивно сортирует только ключи JSON objects, сохраняет порядок arrays,
+  выводит SHA-256 обоих полных documents и unified diff при различии;
+- всегда завершает дочерний backend и удаляет свои temporary resources.
+
+Она не вызывает `npm run openapi:sync`, не записывает committed snapshot или
+generated frontend types и не обращается к T-Bank либо другому внешнему
+сервису. Если контракт действительно изменён, snapshot обновляют только
+осознанной командой `npm run openapi:sync` в `frontend`, затем снова запускают
+эту проверку.
+
+## Ограничение e2e
+
+Проверка Swagger не запускает backend e2e tests. WL-P2-05 (runnable e2e) и
+WL-P2-13 (единый workspace verdict) отложены из-за нестабильного Prisma 7.9.1
+migration gate; дата, rationale и trigger пересмотра находятся в
+[audit remediation registry](audit-remediation.md).