textmachine/docs/archive/prompts/CONTRACT_REVIEW_SESSION_PROMPT_2026-08-15.md

⚠ АРХИВ — ОТРАБОТАН. Исполнен отдельной контракт-ревью-сессией 15–16.08.2026 (разбор с владельцем — 16.08), принят приёмкой оркестратора №17 (D39.138): отчёт — docs/research/28-contract-review.md — носитель решений владельца (§8) и состава батча 0.3.0 (§5); строка 179 закрыта, исполнение — строка 183. Инструкции отсюда не исполнять.

Промт: сессия КОНТРАКТ-РЕВЬЮ — 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. Канал вопросов

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