# Промт: сессия КОНТРАКТ-РЕВЬЮ — API v0 фронт↔платформа на адекватность и индустриальные нормы (строка 179)

> Выдан оркестратором №17 15.08.2026 по заказу владельца (D39.136 п.5; форма «отдельная сессия»
> — слово владельца 15.08, эррата 15.08-в). Запуск — по слову владельца. Тяжёлый класс: полный
> аппарат — эхо-протокол, судейство буллетов, кросс-модельные опровергатели.

## 0. Какую проблему решаем и что даст твой результат

TextMachine — сервис издательского перевода книг: Go-движок `tmctl` (процесс-на-прогон, SQLite
на книгу) · SaaS-платформа `platform/` (пользователи/деньги/очередь, зовёт движок процессами,
проецирует его артефакты в HTTP) · веб-фронт `frontend/` (React, дом — мир моков MSW). Между
фронтом и платформой — ратифицированный контракт **OpenAPI 0.2.3**: канон
`docs/architecture/14-api-contract/openapi.yaml` + компаньон-README рядом (провенанс, К-вопросы).

Контракт рос ТОЧЕЧНЫМИ правками (0.2.0→0.2.3), каждую сверяли «спека ↔ код», но целиком «а
хороший ли это API» не смотрел никто. Владелец заказал жёсткое ревью: без костылей и хаков, по
индустриальным нормам, и — ключевое — **БЕЗ ИНЕРЦИИ от уже принятого**: «ратифицировано ≠
правильно». Живой пример, почему это не паранойя: правило PD-172 ратифицировано в форме «сервер
читает multipart-форму до части `file`, необязательное поле после файла МОЛЧА теряется при
успешном 201» — потому что так делает код платформы. Тихая потеря данных на успешном ответе —
кандидат в протёкшую реализацию, и таких мест может быть больше.

Твой результат: **доклад с СУЖДЁННЫМИ буллетами** — каждый с вердиктом, миграционной ценой и
рекомендацией — из которого владелец и оркестратор ратифицируют батч правок **0.3.0**. Сам ты
НИЧЕГО не правишь и не заводишь: ни спеку, ни код, ни бэклог, ни канон — только отчёт. Момент
идеальный: до беты, по одному построенному потребителю с каждой стороны — дешевле не будет.

## 1. Онбординг (порядок чтения; ⚠ вся документация и код написаны нейросетями — могут ошибаться)

1. `CLAUDE.md` (корень) — гардрейлы; жёсткие для тебя: `.env` НЕ читать · PUML не рендерить ·
   чужие незакоммиченные файлы (сейчас в дереве живёт полигон: `eval/`, `docs/POLYGON_*`,
   `docs/experiments/23-*`) не трогать · git-коммитов НЕ делать вовсе.
2. Канон: `docs/architecture/14-api-contract/openapi.yaml` ЦЕЛИКОМ + компаньон-README рядом
   (К-вопросы, провенанс ✓/◆/○, §2.15 потолок).
3. Код — read-only, все три зоны: `platform/internal/` (httpapi, books, runs, ingest — что сервер
   ДЕЛАЕТ на самом деле) · `frontend/src/api/` + `src/mock/` + использование в `src/showcase/`
   (что клиент реально зовёт, чем лечится сам) · движок: `backend/cmd/tmctl/` +
   `backend/internal/pipeline/{manifest,bankexport,status,export}.go` + эмиттер `events.jsonl`
   (правда данных, которые контракт проецирует).
4. Планы (контракт обязан их пережить): `docs/product-requirements.md` (ПТ-реестр) ·
   `frontend/docs/FRONTEND_SESSION_PROMPT.md` §3 (сценарии S5–S7: подпись банка, читалка,
   экспорт/настройки/лимиты) · `docs/research/16` (ридер-IDE Ф3) · `docs/research/27` (структура
   глав — двинет контракт: правка названий, типы глава/фрагмент) ·
   `docs/architecture/15-money-path.md` · `platform/BACKLOG.md` (П-строки читающей поверхности) ·
   строки единого бэклога 49 (annot-v1) · 94 · 160–162 · 169 · 178 (`docs/PROGRESS.md`).
5. Голова D-лога по контракту — только для контекста ратификаций: D39.99 (v0) · D39.115/123/127/
   129/130/135 (минорные бампы). Помни мандат: эти решения МОЖНО опрокидывать — аргументом.

**Эхо-протокол:** первый деливерабл — ≤10 строк «что я понял: скоуп / инварианты / не-делать»
ДО работы. Расхождение чинится на минуте пять, не на приёмке.

## 2. Метод (ратифицировано направлением — отступление с аргументом в отчёте приветствуется)

Субагенты, панели и воркфлоу-оркестрация для тебя **РАЗРЕШЕНЫ ЯВНО** — дефолт-запреты харнесса
на это ревью не распространяются; изоляция агентов обязательна (читающие мандаты, state-changing
git запрещён перечислением: reset/checkout/restore/clean/stash/add/commit/rebase/push).

1. **Инвентарь фактов** чтением кода трёх зон и планов — каждый факт с `file:line`. Особо:
   расхождения «сервер умеет — контракт молчит» и «контракт обещает — сервер не делает»
   (известные: `BookIntake.title` платформа не читает, `Book.reject_reason` не проецирует —
   это ратифицированный форвард с носителем в P7, НЕ находка; ищи НЕизвестные).
2. **Greenfield-контраст (главный механизм анти-инерции):** агент(ы), которые НАШУ СПЕКУ НЕ
   ВИДЕЛИ, проектируют форму API с нуля от продуктовых требований (собери им бриф из §1 п.4 БЕЗ
   ссылок на спеку). Потом дифф с нашей: совпадение — подтверждение, расхождение — вопрос на суд,
   не приговор.
3. **Линза стандартов:** постатейная сверка с первоисточниками — RFC 9110 (семантика HTTP),
   RFC 9457 (problem details), практики SSE, OpenAPI-конвенции, публичные стайлгайды уровня
   Stripe/GitHub/Google/Microsoft. Интернет-доступ легитимен для чтения стандартов; выводы — с
   цитатой источника.
4. **Аудит квирков:** каждое место спеки, рождённое «уточнением по коду», судится вопросом:
   «это осмысленный контракт или протёкшая деталь реализации — и что дешевле чинить: спеку или
   код?» (обе зоны построены — цена реальна с обеих сторон).
5. **Судейство буллетов ДО отчёта:** каждый кандидат-буллет проходит адверсариальную верификацию
   — опровергатель с установкой опровергать, **кросс-модельно** (опровергатели текстовых/
   оценочных линз — ДРУГИМ семейством модели, чем автор буллета); вердикт CONFIRMED / PLAUSIBLE /
   REJECTED. Выживший буллет несёт: severity · чью боль лечит (фронт/платформа/движок/продукт/
   индустрия) · **миграционную цену** (что и у кого переделывается) · рекомендацию «менять спеку /
   менять код / оставить как есть с записанным обоснованием». REJECTED-буллеты — отдельной
   секцией с причинами (отвержение лишнего — тоже результат).

## 2а. Наши антипаттерны и оплаченные уроки — дисциплина ТВОЕГО ревью, с генезисом (не декор; каждый куплен реальным инцидентом проекта)

Проект ведёт письменный канон дисциплины ревьюера (дом — `docs/ORCHESTRATOR_SESSION_PROMPT.md`,
блок «Анти-паттерны приёмки», и D-ноты D39.46/47/120/121). Шесть ловушек, в которые ревью на
LLM падает систематически — и как промт §2 их гасит:

1. **След отчёта** — ревьюер проверяет только места, НАЗВАННЫЕ автором. У тебя: суди контракт по
   СВОЕЙ карте, построенной из кода и стандартов, а не по карте компаньона и наших ратификаций —
   они и есть «отчёт автора».
2. **Связность вместо истинности** — гладкий, хорошо мотивированный текст убеждает сам собой
   (наша спека многословно обосновывает свои решения — это форма, не доказательство). Гаситель —
   greenfield §2.2: форма API проектируется ДО знакомства с нашими доводами.
3. **Соглашательство с чёткой позицией** — LLM склонны соглашаться с уже принятым/сформулированным.
   Отсюда мандат «ратифицировано ≠ правильно» — он не разрешение, а ОБЯЗАННОСТЬ пере-судить.
4. **Рационализация задним числом** — найдя довод ЗА нашу форму, проверь: существовал бы этот
   довод, если бы ты увидел такую форму в чужом API?
5. **Слепой участок общих моделей** — модели одного семейства обучены на пересекающихся корпусах:
   подтверждение буллета тем же семейством НЕ независимо. Поэтому кросс-модельные опровергатели
   §2.5 — требование, не пожелание (норма D39.120).
6. **Экономия усилия на неудобном** — самые дорогие находки живут там, где читать скучно:
   пагинация, коды ошибок, идемпотентность, повторы. Скучное — читать первым, не последним.

Плюс три урока наших же ресёрчей и замеров:

- **Овер-атрибуция — ТИПОВОЙ провал ресёрчей этого проекта** (верные числа/цитаты не к тому
  предмету; ловилось многократно, вплоть до приёмок): цитаты стандартов — ДОСЛОВНЫЕ, с URL,
  сверенные по первоисточнику; пересказ RFC по памяти модели уликой НЕ является.
- **Сфабрикованная сходимость** (наш повторявшийся паттерн агрегации): «три линзы сходятся»
  ощущается сильнее данных. Перед мульти-линзовым буллетом — leave-one-out: держится ли он без
  каждой из линз по отдельности.
- **Вывод на агрегате до вскрытия единиц запрещён** (урок платных замеров, D39.61): вердикт по
  КЛАССУ («ошибки без машинных кодов», «списки без пагинации») — только после вскрытия конкретных
  мест с `file:line`, минимум по одному на затронутую зону.

**Предметные оси самопроверки этого пака** (норма D39.120; вправе добавить свою или
аргументированно снять): (1) *claim-fidelity* — перед сдачей выборочно пере-открой ≥10 случайных
`file:line`-улик своего отчёта исполнением; (2) *анти-инерция* — у каждого вердикта «оставить как
есть» записан КОНТРАРГУМЕНТ, который ты рассмотрел и отверг (пустая графа = не судил);
(3) *полнота интересов* — каждый буллет несёт, чью боль лечит и кому миграция дорога (§4).

**Разметка свободы:** метод §2 и входы §3 по ПОКРЫТИЮ — «делай ровно так» (каждому входу —
диспозиция, вплоть до «делать не надо, потому что…» — это легитимный ответ с аргументом);
СУЩЕСТВО вердиктов — целиком твоё (ты предлагаешь, ратифицируют владелец и оркестратор).
Аддендумы к промту доезжают только релеем владельца — эхо-подтверди получение и отрази отдельным
пунктом отчёта. Жаргон проекта (банк, юнит, волна, банкнота, сид…) — `docs/glossary.md`.

**Порядок чтения против якорения:** ты-лид читаешь всё; но greenfield-агентам §2.2 наша спека,
компаньон, D-ноты и этот раздел НЕ выдаются — им только продуктовый бриф. Мотивы наших правок
(провенанс ✓/◆/○ компаньона, приёмочные записи фронта) сам читай ПОСЛЕ того, как твоя
собственная карта фактов §2.1 построена.

## 3. Обязательные входы (вопросы, уже стоящие в очереди — каждому дать диспозицию в отчёте)

- **Ф-56**: конец разбора книги никто не объявляет — клиент лечится опросом раз в 3 с; кадр/канал?
- **Ф-57**: какие пары языков продукт принимает — контракт не выражает ни список, ни отказ по паре.
- **Ф-61 + машинные коды + i18n**: платформа и движок шлют человеческие строки хардкод-английским;
  машинных кодов ошибок нет; слово владельца 15.08 — хардкод недопустим во ВСЕХ зонах; как
  контракт должен нести причины (код + словарь клиента? Accept-Language? где живут фразы)?
- **Ф-62**: переименование книги — направление «в контракт» ратифицировано (D39.136 п.4в); дать
  форму — и шире: какие записи на книге вообще легитимны (сейчас на всей поверхности НИ ОДНОЙ).
- **Форма PD-172**: потоковое правило multipart (см. §0) — контракт или протёкшая реализация?
- **Пагинация и масштабы**: банк пагинирован (1000/курсор), а главы (реальная книга — 2284
  раздела), юниты, замечания, события — нет; сверь масштабы с движковыми артефактами.
- **Зашитые числа**: 16 частей · 1 КиБ на поле · page 1000 — принадлежат ли контракту (коммент
  кода платформы зовёт их «делом деплоя»).
- **Паттерн-консистентность**: `paused_reason` required+nullable против `reject_reason` optional
  — одна семантика, два паттерна (спека мотивирует; суди мотивацию); найди ВСЕ такие пары.
- **Идемпотентность** `POST /books` (ретрай загрузки = дубль книги?), семантика 408/413, 404 как
  «на этом деплое нет интейка».
- **Версионная политика**: клиент сверяет только мажор, миноры аддитивны — достаточно ли для
  планов S5–S7/Ф3.
- **К-вопросы компаньона** — статусы и что ревью может закрыть.
- **Спойлер (В-10)**: ТОЛЬКО если владелец к моменту запуска сказал «защита» — тогда форма
  «sense по явному раскрытию»; если «вежливость» или слова нет — НЕ трогать.

## 4. Интересы, которые обязаны быть учтены (владелец 15.08: «учесть интересы все»)

Фронт (что реально нужно UI: лаг, спам запросов, honest states) · платформа (реализуемость,
деньги/холды, деплой) · движок (контракт не должен ВРАТЬ о данных движка и их именах; ложные
друзья класса source/origin уже ловились) · продукт и планы S5–S7/Ф3 (подпись банка, читалка,
экспорт — без слома контракта) · индустрия (стандарты §2.3). Конфликт интересов — называть
явно, не решать молча в чью-то пользу.

## 5. Границы

- Ты НЕ правишь: спеку · код · бэклог · D-лог · README. Единственный твой файл —
  `docs/research/28-contract-review.md` (отчёт). Дерево НЕ коммитить — лендит оркестратор.
- $0 по внешним провайдерам перевода: платных LLM-вызовов НЕТ (агент-токены твоего харнесса —
  не в счёт). Интернет — только чтение стандартов/доков.
- Живой стенд платформы поднимать НЕ требуется (можно read-only читать код тестов, чтобы понять
  поведение; вердикт о рантайме без прогона помечай PLAUSIBLE — D39.129).

## 6. Самопроверка и сдача (мандат, не пожелание)

- «Заявление = команда»: каждый факт — `file:line` или цитата стандарта с URL; числа — командой.
- Записка-план по буллетам (ID → статус → улика; D39.121) — движение по ней, сдача = все ID
  имеют диспозицию.
- Критик полноты на финале: что НЕ покрыто (зона/ось/вход из §3) — явным списком, не молчанием.
- Obstacle reporting: что не удалось прочитать/проверить — явно.
- Отчёт `docs/research/28-contract-review.md`: (1) карта фактов по зонам · (2) буллеты
  CONFIRMED/PLAUSIBLE с ценой и рекомендацией, упорядоченные по severity · (3) REJECTED с
  причинами · (4) предложение состава батча 0.3.0 (или честное «контракт здоров, N точечных
  правок») · (5) не покрытое. Владельцу — краткое резюме поверх файла.
- Стиль отчёта — норма «без саги»: плотность, не объём; эрудиция ≠ улика (каждое утверждение —
  `file:line` или дословная цитата с URL, иначе пометка «мнение»); без пересказа промта и
  шаблонных оговорок.

## 7. Канал вопросов

Непонятно / промт конфликтует с кодом или доками / нужна правка вне твоего файла → пинг
оркестратору через владельца, НЕ интерпретация. Настоящие развилки эскалируй быстро — это норма.