docs(specs): archive local verification remediation

2026-08-23 21:21:22 +03:00
parent 51344d4988
commit 72444dbbb1
11 changed files with 441 additions and 4 deletions
@@ -0,0 +1,103 @@
+## Context
+
+Корень workspace — coordination directory, а не package-manager workspace и не
+Git-репозиторий. `frontend`, `backend`, `specs` и `docs` — независимые Git
+roots. `specs/scripts/verify-openspec-authority.sh` уже показывает правильное
+место для versioned cross-repository tooling: script определяет workspace
+относительно себя, а не доверяет текущей директории.
+
+Frontend закрепляет Node 22 и имеет offline `npm run verify`. Для backend нет
+эквивалентных runtime policy и отдельных quality gates: `lint` запускает ESLint
+с `--fix`, base tsconfig включает тесты, а build tsconfig исключает их.
+Существующие e2e tests создают in-memory Nest application, но их script сначала
+запускает Prisma на фиксированной `/tmp` DB и сейчас падает до Jest. Swagger
+доступен по `/api/docs-json` при `NODE_ENV=development`;
+`frontend/scripts/openapi:sync.mjs` — единственный намеренный writer committed
+snapshot и generated types.
+
+## Goals / Non-Goals
+
+**Цели:**
+
+- Восстановить исполнимые backend gates для lint и TypeScript приложения и
+  тестов с понятной диагностикой failures.
+- Доказать отдельной read-only командой, что полный runtime OpenAPI document
+  совпадает с committed frontend snapshot.
+- Сделать Node/npm bootstrap и конкретные verification commands discoverable
+  для агентов.
+- Сохранить pre-existing working-tree state пользователя; не создавать
+  versioned writes во время проверок.
+
+**Не входит в scope:**
+
+- CI/CD, remote verification, Docker, новый task runner, package-manager
+  workspace или общий workspace verifier.
+- Изоляция backend e2e DB, обновление Prisma packages и восстановление
+  migration gate: WL-P2-05 и зависимый WL-P2-13 отложены из-за нестабильности
+  Prisma 7.9.1 на Node 22.
+- JSON report format, cached results, plug-in architecture, arbitrary diff
+  bases, сохранённые hashes либо fixture/unit-test harness для process scripts.
+- Изменение OpenAPI sync writer, generated frontend types, пользовательских API
+  statuses, T-Bank integration, application features, перенос business glossary
+  `CONTEXT.md` или удаление существующего OpenSpec authority fixture test.
+
+## Decisions
+
+### Backend check и fix — разные операции
+
+Backend предоставляет `lint:check` без `--fix`, `lint:fix` с явным write intent
+и сохраняет `lint` как совместимый alias для `lint:check`. Он предоставляет
+отдельные команды `typecheck:app` и `typecheck:test` на основе выделенных
+tsconfig files. Эти команды не создают repository artifacts; build и e2e не
+объявляются частью нового общего verdict.
+
+### Runtime OpenAPI сверяется отдельной read-only командой
+
+`specs/scripts/verify-runtime-openapi.sh` определяет workspace из собственного
+пути, поднимает backend с детерминированным development environment, ждёт local
+readiness, получает `/api/docs-json` и всегда завершает child process. Команда
+рекурсивно упорядочивает JSON object keys, сохраняя array order, записывает
+canonical runtime и snapshot documents во временную директорию, сравнивает их
+SHA-256 и выводит unified diff при различии.
+
+Она никогда не вызывает `openapi:sync`, не записывает frontend snapshot и не
+обновляет generated types. Это узкий контрактный gate, а не orchestration
+interface для всех репозиториев.
+
+### Bootstrap и документация задают один contract
+
+Оба приложения требуют Node 22 и `npm ci`. Scoped `AGENTS.md` перечисляют
+только реально существующие non-mutating verification commands и явно отделяют
+писатели `lint:fix` и `openapi:sync`. Durable development documentation
+показывает prerequisites и границы отдельной runtime-contract команды.
+
+### Prisma findings явно отложены, а не маскируются обходом
+
+`prisma migrate deploy` 7.9.1 воспроизводимо возвращает пустой schema-engine
+error как на фиксированной, так и на уникальной временной SQLite DB; включение
+engine diagnostics меняет результат. На 2026-08-23 опубликованная latest
+stable version также 7.9.1. Не вводится второй migration mechanism и не
+обновляются зависимости без подтверждённого stable candidate. Реестр фиксирует
+дату, причину и trigger review: следующая stable Prisma должна трижды применить
+existing migrations к чистой DB на Node 22.
+
+## Risks / Trade-offs
+
+- [Runtime backend не стартует или child process остаётся после ошибки] →
+  command создаёт cleanup trap до запуска backend и сохраняет фактический exit
+  status.
+- [Canonicalization скрывает различие контрактов] → нормализуется только
+  порядок object keys; arrays и каждое JSON field остаются частью SHA-256 input.
+- [Prisma schema engine остаётся недоступным на supported runtime] → WL-P2-05
+  и WL-P2-13 остаются `deferred` до опубликованной stable версии, прошедшей
+  оговорённый reproduction gate.
+- [Ignored artifacts путаются с versioned writes] → отдельные команды не
+  считают `build` или e2e своим успехом и документируют свои временные ресурсы.
+
+## Migration Plan
+
+Не нужны migration production data или deployment sequence. Разработчики
+запускают `npm ci` под Node 22 в каждом application repository, используют
+`npm run lint:fix` только осознанно и запускают runtime OpenAPI check отдельно
+из workspace. Rollback — обычный revert independently versioned changes; он не
+меняет committed API artifacts или persistent user data.