textmachine/CLAUDE.md

# TextMachine — контекст для Claude-сессий

Go-бэкенд издательского художественного перевода крупных текстов (ранобэ/вебновеллы, zh/ja/en→ru) через мультиагентный LLM-пайплайн: дешёвый черновик → редактор → детерминированные $0-гейты → судья (Ф2).

## Цели и мерило (канон владельца, 02.08 — каждое решение сверяется с этим)

1. **Продукт:** издательское художественное качество перевода больших текстов — победить translationese; консистентные термины/голоса на всю книгу; чувствительный контент с учётом цензуры провайдеров.
2. **Мультиязычность:** движок ОДИН и общий; языко-/пара-/книго-специфика легитимна, но живёт в ДАННЫХ и отдельных модулях, встраиваемых архитектурно чисто (langpacks · пар-промпты · сид/бриф), и разрабатывается отдельно от ядра. Ревью-вопрос по умолчанию: «заработает ли пара, которой в репо ещё НЕТ, без правки Go?»
3. **Чистая архитектура:** бэкенд легко писать и поддерживать; механизм строится только там, где несёт качество/деньги — не ради галочки трекера.
4. **Современные подходы и харнесс-превосходство:** пайплайн и транспорт на уровне или впереди конкурентных харнесс-решений (калибровка — research/21–22); эмпирика решает — мерить, не верить.
5. **Экономика:** низкий COGS на дешёвых моделях с адресными дорогими вызовами; деньги видимы с первого вызова (телеметрия · потолки · явное согласие на пере-оплату).
6. **Детерминизм:** воспроизводимый прогон (снапшоты · банк памяти · golden) — повторение без сюрпризов и тихих перепокупок.

## Роли сессий и зоны (НЕ править чужую зону)

| Роль | Зона записи | Коммитит сама? | Всё остальное |
|---|---|---|---|
| **Бэкенд** | `backend/` | нет — лендит оркестратор | читать можно; расхождения — пингом оркестратору в `docs/PROGRESS.md` |
| **Полигон (eval)** | `eval/` + `docs/experiments/` | только пре-рег фризы | то же |
| **Оркестратор** | `docs/` (architecture/research/PROGRESS) + корневые онбординг-доки, ревью чужого кода read-only | да | ратифицирует решения, пишет хендофф-промты |
| **Фронт** | `frontend/` | нет — лендит оркестратор | читать можно; пинги, итоги и вопросы — ЗОННЫЙ журнал `frontend/docs/frontend-PROGRESS.md` (решение владельца 02.08/04.08; в `docs/PROGRESS.md` фронт НЕ пишет), туда же пишет и оркестратор; продуктовые требования — `docs/product-requirements.md`, НЕ из памяти |
| **Платформа** | `platform/` (SaaS control plane: пользователи/квоты/очередь/HTTP; движок дёргает процессами, D39.81) | нет — лендит оркестратор | читать можно; пинги и итоги — ЗОННЫЙ журнал `platform/docs/platform-PROGRESS.md` (решение владельца 04.08), в `docs/PROGRESS.md` не пишет |

Координация — журнал `docs/PROGRESS.md` (секции «Бэкенд»/«Полигон»/«Память»/«Голос и состояние»/«Ридер-IDE»; сверху CURRENT-STATE). Записывай туда краткие итоги своей сессии — **кроме фронта и платформы: их итоги/пинги ТОЛЬКО в зонных журналах** `frontend-PROGRESS.md`/`platform-PROGRESS.md` (решение владельца 04.08, D39.100). Закрытые хроники вынесены в слайсы `docs/archive/PROGRESS-*.md` — НЕ читать при онбординге, только по конкретной ссылке. Параллельные сессии — норма: чужие незакоммиченные файлы в дереве не трогать; сессия считается ЖИВОЙ, пока владелец не сказал обратное.

## Источники истины (по убыванию)

1. **`docs/architecture/05-decisions-log.md`** — ратифицированный контракт; при конфликте с любым другим доком побеждает он; сверху файла — карта актуальности (что чем superseded), свежая голова — С ХВОСТА файла. **Правило чтения (онбординг-диета 25.07): карта + живая голова (эра D39.x); корпус D1–D38 = справочник — по ссылкам/grep по D-номеру, целиком НЕ читать.**
2. `docs/experiments/00-provider-quirks.md` — wire-квирки провайдеров (читать ПЕРЕД правкой адаптеров/вызовами провайдеров).
3. `docs/architecture/09-target-architecture.md` (7 слоёв; статус стройки — шапка-таблица) · `12-go-style-notes.md` (норматив общности §0) · `10-prompt-architecture.md` (промпт-тема) · `14-api-contract/` — **ратифицированный контракт API v0 фронт↔платформа** (OpenAPI 3.1 + компаньон, D39.99).
3а. `docs/product-requirements.md` — реестр «что продукт обязан уметь» (производный от ЖИВОГО брифа владельца `START_PROMT.MD` V0–V5 + находок H6–H18; статусы сверены кодом, актуализирует оркестратор при лендингах). Новые V-идеи владельца разбираются сюда, не остаются невидимыми.
4. `docs/architecture/01-decisions.md` (Р1–Р10), `02-mvp-plan.md`, `04-unhappy-paths.md`, `06-memory-risk-registry.md` — тела исторические, читать через ⚠-баннеры 25.07.
5. `docs/research/*` — фактура; часть под ⚠ superseded/построено-баннерами — читай баннер прежде содержимого.
6. `docs/archive/` — история: закрытые промты (`prompts/`) · отчёты паков с ревью-шапками (`reports/`) · исполненные арх-доки (`architecture/`: 07 стратревью · 08 синк-ледджер · 11 план пака-11).

## Гардрейлы (жёсткие)

- **НИКОГДА не читать `.env`** (`backend/.env`, `eval/.env`) — там ключи. `.env.example` можно.
- **PUML не рендерить в svg/png** — владелец смотрит PlantUML-расширением VS Code.
- **Коммиты**: английский, одно предложение ≤30 слов, без Co-Authored-By. `.claude/settings.local.json` НЕ коммитить (ломает пермишены).
- Провайдерские ловушки: **DeepSeek — НИКОГДА не отключать thinking** (эхо-мина; гейт `echoMineViolation` это принуждает); grok-4.3 reasoning off — только ЯВНЫЙ `reasoning_effort:"none"` (дефолт low; wire-квирк в силе, но из РЕДАКТОРСКИХ ролей reasoning-off снят — no-op, D30.1); слаги моделей не менять без live-фактчека `/models`; ⚠ «слаг живой» ≠ «модель та же» — DeepSeek 31.07 сменил веса под слагом (D39.61), при аномалиях сверять поведение и вендор-лог обновлений. **Пробы/запросы падают или ведут себя странно (флейки, 404 живой модели, новый finish_reason, игнор параметров) → идём в официальную доку вендора (deprecations/changelog/status) и гуглим, НЕ гадаем** — интерпретацию аномалии без вендор-сверки в доки/промты не абсорбировать (решение владельца 10.07; правило двух направлений — `00-provider-quirks.md` шапка).
- Дисциплина: не верь заголовкам — грунтуй выводы `file:line`/цитатой; спорное верифицируй адверсариально (author≠reviewer); эмпирика на PD-классике из претрейна считается предварительной до вебновелл-среза.
- **Общность движка (владелец 24.07):** Go-логика НЕ ветвится по паре/книге; пара-данные → `internal/lang`+`configs/langpacks/`, книго-каноны → сид/brief (данные); книжный термин в общем пар-слое = утечка. Тест-данные пары легитимны. Норматив (только больные места): `docs/architecture/12-go-style-notes.md`. Ревью-вопрос по умолчанию: «заработает ли на паре, которой в репо ещё НЕТ, без правки Go?»
- **При компакции/сжатии контекста ВСЕГДА сохранять:** список изменённых файлов · незакрытые находки ревью и их диспозиции · обязательства и открытые вопросы сессии · команды тестов (D39.121).
- **Тесты и гейты не подгонять под зелень:** править или удалять тест/голден/гейт, чтобы он прошёл, — НЕДОПУСТИМО; несогласие с тестом — вопрос оркестратору пингом, не правка (D39.121).
- **Мандат самопроверки в промтах сессий (обязателен, решение владельца 12.07):** промты полигон-сессий — и вообще любых пишущих код / запросы к моделям — ДОЛЖНЫ явно требовать ревью ИСПОЛНЕНИЕМ: своего кода + сформированных запросов к моделям + полученных результатов. Полигон регулярно ошибается/багует, и это искажает эксперименты (D37: заявленные «0 ошибок» = 36 ошибок+биллинг, «13 катастроф» = ~5–6 при оверфлаге судьи; exp13 +10% бюджета). Бэкенд-промты — явный бэкенд-ревью после кода (обычно отрабатывает по опыту, но требовать явно). Пост-хок адверсариальная верификация оркестратора при лендинге — второй рубеж, НЕ замена самопроверки.
- **Git-координация мультисессий:**
  - **Коммитит только оркестратор.** Сессии зон — бэкенд, полигон, фронт, платформа — не коммитят: своё дерево готовят и передают на лендинг (исключение прежнее: пре-рег фризы полигона). Чужую зону не трогает НИКТО.
  - **Форма коммита — ТОЛЬКО с явным списком путей: `git commit -- <путь> <путь>`.** Причина механическая и это корень обоих инцидентов 02.08: голый `git commit` уносит **ВЕСЬ индекс**, включая чужие застейдженные файлы, и чужая работа уезжает под твоим сообщением. Pathspec-форма индекс не трогает.
  - **НИКОГДА `git add -A` / `git add .` / `git commit -a`** — только явные пути.
  - **Перед каждым коммитом:** `git status` (опознать ЧУЖОЕ) и `git diff --cached --name-only`. Увидел в индексе путь вне своей зоны — **не коммить его и не «прибирать»**: снимай не чужое из индекса, а свою задачу — коммить pathspec-формой.
  - **Не оставляй свои файлы застейдженными** между операциями: пока они в индексе, их может унести чужой коммит (этим оркестратор №10 сам подставился дважды). Стейдж и коммит — одной командой.
  - **НИКАКИХ `reset --hard`, перезаписей истории (amend/rebase несвежих коммитов) и `checkout` поверх грязного дерева**, пока возможны незакоммиченные правки параллельных сессий; history-rewrite — только по согласованию через оркестратора при чистом дереве (урок 09.07: rewrite оркестратора стёр незакоммиченные правки полигона).
  - **Чужое уже уехало в твой коммит?** Историю НЕ переписывать — сообщить владельцу/оркестратору; содержимое при этом цело, теряется только атрибуция.
  - Никогда не коммитить: `START_PROMT.MD` (файл владельца) · `.claude/settings.local.json` · книгу и производные (живут в `~/books`, вне git).

## Онбординг новой сессии (порядок чтения)

**⚠ Всю документацию и код проекта пишут нейросети — они могут ошибаться; учитывай при чтении.**

1. Этот файл → `docs/README.md` (карта) → CURRENT-STATE в `docs/PROGRESS.md`. Непонятный жаргон/сокращения — `docs/glossary.md`.
2. `docs/architecture/05-decisions-log.md`: карта актуальности (шапка) + живая голова (D39.x). Целиком НЕ читать — корпус D1–D38 по ссылкам/grep по мере надобности.
3. По роли: Бэкенд — `backend/README.md` + `03-implementation-notes.md` (через баннер) + `12-go-style-notes.md`; Полигон — `eval/README.md` + `experiments/00` + `09-pilot-protocol.md`; Фронт/продукт — `docs/product-requirements.md` + `research/16` (через ревью-шапку) + контракт `architecture/14-api-contract/`; Платформа — `platform/README.md` + зонный журнал + `research/23` + контракт 14; всем — шапка-таблица `09-target-architecture.md` (статус слоёв).