Mayak 1.1.0

Mayak 1.1.0

Mayak стал компактнее, а обязательные локальные проверки теперь исполняют SQL в настоящем
PostgreSQL. В релиз входят извлечение образца из создаваемого проекта, быстрый гейт при
редактировании, исправления конфигурации и агентных сценариев, защита логов и руководство
по обновлению существующих сервисов.

Насколько похудел шаблон

Одинаковый подсчёт Git-снимков v1.0.0 (f2f4b86) и кода перед релизом 2e2f0dc:

Метрика	1.0.0	1.1.0	Изменение
Непустые строки Python во всём шаблоне	38 350	29 226	−23,79%
Исполняемые строки Python во всём шаблоне	28 622	23 703	−17,19%
Исполняемая обвязка: scripts + ai_context + ai_query	10 316	6 161	−40,28%
Непустые строки Python в тестах	18 575	14 957	−19,48%
Исполняемый runtime в project/	4 488	4 592	+2,32%

Главное сокращение — в инструментарии, навигационных слоях и обслуживании шаблона. Runtime
получил дополнительные проверки и исправления. Исполняемые строки считаются одним
validation_support.line_metrics.compute_module_metrics для обеих версий: комментарии,
docstrings и пустые строки не входят. Непустые строки считаются отдельно и включают документацию
в Python. Все пути берутся из Git; локальные окружения, кэши и результаты тестов не учитываются.
Версионный commit меняет manifest/lock и документацию, поэтому эти Python-счётчики не меняются.

Созданный из нового шаблона чистый проект наследует 21 382 непустые строки Python, включая
сохранённый scaffold; потолок — 22 000. Это метрика извлечённого проекта, её нельзя смешивать
с размером полного репозитория. Образец и тесты самого шаблона больше не остаются в runtime
сервиса после make init-project.

Сколько токенов удалось сэкономить

В завершённом мини-бенче сценария T1 — создание каркаса, вертикалей тренеров/залов и удаление
образца — новый пакет расходовал меньше токенов во всех пяти парах:

• −41,45% токенов по медиане пяти пар: считается ввод + вывод учтённых прогонов агента.
• −21,15% времени по медиане пяти пар: по полю agy_seconds учтённых запусков; это не полный срок разработки.
• Изменения токенов по отдельным парам: −41,45%, −27,06%, −51,79%, −47,78%, −2,41%.

Это сравнение f2f4b86 с проверявшимся пакетом 3dbf7b5, а не новый замер финального тега
1.1.0. Менялись вместе код, структура, пример вертикали, проверки и инструкции; экономию
нельзя приписать одной правке текста. Метрика не включает cache-read, отброшенные попытки,
проверяющих и общую денежную стоимость. В дополнительных сценариях T2/T3 устойчивый сигнал
экономии не получен. Корпус — 22 запуска: 5 пар T1, по 3 пары T2/T3.

Полная приёмка T1, включающая чувствительность тестов к поломкам: старый вариант 0/5,
новый 3/5. У двух новых продуктов контроль сломался на зависимости теста от локального
порта. Формальный вердикт предварительно заданного протокола по всем трём задачам остался
«не доказано». Поэтому измеренное сокращение токенов — результат конкретного T1;
универсальная экономия 41% для любого проекта не заявляется.

Счётчики и агрегаты измерений сохранены отдельно.

Что улучшилось

• make gate-fast даёт форматирование, lint, типы и архитектурные проверки во время работы;
  make quality-gates сохраняет полный контроль, включая настоящий PostgreSQL и миграции.
• Образец автоматически переносится в scaffold при инициализации собственного проекта;
  извлечение также убирает тесты/инструменты шаблона и ненужную ему CI job. История миграций
  сохраняется, удаление таблицы добавляется отдельной миграцией.
• Рекомендации для вертикалей требуют контрастных данных, проверки записанного результата,
  защиты каждого пути записи и явного контекста для живой модели. Пример LLM-цикла исполняет
  все tool calls из одного ответа; opt-out тестов сохраняется после форматирования Ruff.
• PostgreSQL DSN сохраняет пробелы и спецсимволы реквизитов, имена баз и IPv6 через реальные
  libpq/SQLAlchemy-парсеры. Слабый тест пароля заменён точным сравнением параметров. Также
  исправлены OpenAPI 422, статус 500 в трассах, ловля malformed LLM replies, проверки startup
  до миграций, сценарии lifecycle и достоверность mutation runner.
• Обновлён urllib3 в lock; логи скрывают чувствительные значения. В
  руководстве обновления перечислены адресные проверки и пути переноса
  исправлений в существующие сервисы. Автоматического обновления чужой копии нет.

Проверка

На коде с финальными исправлениями PR #41: 1 202 теста прошли, один пропущен,
покрытие 90,38%; Docker e2e и извлечённый проект прошли. Все 18 GitHub-проверок PR #41
зелёные. Версионный commit 1.1.0 проходит проверки отдельно перед публикацией.

Дополнительно из main с локальным исправлением DSN собраны два самостоятельных сервиса:
RoomPilot и SupportPilot. Чистые Git-копии прошли 1 309 локальных тестов и 18 Docker e2e,
запросы к настоящей модели RouterAI и независимые проверки Sol. Эти продукты содержат
собственные бизнес-правила, бюджет времени и agent loop; их частные доработки не объявляются
автоматически частью шаблона. Эти результаты не заменяют сертификацию production-среды
или широкую оценку качества/доступности модели.

Обновление

Новый проект: используйте тег v1.1.0, выполните make init-project и замените его identity
по навыку initialize-project. Для существующего сервиса начните с
docs/upgrades.md: перенесите необходимые изменения, затем выполните
make quality-gates, а после endpoint/wiring/migration изменений — make test-e2e.

v1.0.0

A backend service template for projects an AI agent writes and maintains. FastAPI, PostgreSQL, hexagonal layering, one worked vertical meant to be copied.

What makes it different is not the code — it is that the guardrails are measured. A mutation matrix breaks twenty-four things one at a time and checks that something goes red for each: a reversed ORDER BY, a foreign key without ondelete, a tautological SQL round trip, an import cycle, a second Alembic head, an unwired router, a stale generated wrapper, a skill naming a make target that does not exist. All twenty-four are caught on this commit.

In this release

tests	1082, coverage 87.63%
blocking validators	11
CI jobs	8
trap matrix	24 of 24 caught
kernel project/	4 488 executable lines
tooling scripts + ai_context + ai_query	10 302 executable lines

One contract, two agents. docs/agent_rules.md renders to AGENTS.md, which Codex reads directly and Claude Code reads through a CLAUDE.md that imports it. One document, 1 259 words, no second copy to keep in step — ADR-011.

Ten dated decisions in docs/adr/, including ADR-010, which states plainly what the gates cannot see.

Two skills under .agents/skills/, shared by both agents through a symlink: initialize-project and add-vertical, the latter carrying the eleven files and three wiring edits a new vertical costs.

A pre-edit hook that refuses a write to a generated file at the moment the write is attempted, for both agents, because a rule in prose does not stop one.

Known limits

• The gates run none of your queries. A SQL defect is caught only if a test pins its clause as literal text, and a migration is verified only against a real database — make test-e2e. ADR-010 says this in full.
• No authentication, no frontend, no business pipeline. The kernel ships one vertical to copy and nothing that guesses at your domain.
• No upgrade path. A project created from this template owns its copy; there is no mechanism to pull later template changes in.
• The mutation matrix is a development harness, not yet a committed artefact — reproducing the twenty-four is manual for now.

Getting started

make init-project      # writes .env, idempotent
make quality-gates     # the full gate

Then read AGENTS.md, or point your agent at it and copy the reference_task vertical with .agents/skills/add-vertical.