textmachine/CLAUDE.md

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

Go-бэкенд издательского художественного перевода крупных текстов (ранобэ/вебновеллы, zh/ja/en→ru) через мультиагентный LLM-пайплайн: черновик deepseek-v4-flash → **БИЛИНГВАЛЬНЫЙ редактор deepseek-v4-pro ИНТЕРИМ (D30.1/D39.22; 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). Записывай туда краткие итоги своей сессии. Закрытые хроники вынесены в `docs/archive/PROGRESS-*.md` (три слайса: 04–10 · 10–13 · 13–25.07) — НЕ читать при онбординге, только по конкретной ссылке.

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

1. **`docs/architecture/05-decisions-log.md` (D1–D39.53)** — ратифицированный контракт; при конфликте с любым другим доком побеждает он; сверху файла — карта актуальности (что чем 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` (промпт-тема).
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` можно.
- **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-классике из претрейна считается предварительной до вебновелл-среза.
- **Общность движка (владелец 24.07):** Go-логика НЕ ветвится по паре/книге; пара-данные → `internal/lang`+`configs/langpacks/`, книго-каноны → сид/brief (данные); книжный термин в общем пар-слое = утечка. Тест-данные пары легитимны. Норматив (только больные места): `docs/architecture/12-go-style-notes.md`. Ревью-вопрос по умолчанию: «заработает ли на паре, которой в репо ещё НЕТ, без правки Go?»
- **Мандат самопроверки в промтах сессий (обязателен, решение владельца 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`: карта актуальности (шапка) + живая голова (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`; всем — шапка-таблица `09-target-architecture.md` (статус слоёв).

## Текущее состояние (2026-07-26, пак-20 закрыт целиком, голова D39.53)

- **Фазы:** Ф0 ✅ · Ф1-инфра ✅ · арх-ресет D39 исполнен целиком (7 слоёв, паки 11–16) · мини-прогон принят (D39.37, $0.23, операционка до цента) · **пак-20 «банк» ЗАКРЫТ ЦЕЛИКОМ (D39.41–53): ТЕРМИНОЛОГ (роль пар-пака: переводит смердженный банк по KWIC-контекстам, durable-деньги) · флаговый стоп `--verify-bank` (дефолт = авто-продолжение) · ДВУХСЕКЦИОННАЯ редакторская инъекция (закон CONFIRMED + помеченная секция ⟨проверить⟩; ВСЕ строки банка фолдятся в версию) · точечная ре-редактура по ключу (bank-only-сдвиг → пере-пин $0) · банкнота отдельным шиппинг-файлом · языковой экран `gates.terminology.target_script` · дисциплина банкноты (кавычки в свёртке, агрегация из чекпойнтов по чанкам)**. Жанровый словарь ОТМЕНЁН КАК КЛАСС (D39.47: решение о переводе = подпись владельца на банк КНИГИ). Петля ремонта построена и НЕ включается (D39.38; «остаток=0» = ноль в охвате узких детекторов, D39.39).
- **Полигон:** пакеты 6/7/8 закрыты (D39.39/43–46/50/52): размеченный набор чекеров = постоянный измерительный стенд · рубрика K1–K12 ратифицирована · «контексты — главный рычаг терминолога» измерено · расширение эмиссии майнера закрыто ОТРИЦАТЕЛЬНО · частотного экрана для банкноты не существует · слепой судья годен только как катастроф-экран с декоем.
- **Очередь (D39.40/51/53):** пак-19 «голос/состояние» (промт актуализирован 26.07) → **ХОЛОДНЫЙ мини-прогон** (пустой сид, отдельная БД; закрывает ~десять вопросов за ≤$0.23, вкл. холодный старт банкноты, фикс не-CJK парсера, allow_short, судью-решение) → пак-21 «чекеры» (вход: 12 дефектов D39.39 + утечка алфавита) → свип гипотез → добор идеала → МАСШТАБ → пилот Ф2.5.
- **Стек:** draft deepseek-v4-flash thinking-ON (+банкнота) → терминолог (та же дешёвая модель, батчи) → editor deepseek-v4-pro БИЛИНГВ ИНТЕРИМ (glm-5 резерв) → судья gemini-preview + grok-фолбэк 18+ (Ф2, только полигон). ~$0.85/ранобэ держится (D30.4); терминолог — центы на выборках, ≈$1.10 полный банк.
- **Висит на владельце + открытые петли:** ЕДИНЫЙ БЭКЛОГ — таблица в `docs/PROGRESS.md` (единственное место).
- **Стенд:** WSL2, GTX 1070 8GB (localhost из-под прокси = 403 — no-proxy транспорт для local). Книга `/home/ubuntu/books/gu-zhenren/` (GB18030; текст и производные ВНЕ git).