chore: восстановление репозитория из снапшота v0.3.1

Прежняя git-история утрачена при переносе проекта на машину владельца
(снапшот без .git). Хэши коммитов в docs/reports/* относятся к утраченной
истории.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

prestart-litany.md

@@ -0,0 +1,759 @@
+# Литания перед стартом нового проекта
+
+> **Как применять:** положи этот файл в корень нового проекта и дай Claude Code вместе
+> с первой задачей: «Прочитай prestart-litany.md, определи профиль проекта, разверни
+> описанную систему триажем под этот проект, затем приступай к задаче: …».
+>
+> **Источники:** BAZA.CRM (ERP, 22 модуля, Django+React+Celery, боевой прод), EventPlan
+> (геометрический SaaS, FastAPI+React), АПЕКС-М (IoT: FastAPI+React+ESP32, боевой VPS) —
+> плюс аудит всех 17 проектов рабочей папки от 2026-07-26 (Ad-Tycoon, REC dimmer,
+> мониторинг, HS+auth, лендинги и др. — см. litany-audit-2026-07-26.md). Каждая грабля
+> в разделе VI оплачена реальным инцидентом — источник указан в скобках.
+>
+> **Устройство:** ядро сформулировано стек-нейтрально; конкретика стека — в примерах
+> *курсивом* и тегах `[Docker]` `[React]` `[Windows]` `[железо]`… Неприменимое к твоему
+> профилю и стеку отсекается триажем (раздел 0), а не игнорируется молча.
+>
+> **Ссылки на литанию — только слагом** (`` `gotcha-…` `` у граблей, названием пункта у
+> правил), никогда номером: перенумерация родительского документа тихо ломает все
+> производные правила *(EventPlan: ссылки «V.15», «VI.10» из rules/ и ADR-0004 били в
+> пустоту уже через 2 часа после финальной правки литании)*.
+
+---
+
+## 0. Развёртывание (порядок строгий)
+
+### 0.1. Профиль проекта — первый вопрос, до триажа
+
+| Профиль | Признаки | Примеры |
+|---|---|---|
+| **D — документ** | Артефакт = один документ, кода нет | инструкция, руководство |
+| **S — статика** | Один экран/лендинг, нет БД и пользователей; правит не-программист | лендинг, брендбук |
+| **A — одиночный артефакт** | Скетч, скрипт, утилита; один файл-проект | генератор, трей-клиент |
+| **M — продукт без своего прода** | Код, тесты, релизы — но нет своего сервера/БД/денег | игра, расширение, десктоп |
+| **XL — полное ядро** | Прод, БД, деньги, пользователи, контейнеры, железо в поле | ERP, SaaS, IoT-платформа |
+
+Без профилей мелкие проекты выпадают из процесса целиком, а не частично: 6 из 17
+проектов папки жили вообще без git, один версионировался зипами `(4)…(8).zip`.
+
+### 0.2. Минимальное ядро — действует ВСЕГДА, даже для D и S
+
+1. **git с первого файла** + `.gitattributes` (`* text=auto eol=lf`) и `.gitignore` —
+   ДО первого `git add`. Никаких копий-папок и зипов как версий.
+2. **Секрет-гигиена** — включая документацию, примеры команд и **рабочий каталог**:
+   секреты вне git всё равно попадают в бэкапы диска, скриншоты и контекст агента,
+   получившего доступ к папке *(recovery-коды открытым текстом в корне папки проектов)*.
+3. **Опасные действия письменно**; на боевом — только команды, выполняет человек.
+4. **Бэкап перед перезаписью боевого файла** (ротация N копий).
+5. **Версия и дата на артефакте**: подвал сайта, штамп «версии на момент составления»
+   в доке, `v1.0 · дата` в README.
+6. **Плейсхолдеры помечены** (`?`, TODO владельцу) и сверяются перед выкладкой.
+7. **Мини-ритуал закрытия**: обновить дату, строка «что сделали», всё отложенное —
+   письменно в момент откладывания.
+8. **Развилки — через AskUserQuestion**, очевидные дефолты — принять и озвучить.
+9. **Один ADR** даже в S — на 5 строк, но с обязательным «Компромиссом».
+
+### 0.3. Профильные добавки (сверх ядра)
+
+- **D:** SoT — исходник (HTML/markdown), PDF — производный артефакт, пересобирается
+  вместе с ним; раздел «версии ПО на момент составления»; нумерация до третьего уровня
+  (чтобы ссылаться на шаг в переписке); визуальные классы опасности (danger/warn/ok)
+  вместо прозы; владелец и дата пересмотра.
+- **S:** контент отделён от кода **одним файлом** («правишь это, остальное не трогай»);
+  индексация закрыта по умолчанию (`Disallow: /` + noindex), открытие — сознательный
+  акт по чеклисту (robots, аналитика, schema.org, PageSpeed, Вебмастер/Search Console,
+  privacy-policy не заглушка); deny-list «что не выкладывать на прод» (локальный
+  редактор, дизайн-канвас); бюджет веса страницы и картинок; документ передачи
+  не-разработчику (варианты правки по возрастанию сложности, лимиты хостинга).
+- **A:** один README-витрина: что это · пины/константы **одной таблицей** · как
+  собрать · troubleshooting «симптом → причина»; все физические/средовые константы
+  в одном месте файла; способ проверить **без** железа/боевого стека + одна строка
+  «чего он не проверяет».
+- **M:** + чистое ядро и детерминизм (II), версионирование локального состояния (I),
+  адаптер платформы (I), CI-матрица ОС (II), профиль публичного релиза (V), роли (IV).
+- **XL:** литания целиком.
+
+### 0.4. Триаж
+
+Для D/S/A — «профиль + список отклонений» ≤10 строк в README. Для M/XL — полный,
+каждый пункт → **IN / DEFERRED / OUT** с причиной, итог — одним ADR. Формат вердиктов
+(проверен дважды: EventPlan ADR-0004, АПЕКС ADR-024):
+
+| Пункт | Вердикт | Причина / условие |
+|---|---|---|
+| … | IN / DEFERRED / OUT | … |
+
++ обязательный раздел «Компромиссы — что осознанно потеряли». DEFERRED — только
+с условием активации («появятся формы → схемная валидация»), не «потом». Осознанный
+legacy-путь получает зеркальное — **условие снятия** («удалить, когда ни одного
+устройства с plaintext-токеном»), иначе он вечен. Мёртвое правило убивает доверие
+ко всем правилам.
+
+### 0.5. Стартовый бриф и вопросы
+
+**Вопросы одним заходом** (AskUserQuestion): стек и версии тулчейна, число артефактов
+версии, есть ли фронтенд / воркеры / прод / железо, ОС разработчика. Бриф проекта
+пишется по шаблону, проверенному дважды *(HS+auth PROJECT_BRIEF, REC dimmer bootstrap)*:
+принципы-обязательства → **«Чего НЕ делать»** (явные запреты) → этапы с подтверждением
+человека → «что нужно на выходе» → финал **«ничего не пиши в файлы, пока не согласуем;
+вопросы без ответа в документах — задай списком, не делай допущений»**. Полезный
+парный документ — памятка человеку «как ставить задачу»: шаблон [ЗОНА][ДЕЙСТВИЕ],
+формат баг-репорта, «чего НЕ указывать — уже в CLAUDE.md» *(АПЕКС how_to_ask.md)*.
+
+### 0.6. Каркас и финал развёртывания
+
+Развернуть каркас из разделов I–V по итогам триажа. Финал: показать пользователю
+Module Map и список созданных правил на ревью → отдельный коммит каркаса → только
+затем первая боевая задача.
+
+### 0.7. Обратный поток граблей
+
+Копия литании в проекте — read-only архив, её не редактируют. Новые грабли проекта
+пишутся в живой раздел `docs/architecture.md#Грабли проекта` с источником; раз в
+несколько сессий обобщаемое мигрирует в мастер-литанию *(Самолётики: финал «дописывай
+в VI» оказался невыполним — копия заморожена, дописывать было некуда)*.
+
+Раздел VI — постоянный чеклист на всю жизнь проекта, не одноразовое чтение.
+
+Всё общение и документация — на русском. Идентификаторы кода, пути API, хэши и версии
+не переводить — по ним ищут в коде; жаргон — с оригиналом в скобках при первом
+упоминании *(BAZA d64605c)*.
+
+## I. Архитектура — принципы, проверенные боем
+
+1. **Модульность:** один модуль/приложение = одна бизнес-область. Cross-module общение —
+   только события или явные сервис-вызовы через абстракции; прямой импорт внутренностей
+   чужого домена запрещён. Каждый новый модуль в момент создания попадает в Module Map (III.1).
+2. **Сервисный слой:** контроллер/view/handler = parse → call service → respond, ноль
+   логики. Модель = структура данных. Вся бизнес-логика в сервисах; при росте делить на
+   подмодули СРАЗУ (реэкспорт сохраняет внешний контракт), не ждать god-файла.
+3. **Статусы = конечный автомат:** защищённое поле + именованные переходы с
+   source/target/permission + side-effects внутри перехода. Прямое присваивание статуса
+   запрещено — это обход прав, аудита и эффектов.
+4. **Аудит-след обязателен:** каждая транзакция создаёт запись в журнале через **единую
+   точку применения эффекта**. Мутация в обход журнала — критическая ошибка. Контракт
+   логирования — таблицей «событие → что логировать» с именованным логгером, иначе
+   «аудит обязателен» выполняется на глаз *(BAZA CLAUDE.md)*.
+5. **Soft delete** для доменов с документами/деньгами, двухуровневый: документы/деньги =
+   `is_active + deleted_at`; справочники = только `is_active`. Физический delete запрещён;
+   связи на audit-модели — PROTECT.
+6. **Деньги = Decimal** (12,2) или целые минорные единицы. Float рядом с money-полями —
+   блокирующая ошибка. Общий принцип: **число без объявленной единицы — баг, ждущий
+   повода**; единицы измерения и система координат — часть контракта, объявляются
+   письменно один раз *(EventPlan: «единицы — миллиметры», СК от самой длинной стены)*.
+   Есть стандартный формат обмена для домена (GeoJSON, iCal, ISO-коды) — брать его,
+   не изобретать: бесплатные валидаторы и общий язык со всеми слоями.
+7. **Миграции схемы append-only:** существующие не редактировать; каждая data-миграция
+   обратима; большие таблицы — expand → backfill → contract. Механика раннера (glob vs
+   реестр, порядок применения, идемпотентность) — в README рядом с миграциями, иначе
+   каждая сессия изобретает своё *(АПЕКС)*. У грабли «дрейф миграций» записан не только
+   запрет, но и рецепт восстановления *(BAZA: 5 шагов через MigrationLoader)*.
+8. **Внешние вызовы:** только асинхронно (очередь), идемпотентные ключи, retry с backoff,
+   верификация вебхуков, audit-лог каждого вызова. Внешняя платформа/SDK (маркетплейс,
+   магазин, игровая площадка, платёжка) — за адаптером с **двумя реализациями: боевой и
+   Local-заглушкой**; вход в приложение — в try/catch с фолбэком; требования модерации —
+   чеклистом ДО релиза *(Ad-Tycoon: PlatformAdapter, «вечный чёрный экран» без фолбэка)*.
+   Недоступные из твоей инфраструктуры внешние сервисы — письменно списком, иначе агент
+   раз за разом предлагает нерабочее *(АПЕКС: Telegram на RU-VPS, protomaps)*.
+9. **Парные операции симметричны с рождения:** если есть create-эффект — в том же
+   коммите пишется cancel-эффект и ТЕСТ на пару (`gotcha-pair-asymmetry`).
+10. **Без хардкода — в меру.** Значение, которое может измениться, повториться или
+    зависеть от окружения/клиента — в константу/конфиг/env/данные. Самоочевидные
+    единичные значения не выносить. **Доменные параметры** — редактируемые данные
+    (сид + переопределение на сущность), не константы; вычислительное ядро принимает их
+    параметром и остаётся чистым *(EventPlan ADR-0003)*. То же — **матрица прав и
+    фиче-флаги**: данные в БД, редактируемые без релиза *(BAZA)*. Параметры, зависящие
+    от экземпляра (калибровки, коэффициенты per-device/per-tenant) — хранятся при
+    экземпляре, не в коде `[железо]` *(АПЕКС: NVS, калибровка минимум в 3 точках)*.
+    Настроечная константа (таймаут, батч, буфер) — с единицей, формулой следствия и
+    направлением компромисса, иначе следующая сессия крутит её вслепую *(VOX: DMA-буферы
+    «4 мс; меньше → щелчки; больше → латентность»)*.
+11. **Contract First для многослойных контрактов.** Контракт, потребляемый несколькими
+    артефактами — таблица слоёв в CLAUDE.md, изменение обновляет ВСЕ слои одним
+    коммитом. Wire-протокол версионируется отдельно от приложений — два разных SoT,
+    с письменной матрицей «что бампает протокол» (optional-поле → minor, required/
+    переименование → major, багфикс payload не бампает) *(АПЕКС versioning.md)*.
+    **Порядок выката — часть контракта:** сервер раньше клиента, новые поля optional
+    (expand→contract для провода). Совместимость — **декларация клиента**
+    (`api_version_min` в манифесте, клиент сам блокируется), а не блокировка сервером:
+    отклонение данных по версии создаёт слепые зоны ровно у проблемных клиентов
+    *(АПЕКС ADR-016)*. Агент, меняющий контракт, обязан спросить: «нужно ли обновить
+    остальные слои?» Удалил поле из контракта — докажи grep'ом, что его никто не
+    читает *(АПЕКС: orphan-читатели top-level `version`)*.
+12. **Docker-first** (если проект контейнерный): ничего не запускается на хосте; базовый
+    compose + явные именованные override-файлы; healthchecks на всех сервисах; non-root;
+    секреты только env. Осознанное отклонение — строка в реестре долгов «принято
+    осознанно» + **явный запрет альтернативной команды** («никогда `docker compose build
+    frontend`») — запрет важнее правила: именно его агент нарушит по инерции *(АПЕКС)*.
+13. **Fail-safe: неопределённое состояние = безопасное.** Заглушки нереализованных
+    модулей отказывают в безопасную сторону (недописанный чек прав — запрещает,
+    недописанный лимит — блокирует, фича-флаг по умолчанию выключен); где отказ
+    физически опасен — второй барьер вне кода `[железо]` *(REC dimmer: аппаратная
+    подтяжка — ресет/прошивка/Hi-Z = ключи закрыты без участия кода)*. **Деградация
+    вместо отключения**, и «плохие данные» ≠ «нет данных»: политики разные, обе
+    спроектированы явно; **нет данных — не гадать** *(REC dimmer: отказ датчика →
+    вентилятор на максимум, лимиты НЕ применяются)*. Отсутствие показателя ≠ ноль:
+    прочерк, а не 0 *(tray-monitor; мониторинг: `absent()` — отдельный алерт)*.
+    Fail-open/fail-closed выбирается **на каждую точку отдельно, по длительности окна
+    риска** *(АПЕКС ADR-017: HTTP fail-open — окно один запрос; WS fail-closed — канал
+    жил бы часами)*; код ошибки, который UI трактует как команду, не получает второго,
+    инфраструктурного смысла. Отказ канала связи ≠ отказ узла — различие моделируется
+    в протоколе, эскалация зависит от того, что известно *(АПЕКС ADR-011)*.
+14. **Персистентное состояние вне транзакционной БД** (сейв, localStorage, NVS, файл
+    конфига, кэш) — та же дисциплина, что схема БД: `version` + контрольная сумма +
+    **атомарная запись** (temp + rename; два слота пинг-понгом на flash) + миграция при
+    загрузке + roundtrip-тест; битое состояние не роняет приложение — старт с чистого /
+    дефолтов с указанием места поломки *(REC dimmer EEPROM-блоб; мониторинг mktemp+mv;
+    tray-monitor; Ad-Tycoon: `// TODO: restore staff` — купленное исчезало)*.
+15. **Права — на уровне выборки, не UI:** выдача фильтруется по пользователю в самом
+    запросе (IDOR), permission-классы объявлены явно на каждом эндпоинте *(BAZA)*.
+    Пагинация на всех list-эндпоинтах, явный ordering (недетерминированный порядок
+    ломает пагинацию), запрет N+1.
+16. **Retention фиксируется раньше механизма:** для каждой таблицы, растущей от
+    активности (телеметрия, логи, события, аудит) — «сколько храним» решено письменно,
+    компенсирующий контроль (индекс, мониторинг объёма) — сразу *(АПЕКС ADR-019)*.
+    Класс данных, запрещённый к отправке во внешние сервисы **включая облачные AI**, —
+    объявлен письменно ДО первой интеграции *(АПЕКС: 152-ФЗ → только локальная модель)*.
+17. **Один назначенный писатель** — там, где блокировать нельзя (ISR, UI-поток, горячий
+    путь): ресурс пишет ровно один владелец, обмен через двойной буфер/очередь; это
+    парный паттерн к «блокировка на счётчиках» (`gotcha-increment-race`) *(REC dimmer:
+    CCR пишет только ISR TIM6)*. Эксклюзивный ресурс (COM-порт, файл-лок, сокет)
+    освобождается явно до передачи следующему; поток без фреймов — дренаж запоздалых
+    ответов и фильтрация незапрошенного `[железо]` *(АПЕКС release process)*.
+18. **Не создавай второй канал доставки для того, без чего не работает первый:** конфиг,
+    ключ, сертификат, схема — если их доставка идёт другим путём, чем код, отказ
+    доставки убивает возможность починки *(АПЕКС ADR-022: CA вшиты в прошивку — битая
+    отдельная партиция значила бы мёртвый TLS = мёртвый OTA = физическая перепрошивка)*.
+19. **Файлы:** бинарники не в БД — хранится путь; превью асинхронно; статику/медиа
+    отдаёт прокси мимо приложения, приватное — через X-Accel-Redirect/аналог *(BAZA)*.
+    Каждый подписчик события — с уникальным идентификатором подписки (dispatch_uid):
+    двойное подключение = двойные эффекты, почти не диагностируется *(BAZA)*.
+20. **Автономный/демо/offline-режим — как обычный источник данных, а не ветка `if` во
+    всём тракте:** подделывается вход, не тракт *(REC dimmer: STATIC-кадр — обычный
+    валидный сигнал для FSM, пайплайн без спецслучаев)*.
+
+## II. Код и гейты
+
+1. **Гейты с ПЕРВОГО коммита:** форматтер + импорт-сорт + линтер + типы в pre-commit и
+   CI. Для нового кода — 0 warnings сразу; для унаследованного долга — **рэтчет**
+   warn→error с зафиксированным потолком и планом, не разовая зачистка *(BAZA ADR-051)*.
+   Гейты двух уровней: **hard блокирует, soft предупреждает** *(АПЕКС)*. Поведение при
+   провале — письменно: остановиться, показать упавший гейт + полный stderr, не чинить
+   молча; обход по команде — `NOTE: committed with failing <gate>` в тело коммита.
+   Обоснованный пропуск гейта — с условием возврата («тесты — план 0.8.0»), иначе
+   «нулевая терпимость» обходится тихо. Неиспользуемая disable-директива = ошибка.
+   Ложное срабатывание любого сканера гасится **самым узким скоупом** (allow по пути),
+   не глобальным игнором класса правила *(BAZA trivy)*. Локальный гейт и CI — один
+   инструмент одной версии. Форматтеры не трогают append-only артефакты (глобальный
+   exclude на миграции — правило нарушает автоформат, а не человек) *(BAZA 2026-07-21)*.
+   *Инструменты по стеку: Python — black/isort/ruff/mypy; TS — eslint + `tsc -b --noEmit`.*
+2. **Правило, проверяемое машиной — хук, а не абзац.** Каждый инвариант литании,
+   выразимый регуляркой/AST, дублируется PreToolUse-хуком в момент формулировки —
+   иначе живёт до первой спешки *(BAZA: 12 блокирующих — float у денег, физический
+   delete, правка миграции, секреты, DEBUG в prod…)*. Блокирующие и напоминающие хуки —
+   два разных класса; Stop-хук — для напоминаний о ритуалах. Обязательные спутники
+   хука: список исключений (migrations/, node_modules/, собственные литералы паттернов),
+   тесты на сам хук, быстрый путь выхода (оверхед на каждый tool call). Покрытие
+   хука проверяется по **всем шеллам**, которыми реально пользуется агент
+   (`gotcha-hook-shell-blind`).
+3. **Каждый слой каркаса проверяй сразу, не в конце:** после каждого слоя — прогон
+   гейтов. Ошибки ловятся дёшево у источника *(EventPlan)*.
+4. **Тулчейн и системные зависимости проверяй фактически ДО написания конфигов:**
+   запусти и убедись, не предполагай. Версии пинуй; что тянет либа — в ADR/Dockerfile
+   в момент выбора *(EventPlan: corepack pnpm; Shapely→GEOS, weasyprint→pango)*.
+5. **Типы обязательны** на всех функциях. **Функции ≤40 строк** без явного обоснования.
+6. **Тесты зеркалят структуру**, фабрики, AAA. Тест = полная жизненная цепочка, не
+   изолированный вызов. Каждый багфикс приносит тест. Интеграционные — на реальной БД,
+   мок только для внешних сервисов. Фича, меняющая контракт, обновляет свои тесты в том
+   же коммите (`gotcha-feature-test-debt`). Для вычислительного ядра цепочка — не то:
+   там **инварианты алгоритма в docstring** как контракт + property-based тесты, автор
+   инварианта и автор теста — разные агенты *(EventPlan: hypothesis)*. Цифра покрытия —
+   только с конфигурацией замера («69% с greenlet, без него фиктивные 56%»); расхождение
+   тестовой и прод-СУБД — задокументированное ограничение, не умолчание *(АПЕКС)*.
+7. **Тесты wiring — отдельный класс от тестов логики.** Юнит-тест, импортирующий объект
+   напрямую, не проверяет, что система его находит: любая регистрация «по конвенции»
+   (задачи, сигналы, плагины, роуты) требует теста «всё, на что ссылается конфиг,
+   реально зарегистрировано» (`gotcha-silent-unregistered`). **Orphan-check:** публичная
+   функция ядра без единого вызывающего — баг интеграции или мёртвый код
+   (`gotcha-green-modules-dead-system`). Конфиг-поле без потребителя — ложь в диффе;
+   конфиг валидируется при старте (fail fast), единицы измерения совпадают с кодом
+   *(Ad-Tycoon: в конфиге 2, в коде хардкод 0.02 — расхождение в 100 раз)*.
+8. **Тест без боевой среды — спроектирован, не случаен.** Ядро не импортирует ни строчки
+   среды исполнения И ни строчки вендорского SDK — это две разные оси изоляции, обе
+   проверяются **сборкой** (второй target «на хосте»), а не дисциплиной *(REC dimmer:
+   core/ не видит hal/; АПЕКС ADR-021: изоляция окупается тестируемостью даже без
+   миграции; VOX: dsp.h собирается на ПК)*. Внутри ядра запрещены Date.now() /
+   Math.random(): часы и seeded RNG инжектируются — детерминизм = воспроизводимые
+   тесты *(Ad-Tycoon)*. Матрица средств тестирования — с честным «чего НЕ покрывает
+   ни один» *(VOX: Wokwi vs WAV-стенд)*. Мок-режим — полноценный режим приложения со
+   сценарием по расписанию, включая негативные состояния *(tray-monitor: три сервера
+   со сдвинутыми фазами, один намеренно без датчика)*. Симулятор внешней системы —
+   первоклассный артефакт со своими правилами: те же схемы, что у прод-кода (не
+   копипаст полей), seed, префикс SIM_/флаг is_simulated, assert «не прод» *(АПЕКС)*.
+   Для доменов с накопительной динамикой — headless-прогон N шагов ботом с проверкой,
+   что метрики двигаются *(Ad-Tycoon: «7 дней, seed 42» показал экономический тупик)*.
+   Смоук-сценарий на то, что уже ломалось — для слоёв, не берущихся юнит-тестами
+   (GUI, трей, жизненный цикл процесса) *(tray-monitor)*.
+9. **Фоновые задачи** (если есть очередь): никакой бизнес-логики в таске — таска
+   вызывает сервис; queue, time_limit, retry с backoff, идемпотентность; передавать id,
+   не объекты.
+10. **Фронтенд** (если есть): strict-типизация без `any`; единый api-клиент (auth +
+    refresh + interceptor в одном месте); server state отдельно от клиентского *(у нас
+    react-query + zustand)*; формы со схемной валидацией *(RHF + zod)*; дизайн-система
+    классов вместо inline-стилей; error boundary на каждый маршрут **с key**; скачивание
+    защищённых файлов — только через api-клиент (blob); единый паттерн деталей сущностей.
+    **Строки UI — в один ресурс с первого дня**, даже в одноязычном проекте: ретрофит
+    i18n дороже в разы, а правки текстов не должны требовать правки кода *(Ad-Tycoon:
+    файл есть, UI захардкожен — местами показывались ключи)*. **Бюджеты числами**
+    (размер сборки, TTI, запросы) — проверяются при добавлении тяжёлого, не «когда
+    станет медленно».
+11. **CI — это не только гейты:** CI слушает **рабочую** ветку — сменил ветвенную
+    модель → в тот же коммит триггеры CI/хуков (`gotcha-ci-wrong-branch`); для
+    кроссплатформенного артефакта — матрица `ubuntu + windows` (автоматически ловит всю
+    группу Windows-граблей); CI **собирает** релизный артефакт (ловит зависимость от
+    файла вне git); гейт «чистый клон собирается и стартует»; supply-chain в базовом
+    наборе (audit зависимостей, скан образа, встроенный `check --deploy` фреймворка —
+    бесплатный гейт, который никто не включает); coverage-порог *(BAZA)*. Свой
+    CI-раннер не селить рядом с боевыми сервисами — 1600 тестов = OOM соседям *(BAZA)*.
+    Прод-образ намеренно без dev-тулинга; ожидаемое «падение pytest на проде» —
+    задокументированная фича, не поломка *(BAZA)*.
+12. **Лицензионный гейт:** политика лицензий стороннего кода письменно (для закрытого
+    продукта — только пермиссивные); новый компонент — сначала строка в
+    THIRD_PARTY_LICENSES.md, потом в сборку *(REC dimmer)*.
+
+## III. Бумажная работа (карта + документация + версии)
+
+Развернуть с первого дня — «потом» не наступает (`gotcha-docs-drift`).
+
+1. **Карта навигации:** Module Map в CLAUDE.md (строка на модуль: путь — назначение —
+   ключевые сущности) + navigation-док (дерево каталогов; таблица сущностей —
+   генерируется grep'ом, не по памяти; «задача → где искать»). Список крупных файлов —
+   не как список, а как **порог (параметр) + команда генерации + дата сверки +
+   автопроверка в обе стороны** («перерос, но не в списке» и «в списке, но похудел»)
+   *(АПЕКС check-integrity)*. Правило контекст-экономии первым пунктом workflow;
+   большие файлы — поиск → чтение диапазона; правило передавать субагентам.
+2. **Документация — один индекс и один гейт.** Два независимых дерева = двойная цена
+   синхронизации *(BAZA проходила)*. Артефакт, потребляемый кодом (changelog в UI,
+   схема в сборке), законно живёт в коде — но обязан быть в таблице маршрутизации
+   ритуала закрытия. Формат — под проект и потребителя, выбор зафиксировать.
+   **Документация проходит гейт как код**: strict-сборка доков (битые ссылки, файлы
+   вне nav) — дерево без гейта гниёт по ссылкам быстрее, чем по содержанию *(АПЕКС:
+   mkdocs --strict)*. Состав дерева: index, architecture, api-reference, decisions
+   (ADR), versioning, onboarding, runbook (+production-runbook при проде), по-модульные
+   доки; штамп «Обновлено: дата | версия». **Runbook — в формате «Симптом →
+   Диагностика → Фикс»**, не описание системы *(×4 проекта независимо)*. Второй
+   потребитель — человек вне разработки (сборщик, заказчик): его версия **генерируется**
+   из основной, не пишется дважды *(VOX: md→html конвертер «открыть двойным щелчком»)*.
+   README = витрина: версия + badge, таблица модулей (число = факт!), старт.
+3. **ADR:** нетривиальное решение (≥2 реальных альтернатив) → Контекст / Альтернативы /
+   Решение / Причины / **Компромисс** (обязателен). Существующие ADR не редактируются.
+   «Почему не X» — рядом с решением, особенно где ошибка необратима *(Pulse generator:
+   таблица отвергнутых MOSFET с причинами)*. Ключ связывания систем — решение с
+   **организационным следствием**, и оно пишется в Компромисс *(HS+auth: маппинг по
+   email ⇒ «почты сотрудников нельзя переиспользовать» — правило для отдела кадров)*.
+4. **Ритуал закрытия сессии** (скилл с триггер-фразой): «закрываем сессию» → дифф
+   сессии (`git log` + `git status`) → свести затронутые зоны (модуль → дока + карта;
+   процесс → правило; решение → ADR; бамп → changelog; закрытый долг → реестр) →
+   отдельный `docs(sync)`-коммит. **Если сводить нечего — сказать это явно, не молчать**
+   (иначе ритуал незаметно отмирает) *(АПЕКС)*. Канонические имена/URL при сведении
+   сверяются grep'ом с кодом — SoT имени всегда код *(BAZA: `/healthz` числился
+   `/api/health/` в пяти доках)*. После docs-сессии — короткий список реально
+   исполняемых изменений *(АПЕКС post-rules-refactor)*. Штамп ≠ гарантия актуальности.
+5. **Статусы в планах — по факту кода, в обе стороны.** Фантомные хвосты: пункт числится
+   открытым, а код давно есть — перед реализацией «незакрытого» сверка с кодом *(BAZA:
+   2 из 4 хвостов)*. Сводки и индексы правятся **атомарно** с деталью. **Реестр
+   «Критические долги» — в НАЧАЛЕ roadmap** (не в подвале): приоритет, слой, условие
+   закрытия; закрытие — двухфазно: коммит-фикс, затем коммит-пометка с точным SHA
+   первого (смешивать нельзя — SHA фикса ещё не существует в момент правки таблицы)
+   *(АПЕКС)*. Чек-лист `[x]` — только если формулировка однозначно совпадает с диффом;
+   буллеты закрытых релизов — неизменяемая история. **План фазы — в репозитории, не в
+   памяти агента**, с блоком «Ключевые решения (не пере-решать)» со ссылками на ADR —
+   прививка от пере-обсуждения решённого *(АПЕКС 0.7.0-execution-plan)*. Опционально —
+   HTML-дашборд прогресса с блоком DATA, собираемым из git, обновляется в ритуале
+   закрытия *(Dashboard/BAZA)*.
+6. **Версии:** SemVer; письменно объявленный SoT-файл на каждый артефакт; версия
+   **наблюдаема на самом артефакте** (health-эндпоинт, UI «Что нового», экран About
+   устройства). MAJOR.MINOR синхронны только для платформенной пары; прошивки/утилиты/
+   протокол — независимы; при >2 артефактах — **матрица совместимости в changelog
+   минорного релиза** *(АПЕКС)*. Канал релиза (dev/beta/rc) — pre-release suffix SemVer,
+   не отдельная колонка: парсер сам сравнит `0.1.0-debug.1 < 0.1.0-rc.1 < 0.1.0`;
+   префикс артефакта — только в UI/тегах, не в коде *(АПЕКС)*. Changelog — только
+   заметное пользователю, не коммит-лог; запись в changelog обязательна — без неё бамп
+   запрещён. Бамп ТОЛЬКО по явной команде; ритуал «готовимся к бампу»: git log с
+   прошлого бампа → атомарные сценарии ручной проверки, **сгенерированные по диффу, не
+   по памяти** (файл чеклиста в .gitignore) → прогон по одному через AskUserQuestion
+   (на ✗ — стоп) → полный тест-прогон → два зелёных дают право бампать. Сокращённый
+   гейт для PATCH рассматривался и письменно отвергнут — «рождаются вторые патчи в тот
+   же день» *(BAZA ADR-068)*. Тег ставится локально; **push тега — отдельное «да»,
+   каждый раз** *(АПЕКС)*.
+
+## IV. Организация работы с Claude
+
+1. **Модель ветвления объявляется письменно в ADR** — trunk-based или dev/master, по
+   числу людей и наличию ревью, а не по привычке *(АПЕКС живёт trunk-based, ADR-024;
+   BAZA — dev/master)*. Для dev/master: master = стабильный прод, merge только бампом;
+   режим стабилизации — dev держится потоком фиксов, фичи во временных `feature/*`,
+   постоянную третью ветку не заводить *(BAZA ADR-068)*.
+2. **Делегирование:** нетривиальное — субагентам с явным именованием; main loop
+   оставляет себе git, гейты, ревью диффов, интеграцию. **Нижняя граница:** правку 1–3
+   строк не делегировать — оверхед дороже. **Нет подходящего агента — остановиться и
+   спросить, не выдумывать.** Определения агентов модель-нейтральны: модель и effort —
+   во frontmatter, в прозе имён моделей нет (протухают за недели) *(АПЕКС ea13116;
+   контрпример — «Opus 4.8» в CLAUDE.md EventPlan)*. Дорогой агент-архитектор
+   вызывается по письменному списку **обязательных** триггеров — и только по ним.
+   Субагенты не порождают субагентов: лиды возвращают план делегирования текстом,
+   исполнителей запускает main loop. Три проверенных архетипа — субагент как **бюджет
+   контекста**: reviewer-хранитель пронумерованных инвариантов («не переписывай сам»;
+   «чем грозит»), test-runner на дешёвой модели («только вердикт и текст упавших»),
+   doc-scout («файл:строка + цитата, не пересказывай») *(REC dimmer)*. Шкала
+   оркестрации по размеру: роли в одном файле → именованные субагенты → генерируемая
+   студия. Независимых — параллельно, одним сообщением. Субагентам передавать правило
+   контекст-экономии и запрет на commit/push.
+3. **Опасные команды** — список письменно в CLAUDE.md с первого дня: rm -rf,
+   reset --hard, down -v, DROP, force-push, `git clean -f`, `git checkout --` с потерей
+   правок, `docker system prune`, `volume rm`, `dd`, `mkfs`, `pkill -9`, erase-flash,
+   любые действия на прод. Выполнение — только после письменного подтверждения, одно
+   «да» = один вызов. **Текст без хука — декларация:** список дублируется блокирующим
+   хуком, покрытие хука — по всем шеллам (II.2). Письменно же — известные
+   escape-вектора ask-gate: `cd x && git push`, `sh -c`, `eval`, pipe через `xargs` —
+   договорённость не использовать, распространена на субагентов *(BAZA)*. Опасны они
+   не только потерей данных, но и потерей **улик**: сначала понять причину, потом
+   чистить *(АПЕКС runbook)*.
+4. **Не переспрашивай и не угадывай:** решение с очевидным дефолтом — прими, озвучь,
+   двигайся. Развилку, меняющую архитектуру/данные/UX — AskUserQuestion **до** кода.
+   Несколько вопросов — одним заходом.
+5. **TodoWrite** на всё многошаговое; планы — в `docs/plans/`, не в корне. Двухфазность:
+   фикс отдельным коммитом, roadmap/доки — отдельным (причину см. III.5).
+6. **Бюджет CLAUDE.md:** там только то, что нужно КАЖДУЮ сессию — постоянная статья
+   расхода контекста. Ритуалы — **скиллы** с триггер-фразами; правила — файлы с `globs`
+   по зонам кода (грузятся по файлу) *(оба боевых проекта пришли независимо: АПЕКС
+   279→149 строк, BAZA rules→skills)*. `.claudeignore` на шумные каталоги — с обратным
+   правилом: ничто, на что ссылаются правила или память, не скрыто (указатели в
+   невидимое) *(АПЕКС)*. Гигиена памяти: индекс обязателен (нет в MEMORY.md = невидимо
+   при recall), лимит размера (большой файл = документ, в docs/), память ≠ хранилище
+   документов. **У метаданных проекта — свой прогоняемый чек** (битые ссылки CLAUDE.md,
+   захардкоженные счётчики, таблица крупных файлов, покрытие хуков): их дрейф не
+   роняет ни один тест *(АПЕКС check-integrity.ps1)*. Одна точка входа для агента,
+   инструменто-нейтральная: смена инструмента = миграция содержимого, чужие каталоги
+   удаляются тем же коммитом (`gotcha-two-agent-configs`).
+7. **Систематически нарушаемое правило — дефект системы, а не людей.** Гайд не
+   покрывает реальную потребность — расширь систему и задокументируй, а не копи
+   исключения *(BAZA: один класс кнопки закрыл годы техдолга)*. Осознанное исключение
+   пишется **в самом правиле** — с границей применимости *(BAZA viewsets-only)*.
+   Заморозка направления фиксируется в правиле явно («i18n ЗАМОРОЖЕН: … не трогать»),
+   иначе очередная сессия «доводит до ума» замороженный слой *(BAZA)*. Правило,
+   невыполнимое по построению («не портировать вручную» между двумя деревьями одного
+   кода) — сигнал менять структуру, не дисциплину: одномоментный перенос, старое
+   read-only *(АПЕКС ADR-020)*.
+8. **Гигиена сессии:** следить за автокомпактом — ссылки на docs/ позволяют перечитать
+   первоисточник после сжатия контекста; сессия ушла не туда — дешевле поправить
+   CLAUDE.md и начать новую, чем выправлять *(REC dimmer)*. Конфиги быстро меняющихся
+   сторонних сервисов — по актуальной официальной документации, не по памяти модели;
+   версии сверяются ДО генерации конфигов (`gotcha-llm-stale-configs`).
+9. **Протокол отладки** (именованный ритуал с триггер-фразой): снаружи внутрь
+   (UI → сеть → бэкенд → БД); **не чинить первую найденную причину** — проверить, нет
+   ли слоёв под ней; подтвердить фикс фактически до объявления победы; пойманное —
+   в memory/грабли *(BAZA tyranid-hunt)*.
+
+## V. Прод, эксплуатация, наблюдаемость
+
+1. **Боевые серверы — только команды, никакого «я сделаю сам».** На прод/VPS агент не
+   выполняет НИЧЕГО самостоятельно. Он выдаёт готовые команды блоком, выполняет человек.
+   Одно письменное подтверждение = одно действие; «да» из прошлого раза не переносится.
+   *(АПЕКС)*
+2. **Деплой-чеклист письменно и всегда целиком:** build ВСЕХ артефактов («изменения не
+   появились» = собрал не всё — артефактов деплоя больше одного, перечисли ВСЕ и способ
+   сборки каждого, `gotcha-partial-build`) → перезапуск ВСЕХ производных контейнеров →
+   прокси → статусы → логи воркеров → smoke-тест. Частичные варианты — **флаги одного
+   скрипта** (`--backend`/`--frontend`), не отдельные инструкции *(АПЕКС)*.
+3. **Деплой — один канонический скрипт с проверками внутри** *(BAZA deploy.sh)*: отказ
+   при грязном дереве/чужой ветке; список пересоздаваемых сервисов **вычисляется из
+   compose**, не хардкодится (новый воркер попадает в деплой сам); бэкап — при
+   непустом плане миграций; ожидание healthy по inspect с таймаутом, не «на глаз»;
+   smoke = версия из health-эндпоинта, не 200 OK; при провале health-gate скрипт
+   **печатает точную команду отката**. **Точка отката для проекта с миграциями — пара
+   (коммит, дамп)**, образа `:prev` недостаточно: откат кода через миграционный рубеж
+   без отката БД падает на отсутствующих колонках. Rollback — отдельный парный скрипт:
+   подтверждение словом, страховочный дамп текущего состояния ДО восстановления,
+   `--code-ref`, финальная сверка схемы с кодом *(BAZA rollback.sh)*. Фронт-статика:
+   новая сборка рядом (`dist_new`) → атомарный swap, старая = точка отката *(АПЕКС)*.
+4. **Секрет-гигиена, три слоя раздельно: код / состояние / секреты.** `.env` в
+   `.gitignore`, `.env.example` с плейсхолдерами и маркерами `[SECRET] → менеджер`;
+   шифрованные секреты (SOPS+age) коммитятся намеренно, ключ вне репо; учётки внешних
+   SaaS — в парольном менеджере, не в `.env` *(HS+auth)*. Клиентские секреты —
+   платформенный механизм (DPAPI/keychain) + письменно «от чего это НЕ защищает»
+   *(tray-monitor)*. **Секрет в URL = секрет в access-логе и Referer** — маскирование
+   в логах приложения + `access_log off` на эндпоинте *(АПЕКС: JWT в query WS)*.
+   Предупреждать о риске ДО команды, которая выведет секрет в терминал/историю.
+   Утечка = ротация в ту же сессию *(BAZA: PAT)*.
+5. **Канонические пути и имена — письменно в момент создания:** путь на сервере, имена
+   контейнеров, бакетов *(АПЕКС: /opt/signe/ vs «угаданный» /opt/signe-server/)*.
+   Плюс **реестр занятого**: порты/адреса/имена проверяются на конфликт с соседями,
+   включая вендорские дефолты *(REC dimmer: дефолтный IP ноды = дефолт диммера;
+   Grafana 3001 из-за forgejo)*. Порядок старта зависимостей (VPN раньше docker) — либо
+   в юните (`After=`), либо задокументирован как штатный симптом *(мониторинг)*.
+6. **Наблюдаемость** (при проде — обязательна): **внешний наблюдатель** — всё, что
+   запущено на самом сервере, не видит отказ самого сервера *(АПЕКС)*. Health-эндпоинт
+   как liveness («200 degraded») → мониторинг по ключевому слову `"status":"ok"`, не по
+   коду ответа; публичный health не утекает текст исключений. **Dead man's switch на
+   всю периодику** (бэкап, отчёты, синк): «должно было запуститься и не запустилось» —
+   отдельный класс отказов, cron сам о себе не сообщит; сигналы «упал» / «успех
+   устарел» / «успехов не было ни разу» / «метрики вообще нет» слепы по отдельности —
+   нужны все *(мониторинг: BackupNeverSucceeded не видит BackupTooOld)*; ping только на
+   успех, grace с запасом, таймзона сверяется, не предполагается. Структурированные
+   логи + сквозной request_id — с первого дня, задним числом невозможно *(АПЕКС)*.
+   Пороги живут на сервере; клиент отображает решения, не принимает их; цвета клиента =
+   правила стека («жёлтая цифра значит то же, что жёлтая иконка») *(tray-monitor)*.
+   Healthcheck проверяет живой процесс, а не прокси-артефакт (файл/лог/таймстамп);
+   устранив причину — пройди по проверкам, которые на неё опирались
+   (`gotcha-proxy-healthcheck`). Предохранители в скриптах: опасная конфигурация не
+   стартует, обход — только явным флагом с говорящим именем
+   (`ALLOW_PUBLIC_UNAUTHENTICATED=1`) и перечислением того, что утечёт *(мониторинг)*.
+7. **Бэкап не существует, пока не проверено восстановление.** Дамп — вне тома с
+   данными; проверка целостности (`--verify`); retention письменно (daily/weekly/
+   monthly); **один SoT расписания** (`gotcha-double-cron`); процедура restore
+   написана; **поимённый список критических артефактов с ценой пропуска каждого**
+   *(HS+auth: noise.private_key — иначе перерегистрация всех узлов)*. Проверка на
+   **bootstrap paradox**: пройди по зависимостям процедуры восстановления — нет ли
+   тех, что сами восстанавливаются этой процедурой *(HS+auth: бэкап на NAS, доступном
+   через ту же mesh-сеть; REC dimmer: «сбить IP с панели → починить с панели» — пункт
+   приёмки)*. Внешнее хранилище/LFS считается рабочим только после скачивания объекта
+   с чистой машины *(Ad-Tycoon: LFS отдавал 404, 31 файл утерян безвозвратно)*.
+8. **Приёмка и необратимость.** Приёмочный чек-лист — парный артефакт спеки, и он
+   **диктует наблюдаемость**: сначала «как проверяем», из этого — какую диагностику
+   обязан отдавать продукт (счётчики, uptime, версия на самом устройстве) *(REC
+   dimmer)*. **Ворота этапа:** неизвестность закрывается ДО необратимых/дорогих работ;
+   условные этапы не проектируются заранее; фазовый гейт — измеримый пользовательский
+   результат с правом остановить продукт («загрузил → план ≤3 мин против 2 ч; нет
+   „вау“ → пересматриваем») *(EventPlan roadmap)*; ценность раньше «умной» части —
+   ML/распознавание после подтверждения тупого варианта. Отказные сценарии
+   обновления — часть приёмки: битый файл → отказ по CRC, питание в момент записи →
+   грузится старое; «что деградирует во время обновления» записано *(REC dimmer)*.
+   В пайплайне с необратимыми шагами guard выполняется **до первого необратимого**
+   *(АПЕКС: compat-check до записи identity)*. Запас по предельным параметрам вместо
+   защиты, когда отказ необратим («полевик умрёт раньше любой защиты»). Критерий
+   приёмки чисто-архитектурного рефакторинга — **байт-идентичный наблюдаемый выход**
+   до/после, иначе это не рефакторинг *(АПЕКС ADR-021)*. Debug-функциональность
+   физически отсутствует в релизном артефакте (`#ifdef`/сборка), а не «выключена
+   настройкой»: debug-роуты, mock-режимы, фейковый логин *(АПЕКС)*.
+9. **Профиль «публичный релиз»** — отдельный от своего прода: как только артефакт
+   уходит в чужой магазин/Marketplace/публичный домен — LICENSE + поле в манифесте,
+   README-витрина со скриншотами, CHANGELOG, иконка, локализация пользовательских
+   доков (внутренние — на одном языке, и это записано), чеклист модерации ДО релиза
+   *(claude-office-dashboard)*.
+10. **Межпроектные контракты:** значения, которые один проект ВЫДАЁТ, а другой
+    ПОТРЕБЛЯЕТ — таблицей с явным эмитентом и потребителем, «совпадают байт в байт»,
+    включая trailing slash и порт *(HS+auth: OIDC)*. Перечислить ВСЕ пары «кто → кому
+    ходит»: браузер ≠ контейнер, оба должны достучаться — поломки живут в паре, о
+    которой не подумали. **Общий эталон проверяется первым** при «не работает»: земля
+    для сигналов, NTP для токенов (clock skew валит exp/iat), кодировка для текста,
+    таймзона для дат — и записывается в предусловия *(Pulse generator + HS+auth,
+    независимо)*. `[железо]` Однократные ручные предусловия среды («выпаять флеш»,
+    modprobe модуля, драйвер) — письменный чек-лист, не проза. Комплект артефактов
+    железного проекта: pinout · схема подключения · BOM · порядок сборки · приёмка
+    (три проекта пришли независимо); **SoT по «ногам» — документ**, в коде ровно один
+    заголовок (pins.h), его отражающий; при противоречии прав документ *(REC dimmer)*.
+
+## VI. Литания против граблей
+
+> Каждая — реальный инцидент; чти их, дабы не повторить. Теги — к какому стеку/профилю
+> применима; при триаже неприменимые группы отсекай целиком. Ссылайся слагом, не номером.
+
+### Контейнеры и деплой `[Docker]`
+
+1. `gotcha-migration-drift` **Дрейф миграций** `[+Django]`. makemigrations в контейнере
+   без bind-mount → файл живёт в слое образа, БД помнит, git нет; rebuild — файл исчез.
+   Потеряно 18 файлов. → makemigrations ТОЛЬКО через dev-override с bind-mount; после —
+   `git status`; CI-гейт «чистый migrate с нуля». Рецепт восстановления — записан (I.7).
+   *(BAZA)*
+2. `gotcha-stale-workers` **Воркеры на старом образе** `[+очередь]`. `up -d app` не
+   трогает worker/beat/asgi — очередь выполняет старый код, симптомов не даёт. →
+   деплой-чеклист V.2 целиком; список сервисов вычисляется из compose. *(BAZA)*
+3. `gotcha-proxy-cache` **Прокси кэширует upstream.** После пересборки — 502 или старый
+   фронт. → лечить причину конфигом: `resolver 127.0.0.11 valid=10s` + переменные
+   upstream в каждом location — после этого рестарт nginx не нужен; ритуал рестарта —
+   подстраховка, знай, что он маскирует незакрытую причину. *(BAZA, вылечено 3ae5995)*
+4. `gotcha-partial-build` **Артефактов деплоя больше одного.** Пересборка бэкенда не
+   деплоит фронт (в контейнере он или нет — неважно); «изменения не появились» — почти
+   всегда это. → перечисли ВСЕ артефакты и способ сборки каждого. *(BAZA, АПЕКС)*
+5. `gotcha-pidfile` **Pidfile в контейнере.** `docker restart` сохраняет ФС →
+   осиротевший pidfile → вечный рестарт, периодика молча стоит. → pidfile в
+   one-process-контейнере не нужен никогда. Парная: healthcheck, проверявший pidfile,
+   стал вечно-ложным после лечения — устранив причину, пройди по проверкам, которые на
+   неё опирались (`gotcha-proxy-healthcheck`). *(BAZA)*
+6. `gotcha-interval-schedule` **Интервальные расписания сбрасываются рестартом**
+   планировщика → суточная задача «каждые 24ч» не срабатывает никогда. → crontab-выражения
+   для суточных/еженедельных. *(BAZA)*
+7. `gotcha-silent-unregistered` **Расписание ≠ реестр** `[+очередь]`. Задача, не
+   попавшая в реестр воркера (autodiscover не видит подпакет), отбрасывается МОЛЧА —
+   beat шлёт, воркер отвечает «unregistered», симптом — тишина. Юнит-тесты, импортирующие
+   задачу напрямую, бага не видят. → тест «расписание ⊆ реестр» + проверка в
+   деплой-скрипте; у планировщика нет громкого режима отказа — создай его. *(BAZA, прод)*
+8. `gotcha-dev-prod-settings` **Dev-стек на prod-настройках.** Забытый override →
+   prod-whitelist хостов → 400 на локальном домене. → явные именованные override-файлы
+   и одна задокументированная команда запуска dev-стека. *(BAZA)*
+9. `gotcha-exec-bit` **Права/окружение контейнера ≠ хоста** `[+Windows]`. Скрипт без +x,
+   том с чужим uid → Permission denied. → скрипты звать через `sh <путь>`; явные права
+   томов; проверка после первого up. *(BAZA)*
+10. `gotcha-rootowned-bindmount` **Bind-mount на несуществующий путь** — docker создаст
+    каталог от root, задача не от root писать не сможет. → создавать каталоги заранее
+    в скрипте. *(мониторинг)*
+11. `gotcha-docker-bypasses-ufw` **Границу доступа определяет bind-адрес, не фаервол.**
+    Docker пишет правила в nat в ОБХОД ufw — `ufw deny 9090` порт не закроет. → bind
+    на tailnet/localhost; публичный bind — осознанное решение. *(мониторинг)*
+12. `gotcha-container-oom` **Контейнерный лимит памяти без внутреннего лимита процесса**
+    → OOM-kill вместо деградации. → лимит процесса ниже лимита контейнера. *(АПЕКС)*
+13. `gotcha-env-special-chars` **Спецсимволы `#$!%&` в пароле** ломают парсер
+    .env/compose → контейнер в вечном Restarting. *(АПЕКС)*
+14. `gotcha-compose-env-drift` **Дефолты в compose разошлись с .env.example** → стек
+    поднимается с другими именами БД/юзера. → один источник дефолтов. *(АПЕКС)*
+
+### Данные и логика
+
+15. `gotcha-journal-bypass` **Мутация в обход журнала.** Ручное списание меняло остаток
+    напрямую — журнал слеп, аудит дыряв. → ЕДИНАЯ точка применения эффекта, все пути
+    через неё. *(BAZA)*
+16. `gotcha-pair-asymmetry` **Асимметрия парных операций.** Создание покрывало 2 метода
+    оплаты, отмена — 1: проводка-сирота, отчёт врал. → create+cancel парой, тест на цикл
+    create→cancel→след чист. *(BAZA)*
+17. `gotcha-increment-race` **Гонки на инкрементах.** Два параллельных движения читают
+    один остаток → lost update. → блокировка (select_for_update) внутри транзакции на
+    любых счётчиках с первого дня + конкурентный тест. Где лочить нельзя (ISR, UI) —
+    один назначенный писатель (I.17). *(BAZA)*
+18. `gotcha-placeholder-data` **Плейсхолдер, притворяющийся данными.** Черновые значения
+    без пометки уезжают как «проверенные». → помечать (`?`, TODO владельцу); гейт перед
+    прод — плейсхолдеров не осталось. *(EventPlan)*
+19. `gotcha-number-null` **Number(null) === 0** `[React/формы]`. Трансформ на маунте:
+    null FK → 0 → «выбрана» несуществующая запись. → null-безопасные setValueAs. *(BAZA)*
+20. `gotcha-green-modules-dead-system` **Модули зелёные — система мертва.** 74 честных
+    юнит-теста, архитектура по гайдлайнам — а ключевая функция ядра не вызывается
+    нигде, автосейва не существует (ноль вызовов), софтлок за 12 минут. → orphan-check
+    «кто вызывает» по каждой публичной функции ядра; интеграционный тест полного цикла;
+    для накопительных доменов — headless-прогон N шагов с проверкой, что метрики
+    двигаются. *(Ad-Tycoon, независимое ревью)*
+21. `gotcha-orphan-config` **Конфиг-поле без потребителя.** Поля загружаются,
+    валидируются — и никем не читаются; рядом код с хардкодом, расходящимся с конфигом
+    в 100 раз. → вынес в конфиг = есть потребитель и тест, что читается именно оно;
+    валидация при старте; единицы сходятся. *(Ad-Tycoon)*
+22. `gotcha-gitignored-dependency` **Зависимость от артефакта вне git.** Детект платформы
+    завязан на плагин из каталога в .gitignore — работает только на машине разработки,
+    в чистом клоне и CI ломается молча. → гейт «чистый клон собирается и стартует».
+    *(Ad-Tycoon)*
+
+### Версии и контракты
+
+23. `gotcha-version-sot` **Несколько «источников истины» версии.** pyproject vs
+    настройки vs package.json расползаются. → SoT-файлы письменно, остальное не
+    считается. *(BAZA)*
+24. `gotcha-version-symmetry` **Автовыравнивание версий «для симметрии».** PATCH
+    независим — ровнять = фейковые релизы. → бамп только изменившегося. *(BAZA)*
+25. `gotcha-lexicographic-semver` **Лексикографическое сравнение версий.**
+    `"0.10.0" < "0.9.0"` строками — стреляет в OTA, когда MINOR доходит до 10. →
+    сравнение только semver-парсером. И вторая линия: **guard от даунгрейда на стороне
+    клиента** — `strcmp(...)!=0` означало «ставлю всё, что отличается»; серверная
+    монотонность фида — единая точка отказа, способная забрикать флот одной ошибочной
+    публикацией; намеренный откат — «старый код под более высокой версией».
+    *(АПЕКС, ADR-023)*
+26. `gotcha-feature-test-debt` **Тестовый долг фичи.** Фича изменила ответ эндпоинта,
+    тесты не тронули — красный набор всплыл через неделю у чужой сессии. → тесты
+    контракта в том же коммите, полный прогон перед push. *(BAZA)*
+27. `gotcha-tsc-no-b` **`tsc` без `-b` не проверяет project references** `[TS]`.
+    Локально зелёный, сборка на сервере падает. → `tsc -b --noEmit` при
+    composite/references. *(АПЕКС)*
+
+### Windows и кодировки `[Windows]`
+
+28. `gotcha-gitattributes` **Переносы строк без `.gitattributes`.** autocrlf →
+    LF↔CRLF-дрейф, в Linux-контейнере ломаются скрипты с CRLF. → `* text=auto eol=lf`
+    с ПЕРВОГО коммита. *(EventPlan: 80+ предупреждений)*
+29. `gotcha-non-ascii-toolchain` **Не-ASCII там, где системная кодировка.** Три канала:
+    (а) файлы, которые парсит тулчейн — только ASCII *(АПЕКС: PlatformIO упал на
+    кириллице в partitions_apex.csv — cp1251)*; (б) **stdout вспомогательных скриптов**
+    на Windows — cp1251, `UnicodeEncodeError` на любом спецсимволе →
+    `PYTHONIOENCODING=utf-8` или ASCII-вывод *(воспроизведено дважды при аудите)*;
+    (в) **stdin хуков** читать как UTF-8 байты явно — иначе кириллица-мохито
+    *(office-dashboard 2c047ee)*.
+30. `gotcha-windows-bindmount` **Windows bind-mount врёт.** Задержка синхронизации →
+    контейнер видит старый файл. → docker cp или --no-cache при сборке фронта. *(BAZA)*
+31. `gotcha-case-insensitive-headers` **`HTTPClient.h` vs `HttpClient.h`** — две
+    библиотеки, различающиеся регистром имени, конфликтуют на регистронезависимой ФС.
+    *(АПЕКС)*
+
+### Инфраструктура `[инфра/прод]`
+
+32. `gotcha-shared-proxy` **Общий реверс-прокси: глобальные объекты и Host.**
+    Одноимённые `map`/`upstream` → «duplicate map»; proxy_pass по IP без `Host $host` →
+    400 от whitelist. → имена глобальных объектов уникальны per-vhost; Host всегда.
+    *(BAZA)*
+33. `gotcha-fail2ban-self` **Авто-защиты банят свою автоматизацию.** fail2ban целевой
+    системы банит настройщика после 2 SSH-коннектов (ssh-copy-id = 2 = бан). → свой IP
+    в доверенные ДО работ. *(BAZA: NAS)*
+34. `gotcha-pipefail` **Пайп без `set -o pipefail`** → код возврата от последней команды:
+    упавший pg_dump + живой gzip = пустой архив и «успех». Зелёный статус над битым
+    дампом хуже отсутствия бэкапа. *(мониторинг)*
+35. `gotcha-tls-bare-ip` **Запрос по голому IP при сертификате на домен** провалит
+    TLS-проверку — в инструкциях и конфигах всегда домен. *(АПЕКС)*
+36. `gotcha-crypto-defaults` **Дефолты криптоутилит небезопасны.** htpasswd по умолчанию
+    bcrypt cost 5 (32 раунда) — задавать стоимость явно (`-C 12`). *(мониторинг)*
+37. `gotcha-https-redirect-proxy` **HTTPS-редирект за SSL-прокси хостинга** =
+    бесконечный редирект: `RewriteCond %{HTTPS} off` не видит прокси. → редиректы —
+    средствами панели/прокси; за прокси о схеме судят по `X-Forwarded-Proto`.
+    *(лендинг; родня `gotcha-shared-proxy` — за прокси реальность не та, что видит
+    приложение)*
+38. `gotcha-robots-secret` **Секретный путь в robots.txt.** Строка `Disallow` сама
+    выдаёт путь любому, кто откроет robots. → секретные пути не упоминать нигде
+    публично. *(лендинг)*
+39. `gotcha-double-cron` **Два механизма расписания** (`/etc/cron.d/*` и `crontab -e`) →
+    задача дважды за ночь. → SoT расписания — один файл, создаётся setup-скриптом.
+    *(АПЕКС)*
+40. `gotcha-nginx-details` **Мелочи nginx:** `expires` + `add_header Cache-Control`
+    вместе = дублирующийся заголовок; на Debian пользователь `www-data`, не `nginx`.
+    *(АПЕКС)*
+
+### Процесс
+
+41. `gotcha-docs-drift` **Документация отстаёт молча.** Месяц без сведения = 35 файлов
+    лжи и день работы 10 субагентов. → ритуал закрытия сессии (III.4), каждый раз.
+    *(BAZA)*
+42. `gotcha-god-files` **God-файлы съедают контекст и дисциплину.** serializers на 940
+    строк, страница на 1290. → делить при росте, карта крупных файлов с автопроверкой
+    (III.1), точечное чтение. *(BAZA)*
+43. `gotcha-phantom-tails` **Фантомные хвосты плана.** «Незакрытые» пункты roadmap
+    давно сделаны — сессия готова повторить работу. → статусы по факту кода, сверка
+    перед реализацией (III.5). *(BAZA: 2 из 4)*
+44. `gotcha-silent-later` **Молчаливое «потом».** Каждое «потом допишем» без записи
+    исчезает. → всё отложенное — письменно (план, ADR-компромисс, реестр долгов,
+    memory) в момент откладывания. *(BAZA)*
+45. `gotcha-ci-wrong-branch` **CI слушает не ту ветку.** Workflows на master, работа
+    месяц шла в dev — гейты тихо перестали существовать. → сменил ветвенную модель →
+    в тот же коммит триггеры CI/хуков/автоматики. *(BAZA d9804c2)*
+46. `gotcha-hook-shell-blind` **Хук слеп к реальному шеллу.** Matcher `Bash`, работа
+    идёт в PowerShell — защита существует и не работает. → покрытие хука по всем
+    шеллам, проверяется скриптом целостности. *(АПЕКС)*
+47. `gotcha-renumbered-parent` **Перенумерация родительского документа** тихо ломает все
+    производные ссылки. → ссылаться слагом; при реструктуризации — прогнать ссылки в
+    производных. *(EventPlan: ссылки на литанию били в пустоту через 2 часа)*
+48. `gotcha-two-agent-configs` **Две конфигурации агента.** Проект вёлся двумя
+    инструментами, конфигурация дважды мигрировала и рассинхронизировалась. → одна
+    инструменто-нейтральная точка входа; чужие каталоги удаляются тем же коммитом.
+    *(Ad-Tycoon ADR-010)*
+49. `gotcha-automated-prompt` **Системные инъекции неотличимы от пользователя.**
+    Автоуведомление фоновой задачи пришло как «промпт пользователя» и снимало
+    экстренную остановку. → механика, реагирующая на «пользователь написал», обязана
+    фильтровать автоматику. *(office-dashboard v0.13.2)*
+50. `gotcha-llm-stale-configs` **Конфиги по памяти модели.** Синтаксис быстро меняющихся
+    сервисов, выдуманный по памяти, не совпадает с текущей версией *(HS+auth: Authentik
+    2026.x убрал Redis)*. → сверка с актуальной официальной докой; версии пинуются и
+    записываются ДО генерации.
+51. `gotcha-modal-drag-close` **Модалка закрывается при drag-выделении текста**
+    `[React]` (mouseup ловится на бэкдропе). → закрытие по клику, начатому и
+    завершённому на бэкдропе. *(АПЕКС)*
+52. `gotcha-404-swallows-detail` **Глобальный 404-хендлер глотает содержательные
+    `detail` роутеров.** → хендлер пропускает существующий detail. *(АПЕКС)*
+
+---
+
+**Финал:** литания прочитана, профиль определён, триаж проведён, каркас развёрнут и
+отревьюен — можно начинать. Новые грабли проекта — в живой раздел
+`docs/architecture.md#Грабли проекта` (копия литании read-only), обобщаемое —
+периодически в мастер-литанию: она живёт, пока её кормят инцидентами.