textmachine/docs

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

Проект: издательский художественный перевод крупных текстов (книги, ранобэ, вебновеллы) мультиагентным пайплайном поверх LLM API; пара языков — данные, не код, сегодня боевая zh→ru. Go-бэкенд + веб-фронт ридер-IDE (Ф3) + платформа (SaaS control plane, platform/, D39.81). Цели и мерило — канон в ../CLAUDE.md; онбординг сессий — там же. Стартовый бриф владельца: ../START_PROMT.MD — живой документ, его V-идеи разобраны в реестр требований (ниже).

Состояние проекта НЕ здесь — кроме таблицы активных промтов ниже, и это осознанное исключение: она отвечает на вопрос «какой файл мой», без которого холодная сессия выбирает роль сама (проверено слепым замером входа). Всё остальное состояние — Очередь, курс, бэклог — CURRENT-STATE в шапке PROGRESS.md; решения — architecture/05-decisions-log.md (при конфликте с любым доком побеждает он). Эта страница — только карта «что где лежит».

Карта

• glossary.md — жаргон и сокращения (D-номер, паки, банк, голден, K/DC/H/L…) одним экраном.

• product-requirements.md — реестр «что продукт обязан уметь»: производное живого брифа владельца и его находок, статусы сверены кодом.

• architecture/ — синтез и контракты:

  • 05-decisions-log.md — источник истины по решениям: ратифицированный контракт, при конфликте побеждает он. Дисциплина чтения (грепать номер, не читать целиком, баннер прежде тела) — в каноне ../CLAUDE.md, здесь не дублируется. Статус и тело ЛЮБОГО номера одним хопом — реестр 05-decisions-index.md (все ноты, колонка тем для грепа «какой закон по X»).
  • 09-target-architecture.md — целевая 7-слойная архитектура (статус стройки — шапка-таблица; §3 — карта находок H/L) · 10-prompt-architecture.md — промпт-слой · 12-go-style-notes.md — норматив общности §0 · 13-tech-debt-anchors.md — якоря техдолга + археология выселенных строк бэклога §Б-* (справочник к бэклогу, НЕ трекер) · 14-api-contract/ — контракт API v0 фронт↔платформа (D39.99): нормативная спека OpenAPI 3.1 (типы фронта генерятся из неё) + компаньон-README с провенансом каждой строки (легенда — в нём самом; зонная копия frontend/docs/api-contract/ — байт-зеркало, сверять при лендинге).
  • Топикальные входы (D39.126; НЕ источники истины, при конфликте побеждает D-лог): 15-money-path.md — деньги от гранта до settle одним маршрутом · 16-events-emitter.md — сборка-норматив эмиттера шва — обязательное пре-чтение перед кодом эмиттера · 17-seam-inbound-law.md — закон ВХОДНОЙ двери шва движок↔платформа — РАТИФИЦИРОВАН D39.156: семь пунктов дисциплины, двери встают паками без нового решения владельца · 18-bank-ontology.md — онтология банка памяти (РАТИФИЦИРОВАНА D39.158): три роли носителей, единственные писатели, дисциплина проекции — обязательное пре-чтение перед кодом, трогающим банк или его артефакты · STACK.md — карта «роль → модель → конфиг → квирки».
  • Исторические, читать через ⚠-баннеры: 01-decisions.md (Р1–Р10) · 02-mvp-plan.md · 03-implementation-notes.md · 04-unhappy-paths.md · 06-memory-risk-registry.md.

• experiments/ — эмпирика полигона: 00-provider-quirks.md — читать перед любым вызовом провайдера; 08-cost-model-v2.md — денежная модель; 09-pilot-protocol.md — пилот Ф2.5; остальные — отчёты экспериментов. ⚠ У каждого отчёта статус в его ревью-шапке: читай шапку прежде тела — она первична и говорит, ратифицированы выводы или заморожены.

• research/ — фактура ресёрчей; у принятых — ревью-шапки, часть тел под ⚠ superseded: читай баннер прежде содержимого. Ключевые для навигации: 15 голос · 16 ридер-IDE · 17 внешняя критика · 18 рычаги качества · 19 нарезка · 20 банк-майнинг · 21 обзор транспорта · 22 доменные харнессы · 23 шов движок↔платформа · 25 холодное ревью шва — читать перед любым кодом стыка · 24 арбитраж банка · 26 официальные практики Anthropic · 28 контракт-ревью API v0 — носитель для исполняющих сессий, читать оригинал, не пересказ.

• PROGRESS.md — журнал: CURRENT-STATE + ЕДИНЫЙ БЭКЛОГ (единственный трекер) + живой хвост хроники. НЕ источник решений.

• Тулчейн на чистой машине. Версии не здесь — их носители: backend/Makefile и platform/Makefile (GO_MIN_VERSION, GOLANGCI_VERSION), frontend/package.json (engines), platform/docs/STACK_DECISIONS.md §«Postgres на стенде без root», eval/requirements.txt + eval/.python-version. Здесь только то, чего нет нигде: ставим в ~/.local/opt/<инструмент> с симлинком в ~/.local/bin (он уже в PATH), берём последний патч пинованного минора, а не следующий минор — линтер пинован точным равенством и разъедется. Root требуют ровно два пакета: build-essential (без C-компилятора нет -race, а снять -race значит выдать отсутствие тулчейна за зелёный прогон — см. комментарий над целью test в backend/Makefile) и python3-venv (в системном питоне нет ensurepip, и установка полигона по eval/README.md обрывается на первом шаге).

• scripts/counts.py — производные числа доков считаются им, а не руками (голова по трём носителям · счёт очереди и зон · вес открытых строк регистра платформы · полнота реестра нот); --check даёт ненулевой код на расхождении; --lint — линтер file:line-якорей живых доков (D39.126). Его же зовёт зонный хук scripts/githooks/pre-commit: --lint якорей — при коммите, задевающем ЛЮБОЙ док или CLAUDE.md; --check чисел и головы — при коммите с D-логом или PROGRESS (оба --from-index, предупреждает, не блокирует). ⚠ Гейт бутстрапится ЧУЖОЙ зоной — это ДЕФЕКТ, а не порядок работы (строка бэклога 220): судит он CLAUDE.md и доки трёх зон, а в .git/hooks/ его кладёт единственный установщик frontend/scripts/githooks/install.mjs, то есть побочный эффект npm install в зоне, которая ЗАМОРОЖЕНА. На свежем клоне .git/hooks/ пуст и гейт молчит, не проверив ничего. Пока строка открыта, бутстрап делается руками (node frontend/scripts/githooks/install.mjs) — и это ВРЕМЕННАЯ мера, которую строка 220 закрывает, а не способ жить дальше. ⚠ Шапка систематически отстаёт от хвоста у ЛЮБОГО автора — потому проверка механическая, а не «посмотрю внимательно».

• Активные хендофф-промты — какой файл ТВОЙ (состав обновляется при каждом лендинге, D39.80; здесь — только то, что отвечает на вопрос «какой файл мой»; хроника, причины и статусы РАБОТ — CURRENT-STATE и D-лог):

  Роль	Активный промт	Статус
  Оркестратор	ORCHESTRATOR_SESSION_PROMPT.md	роль и нормы; счётчик роли — CURRENT-STATE
  Бэкенд	активного НЕТ	пак «тихая порча» ОТРАБОТАН, ПРИНЯТ и ЗАЛЕНДЖЕН 28.08 (D39.164): инъекция банка больше не теряется на провайдере с одним системным слотом, дыра выдачи видна читателю В ТЕКСТЕ, повтор принятого документа сходится. Промт — в archive/prompts/. ⚠ Заказ §3.2 был ПЕРЕ-ФОРМУЛИРОВАН находкой исполнителя (маркер существовал и врал), а подсказка промта про место правки ОТКЛОНЕНА им с грунтом — оба решения ратифицированы. Свободные строки зоны: 228 (алиас возвращает отклонённую поверхность), 230 (размен сходимости), 141-остаток, 131. Четыре промта входной двери шва — в archive/prompts/ (D39.158)
  Платформа	активного НЕТ	пак P9 ОТРАБОТАН, ПРИНЯТ и ЗАЛЕНДЖЕН 28.08 (D39.162): дверь правок банка смонтирована, ключи доехали, полоса стала сквозной вместе с каноном 0.6.0. Промт — в archive/prompts/. ⚠ Открытым остался архитектурный стоп PD-410 (платформа продаёт главы, движку идёт только --ceiling-usd) и продуктовый вопрос владельцу по Н2/Н3. Следующая работа зоны — по строкам 215/216 и регистру, запуск по слову владельца
  Полигон	POLYGON_EXP2223_REDO_SESSION_PROMPT.md (отложенный — POLYGON_PACKAGE4_SESSION_PROMPT.md, строка 85)	фаза Д ИДЁТ; ⚠ живой носитель курса — в eval/dovodka/, какой именно называет зона (⚠ POLYGON_PHASE_D_HANDOFF.md — перекрытый снимок, читать не как курс)
  Фронт	активного НЕТ	ЗОНА ЗАМОРОЖЕНА (D39.136 п.2 + D39.147: разморозка отдельным словом владельца, не привязана к P7); перечень первого касания — в зонном журнале
  Контракт	активного НЕТ	минор 0.6.0 ПРИНЯТ и заленджен 28.08 (D39.162/D39.163): полоса прогресса объявлена сквозной, Progress.stage заведён ВТОРЫМ ограниченным исключением из границы «ничего о том, КАК переводится книга». До него — 0.5.0 (D39.161, дверь правок банка). Хвост компаньона — строка 203, следующий минор по её пункту (к)

  Отработанные промты — archive/prompts/, отчёты с ревью-шапками — archive/reports/. Зонные журналы фронта и платформы — frontend-PROGRESS.md / platform-PROGRESS.md в их зонах (прогресс зон только там, D39.100).

• Чужие зоны — фронт и платформа (читать при касании стыка; каждая ведёт СВОЙ зонный бэклог — единый бэклог их строк не принимает, D39.84): ../frontend/ — веб-интерфейс: промт фронт-сессий + STACK_DECISIONS.md (пины версий точными числами и ловушки) + BACKLOG.md · ../platform/ — SaaS control plane: README + BACKLOG.md + docs/ (зонный журнал platform-PROGRESS.md · регистр дефектов · STACK_DECISIONS.md с рецептом стенда и инвентарём каналов шва · ENGINEERING_STANDARDS.md — ратифицирован; КАЖДЫЙ промт платформенной сессии обязан на него ссылаться, отступление = пинг · PLATFORM_DIRECTION.md — ратифицированное направление зоны: аутентификация, деньги, стандарты, скорость · архив промтов).

• archive/ — история (правила архива): закрытые промты (prompts/) · отчёты с ревью-шапками (reports/ — на них ссылаются приёмки) · исполненные арх-доки (architecture/) · слайсы хроники PROGRESS-*.md. Инструкции оттуда не исполнять.

• Диаграммы: ../backend/docs/components.puml · ../backend/docs/pipeline.puml — дом рядом с кодом (D39.80), правятся бэкендом одним коммитом с кодом; вручную НЕ рендерить — их смотрят нативно, рендер не нужен.

Ключи провайдеров

Имена переменных per-провайдер — поле api_key_env в backend/configs/models.yaml (носитель, который читает КОД, поэтому разойтись с реальностью резолва не может). У полигона свои дополнительные провайдеры — имена в его же скриптах, движковый носитель их не покрывает и не должен. Наполненность ключей — .env деплоя, его НЕ читать; при сомнении спрашивать владельца. ⚠ Ручной перечень здесь не держим: он уже лгал умолчанием — называл семь имён, когда в ходу было девять.