textmachine/docs/README.md

# TextMachine — документация

Проект: бэкенд (позже — фронтенд-IDE) художественного перевода крупных текстов (книги, ранобэ, вебновеллы; zh/ja/en→ru) через мультиагентный пайплайн поверх LLM API. Стартовый бриф: [../START_PROMT.MD](../START_PROMT.MD). Онбординг Claude-сессий: [../CLAUDE.md](../CLAUDE.md).

Ключевые цели:
1. Максимальное художественное качество — победить «нехудожественность» AI-переводов.
2. Низкая себестоимость: пайплайн из дешёвых моделей + редкие адресные вызовы дорогих.
3. Банк памяти / глоссарий на всю книгу — консистентность имён, терминов, стиля.
4. Обработка 18+ с учётом цензуры провайдеров (мультипровайдерность).
5. Телеметрия токенов/стоимости/качества с первого дня.

## Структура

- `architecture/` — синтез. **Источник истины по решениям — [`05-decisions-log.md`](architecture/05-decisions-log.md) (D1–D39.16); при конфликте с любым доком он выше.**
  - `01-decisions.md` — принципы Р1–Р10; `02-mvp-plan.md` — фазы и приёмка (v3, 09.07); `03-implementation-notes.md` — контракты Фазы 0; `04-unhappy-paths.md` — ~70 режимов отказа → механизм; `06-memory-risk-registry.md` — реестр рисков банка памяти; **[`07-strategic-review.md`](architecture/07-strategic-review.md) — стратегический аудит (09.07): вердикт end-to-end, топ-риски, курс-коррекции**; **[`08-sync-audit-ledger.md`](architecture/08-sync-audit-ledger.md) — верифицированный ледджер синк-аудита «сломанного телефона» (65 находок, D39)** · **[`09-target-architecture.md`](architecture/09-target-architecture.md) — целевая 7-слойная архитектура + фазовый план арх-ресета (D39; инвариант общности §0.1)** · [`10-prompt-architecture.md`](architecture/10-prompt-architecture.md) — консолидированная промпт-заметка (концерн 4); **[`11-implementation-plan.md`](architecture/11-implementation-plan.md) — РАТИФИЦИРОВАННЫЙ план стройки пере-прогонного стека (D39.12; дизайн-оф-рекорд бэкенд-пака, три рубежа верификации)**; `components.puml`/`pipeline.puml` — диаграммы v3 (владелец смотрит PlantUML-расширением VS Code; вручную НЕ рендерить).
- `experiments/` — эмпирика «Полигона»: `00-provider-quirks` (читать перед любым вызовом провайдера), `01-token-calibration`, `02-refusal-benchmark`, `03-local-stand`, `04-editor-quality`, `06-local-extraction`, `07-coverage-precision`, `08-cost-model-v2` (актуальная денежная модель), `09-pilot-protocol` (пилот Ф2.5 + поправки D13), `10-explicit-benchmark` (18+ violence-рука канала B), `11-erotica-benchmark` (erotica по трём парам/регистрам — закрытие D14.4, D22).
- `research/` — фактура исследований 04–05.07: `01–10` базовые, `11-gap-*` добор критиком, `12-*` режимы отказа/отзывы/таксономии (+ два внешних материала с провенанс-шапками), `13` валидация памяти, `14` адаптивная память, `15` голос и состояние (принят, D21), **`16` ридер-IDE (принят с ревью-шапкой, D29)**, **`17` внешняя критика GPT-5.6 (принят с ревью-шапкой, D25)** — у 16/17 читать шапку прежде тела. **`18` рычаги качества (два отчёта, D36)** · **`19` нарезка+когезия+контракт t/e (D39.1)** · **`20` банк-майнинг W1.5 (D39.6)** · **`21` обзор LLM-транспорта чужих харнессов (23.07: наш транспорт опережает/вровень со всеми 11; рекомендации DEFER до после пере-прогона, Q7-квирки — кандидаты до вендор-сверки)** — у всех ревью-шапки. ⚠ Часть под superseded-баннерами (01/02/03/04/05/09 и gap-1/2/5) — **читай баннер прежде содержимого**.
- `PROGRESS.md` — **журнал** (CURRENT-STATE сверху, ниже хронология; НЕ источник решений).
- **Активные хендофф-промты (пост-D39.21, 23.07):** [`BACKEND_TRANSPORT_PACK_SESSION_PROMPT.md`](BACKEND_TRANSPORT_PACK_SESSION_PROMPT.md) (пак-12 «транспорт-гигиена»: 10 wire-нейтральных пунктов; гейт открыт; **лендится ПЕРВЫМ**) · [`BACKEND_PACK13_QA_SESSION_PROMPT.md`](BACKEND_PACK13_QA_SESSION_PROMPT.md) (пак-13 «выпускной QA» по D39.20/21: 7 пунктов, wire-двигающий; приёмка на дефект-корпусе rerun2) · [`ORCHESTRATOR_SESSION_PROMPT.md`](ORCHESTRATOR_SESSION_PROMPT.md) (хендофф №5) · [`POLYGON_PACKAGE4_SESSION_PROMPT.md`](POLYGON_PACKAGE4_SESSION_PROMPT.md) (residual пилот/18+/echo). **ПЕРЕ-ПРОГОН ИСПОЛНЕН И ПРОЧИТАН (D39.20).** Закрытые — в `archive/prompts/` (свежие: пере-прогон→D39.20, research/21→23.07, преп→D39.19).
- `archive/` — закрытые сессионные промты (только история, инструкции оттуда не исполнять).

## Статус (2026-07-23, пост-D39.20 — механизация выпускного качества)

Фаза 0 ✅; Ф1-инфра ✅ (D20–D28). **АРХ-РЕСЕТ D39 ИСПОЛНЕН ЦЕЛИКОМ:** 7-слойная архитектура (`09-*`) → исследовательская программа (D39.1–D39.10) → план (D39.12, `11-*`) → стройка пака-11 (D39.13–D39.19: волновой исполнитель · чанкер output-бюджет · src→dst-редактор · Go-майнер паритет-EXACT · банкнота · `internal/lang`+langpacks · reject-set · echo-сплит). **ПЕРЕ-ПРОГОН rerun2 ИСПОЛНЕН И ПРОЧИТАН (D39.20, 23.07):** операционка вся подтверждена живьём (ОДИН resnapshot · **$0-резюм драфта ×3 арма** · echo 0 · $6.63<$15 · майнинг-стоп→подпись→reject-set); **планка ≤2 НЕ пройдена** — но дефект-классы полностью механизируемы. Три сигнала (судья dspro 0.679>glm 0.589>>mistral 0.232, floor-шум 0 · два слепых чтения): **анти-корреляция гладкость↔верность доказана трижды**; **mistral исключён как несущий редактор** (голос = north-star промпта); dspro-vs-glm → итерация №2 после механизации (драфт $0). research/21: транспорт наш опережает/вровень со всеми 11, рефакторинг отвергнут. **Эксп ЗАКРЫТ (D39.22), итерация №2 отложена; редактор = deepseek-v4-pro ИНТЕРИМ (glm-резерв); стайл-каноны D39.21 ратифицированы.** **Очередь (курс — разработка бэкенда):** пак-12 транспорт-гигиена (лендится первым) → пак-13 «выпускной QA» (wire-двигающий; вкл. дефолт-редактор dspro) → сид-дельта (元/赤城/学堂家老/春秋蝉) → масштаб целой книги + канал B вживую + Ф2-механизмы (D21 голос/состояние, native-Gemini судья) + ja→ru §B5 → пилот Ф2.5 (блокеры прежние: билингв-якорь D25.9-Q1, корпус, судья-дублёр D22.6). Судья 18+ = grok-фолбэк (квирк D22.6 подтверждён живьём). Ключ xAI: единый, data-sharing, off перед продом (D27).

## Доступные ключи от моделей
DEEPSEEK_API_KEY, ZAI_API_KEY, KIMI_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, XAI_API_KEY, MISTRAL_API_KEY