textmachine/CLAUDE.md

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

Go-бэкенд издательского художественного перевода крупных текстов (ранобэ/вебновеллы, zh/ja/en→ru) через мультиагентный LLM-пайплайн: черновик (интерим DeepSeek; переводчик выбирает exp13) → **БИЛИНГВАЛЬНЫЙ редактор (D30.1; кандидат glm-5)** → судья Gemini (Ф2). Цели: победить translationese; низкий COGS (~$0.85/ранобэ после флипа D1 — D30.4); детерминированный банк памяти книги; 18+ с учётом цензуры; телеметрия денег с первого дня.

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

| Роль | Зона записи | Всё остальное |
|---|---|---|
| **Бэкенд** | `backend/` | читать можно; расхождения — пингом оркестратору в `docs/PROGRESS.md` |
| **Полигон (eval)** | `eval/` + `docs/experiments/` | то же |
| **Оркестратор** | `docs/` (architecture/research/PROGRESS), ревью чужого кода read-only | ратифицирует решения, пишет хендофф-промты |

Координация — журнал `docs/PROGRESS.md` (секции «Бэкенд»/«Полигон»/«Память»/«Голос и состояние»/«Ридер-IDE»; сверху CURRENT-STATE). Записывай туда краткие итоги своей сессии. Закрытая хроника 04–10.07 вынесена в `docs/archive/PROGRESS-2026-07-04-10.md` (D31) — НЕ читать при онбординге, только по конкретной ссылке.

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

1. **`docs/architecture/05-decisions-log.md` (D1–D39.11)** — ратифицированный контракт; при конфликте с любым другим доком побеждает он; сверху файла — карта актуальности (что чем superseded).
2. `docs/architecture/07-strategic-review.md` — стратегический аудит 09.07 (вердикт, риски, курс-коррекции).
3. `docs/experiments/00-provider-quirks.md` — wire-квирки провайдеров (читать ПЕРЕД правкой адаптеров/вызовами провайдеров).
4. `docs/architecture/01-decisions.md` (Р1–Р10), `02-mvp-plan.md` (фазы v3), `04-unhappy-paths.md`, `06-memory-risk-registry.md`.
5. `docs/research/*` — фактура; часть под ⚠ superseded-баннерами — читай баннер прежде содержимого.
6. `docs/archive/` — закрытые промты, только история.

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

- **НИКОГДА не читать `.env`** (`backend/.env`, `eval/.env`) — там ключи. `.env.example` можно.
- **18+ уровень 3** (несовершеннолетние в сексуальном контексте) — не обрабатывать/не анализировать; `eval/data/refusal_corpus/*` не открывать без прямой задачи владельца.
- **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`. **Пробы/запросы падают или ведут себя странно (флейки, 404 живой модели, новый finish_reason, игнор параметров) → идём в официальную доку вендора (deprecations/changelog/status) и гуглим, НЕ гадаем** — интерпретацию аномалии без вендор-сверки в доки/промты не абсорбировать (решение владельца 10.07; правило двух направлений — `00-provider-quirks.md` шапка).
- Дисциплина: не верь заголовкам — грунтуй выводы `file:line`/цитатой; спорное верифицируй адверсариально (author≠reviewer); эмпирика на PD-классике из претрейна считается предварительной до вебновелл-среза.
- **Мандат самопроверки в промтах сессий (обязателен, решение владельца 12.07):** промты полигон-сессий — и вообще любых пишущих код / запросы к моделям — ДОЛЖНЫ явно требовать ревью ИСПОЛНЕНИЕМ: своего кода + сформированных запросов к моделям + полученных результатов. Полигон регулярно ошибается/багует, и это искажает эксперименты (D37: заявленные «0 ошибок» = 36 ошибок+биллинг, «13 катастроф» = ~5–6 при оверфлаге судьи; exp13 +10% бюджета). Бэкенд-промты — явный бэкенд-ревью после кода (обычно отрабатывает по опыту, но требовать явно). Пост-хок адверсариальная верификация оркестратора при лендинге — второй рубеж, НЕ замена самопроверки.
- **Git-координация мультисессий:** НИКАКИХ `reset --hard`, перезаписей истории (amend/rebase несвежих коммитов) и `checkout` поверх грязного дерева, пока возможны незакоммиченные правки параллельных сессий — сначала `git status` и опознание ЧУЖИХ изменений; чужое не трогать; history-rewrite — только по согласованию через оркестратора при чистом дереве (урок 09.07: rewrite оркестратора стёр незакоммиченные правки полигона).

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

1. Этот файл → `docs/README.md` (карта) → CURRENT-STATE в `docs/PROGRESS.md`.
2. `docs/architecture/05-decisions-log.md` целиком (контракт).
3. По роли: Бэкенд — `backend/README.md` + `03-implementation-notes.md`; Полигон — `eval/README.md` + `experiments/00` + `09-pilot-protocol.md`; всем — `07-strategic-review.md` §6–9 (вердикт/риски/курс).

## Текущее состояние (2026-07-19, пост-D39.16 — эра «стройка пере-прогонного стека»)

Фаза 0 ✅; **Ф1-инфра ✅** (D20–D28; golden = инвариант детерминизма, №8 README = экспорт-контракт). Арка «качество-первым» D26→D38.5 ЗАКРЫТА (хроника — `docs/archive/PROGRESS-2026-07-10-13.md`; потолок художественности — в организации пайплайна, не в моделях). **АРХ-РЕСЕТ D39:** синк-аудит «сломанного телефона» (65 находок/0 refuted — `08-sync-audit-ledger.md`) → **7-слойная целевая архитектура** (`09-target-architecture.md`; промпт-тема — `10`); **инвариант общности §0.1** — любая книга/пара/структура, пара = ось данных. **Исследовательская программа ЗАВЕРШЕНА (D39.1–D39.10):** research/19 (нарезка+когезия+волны W0–W3) + research/20 (банк-майнинг W1.5: детектор V-A/B/C, алиас-ярусы, banknote-v1, плагины P1–P6); exp15/Q4a/exp16 — несущее: сцен-детекцию/carryover/logical-границу НЕ строить, слабое звено = РЕДАКТОР → свап-арм (glm→mistral/deepseek-pro), банк W1.5 = детектор-код (WHICH recall 0.97) + банкнота (dst) + Палладий (имена) + подпись, фертильность 1.20·cjk+0.39·other. **План реализации РАТИФИЦИРОВАН (D39.12, `architecture/11-implementation-plan.md`)** — три рубежа верификации, 4 гейтнутых арма. **Стройка (пак-11, ЕДИНОЙ сессией по решению владельца, блоками):** Block A залендён (D39.13: чанкер output-бюджет + edit-единицы + src→dst-блок редактора [закрытие D30.1] + eager-clients + rate-guard + base/enriched split + банкнота-ядро); continuation залендён (D39.14: Go-майнер паритет-EXACT + банкнота 12-точек + DC-чекеры + `export --pairs` + арм-конфиги + волновой снапшот-аддитив; рубеж-2-долг погашен, clean bill). **Арх-проход залендён (D39.16, директива владельца): язык-данные майнера вынесены из `pipeline/`-констант в `internal/lang`+`configs/langpacks/` (граница компиль-enforced, байт-точно — парити EXACT, golden байт-идентичен); `x/text/language.Tag` ОТВЕРГНУТ (CLDR-инстабильность в вердиктах — держим точные предикаты `isRuTarget`); DC-чекеры/снапшот-фолд DEFER (майнер offline/нейтральность).** **Осталось: R1 драйвер-свитч** (волновой исполнитель W1/W1.5/W2 + структурный golden-рерайт + фолд `pack.Version()`/загрузка langpack при wiring майнера живым) → приёмка → единый resnapshot (D30.9) → пере-прогон 3–10 глав → чтение владельца (планка 2 претензии). Стек не менялся с D38.5 (draft flash thinking-ON → editor glm-5 БИЛИНГВ v3 → судья gemini-preview; ~$0.85/ранобэ D30.4). **Висит на владельце:** тачпойнты exp16 (пол/алиасы/precision@30) · W1.5-UX · политика стиха DC5 · ja→ru-реплика (тест общности §B5, DEFER-чекеры едут туда) · **ре-чек прайса DeepSeek у катовера слагов 24.07** (до него платных deepseek-прогонов нет) · старые висящие (пилот Ф2.5: билингв-якорь D25.9-Q1, корпус, судья-дублёр D22.6). Ключ xAI: единый, data-sharing, off перед продом (D27). Книга на стенде `/home/ubuntu/books/gu-zhenren/` (GB18030; текст и производные ВНЕ git). Ключи: DEEPSEEK, ZAI, KIMI, OPENAI, GEMINI, XAI, MISTRAL. Стенд: WSL2, GTX 1070 8GB (localhost из-под прокси = 403 — no-proxy транспорт для local).