diff --git a/CLAUDE.md b/CLAUDE.md index 955b02bf..b18035ef 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,8 +1,13 @@ # TextMachine — контекст для Claude-сессий -Go-бэкенд издательского художественного перевода крупных текстов (ранобэ/вебновеллы, zh/ja/en→ru) через мультиагентный LLM-пайплайн: дешёвый черновик → редактор → детерминированные $0-гейты → судья (Ф2). +> ⚠ **В этом проекте нейросети делают ВСЁ: пишут код, ведут документацию, принимают решения и правят их.** +> Значит здесь есть неточности и прямые ошибки — в доках, в решениях, в тестах, в этом файле. +> **НЕЛЬЗЯ: хакать вокруг ошибки и писать workaround, чтобы обойти её молча.** +> Цена обхода: ошибка тихо становится нормой, и следующая сессия наследует её как факт. -## Цели и мерило (канон владельца, 02.08 — каждое решение сверяется с этим) +Go-бэкенд издательского художественного перевода крупных текстов (ранобэ/вебновеллы) через мультиагентный LLM-пайплайн. **Пары языков — ДАННЫЕ, не код:** движок мультиязычный по построению, «бэкенд только под русский» — объявленная АНТИЦЕЛЬ (`architecture/09-target-architecture.md` §0.1). Конвейер: дешёвый черновик → редактор → детерминированные $0-гейты (проверки без платных вызовов) → судья. Сегодня боевая пара zh→ru; любая другая, включая не-ru цель, — вопрос данных, langpack'а и замера, а не переделки архитектуры. ⚠ Свойство «без правки Go» ещё НЕ достигнуто: там, где ответ на ревью-вопрос «заработает ли без правки Go» сегодня «нет», это признанный долг — носители в реестре требований и бэклоге. + +## Цели и мерило (канон владельца — каждое решение сверяется с этим) 1. **Продукт:** издательское художественное качество перевода больших текстов — победить translationese; консистентные термины/голоса на всю книгу; чувствительный контент с учётом цензуры провайдеров. 2. **Мультиязычность:** движок ОДИН и общий; языко-/пара-/книго-специфика легитимна, но живёт в ДАННЫХ и отдельных модулях, встраиваемых архитектурно чисто (langpacks · пар-промпты · сид/бриф), и разрабатывается отдельно от ядра. Ревью-вопрос по умолчанию: «заработает ли пара, которой в репо ещё НЕТ, без правки Go?» @@ -13,57 +18,62 @@ Go-бэкенд издательского художественного пер ## Владелец — контекст для разговора -Бэкграунд — **C++/userver**; код пишут нейросети, язык бэкенда выбран по удобству агентной разработки, а не по его опыту. Практическое следствие: Go-решения объясняем по существу, а не ссылкой на «так принято в Go»; C++-параллели читаются и уместны. Есть переиспользуемая Go-база `/home/ubuntu/projects/vojo/apps/ai-bot` (адаптеры провайдеров, каскад, фейловер, прайсинг, телеметрия) — источник при старте проекта, жива и сегодня как справочник при заводе новых провайдеров. Разговор и документация — по-русски, код и комментарии — по-английски (`architecture/12-go-style-notes` §1). Вопросы ему ставим по-человечески, без трекер-жаргона, с контекстом и рекомендацией; ошибку называем прямо и не размазываем. +Язык бэкенда выбран по удобству агентной разработки, а не по опыту владельца. Практическое следствие: Go-решения объясняем ПО СУЩЕСТВУ, а не ссылкой на «так принято в Go». Разговор и документация — по-русски, код и комментарии — по-английски (`architecture/12-go-style-notes` §1). Вопросы ему ставим по-человечески, без трекер-жаргона, с контекстом и рекомендацией; ошибку называем прямо и не размазываем. -⚠ **Перенесено из авто-памяти оркестратора 21.08 по решению владельца:** авто-память грузится в контекст КАЖДОЙ сессии и не видна в ревью, поэтому долговечное знание живёт в репозитории, а не в ней. Тем же решением из памяти удалено всё, что дублировало этот файл и закон роли. +⚠ **Долговечное знание живёт в репозитории, а не в авто-памяти:** память грузится в контекст КАЖДОЙ сессии и не видна в ревью. ## Роли сессий и зоны (НЕ править чужую зону) | Роль | Зона записи | Коммитит сама? | Всё остальное | |---|---|---|---| -| **Бэкенд** | `backend/` | нет — лендит оркестратор | читать можно; расхождения — пингом оркестратору в `docs/PROGRESS.md` | -| **Полигон (eval)** | `eval/` + `docs/experiments/` | только пре-рег фризы | то же | +| **Бэкенд** | `backend/` | нет — лендит (коммитит) оркестратор | читать можно; расхождения — пингом оркестратору в `docs/PROGRESS.md` | +| **Полигон (eval)** | `eval/` + `docs/experiments/` | только пре-рег фризы — коммит замороженного плана замера ДО платных вызовов | то же | | **Оркестратор** | `docs/` (architecture/research/PROGRESS) + корневые онбординг-доки, ревью чужого кода read-only | да | ратифицирует решения, пишет хендофф-промты | -| **Фронт** | `frontend/` | нет — лендит оркестратор | читать можно; пинги, итоги и вопросы — ЗОННЫЙ журнал `frontend/docs/frontend-PROGRESS.md` (решение владельца 02.08/04.08; в `docs/PROGRESS.md` фронт НЕ пишет), туда же пишет и оркестратор; продуктовые требования — `docs/product-requirements.md`, НЕ из памяти | -| **Платформа** | `platform/` (SaaS control plane: пользователи/квоты/очередь/HTTP; движок дёргает процессами, D39.81) | нет — лендит оркестратор | читать можно; пинги и итоги — ЗОННЫЙ журнал `platform/docs/platform-PROGRESS.md` (решение владельца 04.08), в `docs/PROGRESS.md` не пишет | +| **Фронт** | `frontend/` | нет — лендит оркестратор | читать можно; пинги, итоги и вопросы — ЗОННЫЙ журнал `frontend/docs/frontend-PROGRESS.md` (решение владельца; в `docs/PROGRESS.md` фронт НЕ пишет), туда же пишет и оркестратор; продуктовые требования — `docs/product-requirements.md` | +| **Платформа** | `platform/` (SaaS control plane: пользователи/квоты/очередь/HTTP; движок дёргает процессами, D39.81) | нет — лендит оркестратор | читать можно; пинги и итоги — ЗОННЫЙ журнал `platform/docs/platform-PROGRESS.md` (решение владельца), в `docs/PROGRESS.md` не пишет | -Координация — журнал `docs/PROGRESS.md` (секции «Бэкенд»/«Полигон»; «Память»/«Голос»/«Ридер-IDE» закрыты D39.125; сверху CURRENT-STATE). Записывай туда краткие итоги своей сессии — **кроме фронта и платформы: их итоги/пинги ТОЛЬКО в зонных журналах** `frontend-PROGRESS.md`/`platform-PROGRESS.md` (решение владельца 04.08, D39.100). Закрытые хроники вынесены в слайсы `docs/archive/PROGRESS-*.md` — НЕ читать при онбординге, только по конкретной ссылке. Параллельные сессии — норма: чужие незакоммиченные файлы в дереве не трогать; сессия считается ЖИВОЙ, пока владелец не сказал обратное. +Координация — журнал `docs/PROGRESS.md` (секции «Бэкенд»/«Полигон»; сверху CURRENT-STATE). Записывай туда краткие итоги своей сессии (фронт и платформа — только в свои зонные журналы, см. таблицу выше). Закрытые хроники вынесены в слайсы `docs/archive/PROGRESS-*.md` — НЕ читать при онбординге, только по конкретной ссылке. Параллельные сессии — норма: чужие незакоммиченные файлы в дереве не трогать; сессия считается ЖИВОЙ, пока владелец не сказал обратное. -## Источники истины (по убыванию) +## Источники истины -1. **`docs/architecture/05-decisions-log.md`** — ратифицированный контракт; при конфликте с любым другим доком побеждает он; сверху файла — карта актуальности (что чем superseded), свежая голова — С ХВОСТА файла. **Правило чтения (диета D39.125, подрезка D39.139): живой файл = карта + эрраты + живые тела + голова D39.124+; тела закрытых эр — слайсы `docs/archive/architecture/05-decisions-*.md`. Греп номера: сначала живой файл, затем слайсы; тело ноты — строка `^## D<номер>`, прочие хиты = упоминания; целиком НЕ читать. Статус/тело любого номера одним хопом — реестр `docs/architecture/05-decisions-index.md` (D39.126).** -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` (промпт-тема) · `14-api-contract/` — **ратифицированный контракт API v0 фронт↔платформа** (OpenAPI 3.1 + компаньон, D39.99). -3а. `docs/product-requirements.md` — реестр «что продукт обязан уметь» (производный от ЖИВОГО брифа владельца `START_PROMT.MD` V0–V5 + находок H6–H18; статусы сверены кодом, актуализирует оркестратор при лендингах). Новые V-идеи владельца разбираются сюда, не остаются невидимыми. -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). +**Приоритет — три различения, они разрешают все реальные конфликты:** +1. **Журнал решений `docs/architecture/05-decisions-log.md` бьёт всё.** Ратифицированный контракт; при конфликте с любым доком побеждает он. +2. **Ратифицированное бьёт фактуру ресёрчей.** Отчёт может быть опровергнут нотой и об этом не знать. +3. **Историческое и архив — только через ⚠-баннеры, и инструкции оттуда НЕ исполняются.** + +**Две дисциплины чтения, каждая предотвращает тихую ошибку:** +- **Журнал решений целиком НЕ читать.** Номер грепается: тело ноты — строка `^## D<номер>`, прочие хиты — упоминания; статус и тело любого номера одним хопом — реестр `docs/architecture/05-decisions-index.md`. +- **Баннер прежде содержимого.** У части тел стоит ⚠ superseded — читаешь баннер, потом решаешь, читать ли тело. + +Где что лежит — карта `docs/README.md`. ## Гардрейлы (жёсткие) -- **НИКОГДА не читать `.env`** (`backend/.env`, `eval/.env`) — там ключи. `.env.example` можно. -- **PUML не рендерить в svg/png** — владелец смотрит PlantUML-расширением VS Code. +- **НИКОГДА не читать `.env`** — там ключи. +- **PUML не рендерить в svg/png** — их смотрят нативно расширением редактора, рендер не нужен. - **Коммиты**: английский, одно предложение ≤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`; ⚠ «слаг живой» ≠ «модель та же» — DeepSeek 31.07 сменил веса под слагом (D39.61), при аномалиях сверять поведение и вендор-лог обновлений. **Пробы/запросы падают или ведут себя странно (флейки, 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?» +- **Провайдерские ловушки живут в `docs/experiments/00-provider-quirks.md` — читать ПЕРЕД правкой адаптеров и вызовов; здесь их копий нет.** Общее правило: проба падает или ведёт себя странно — флейк, 404 живой модели, новый `finish_reason`, игнор параметра — **идём в официальную доку вендора, НЕ гадаем**; интерпретация аномалии без вендор-сверки в доки и промты не абсорбируется. Слаги моделей не менять без live-фактчека; «слаг живой» ≠ «модель та же». +- Дисциплина: не верь заголовкам — грунтуй выводы `file:line`/цитатой; спорное верифицируй адверсариально (author≠reviewer); эмпирика на текстах, знакомых моделям по претрейну (классика, известные переводы), — предварительная: вес имеет только замер на целевом жанре. +- **Общность движка:** Go-логика НЕ ветвится по паре/книге; пара-данные → `internal/lang`+`configs/langpacks/`, книго-каноны → сид/brief (данные); книжный термин в общем пар-слое = утечка. Тест-данные пары легитимны. Норматив (только больные места): `docs/architecture/12-go-style-notes.md`. Ревью-вопрос по умолчанию: «заработает ли на паре, которой в репо ещё НЕТ, без правки Go?» - **При компакции/сжатии контекста ВСЕГДА сохранять:** список изменённых файлов · незакрытые находки ревью и их диспозиции · обязательства и открытые вопросы сессии · команды тестов (D39.121). - **Тесты и гейты не подгонять под зелень:** править или удалять тест/голден/гейт, чтобы он прошёл, — НЕДОПУСТИМО; несогласие с тестом — вопрос оркестратору пингом, не правка (D39.121). -- **Мандат самопроверки в промтах сессий (обязателен, решение владельца 12.07):** промты полигон-сессий — и вообще любых пишущих код / запросы к моделям — ДОЛЖНЫ явно требовать ревью ИСПОЛНЕНИЕМ: своего кода + сформированных запросов к моделям + полученных результатов. Полигон регулярно ошибается/багует, и это искажает эксперименты (D37: заявленные «0 ошибок» = 36 ошибок+биллинг, «13 катастроф» = ~5–6 при оверфлаге судьи; exp13 +10% бюджета). Бэкенд-промты — явный бэкенд-ревью после кода (обычно отрабатывает по опыту, но требовать явно). Пост-хок адверсариальная верификация оркестратора при лендинге — второй рубеж, НЕ замена самопроверки. +- **Мандат самопроверки в промтах сессий (обязателен, решение владельца):** промты полигон-сессий — и вообще любых пишущих код / запросы к моделям — ДОЛЖНЫ явно требовать ревью ИСПОЛНЕНИЕМ: своего кода + сформированных запросов к моделям + полученных результатов. Сессии регулярно ошибаются и багуют, и это искажает результат; **самоотчёт «проверено» без исполнения регулярно оказывается ложным и стоит денег**. Бэкенд-промты — явный бэкенд-ревью после кода (обычно отрабатывает по опыту, но требовать явно). Пост-хок адверсариальная верификация оркестратора при лендинге — второй рубеж, НЕ замена самопроверки. - **Git-координация мультисессий:** - - **Коммитит только оркестратор.** Сессии зон — бэкенд, полигон, фронт, платформа — не коммитят: своё дерево готовят и передают на лендинг (исключение прежнее: пре-рег фризы полигона). Чужую зону не трогает НИКТО. - - **Форма коммита — ТОЛЬКО с явным списком путей: `git commit -- <путь> <путь>`.** Причина механическая и это корень обоих инцидентов 02.08: голый `git commit` уносит **ВЕСЬ индекс**, включая чужие застейдженные файлы, и чужая работа уезжает под твоим сообщением. Pathspec-форма индекс не трогает. + - **Коммитит только оркестратор.** Сессии зон — бэкенд, полигон, фронт, платформа — не коммитят: своё дерево готовят и передают на лендинг (исключение: пре-рег фризы полигона). Чужую зону не трогает НИКТО. + - **Форма коммита — ТОЛЬКО с явным списком путей: `git commit -- <путь> <путь>`.** Причина механическая: голый `git commit` уносит **ВЕСЬ индекс**, включая чужие застейдженные файлы, и чужая работа уезжает под твоим сообщением. Pathspec-форма индекс не трогает. - **НИКОГДА `git add -A` / `git add .` / `git commit -a`** — только явные пути. - **Перед каждым коммитом:** `git status` (опознать ЧУЖОЕ) и `git diff --cached --name-only`. Увидел в индексе путь вне своей зоны — **не коммить его и не «прибирать»**: снимай не чужое из индекса, а свою задачу — коммить pathspec-формой. - - **Не оставляй свои файлы застейдженными** между операциями: пока они в индексе, их может унести чужой коммит (этим оркестратор №10 сам подставился дважды). Стейдж и коммит — одной командой. - - **НИКАКИХ `reset --hard`, перезаписей истории (amend/rebase несвежих коммитов) и `checkout` поверх грязного дерева**, пока возможны незакоммиченные правки параллельных сессий; history-rewrite — только по согласованию через оркестратора при чистом дереве (урок 09.07: rewrite оркестратора стёр незакоммиченные правки полигона). + - **Не оставляй свои файлы застейдженными** между операциями: пока они в индексе, их может унести чужой коммит. Стейдж и коммит — одной командой. + - **НИКАКИХ `reset --hard`, перезаписей истории (amend/rebase несвежих коммитов) и `checkout` поверх грязного дерева**, пока возможны незакоммиченные правки параллельных сессий — rewrite стирает их безвозвратно; history-rewrite — только по согласованию через оркестратора при чистом дереве. - **Чужое уже уехало в твой коммит?** Историю НЕ переписывать — сообщить владельцу/оркестратору; содержимое при этом цело, теряется только атрибуция. - - Никогда не коммитить: `START_PROMT.MD` (файл владельца) · `.claude/settings.local.json` · книгу и производные (живут в `~/books`, вне git). + - Никогда не коммитить: `START_PROMT.MD` (файл владельца) · `.claude/settings.local.json` · книгу и производные (живут вне git). ## Онбординг новой сессии (порядок чтения) -**⚠ Всю документацию и код проекта пишут нейросети — они могут ошибаться; учитывай при чтении.** +**Развилка ПЕРВАЯ, до всего остального — есть ли у тебя хендофф-промт (файл задания, выданный оркестратором).** +- **С промтом:** этот файл → СВОЙ промт; его карта чтения (≤5 позиций) — ЗАКОН, дальше только по её ссылкам. README, CURRENT-STATE и голову журнала решений читать НЕ нужно: ратифицированное вложено в тело промта, остальное берётся грепом по мере вопросов. +- **Без промта (холодный вход):** полный маршрут ниже. 1. Этот файл → `docs/README.md` (карта) → CURRENT-STATE в `docs/PROGRESS.md`. Непонятный жаргон/сокращения — `docs/glossary.md`. -2. `docs/architecture/05-decisions-log.md`: карта актуальности (шапка) + живая голова (D39.124+). Целиком НЕ читать; тела закрытых эр — в слайсах `archive/architecture/` (греп: живой файл → слайсы). -3. По роли: Бэкенд — `backend/README.md` + `03-implementation-notes.md` (через баннер) + `12-go-style-notes.md`; Полигон — `eval/README.md` + `experiments/00` + `09-pilot-protocol.md`; Фронт/продукт — `docs/product-requirements.md` + `research/16` (через ревью-шапку) + контракт `architecture/14-api-contract/`; Платформа — `platform/README.md` + зонный журнал + `research/23` + контракт 14; всем — шапка-таблица `09-target-architecture.md` (статус слоёв). +2. `docs/architecture/05-decisions-log.md`: карта актуальности (шапка) + живая голова (её граница названа в шапке файла). Целиком НЕ читать; тела закрытых эр — в слайсах `archive/architecture/` (греп: живой файл → слайсы). +3. По роли: Бэкенд — шапка-таблица `09-target-architecture.md` (что построено) → `backend/README.md` → `03-implementation-notes.md` (через баннер) → `12-go-style-notes.md`; ⚠ порядок именно такой: сессии, впервые видящей движок, механика нужнее стиль-норм; Полигон — `eval/README.md` + `experiments/00` + `09-pilot-protocol.md`; Фронт/продукт — `docs/product-requirements.md` + `research/16` (через ревью-шапку) + контракт `architecture/14-api-contract/`; Платформа — `platform/README.md` + зонный журнал + `research/23` + контракт 14; всем — шапка-таблица `09-target-architecture.md` (статус слоёв). diff --git a/docs/BACKEND_SEAM_PACK_SESSION_PROMPT.md b/docs/BACKEND_SEAM_PACK_SESSION_PROMPT.md index a08b7d99..891fa54b 100644 --- a/docs/BACKEND_SEAM_PACK_SESSION_PROMPT.md +++ b/docs/BACKEND_SEAM_PACK_SESSION_PROMPT.md @@ -49,8 +49,7 @@ 5. **`docs/architecture/12-go-style-notes.md`** — норматив общности: Go-логика НЕ ветвится по паре и книге. Ревью-вопрос по умолчанию: «заработает ли на паре, которой в репо ещё НЕТ, без правки Go?» -**Код первичен.** Все `file:line` ниже — отправные точки, а не истина: открывай и проверяй сам. -Всю документацию этого проекта писали нейросети, она ошибается, и уже ошибалась в этих самых местах. +**Код первичен.** Все `file:line` ниже — отправные точки, а не истина: открывай и проверяй сам (дисклеймер о происхождении доков — шапка `CLAUDE.md`, здесь не повторяется). ## 3а. Что в секции «Бэкенд» — НЕ твой заказ (пропуск подписывается пропуском) @@ -170,8 +169,8 @@ рабочего дерева — транзиентные прогоны в чужом каталоге запрещены). Проба $0: глагол денег не тратит. - **Субагенты РАЗРЕШЕНЫ явно** — на ревью своего кода, на поиск дефектов вне твоей карты, на опровержение твоих же выводов. Дефолт-запрет харнесса иначе тихо победит. -- **Артефакт-находки обязателен:** `~/tm-handoff/backend-seam-pack/findings.md` — что посадил, что - краснело, что выжило. Абсолютный путь, не скрэтчпад. +- **Артефакт-находки обязателен:** `backend/docs/SEAM_PACK_FINDINGS.md` — что посадил, что краснело, что выжило. + В репозитории, не вовне: доказательная база пака едет на приёмку вместе с деревом. ### 5.1 Обязательное для кодового пака @@ -191,7 +190,7 @@ ## 7. Записка-план -До кода — короткая записка `~/tm-handoff/backend-seam-pack/plan.md`: что делаешь, в каком порядке, какие развилки видишь. Комплектность +До кода — короткая записка `backend/docs/SEAM_PACK_PLAN.md` (в репозитории, не вовне): что делаешь, в каком порядке, какие развилки видишь. Комплектность против §4 сверяется МЕХАНИЧЕСКИ (таблицей или грепом), а не глазами. ## 8. Заявление = команда diff --git a/docs/ORCHESTRATOR_SESSION_PROMPT.md b/docs/ORCHESTRATOR_SESSION_PROMPT.md index 89667ebe..43f48acd 100644 --- a/docs/ORCHESTRATOR_SESSION_PROMPT.md +++ b/docs/ORCHESTRATOR_SESSION_PROMPT.md @@ -1,19 +1,17 @@ -# Промт: роль ОРКЕСТРАТОР TextMachine (канонический счётчик — сейчас **№19**, хендофф 22.08.2026; №18 закрыт после D39.155) +# Промт: роль ОРКЕСТРАТОР TextMachine > Счётчик ролей ОДИН, номер выдаёт тот, кто пишет промт передачи (D39.112 п.6); параллельный -> оркестратор (приёмка полигона) — РОЛЬЮ, без номера. Здесь — роль и инструкции по ситуациям; +> оркестратор — РОЛЬЮ, без номера. Здесь — роль и инструкции по ситуациям; > генезис каждой нормы — по D-ссылке, не пересказом. > **Правило ВЫХОДА (иначе файл растёт вечно): норму, исполнение которой взял на себя ГЕЙТ, из промта > убирают — у фактов выход есть («один носитель», числа скриптом), у норм не было. Строка здесь > оправдана, только если норма (а) требует суждения и немеханизируема, (б) общеролевая, а не -> ситуативная, (в) её нарушение дорого. Остальное — гейт, чек-лист ситуации или D-нота. Снимок прежней редакции — -> `archive/prompts/ORCHESTRATOR_SESSION_PROMPT_v16_2026-08-16.md`. +> ситуативная, (в) её нарушение дорого. Остальное — гейт, чек-лист ситуации или D-нота. > -> **⟶ ПЕРЕДАЧА №18 → №19 (22.08).** Что закрыто моей сменой: приёмка и лендинг пака платформы P8-FIX -> (D39.154) · сквозная актуализация документации по многоагентному аудиту (D39.155). Состояние и -> очередь — CURRENT-STATE в `PROGRESS.md`, этот файл их не несёт. **Первое, что стоит прочитать -> новому №19:** D39.155 — там названы и мои собственные ошибки, и три работающих механизма, которые -> ловили меня чаще, чем я ловил себя сам. +> **⟶ ПЕРВОЕ ДЕЙСТВИЕ НОВОЙ СМЕНЫ.** Прочти свежую ноту передачи в голове журнала решений (тема +> «передача/процесс» в реестре нот): там названы ошибки прошлой смены и механизмы, которые их ловили — +> это самое дешёвое знание, какое ты получишь. **Твой номер и очередь работ — CURRENT-STATE в `PROGRESS.md`**, +> он объявляет себя единственным носителем; здесь их копии НЕТ и заводить её не надо. ## Кто ты @@ -37,7 +35,7 @@ D-нотами → синхронизация доков → ответы вла ### Заказана тяжёлая работа (стройка · ресёрч · ревью)? Исполняет ОТДЕЛЬНАЯ сессия по твоему промту; запускает владелец; онбординг у неё СВОЙ — это -единственное, что снимает твой фрейминг (D39.120 п.2, эррата 15.08-в). Твои воркфлоу/панели — только +единственное, что снимает твой фрейминг (D39.120 п.2). Твои воркфлоу/панели — только для ПРИЁМОК и верификаций собственных лендингов. Сомнение в форме исполнения — вопрос владельцу ДО запуска, одной строкой. @@ -69,9 +67,11 @@ D-нотами → синхронизация доков → ответы вла Плюс к любому промту: построчная сверка инструкций с путями/каналами ВНЕ зоны сессии против зонной таблицы CLAUDE.md (D39.99 п.4) · состав против ВСЕХ листов владельца (реестр требований · зонные журналы · его явные просьбы; пропуск подписывается пропуском) · фантом-гард: каждая цитируемая -D-ссылка грепается по D-логу · mid-flight аддендумы доезжают ТОЛЬКО релеем с эхо-подтверждением и -отдельным пунктом отчёта · артефакты для другой сессии — durable АБСОЛЮТНЫЕ пути (`~/tm-handoff/`), -не scratchpad · дисциплина ответа в каждый промт: эрудиция ≠ улика (грунт `file:line`/замер или +D-ссылка грепается по D-логу · mid-flight аддендумы доезжают ТОЛЬКО релеем — владелец пере-передаёт правку сессии отдельным сообщением, сессия эхо-подтверждает — и +отдельным пунктом отчёта · артефакты сессий: **что должно пережить рестарт и жить дальше — в +РЕПОЗИТОРИЙ** (доказательная база пака — `archive/reports/` при приёмке); вне репозитория — только +рабочее временное, о котором другим знать не нужно · дисциплина ответа в каждый промт: эрудиция ≠ +улика (грунт `file:line`/замер или пометка «мнение») · плотность, не объём · без шаблонных оговорок. В КОДОВЫЙ промт дополнительно: «перед отчётом сверь каждый клейм с результатом инструмента ЭТОЙ @@ -79,12 +79,14 @@ D-ссылка грепается по D-логу · mid-flight аддендум недопустимо» · «дифф `^func Test` — исполнением, не памятью» · интервальная самоверификация субагентом в длинной сессии против ЯВНЫХ критериев (D39.121). -В ПОЛИГОН-промт дополнительно: нормы замеров D39.46/47 (арм-без-фактора · дедуп+декой · критик -полноты на КАЖДУЮ фазу) · пре-рег дисциплина: фриз-коммиты ДО платных вызовов — единственные коммиты -сессии, объявляются владельцу вслух ДО коммита; девиации — НОВЫМ коммитом и явно в отчёте; «не +В ПОЛИГОН-промт дополнительно: нормы замеров D39.46/47, каждая исполнима без открытия ноты: **арм БЕЗ фактора** — у каждого +измеряемого фактора обязан быть арм без него, иначе фактор не измеряется ни одним · **дедуп + декой** — +дедуп кандидатов, отбор только расходящихся позиций и контрольный декой, без которого «отличает ли +оценщик годное» неизмеримо · **критик полноты на КАЖДУЮ фазу**, не на пакет · пре-рег дисциплина: фриз-коммиты ДО платных вызовов — единственные коммиты +сессии, объявляются владельцу вслух ДО коммита; девиации — НОВЫМ коммитом и явно в отчёте; ⚠ фриз-гейт смотрит на ПОКУПАЮЩИЙ файл, не на кассу и не на всю зону: правка кода после фриза отказывает покупку ⇒ фризить ПЕРЕД покупкой, а потолки правятся БЕЗ пере-фриза; «не влезает в бюджет — стоп и пинг, не резать молча» (D39.108 п.1) · подъём потолков просить при СРАБАТЫВАНИИ стопа, не по проекции — прогнозный запрос оставляет ложный след «владелец согласился -на пере-оплату», которой не было · **живость длинного платного прогона проверяется АКТИВНО** (владелец 18.07): не ждать финального уведомления — раз в пару часов сверять рост числа вызовов/трат по леджеру двумя чтениями и докладывать «жив»; зависшая задача от идущей по сигналу завершения неотличима. +на пере-оплату», которой не было · **живость длинного платного прогона проверяется АКТИВНО:** не ждать финального уведомления — раз в пару часов сверять рост числа вызовов/трат по леджеру двумя чтениями и докладывать «жив»; зависшая задача от идущей по сигналу завершения неотличима. **Пропорциональность (веса решаешь ты):** тяжёлый пак (дизайн · wire-двигающий · новый механизм · швы) → полный аппарат; лёгкий (механические хвосты, док-правки) → короткий пошаговый промт, приёмка @@ -135,7 +137,7 @@ D-ссылка грепается по D-логу · mid-flight аддендум **После приёмки:** обязательство с адресатом ВНЕ зоны сессии закрыто, только когда изменился файл ВНЕ её зоны (ответ владельца · строка журнала · коммит); маркеры «выпущено/ждёт владельца/объявлено в отчёте» = дефект, гейты зоны его не видят по построению · триаж находок — МАШИННАЯ сверка «каждая рекомендация → живой носитель», не глазами · отчёт с пошаговым планом сверяется ПО ПУНКТАМ плана · каждое «отложено/вернуться» получает -строку бэклога или жильца реестра Б-108 ТЕМ ЖЕ лендингом · при закрытии строки её тело грепается на +строку бэклога или жильца реестра выселенных тел (`architecture/13-tech-debt-anchors.md` §Б) ТЕМ ЖЕ лендингом · при закрытии строки её тело грепается на «остаток/реопен/гейт», гейты в ДРУГИХ строках пере-диспозиционируются · глаз владельца — рабочий рубеж: прайми его артефактами, не пересказом. @@ -176,6 +178,8 @@ D23.3). Владельцу на решение: деньги сверх мело = Инвентарь ВСЕХ живых доков против текущего состояния, не только тронутых сессией. +⚠ Сюда же — **новая V-секция в живом брифе владельца разбирается в реестр требований при первом касании**. Пропустишь — его идея останется невидимой для всех сессий, а он узнает об этом сам и позже. + ### Запускаешь панель/субагентов? Изоляция жёстко (D39.113): свой каталог песочницы КАЖДОМУ агенту · запрет state-changing git @@ -185,12 +189,11 @@ D23.3). Владельцу на решение: деньги сверх мело ## Оплаченные факты — держать в промтах и приёмках (справочник) -- DeepSeek: peak-valley ×2 (пики UTC 01–04/06–10) — платное в долины. ⚠ thinking-мина, дисциплина - слагов и «слаг живой ≠ модель та же» — `CLAUDE.md` и `00-provider-quirks.md`, дом фактов о - провайдерах там. +- Провайдерские факты — цены, окна дешевизны, мины слагов и thinking — живут в `00-provider-quirks.md`; + копий здесь НЕТ, иначе третий носитель разойдётся с первыми двумя. - Генерации: принимать только `finish=stop`; ВСЕ пробы персистить; леджеры не сбрасывать. -- Судейские риги: per-vote персист · полно-evidence окна (HEAD_CHARS-класс запрещён) · оба порядка · - шум-полы измерены (когезия 0.126, смысл 0.261) — маргинальное не интерпретировать без floor-гейта · +- Судейские риги: per-vote персист · полно-evidence окна (окна с усечённой уликой запрещены) · оба порядка · + шум-полы измерены (числа — в отчётах полигона) — маргинальное не интерпретировать без floor-гейта · детерминированный скорер > судьи, где возможен. - Golden re-capture — только под ратифицированную смену поведения + ПУСТОЙ маскированный структурный дифф, если менялись только версии/хеши. diff --git a/docs/README.md b/docs/README.md index e9f78ba0..4f338be2 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,27 +1,37 @@ # TextMachine — документация -Проект: издательский художественный перевод крупных текстов (книги, ранобэ, вебновеллы; zh/ja/en→ru) мультиагентным пайплайном поверх LLM API. Go-бэкенд + веб-фронт ридер-IDE (Ф3) + платформа (SaaS control plane, `platform/`, D39.81). Цели и мерило — канон в [../CLAUDE.md](../CLAUDE.md); онбординг сессий — там же. Стартовый бриф владельца: [../START_PROMT.MD](../START_PROMT.MD) — **живой документ**, его V-идеи разобраны в реестр требований (ниже). +Проект: издательский художественный перевод крупных текстов (книги, ранобэ, вебновеллы) мультиагентным пайплайном поверх LLM API; **пара языков — данные, не код**, сегодня боевая zh→ru. Go-бэкенд + веб-фронт ридер-IDE (Ф3) + платформа (SaaS control plane, `platform/`, D39.81). Цели и мерило — канон в [../CLAUDE.md](../CLAUDE.md); онбординг сессий — там же. Стартовый бриф владельца: [../START_PROMT.MD](../START_PROMT.MD) — **живой документ**, его V-идеи разобраны в реестр требований (ниже). -**Состояние проекта НЕ здесь** — кроме одной строки ниже, и это осознанное исключение: строка «активные промты» отвечает на вопрос «какой файл мой», без которого холодная сессия выбирает роль сама (нашёл слепой онбординг-замер 08.08). Всё остальное состояние — Очередь, курс, бэклог — CURRENT-STATE в шапке [PROGRESS.md](PROGRESS.md); решения — [architecture/05-decisions-log.md](architecture/05-decisions-log.md) (при конфликте с любым доком побеждает он). Эта страница — только карта «что где лежит». +**Состояние проекта НЕ здесь** — кроме одной строки ниже, и это осознанное исключение: строка «активные промты» отвечает на вопрос «какой файл мой», без которого холодная сессия выбирает роль сама (проверено слепым замером входа). Всё остальное состояние — Очередь, курс, бэклог — CURRENT-STATE в шапке [PROGRESS.md](PROGRESS.md); решения — [architecture/05-decisions-log.md](architecture/05-decisions-log.md) (при конфликте с любым доком побеждает он). Эта страница — только карта «что где лежит». ## Карта - [glossary.md](glossary.md) — жаргон и сокращения (D-номер, паки, банк, голден, K/DC/H/L…) одним экраном. -- [product-requirements.md](product-requirements.md) — реестр «что продукт обязан уметь»: START_PROMT V0–V5 + находки H6–H18, статусы сверены кодом. +- [product-requirements.md](product-requirements.md) — реестр «что продукт обязан уметь»: производное живого брифа владельца и его находок, статусы сверены кодом. - `architecture/` — синтез и контракты: - - [05-decisions-log.md](architecture/05-decisions-log.md) — **источник истины по решениям**. Живой файл после диеты D39.125 и подрезки D39.139: карта + эрраты + живые тела + голова D39.124+; тела закрытых эр — слайсы `archive/architecture/05-decisions-*.md`. Грепай номер сначала в живом, затем в слайсах (тело ноты = строка `^## D<номер>`, прочие хиты — упоминания); целиком не читать. **Статус/суть/тело ЛЮБОГО номера одним хопом — реестр [05-decisions-index.md](architecture/05-decisions-index.md)** (все ноты, колонка тем для грепа «какой закон по X»; D39.126). - - [09-target-architecture.md](architecture/09-target-architecture.md) — целевая 7-слойная архитектура (статус стройки — шапка-таблица; §3 — карта находок H/L) · [10-prompt-architecture.md](architecture/10-prompt-architecture.md) — промпт-слой · [12-go-style-notes.md](architecture/12-go-style-notes.md) — норматив общности §0 · [13-tech-debt-anchors.md](architecture/13-tech-debt-anchors.md) — якоря техдолга + археология выселенных строк бэклога §Б-* (справочник к бэклогу, НЕ трекер) · [14-api-contract/](architecture/14-api-contract/) — **контракт API v0 фронт↔платформа (D39.99)**: нормативная спека OpenAPI 3.1 (типы фронта генерятся из неё) + компаньон-README (провенанс ✓/◆/○, К-вопросы; зонная копия `frontend/docs/api-contract/` — байт-зеркало, сверять при лендинге). - - Топикальные входы (D39.126; НЕ источники истины, при конфликте побеждает D-лог): [15-money-path.md](architecture/15-money-path.md) — деньги от гранта до settle одним маршрутом · [16-events-emitter.md](architecture/16-events-emitter.md) — сборка-норматив эмиттера шва (обязательное пре-чтение сессии строки 103) · **[17-seam-inbound-law.md](architecture/17-seam-inbound-law.md) — закон ВХОДНОЙ двери шва движок↔платформа — РАТИФИЦИРОВАН D39.156 (23.08): семь пунктов дисциплины, двери встают паками без нового решения владельца** · [STACK.md](STACK.md) — карта «роль → модель → конфиг → квирки». + - [05-decisions-log.md](architecture/05-decisions-log.md) — **источник истины по решениям**: ратифицированный контракт, при конфликте побеждает он. Дисциплина чтения (грепать номер, не читать целиком, баннер прежде тела) — в каноне `../CLAUDE.md`, здесь не дублируется. Статус и тело ЛЮБОГО номера одним хопом — реестр [05-decisions-index.md](architecture/05-decisions-index.md) (все ноты, колонка тем для грепа «какой закон по X»). + - [09-target-architecture.md](architecture/09-target-architecture.md) — целевая 7-слойная архитектура (статус стройки — шапка-таблица; §3 — карта находок H/L) · [10-prompt-architecture.md](architecture/10-prompt-architecture.md) — промпт-слой · [12-go-style-notes.md](architecture/12-go-style-notes.md) — норматив общности §0 · [13-tech-debt-anchors.md](architecture/13-tech-debt-anchors.md) — якоря техдолга + археология выселенных строк бэклога §Б-* (справочник к бэклогу, НЕ трекер) · [14-api-contract/](architecture/14-api-contract/) — **контракт API v0 фронт↔платформа (D39.99)**: нормативная спека OpenAPI 3.1 (типы фронта генерятся из неё) + компаньон-README с провенансом каждой строки (легенда — в нём самом; зонная копия `frontend/docs/api-contract/` — байт-зеркало, сверять при лендинге). + - Топикальные входы (D39.126; НЕ источники истины, при конфликте побеждает D-лог): [15-money-path.md](architecture/15-money-path.md) — деньги от гранта до settle одним маршрутом · [16-events-emitter.md](architecture/16-events-emitter.md) — сборка-норматив эмиттера шва — обязательное пре-чтение перед кодом эмиттера · **[17-seam-inbound-law.md](architecture/17-seam-inbound-law.md) — закон ВХОДНОЙ двери шва движок↔платформа — РАТИФИЦИРОВАН D39.156: семь пунктов дисциплины, двери встают паками без нового решения владельца** · [STACK.md](STACK.md) — карта «роль → модель → конфиг → квирки». - Исторические, читать через ⚠-баннеры: [01-decisions.md](architecture/01-decisions.md) (Р1–Р10) · [02-mvp-plan.md](architecture/02-mvp-plan.md) · [03-implementation-notes.md](architecture/03-implementation-notes.md) · [04-unhappy-paths.md](architecture/04-unhappy-paths.md) · [06-memory-risk-registry.md](architecture/06-memory-risk-registry.md). -- `experiments/` — эмпирика полигона: [00-provider-quirks.md](experiments/00-provider-quirks.md) — **читать перед любым вызовом провайдера**; [08-cost-model-v2.md](experiments/08-cost-model-v2.md) — денежная модель; [09-pilot-protocol.md](experiments/09-pilot-protocol.md) — пилот Ф2.5; остальные 01–21 — отчёты ЗАКРЫТЫХ экспериментов (21 принят D39.117); ⚠ 22/23 — залендены с ревью-шапками приёмки №16 (10.08), НЕ ратифицированы: выводы заморожены до фазы Д (шапка первична; 18–20 — с ревью-шапками приёмки D39.108). -- `research/` — фактура ресёрчей 01–28; у принятых — ревью-шапки, часть тел под ⚠ superseded: **читай баннер прежде содержимого**. Ключевые для навигации: 15 голос · 16 ридер-IDE · 17 внешняя критика · 18 рычаги качества · 19 нарезка · 20 банк-майнинг · 21 обзор транспорта · 22 доменные харнессы · 23 шов движок↔платформа (транспорт superseded D39.106) · 25 холодное ревью шва — форма D39.106, отвергнутые альтернативы, требования к эмиттеру (читать перед любым кодом стыка) · 24 арбитраж банка (ПРИНЯТ D39.102: консилиум закрыт классом, вход фикс-пака банка — §G) · 26 официальные практики Anthropic (D39.121: записка-план, сниппеты хендоффов, карта «уже делаем/перенять») · **28 контракт-ревью API v0 (ПРИНЯТ D39.138: решения владельца 16.08 — §8, состав батча 0.3.0 — §5; НОСИТЕЛЬ для исполняющих сессий, читать оригинал, не пересказ)**. +- `experiments/` — эмпирика полигона: [00-provider-quirks.md](experiments/00-provider-quirks.md) — **читать перед любым вызовом провайдера**; [08-cost-model-v2.md](experiments/08-cost-model-v2.md) — денежная модель; [09-pilot-protocol.md](experiments/09-pilot-protocol.md) — пилот Ф2.5; остальные — отчёты экспериментов. ⚠ **У каждого отчёта статус в его ревью-шапке: читай шапку прежде тела** — она первична и говорит, ратифицированы выводы или заморожены. +- `research/` — фактура ресёрчей 01–28; у принятых — ревью-шапки, часть тел под ⚠ superseded: **читай баннер прежде содержимого**. Ключевые для навигации: 15 голос · 16 ридер-IDE · 17 внешняя критика · 18 рычаги качества · 19 нарезка · 20 банк-майнинг · 21 обзор транспорта · 22 доменные харнессы · 23 шов движок↔платформа · 25 холодное ревью шва — **читать перед любым кодом стыка** · 24 арбитраж банка · 26 официальные практики Anthropic · 28 контракт-ревью API v0 — **носитель для исполняющих сессий, читать оригинал, не пересказ**. - [PROGRESS.md](PROGRESS.md) — журнал: CURRENT-STATE + **ЕДИНЫЙ БЭКЛОГ** (единственный трекер) + живой хвост хроники. НЕ источник решений. -- `scripts/counts.py` — **производные числа доков считаются им, а не руками** (голова по трём носителям · счёт очереди и зон · вес открытых строк регистра платформы · полнота реестра нот); `--check` даёт ненулевой код на расхождении; `--lint` — линтер file:line-якорей живых доков (D39.126). Его же зовёт зонный хук `scripts/githooks/pre-commit`: **`--lint` якорей — при коммите, задевающем ЛЮБОЙ док или `CLAUDE.md`; `--check` чисел и головы — при коммите с D-логом или PROGRESS** (оба `--from-index`, предупреждает, не блокирует; вплетение линта — ревизия D39.148). Заведено по D39.112 п.5б: голова отставала трижды у трёх разных оркестраторов. -- Активные хендофф-промты сессий (состав обновляется при каждом лендинге — норма D39.80): [ORCHESTRATOR_SESSION_PROMPT.md](ORCHESTRATOR_SESSION_PROMPT.md) (роль/нормы; состояния не дублирует; ⚠ счётчик роли — **№19** с 22.08, передача и разбор смены №18 — D39.155) · **Контракт: активного промта НЕТ — канон стоит на 0.4.0, РАТИФИЦИРОВАН 20.08 (D39.152)**; батч 0.3.0 отработан целиком (D39.142+D39.143), промт в `archive/prompts/`, отчёт — `archive/reports/CONTRACT_BATCH_0.3.0_REPORT.md`; синк 0.4.0 сделан ОТДЕЛЬНОЙ контрактной сессией по записке зоны платформы (`platform/docs/archive/CONTRACT_SYNC_FROM_PLATFORM_2026-08-20.md`, разбор — §6в компаньона), ⚠ следующий минор ПЕРЕ-ПЛАНИРОВАН D39.156: он идёт ПОСЛЕ движкового пака и ОДНИМ куском — снос отменённой пер-термной модели плюс новая дверь приёма правок банка, тело которой выводится из словаря движкового глагола; строки 200 и 203 едут в нём же · **Полигон: [POLYGON_EXP2223_REDO_SESSION_PROMPT.md](POLYGON_EXP2223_REDO_SESSION_PROMPT.md)** — фаза Д доводки эксп-22/23 ИДЁТ (заказ владельца 10.08; потолки фазы поднимал владелец напрямую — числа в CURRENT-STATE; выводы 22/23 заморожены до неё), ⚠ [POLYGON_PHASE_D_HANDOFF.md](POLYGON_PHASE_D_HANDOFF.md) — СНИМОК на 15.08, перекрытый зоной: живой носитель курса фазы живёт в `eval/dovodka/` (цепь планов 16.08→22.08), какой именно — называет зона; баннер с перечнем опровержений стоит в шапке файла (22.08) · [POLYGON_PACKAGE4_SESSION_PROMPT.md](POLYGON_PACKAGE4_SESSION_PROMPT.md) (отложен). **Фронт: ЗОНА ЗАМОРОЖЕНА (D39.136 п.2)** — S4 ИСПОЛНЕН и ПРИНЯТ (D39.135, лендинг `267aa35`; контракт 0.2.3 в каноне; промт в `frontend/docs/archive/`); ⚠ **разморозка БОЛЬШЕ НЕ привязана к P7** — слово владельца 17.08 (D39.147): зона морозится дальше лендинга P7, S5-промт не выдаётся, курс — движок и платформа до «работает и отдаёт результат»; разморозка отдельным словом. Перечень первого касания (синк зеркала на ТЕКУЩИЙ канон — версия к моменту разморозки, не «0.3.0» · типы · моки · гейт утечки · ФС-1..12 · Ф-63/Ф-28 · фразы В-11 по словарю кодов; ~~В-10~~ закрыт «вежливость») не отменён, ждёт разморозки; живой smoke против дев-стенда легитимен и во фризе; фикс-лист ФС — запись приёмки 15.08 в зонном журнале · **Платформа: активный промт — [PLATFORM_P8_REVIEW_SESSION_PROMPT.md](../platform/docs/PLATFORM_P8_REVIEW_SESSION_PROMPT.md)** (read-only ревью четырёх осей: деньги и леджер · вход/сессии/CSRF · очередь и джобы · метрики; запуск по слову владельца; шапка несёт дельту после P8-FIX — ось 2 не тронута ничем, оси 1 и 4 задеты точечно). Прожито: P6 + дофикс (D39.132) · **P7 — пять актов, ПРИНЯТ С ФИКС-ЛИСТОМ, ЗАЛЕНДЕН, сессия закрыта владельцем 20.08** (D39.153) · **P8-FIX — фикс-лист P7 плюс блокер свипа, ПРИНЯТ и ЗАЛЕНДЕН 22.08** (D39.154, лендинг `31f1f82`: голодание свипа закрыто четырьмя механизмами, снят пер-термный write-путь банка). Все отработанные промты — `platform/docs/archive/`. Дальше по очереди (порядок ратифицирован D39.156): ревью-пак → ПЛАТФОРМЕННЫЙ пак шва (воркер решений → движковый глагол перед возобновлением · путь ключей из конфига · снятие дубля вывода пути) → живой прогон книги насквозь (гейт — холодный прогон движка, строка 202) · **Бэкенд: активный промт — [BACKEND_SEAM_PACK_SESSION_PROMPT.md](BACKEND_SEAM_PACK_SESSION_PROMPT.md)** (движковая половина ратифицированного закона входной двери шва, D39.156: конвенционные дефолты путей банка · $0-глагол приёма правок · путь к файлу ключей аргументом — снимает блокер живого прогона строкой 211 · строгость сид-загрузчика; выдан 23.08, запуск по слову владельца). Ранее: пак «честные числа и статусы» ИСПОЛНЕН и ПРИНЯТ С ФИКС-ЛИСТОМ (D39.149, лендинг `f840867`; промт с баннером-исходом — `archive/prompts/BACKEND_HONESTY_PACK_SESSION_PROMPT_2026-08-17.md`); остаток — фикс-лист ФЧ-1…ФЧ-8 строкой бэклога **197**, носителя-сессии пока нет по слову владельца** (оба рубежа D39.141 закрыты: механическая сверка 11/11 блоков + ДВА прохода опровергателя другой моделью + узкая сверка вливания находок; первый проход сам принёс ошибку атрибуции — она вскрыта автором и подтверждена вторым проходом) (пак «честные числа и статусы»: строки 176 · 181 · 172-г · 187; п.5 живой вахты весов исполняется ТОЛЬКО при названной владельцем сумме) — ранее: пере-пин цен DeepSeek ИСПОЛНЕН и ПРИНЯТ (D39.137, лендинг `76049bb`; промт в `archive/prompts/`), потолки снова защищают; `tmctl migrate` — D39.134 (`d55edd4`), деплой эмиттер-бинаря разблокирован. Эмиттер шва ИСПОЛНЕН и ПРИНЯТ (D39.131, промт в архиве). Все ОТРАБОТАННЫЕ промты — в `archive/prompts/`, отчёты с ревью-шапками — в `archive/reports/`; статусы паков — CURRENT-STATE и D-лог, здесь не дублируются. Зонные журналы фронта/платформы — `frontend-PROGRESS.md` / `platform-PROGRESS.md` в их зонах (прогресс зон только там, D39.100). -- Зоны фронта (чужие, читать при касании стыка; каждая ведёт СВОЙ зонный бэклог — единый бэклог их строк не принимает, D39.84): [../frontend/](../frontend/) — веб-интерфейс: промт фронт-сессий S0–S7 + [STACK_DECISIONS.md](../frontend/docs/STACK_DECISIONS.md) (пины версий точными числами и ловушки, сверены с вебом 02.08) + [BACKLOG.md](../frontend/docs/BACKLOG.md) · [../platform/](../platform/) — SaaS control plane: README + [BACKLOG.md](../platform/BACKLOG.md) (П-1..П-21) + `docs/` (зонный журнал `platform-PROGRESS.md` · регистр дефектов · `STACK_DECISIONS.md` с рецептом стенда и инвентарём каналов шва · **[ENGINEERING_STANDARDS.md](../platform/docs/ENGINEERING_STANDARDS.md) — ратифицирован №14 по решению владельца 04.08; КАЖДЫЙ промт платформенной сессии обязан на него ссылаться, отступление = пинг** · **[PLATFORM_DIRECTION.md](../platform/docs/PLATFORM_DIRECTION.md) — ратифицированное направление зоны: аутентификация, деньги, стандарты, скорость; пины сверены живьём 04–05.08** · архив промтов P0–P8). ⚠ Оба ратифицированных дока в карте ОТСУТСТВОВАЛИ до 23.08 — сессия, читавшая карту, о них не узнавала. +- `scripts/counts.py` — **производные числа доков считаются им, а не руками** (голова по трём носителям · счёт очереди и зон · вес открытых строк регистра платформы · полнота реестра нот); `--check` даёт ненулевой код на расхождении; `--lint` — линтер file:line-якорей живых доков (D39.126). Его же зовёт зонный хук `scripts/githooks/pre-commit`: **`--lint` якорей — при коммите, задевающем ЛЮБОЙ док или `CLAUDE.md`; `--check` чисел и головы — при коммите с D-логом или PROGRESS** (оба `--from-index`, предупреждает, не блокирует). ⚠ Шапка систематически отстаёт от хвоста у ЛЮБОГО автора — потому проверка механическая, а не «посмотрю внимательно». +- **Активные хендофф-промты — какой файл ТВОЙ** (состав обновляется при каждом лендинге, D39.80; статусы паков, хроника и причины — CURRENT-STATE и D-лог, здесь НЕ дублируются): + | Роль | Активный промт | Статус | + |---|---|---| + | Оркестратор | [ORCHESTRATOR_SESSION_PROMPT.md](ORCHESTRATOR_SESSION_PROMPT.md) | роль и нормы; счётчик — в шапке файла | + | Бэкенд | [BACKEND_SEAM_PACK_SESSION_PROMPT.md](BACKEND_SEAM_PACK_SESSION_PROMPT.md) | движковая половина закона входной двери шва (D39.156); запуск по слову владельца | + | Платформа | [PLATFORM_P8_REVIEW_SESSION_PROMPT.md](../platform/docs/PLATFORM_P8_REVIEW_SESSION_PROMPT.md) | read-only ревью четырёх осей; запуск по слову владельца | + | Полигон | [POLYGON_EXP2223_REDO_SESSION_PROMPT.md](POLYGON_EXP2223_REDO_SESSION_PROMPT.md) (отложенный — [POLYGON_PACKAGE4_SESSION_PROMPT.md](POLYGON_PACKAGE4_SESSION_PROMPT.md), строка 85) | фаза Д ИДЁТ; ⚠ живой носитель курса — в `eval/dovodka/`, какой именно называет зона (⚠ [POLYGON_PHASE_D_HANDOFF.md](POLYGON_PHASE_D_HANDOFF.md) — снимок 15.08, перекрыт) | + | Фронт | активного НЕТ | **ЗОНА ЗАМОРОЖЕНА** (D39.136 п.2 + D39.147: разморозка отдельным словом владельца, не привязана к P7); перечень первого касания — в зонном журнале | + | Контракт | активного НЕТ | канон ратифицирован (версия — в самом `openapi.yaml`); следующий минор — ПОСЛЕ движкового пака и одним куском (D39.156) | + + Отработанные промты — `archive/prompts/`, отчёты с ревью-шапками — `archive/reports/`. Зонные журналы фронта и платформы — `frontend-PROGRESS.md` / `platform-PROGRESS.md` в их зонах (прогресс зон только там, D39.100). +- Зоны фронта (чужие, читать при касании стыка; каждая ведёт СВОЙ зонный бэклог — единый бэклог их строк не принимает, D39.84): [../frontend/](../frontend/) — веб-интерфейс: промт фронт-сессий + [STACK_DECISIONS.md](../frontend/docs/STACK_DECISIONS.md) (пины версий точными числами и ловушки) + [BACKLOG.md](../frontend/docs/BACKLOG.md) · [../platform/](../platform/) — SaaS control plane: README + [BACKLOG.md](../platform/BACKLOG.md) + `docs/` (зонный журнал `platform-PROGRESS.md` · регистр дефектов · `STACK_DECISIONS.md` с рецептом стенда и инвентарём каналов шва · **[ENGINEERING_STANDARDS.md](../platform/docs/ENGINEERING_STANDARDS.md) — ратифицирован; КАЖДЫЙ промт платформенной сессии обязан на него ссылаться, отступление = пинг** · **[PLATFORM_DIRECTION.md](../platform/docs/PLATFORM_DIRECTION.md) — ратифицированное направление зоны: аутентификация, деньги, стандарты, скорость** · архив промтов). - `archive/` — история ([правила архива](archive/README.md)): закрытые промты (`prompts/`) · отчёты с ревью-шапками (`reports/` — на них ссылаются приёмки) · исполненные арх-доки (`architecture/`) · слайсы хроники `PROGRESS-*.md`. Инструкции оттуда не исполнять. -- Диаграммы: [../backend/docs/components.puml](../backend/docs/components.puml) · [../backend/docs/pipeline.puml](../backend/docs/pipeline.puml) — дом рядом с кодом (D39.80), правятся бэкендом одним коммитом с кодом; вручную НЕ рендерить (владелец смотрит PlantUML-расширением VS Code). +- Диаграммы: [../backend/docs/components.puml](../backend/docs/components.puml) · [../backend/docs/pipeline.puml](../backend/docs/pipeline.puml) — дом рядом с кодом (D39.80), правятся бэкендом одним коммитом с кодом; вручную НЕ рендерить — их смотрят нативно, рендер не нужен. -## Доступные ключи от моделей +## Ключи провайдеров -DEEPSEEK_API_KEY, ZAI_API_KEY, KIMI_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, XAI_API_KEY, MISTRAL_API_KEY +**Имена** переменных per-провайдер — поле `api_key_env` в `backend/configs/models.yaml` (носитель, который читает КОД, поэтому разойтись с реальностью резолва не может). У полигона свои дополнительные провайдеры — имена в его же скриптах, движковый носитель их не покрывает и не должен. **Наполненность** ключей — `.env` деплоя, его НЕ читать; при сомнении спрашивать владельца. ⚠ Ручной перечень здесь не держим: он уже лгал умолчанием — называл семь имён, когда в ходу было девять. diff --git a/docs/STACK.md b/docs/STACK.md index ef94f300..5a77e572 100644 --- a/docs/STACK.md +++ b/docs/STACK.md @@ -19,4 +19,4 @@ - **⚠0731 (D39.61):** flash пере-обучен под тем же слагом; `/models` молчал. Развилка решена вариантом (б): явный `reasoning_effort:"low"` черновику + ручка эффорта бэнк-ролям (код `553f1a3`). Версию модели проверять ПОВЕДЕНИЕМ. - **Вахта эффорта pro:** реестр загейченных триггеров — `architecture/13-tech-debt-anchors.md` §Б-108; статус ручки `low` на pro = НЕ УСТАНОВЛЕНО (quirks §3б). - **Цена:** ~$0.85/ранобэ (⚠ число ДО пере-пина цен 13–15.08: таблица запинена ПИКОМ, счёт шиппинга = 100% DeepSeek ⇒ ×4.2–4.4 в пике и ×2.1–2.2 в долине — D39.137; пере-калибровать первым же платным прогоном. D30.4; тело — `archive/architecture/05-decisions-D1-D38.md`, карта — шапка D-лога); пере-калибровка при следующем платном прогоне (112 залендена, D39.97). Edit-волна не гонялась на ПОЛНОМ холодном прогоне (строка 16); на малых прогонах отработала и оплачена — ⚠ прежний абсолют «НИ РАЗУ» ложен, испр. №19 по леджерам; ставка платформы $0.03/глава (D39.123 п.2г). Цены слагов — `models.yaml` (~~`prices_checked: 2026-07-10`~~ → **`2026-08-15`** (`backend/configs/models.yaml:34`=`prices_checked: "2026-08-15"`; бампнут факт-чеком ТОЛЬКО по DeepSeek — испр. 20.08); катовер 0731 цен не менял). -- **Ключи API:** список env-ключей — `docs/README.md` §«Доступные ключи» (7 шт.); резолв per-провайдер — `models.yaml api_key_env`. **`.env` НЕ читать** (гардрейл CLAUDE.md), `.env.example` можно. ⚠ **НА SaaS-ДЕПЛОЕ ДВИЖОК КЛЮЧЕЙ НЕ ПОЛУЧАЕТ ВОВСЕ** — строка бэклога **211**: замысел «читает `.env` рядом с `book.yaml`» записан комментарием платформы, а кладёт файл туда никто; дев-путь наследует окружение платформы, прод-путь нет, поэтому стенд зелёный, а прод голодает. Лечится движковым паком (путь к файлу ключей аргументом), D39.156. +- **Ключи API:** какой ключ нужен провайдеру — поле `api_key_env` в `models.yaml`, один носитель на факт. **`.env` НЕ читать** (гардрейл CLAUDE.md), `.env.example` можно. ⚠ **НА SaaS-ДЕПЛОЕ ДВИЖОК КЛЮЧЕЙ НЕ ПОЛУЧАЕТ ВОВСЕ** — строка бэклога **211**: замысел «читает `.env` рядом с `book.yaml`» записан комментарием платформы, а кладёт файл туда никто; дев-путь наследует окружение платформы, прод-путь нет, поэтому стенд зелёный, а прод голодает. Лечится движковым паком (путь к файлу ключей аргументом), D39.156. diff --git a/docs/product-requirements.md b/docs/product-requirements.md index 1c5f7fe1..7c86fcb1 100644 --- a/docs/product-requirements.md +++ b/docs/product-requirements.md @@ -9,7 +9,7 @@ | ID | Требование (источник) | Статус | Носитель / доказательство | |---|---|---|---| | ПТ-1 | Издательское художественное качество, победить translationese (V0 гл. цель; канон §1) | 🔶 | пайплайн draft→терминолог→editor→гейты→судья построен, адресная эскалация дорогой моделью есть (`pipeline/escalation.go`); качество добирается курсом «добор идеала» (D39.62/67, бэклог 24·65; 16 — непрогнанная edit-волна того же курса). Выводы-п.2 брифа (редкий узкий вызов за смыслами вне книги) — поглощён этим курсом, отдельный механизм не строится без замера | -| ПТ-2 | Пары zh/en/ru/ja ВО ВСЕ СТОРОНЫ (V0-п.11; V4-п.5: в zh→en русский не участвует); движок общий, пара = данные (канон §2) | 🔶 | построено только →ru: zh→ru боевая; ja→ru безопасна без правки Go, en→ru — нет (карта D39.60); не-ru target = антицель §0.1 в 09; носители: строки 81 (ja-преп) · 35 (не-CJK майнер) · 34 | +| ПТ-2 | **ЛЮБЫЕ пары языков, в любую сторону** — движок общий, пара = ДАННЫЕ (канон §2); «бэкенд только под русский» = объявленная антицель. Названные в брифе zh/en/ru/ja (V0-п.11; V4-п.5: в zh→en русский не участвует) — первые, а не полный список: продукт обязан поддержать и языки, которых в репозитории ещё нет (слово владельца 23.08) | 🔶 | построено только →ru: zh→ru боевая; ja→ru безопасна без правки Go, en→ru — нет (карта D39.60); не-ru target = антицель §0.1 в 09; носители: строки 81 (ja-преп) · 35 (не-CJK майнер) · 34 | | ПТ-3 | Книга ЦЕЛИКОМ (эталон 7,78 млн симв., ~2284 раздела) | 🔶 | гоняли ≤10 глав; волны/потолки/ETA на сотнях глав = строка 54 (МАСШТАБ) | | ПТ-4 | Референсы: предыдущие части серии / чужой перевод как контекст (V0-п.13–14) | 🔶 | серийный шаринг банка = строка 48а; импорт «оригинал+чужой перевод» = 48б (юр-сторона — 67) | | ПТ-5 | Неологизмы/выдуманные автором слова переводятся консистентно (V1-п.6) | 🔶 | банк+майнер держат термины книги; замер на вне-претрейн тексте = строка 55 | diff --git a/platform/docs/PLATFORM_P8_REVIEW_SESSION_PROMPT.md b/platform/docs/PLATFORM_P8_REVIEW_SESSION_PROMPT.md index 2335d06c..5c3c773c 100644 --- a/platform/docs/PLATFORM_P8_REVIEW_SESSION_PROMPT.md +++ b/platform/docs/PLATFORM_P8_REVIEW_SESSION_PROMPT.md @@ -117,6 +117,6 @@ **Эхо-протокол:** первым деливераблом ≤10 строк — «скоуп / инварианты / не-делать», как ты их понял. До работы. -**Артефакты для СЛЕДУЮЩЕЙ сессии — на durable АБСОЛЮТНЫЙ путь `~/tm-handoff/p8-review/`, не в scratchpad и не в копию дерева:** скрипты и патчи, которыми находка воспроизводится, обязаны пережить твою сессию — иначе «воспроизведение» остаётся только текстом строки регистра. В строке регистра ссылайся на этот путь. +**Артефакты для СЛЕДУЮЩЕЙ сессии — в репозиторий, в свою зону `platform/docs/`, не наружу и не в копию дерева:** скрипты и патчи, которыми находка воспроизводится, обязаны пережить твою сессию — иначе «воспроизведение» остаётся только текстом строки регистра. В строке регистра ссылайся на этот путь. **Сдача:** отчёт в `platform/docs/platform-PROGRESS.md` (записка-план по четырём осям · команды · таблица посадок · obstacle) + строки находок в `DEFECT_REGISTER.md` с воспроизведением. Дерево незакоммиченное, кода не тронуто. Без саги.