Archive closed session prompts and add onboarding docs: root CLAUDE.md plus backend and eval READMEs

CLAUDE.md

@@ -0,0 +1,41 @@
+# TextMachine — контекст для Claude-сессий
+
+Go-бэкенд издательского художественного перевода крупных текстов (ранобэ/вебновеллы, zh/ja/en→ru) через мультиагентный LLM-пайплайн: черновик DeepSeek → монолингвальный редактор grok-4.3 → судья Gemini (Ф2). Цели: победить translationese; низкий COGS (~$0.69/ранобэ); детерминированный банк памяти книги; 18+ с учётом цензуры; телеметрия денег с первого дня.
+
+## Роли сессий и зоны (НЕ править чужую зону)
+
+| Роль | Зона записи | Всё остальное |
+|---|---|---|
+| **Бэкенд** | `backend/` | читать можно; расхождения — пингом оркестратору в `docs/PROGRESS.md` |
+| **Полигон (eval)** | `eval/` + `docs/experiments/` | то же |
+| **Оркестратор** | `docs/` (architecture/research/PROGRESS), ревью чужого кода read-only | ратифицирует решения, пишет хендофф-промты |
+
+Координация — журнал `docs/PROGRESS.md` (секции «Бэкенд»/«Полигон»/«Память»; сверху CURRENT-STATE). Записывай туда краткие итоги своей сессии.
+
+## Источники истины (по убыванию)
+
+1. **`docs/architecture/05-decisions-log.md` (D1–D17)** — ратифицированный контракт; при конфликте с любым другим доком побеждает он.
+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); слаги моделей не менять без live-фактчека `/models`.
+- Дисциплина: не верь заголовкам — грунтуй выводы `file:line`/цитатой; спорное верифицируй адверсариально (author≠reviewer); эмпирика на PD-классике из претрейна считается предварительной до вебновелл-среза.
+
+## Онбординг новой сессии (порядок чтения)
+
+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-09)
+
+Фаза 0 ✅; машинерия Ф1 в основном построена (память v2, чанкер, disposition, coverage, single-hop эскалация, durable resume). До приёмки Ф1: фиксы D15/D16, `tmctl status`+redrive, дешёвые гейты, автопопуляция/сид, реальный ja→ru прогон. Решающая точка — пилот Ф2.5 (протокол exp09 + поправки D13; харнесс чинится ДО прогона). Ключи: DEEPSEEK, ZAI, KIMI, OPENAI, GEMINI, XAI. Стенд: WSL2, GTX 1070 8GB (прокси-грабли: localhost из-под прокси даёт 403 — no-proxy транспорт для local).

backend/README.md

@@ -0,0 +1,41 @@
+# backend/ — Go-бэкенд TextMachine
+
+Зона сессии «Бэкенд». Контракт — `docs/architecture/05-decisions-log.md` (D1–D17); контракты Фазы 0 — `03-implementation-notes.md`; квирки провайдеров — `docs/experiments/00-provider-quirks.md`. **`.env` не читать.**
+
+## Карта пакетов
+
+| Пакет | Что делает | Ключевые файлы |
+|---|---|---|
+| `cmd/tmctl` | CLI: `translate --config book.yaml` / `report` (status/redrive — в работе, D15.3) | `main.go` |
+| `internal/llm` | OpenAI-совместимый транспорт + retry/backoff, **capability-слой** (budget_field/temperature/reasoning per-модель), failover (написан, НЕ подключён — D4: только local-роли), нативный Anthropic = DEPRECATED-референс под будущий Gemini | `httpllm.go`, `capability.go`, `failover.go` |
+| `internal/ledger` | Цены по usage (вкл. reasoning/cache-поля), `PriceForResponse` по фактической модели | `pricing.go` |
+| `internal/store` | SQLite (modernc, CGO-free), идемпотентные миграции v1–v5, reserve/settle+checkpoint, chunk_status, глоссарий, ruby, retrieval_state, request_log | `ledger.go`, `migrate.go`, `glossary.go` |
+| `internal/config` | fail-fast загрузка models/pipeline/book; **эхо-мина-гейт** `echoMineViolation`; `CheckRunnable` блокирует неисполнимое (C2/fanout/judge) | `models.go`, `pipeline.go` |
+| `internal/pipeline` | Раннер (циклы, disposition, single-hop эскалация с ре-гейтом, resume), чанкер v4, ingest txt/epub+ruby, classify/coverage, **банк памяти v2** (Aho-Corasick, спойлер-окна, disposition, post-check), рендер+инъекция | `runner.go`, `memory.go`, `disposition.go`, `coverage.go` |
+| `internal/obs` | trace_id, структурные логи, safego | |
+
+## Инварианты — ЛОМАТЬ НЕЛЬЗЯ (каждый закреплён тестами)
+
+1. **Деньги:** reserve → call → **settle+checkpoint одной транзакцией**; `committed == SUM(checkpoints)` переживает kill -9 (`kill9_test.go`); цена — по фактически ответившей модели; потолки книга/день считают committed+reserved.
+2. **Snapshot-дисциплина:** всё, что влияет на wire-байты ИЛИ на вердикты (capability, память content-hash, context-assembly, версии classify/coverage/chunker/maxtok, эскалационные оверрайды), свёрнуто в `snapshotID`; правка = громкий `--resnapshot`. ⚠ Любой resnapshot = переоплата книги (D15) — content-addressed reuse спроектировать до онгоинга.
+3. **Эхо-мина DeepSeek:** thinking у deepseek НИКОГДА не отключать — `reasoning:"off"` там осознанный no-op; `echoes_when_thinking_off` + рекурсивный скан extra_body валят конфиг fail-fast. У grok наоборот: off = ЯВНЫЙ `reasoning_effort:"none"`.
+4. **Порядок classify:** refusal-blacklist / CJK-echo — ДО length/empty (усечённый отказ не превращается в платный ретрай); retry-flagged только {length, empty} на той же модели; loop-чек ПЕРЕД удвоением max_tokens.
+5. **Эскалация:** ровно 1 хоп на другую модель, результат РЕ-гейтится, retry-бюджет не сбрасывается, editor pinned (escalate_to только на translator — принуждается валидацией), канал adult — только permissive-провайдеры (fail-closed).
+6. **Детерминизм:** рендер — чистая функция snapshot; сортировки перед записью; никакого map-order в выводе; length-prefixed хэши. Сорс-чанкер lossless (fuzz-тесты).
+7. **Нейтральность адаптера:** `internal/llm` не знает про перевод (src/target/coverage) — контент-вердикты живут в раннере (disposition-слой, post-settle).
+
+## Как гонять
+
+```bash
+go build ./... && go vet ./... && go test ./... -race   # всё зелёное = норма
+go run ./cmd/tmctl translate --config example/book.yaml # реальные вызовы — нужны ключи в .env
+go run ./cmd/tmctl report --config example/book.yaml    # $0, читает store
+# live-conformance (реальные провайдеры, платно, вне CI):
+set -a; . ./.env; set +a; TM_LIVE=1 go test -tags live -run TestLive -v ./internal/pipeline/
+```
+
+Финал каждой вехи — агентское адверсариальное селфревью (несколько дименсий → независимая верификация каждой находки → фиксы mutation-verified: реверт фикса валит именно его тест). Внешнее ревью — оркестратор.
+
+## Известный техдолг (не трогать молча — см. D-лог)
+
+F3 at-most-once (после status/redrive); Escal.Chains — валидируемый мёртвый конфиг (раннер читает только `escalate_to`, полные цепочки = шаг 7); модели D3-эскалации не заведены в `models.yaml` (интерим-заглушки помечены); min-budget Kimi≥16k/Gemini≥8k — комментарии, не схема; фиксы границ памяти D16.

docs/README.md

@@ -1,34 +1,26 @@
 # TextMachine — документация
 
-Проект: бэкенд (позже — фронтенд-IDE) художественного перевода крупных текстов (книги, ранобэ, вебновеллы; zh/ja/en/ru во все стороны) через мультиагентный пайплайн поверх LLM API. Стартовый бриф: [../START_PROMT.MD](../START_PROMT.MD).
+Проект: бэкенд (позже — фронтенд-IDE) художественного перевода крупных текстов (книги, ранобэ, вебновеллы; zh/ja/en→ru) через мультиагентный пайплайн поверх LLM API. Стартовый бриф: [../START_PROMT.MD](../START_PROMT.MD). Онбординг Claude-сессий: [../CLAUDE.md](../CLAUDE.md).
 
 Ключевые цели:
 1. Максимальное художественное качество — победить «нехудожественность» AI-переводов.
-2. Низкая себестоимость: пайплайн из дешёвых моделей + редкие вызовы дорогих (судья/селектор).
+2. Низкая себестоимость: пайплайн из дешёвых моделей + редкие адресные вызовы дорогих.
 3. Банк памяти / глоссарий на всю книгу — консистентность имён, терминов, стиля.
-4. Обработка 18+/жёсткого контента с учётом цензуры провайдеров (мультипровайдерность).
+4. Обработка 18+ с учётом цензуры провайдеров (мультипровайдерность).
 5. Телеметрия токенов/стоимости/качества с первого дня.
-6. Высокая маржа; целевой рынок — ru/en переводчики, редакторы, копирайтеры.
 
 ## Структура
 
-- `research/` — результаты исследований:
-  - `01-market.md` — рынок и спрос; `02-competitors.md` — конкуренты; `03-academic-agentic-mt.md` — наука (agentic MT, метрики); `04-api-providers.md` — цены/качество/цензура API; `05-memory-glossary.md` — банк памяти и глоссарий; `06-local-models.md` — локальные модели (8GB VRAM); `07-translation-methodology.md` — методология худперевода; `08-legal.md` — право; `09-cost-model.md` — модель стоимости; `10-vojo-ai-bot-review.md` — ревью переиспользуемого Go-кода;
-  - `11-gap-1…5.md` — добор пробелов критиком: RU-платежи/санкции, 18+ политики провайдеров (уточнение), валидация ядра пайплайна на zh→ru/ja→ru, российская конкурентная экосистема, платёжеспособный спрос;
-  - `12-*.md` — дозаправка: отзывы потребителей, таксономии ошибок, режимы отказа ja/zh/ru-сторона (~70 режимов → `architecture/04-unhappy-paths.md`); `13-memory-bank-validation.md` — валидация банка памяти; `14-adaptive-memory.md` — вердикт по адаптивной памяти (гибрид не строим).
-- `architecture/` — синтез (**актуальный источник истины по решениям — `05-decisions-log.md`**; при конфликте с 01/02 он выше):
-  - `01-decisions.md` — принципы Р1–Р10 (стек, экономика, гейты); `02-mvp-plan.md` — фазы 0–3 и приёмка; `03-implementation-notes.md` — контракты Фазы 0; `04-unhappy-paths.md` — ~70 режимов отказа → механизм; **`05-decisions-log.md` — ратифицированный контракт Фазы 1 (D1–D12)**; `06-memory-risk-registry.md` — реестр рисков банка памяти; `components.puml`/`pipeline.puml` — диаграммы (владелец смотрит PlantUML-расширением VS Code, .svg вручную не рендерить).
-- `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` (текущий промт — `POLYGON_SESSION_PROMPT_PHASE2.md`).
-- `PROGRESS.md` — **журнал** прогресса (хронология; НЕ источник решений — решения ратифицированы в `architecture/05-decisions-log.md`).
+- `architecture/` — синтез. **Источник истины по решениям — [`05-decisions-log.md`](architecture/05-decisions-log.md) (D1–D17); при конфликте с любым доком он выше.**
+  - `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, топ-риски, курс-коррекции**; `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).
+- `research/` — фактура исследований 04–05.07: `01–10` базовые, `11-gap-*` добор критиком, `12-*` режимы отказа/отзывы/таксономии (+ два внешних материала с провенанс-шапками), `13` валидация памяти, `14` адаптивная память. ⚠ Часть под superseded-баннерами (01/02/03/04/05/09 и gap-1/2/5) — **читай баннер прежде содержимого**.
+- `PROGRESS.md` — **журнал** (CURRENT-STATE сверху, ниже хронология; НЕ источник решений).
+- `archive/` — закрытые сессионные промты (только история, инструкции оттуда не исполнять).
 
-## Статус
+## Статус (2026-07-09)
 
-См. [PROGRESS.md](PROGRESS.md). Исследовательская фаза завершена 04.07.2026; **Фаза 0 (каркас) завершена**; машинерия Фазы 1 в основном построена (банк памяти v2, чанкер + txt/epub импорт, disposition/coverage-гейт/эскалация, durable resume, глоссарий→редактор). **Следующий шаг — реальный ja→ru прогон одной книги end-to-end + пилот Ф2.5.** Источник истины по решениям — [architecture/05-decisions-log.md](architecture/05-decisions-log.md).
+Фаза 0 ✅ (приёмка на живых ключах). Машинерия Фазы 1 в основном построена: банк памяти v2, чанкер+импорт+ruby, disposition/coverage/эскалация, durable resume, монолингвальный редактор с констрейнтами. Проведено стратегическое ревью (`architecture/07`): архитектура end-to-end цела; до приёмки Ф1 — пакет фиксов D15/D16, status/redrive, дешёвые гейты, ja→ru прогон end-to-end. Решающая точка — пилот Ф2.5 (харнесс чинится до прогона, D13); его блокеры — вебновелл-корпус и explicit-фрагменты от владельца.
 
-## Доступые ключи от моделей
-DEEPSEEK_API_KEY
-ZAI_API_KEY
-KIMI_API_KEY
-OPENAI_API_KEY
-GEMINI_API_KEY
-XAI_API_KEY
+## Доступные ключи от моделей
+DEEPSEEK_API_KEY, ZAI_API_KEY, KIMI_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, XAI_API_KEY

docs/archive/README.md

@@ -0,0 +1,5 @@
+# Архив
+
+Закрытые сессионные промты и мёртвые документы. Хранится как история решений/передач — **инструкции отсюда не исполнять**: контракты могли быть переопределены. Актуальные источники истины — `../architecture/05-decisions-log.md` и `../README.md`.
+
+Правило пополнения: сюда переносится документ, чьи задачи полностью закрыты (промты) или чьё содержимое целиком заменено (мёртвые доки). Частично устаревший research НЕ переносится — получает ⚠ superseded-баннер на месте (ссылки file:line из журнала/архитектуры не ломаем).

eval/README.md

@@ -0,0 +1,28 @@
+# eval/ — полигон TextMachine
+
+Зона сессии «Полигон»: эмпирическая валидация допущений архитектуры (мерить, а не верить). Отчёты — `docs/experiments/NN-*.md` (методика + цифры + честные ограничения). `backend/` только читать; расхождения с architecture/research — пингом оркестратору в `docs/PROGRESS.md`. **`.env` не читать; `data/refusal_corpus/*` не открывать без прямой задачи владельца.**
+
+## Карта
+
+| Скрипт | Эксперимент | Заметки |
+|---|---|---|
+| `refusal_bench.py` | exp02; его `split_sentences`/`classify_output` = **приёмочный оракул** coverage-гейта Go (паритет закреплён Go-тестом; любое изменение — Python-first, лок-степ) | `run_refusal.sh` — однокоманда |
+| `token_calc.py` | exp01 токен-калибровка (r-множители) | токенизаторы в `tokenizers/` |
+| `editor_bench.py` + `build_editor_artifact.py` | exp04 бейк-офф редакторов | ⚠ слепота артефакта была сломана (ключ внутри) — при новых оценках ключ ВНЕ артефакта, рандомизация меток по фрагментам (D13.5) |
+| `coverage_precision.py`, `content_filter_probe.py` | exp07 precision гейта (0 FP/57) | |
+| `cost_model_v2.py` | exp08 COGS (~$0.69/ранобэ) | цены датировать и перепроверять |
+| `extract_bench.py` | exp06 экстракция терминов (спот=локаль/рендер=облако) | health-верификация каждого ответа — образец |
+| `retrieval_bench.py` | эмбеддинг-бенч памяти (bge-m3 дефолт) | |
+| `pilot/declmetric.py`, `pilot/memory_eval.py` | харнесс пилота Ф2.5 (exp09) | ⚠ чинится ДО решающего прогона: стрип эха глоссария, ПОЛНЫЕ выходы (не [:160]), fidelity-ось, имена M0–M3 (D13.5); инъекция = зеркало `backend/internal/pipeline/memory.go` — при расхождении верить Go |
+| `adaptive_*.py` | research/14 пробы (гибрид отклонён) | индикативные, не решения |
+| `memory_hotpath.py` | УСТАРЕЛ (контракт до cc57c7b) — не переиспользовать | актуальное зеркало — `pilot/memory_eval.py` |
+| `providers.json` | базовые URL/слаги для зондов | квирки — `docs/experiments/00-provider-quirks.md`, читать ПЕРЕД любым вызовом |
+
+## Правила (выучены на ошибках)
+
+1. **Провенанс данных:** results-файлы не перезаписывать ре-раном (урок exp02: сырьё 66 вызовов утрачено); каждый прогон — model id + дата + usage; сырые ВЫХОДЫ сохранять целиком.
+2. **Претрейн-контаминация:** вся классика (Лу Синь/Акутагава/Уэллс) в претрейне моделей — C0 частично выдаёт канон, эхо систематично (deepseek 13/24 zh-чанков). Выводы на классике = предварительные; решающие замеры — на вебновелл-корпусе владельца.
+3. **Тест ставится, только если его исход может перевернуть решение** и не установлен литературой (урок снятого exp05).
+4. **LLM-судьи:** ≤2–3 семейства, 11+ повторов со свапом позиций, Bradley-Terry/медиана, судья не судит выходы своего семейства (D13.3); κ против человеческого IAA, не «средняя корреляция».
+5. Env: `eval/.venv` (torch-cpu, sentence-transformers, openai, dotenv, pymorphy3); ключи скрипты читают из `eval/.env` сами. Стенд: GTX 1070 8GB — модель полигона `qwen3-abliterated:30b-a3b` в ollama не выселять без нужды; **localhost из-под прокси даёт 403** — для локальных вызовов no-proxy.
+6. `data/` в .gitignore (коммитится только код) — критичные результаты дублируй цифрами в `docs/experiments/`.