textmachine/docs/BACKEND_BOOKWRITER_PACK_SESSION_PROMPT.md

Промт: движок, пак «писатель книги» — переведённая книга становится ФАЙЛОМ

0. Какая проблема и что решит твой результат

Проект переводит книги и не умеет отдать книгу. Ни одной стороной. Движок отдаёт только поток: renderExport (backend/cmd/tmctl/render.go:565) печатает стабильный JSON tm-export-v1 либо --plaintext с аудит-баннерами === CHAPTER N CHUNK M ===. Греп epub|fb2|docx по backend/**/*.go минус _test.go даёт 43 строки, из них 26 в internal/chunk/ingest.go — всё на стороне ЧТЕНИЯ. ⚠ И писатель EPUB в дереве УЖЕ ЕСТЬ — backend/internal/chunk/chunktest/epub.go:37-112 (BuildEPUB/BuildEPUBAt): настоящий OCF-контейнер, mimetype первым и zip.Store, container.xml, content.opf с manifest+spine, XHTML. Он ТЕСТОВЫЙ, обратим ингесту по построению и запинен (ingest_test.go:537 TestEPUBFixtureMimetypeIsOCFConformant). Его шапка предупреждает: дублирование zip/OPF-строителя развело бы две копии. Начинать с него — как именно, размечено в §3.1. Платформа обещанные каноном ручки выдачи не монтирует, её ExportFormats захардкожен пустым (platform/cmd/tmplatformd/runner.go:191).

Что решит твой результат: переведённую книгу можно будет открыть в читалке. Сегодня цель №1 канона («издательское художественное качество») не проверяется ничем на выходе: результат некуда открыть. Носитель — строка 236 единого бэклога, вес «блокер-очереди», пункт 1 очереди №20.

Чего твой результат НЕ решает: дверь платформы (createExport/getExport) — отдельная работа ПОСЛЕ живого прогона, потому что до него неизвестно, что реально кладётся в файл.

1. Зона записи и git

Пишешь только в backend/. Не коммитишь: дерево готовишь и передаёшь оркестратору. Канон git — в CLAUDE.md, здесь не дублируется.

2. Карта чтения — ПЯТЬ позиций, дальше только по их ссылкам

1. backend/internal/pipeline/export.go — прежде всего блок CAVEATS над Export: три состояния КНИГИ, о которых файл обязан не соврать. ⚠ Ещё два состояния — ПОЮНИТНЫЕ, в CAVEATS их нет; они в §3.2.
2. backend/cmd/tmctl/render.go:562-630=func renderExport — существующий рендер: чем --plaintext НЕ годится в качестве книги (аудит-баннеры, флаги в скобках) и арифметика withheld/incomplete (:573-587), которую твой файл обязан повторить.
3. backend/internal/chunk/ingest.go — как книга РАЗБИРАЕТСЯ из epub: писатель обязан быть обратим к этому чтению, иначе круг «загрузил → получил» не замыкается (§4 — равенством, не парсом).
4. docs/architecture/12-go-style-notes.md §0 — норматив общности: пары языков это ДАННЫЕ.
5. docs/PROGRESS.md, строка БЭКЛОГА 201 (grep -n '^| 201 |') — синтетический заголовок едет внутри текста юнита; твоя граница, см. §3.3.

3. Работа

3.1 Что построить (делай РОВНО так)

Движковый писатель книги из BookExport, вызываемый из tmctl. Минимум два формата: EPUB (книга для читалки) и чистый текст — без аудит-баннеров === CHAPTER …, без флагов в скобках и без операторских маркеров вроде gapMarker (render.go:56-67 — английская лексика аудит-поверхности, читателю не годится). ⚠ Это запрет на ОПЕРАТОРСКИЙ словарь, не на честность: как показать читателю неполноту — решение §3.2. Существующий --plaintext не трогать и не переименовывать — это его ВЫВОД, запинённый export_cli_test.go/exportgap_cli_test.go; вынос арифметики withheld/incomplete в общий хелпер допустим. JSON — машинная поверхность двух потребителей: полигон (eval/README.md:80=для глаз — «--plaintext для глаз, дефолтный JSON для скриптов») и платформа (platform/internal/runner/engine.go:148=func ExportArgs → :191 ingest.DecodeExport); менять форму tm-export-v1 — значит менять платформу из чужой зоны.

⛔ ОДИН файл на книгу на формат — так требует контракт (docs/architecture/14-api-contract/openapi.yaml:2489-2492=A built copy of the book: Export = «A built copy of the book, behind a link»); деление на главы живёт ВНУТРИ файла (spine EPUB, разделители в txt), а не набором файлов.

Основа — chunktest/epub.go (инварианты — РОВНО так, форму выноса решаешь сам). Напрямую из tmctl он невызываем: принимает *testing.T и зовёт t.Fatal/t.TempDir() (epub.go:37-50), а копировать его второй раз запрещает его же шапка. Значит общую OCF-часть (mimetype первым и zip.Store, container.xml, запись entry) выносишь в прод-пакет без import "testing" и переводишь chunktest на неё — либо пишешь прод-писатель от его инвариантов и аргументируешь, почему две копии не разойдутся. Инварианты: import "testing" в прод-коде запрещён · тест-файлы, импортирующие chunktest (их 9), остаются зелёными БЕЗ правки ассертов и сигнатур · в прод НЕ переезжает ничего тестового: ручки MType/EntryName, OPF-заглушка с <dc:title>Test</dc:title> и висячим unique-identifier="uid" (epub.go:89-90), XHTML-шаблон epub.go:103 с <title>c</title><style>.x{color:red}</style> — это ДЕКОЙ, на который сидит ingest_test.go:95; поднятый в прод, он уедет читателю в каждую главу.

⛔ Файл обязан быть ДЕТЕРМИНИРОВАН: два прогона на одних данных дают побайтово одинаковый файл. EPUB — это zip. У archive/zip из stdlib таймметки записей по умолчанию нулевые, порядок записей = порядок вызовов Create — стартовый chunktest/epub.go этим уже детерминирован. Утечку вносишь только сам: FileHeader.Modified/zip.FileInfoHeader от файловой системы, обход map при записи, и — главное — <meta property="dcterms:modified">, которую EPUB 3 ТРЕБУЕТ (§3.3-бис): значение бери детерминированное из данных прогона, не time.Now(). ⛔ Провалившийся cmp чинить удалением этого элемента НЕЛЬЗЯ — получишь неконформный EPUB. Докажи прогоном двух ПРОЦЕССОВ, а не рассуждением.

3.2 Пять состояний, о которых файл не имеет права соврать (делай РОВНО так)

Три — счётчики BookExport; Export их уже вычисляет (блок CAVEATS) — не изобретай заново:

• PendingUnits > 0 — книга переведена НЕ ЦЕЛИКОМ.
• GhostRows > 0 — есть строки вне текущего манифеста (в Chunks их нет по построению — состояние доступно только счётчиком).
• ConfigDrift == true — текущий конфиг рендерит не тот снапшот, что несут строки.

⚠ Ещё ДВА — ПОЮНИТНЫЕ, в счётчиках BookExport их НЕТ; renderExport считает их сам (render.go:573-587, баннеры :601-622) — повтори эту арифметику, не изобретай:

• withheld — Disposition != "pending" && FinalText == "": substantive-флаг или skip выше по конвейеру, текст сознательно не отгружен (D2: заражённый вывод не отгружается; export.go:359-395). PendingUnits его НЕ считает. ApplyHeading на пустой текст заголовок не клеит, так что глава молча начнётся со СЛЕДУЮЩЕГО юнита.
• incomplete — DroppedMembers > 0 при непустом FinalText: c-lite выбросил член юнита, текст настоящий, но с дырой без шва (export.go:45-54; причина — DroppedReason).

Живая посадка на оба — acceptance (числа в §4): при pending_units=0 там удержан открывающий юнит книги и усечён юнит главы 10. Файл, сверенный только с тремя счётчиками, там выйдет «молча полным» — худший исход этого пака.

Рамка ратифицирована ДО этого пака и бьёт «решаешь сам»:

• Контракт 14 (D39.99; docs/architecture/14-api-contract/openapi.yaml:836-853=finished or not, createExport): неполная книга экспортируется — «may be exported, finished or not», а ЧТО содержит файл неполной книги — «not fixed here», то есть решается ЗДЕСЬ. Следствие: «только отказ» как единственное поведение НЕДОПУСТИМО — дверь платформы обязана уметь выдать неполную книгу.
• D29.1(б): reader-facing выдача — fail-closed (0 красных для structurally_complete). D25.1 требует ратифицировать лестницу run_complete / structurally_complete / quality_reviewed / publishable ДО первого reader-facing артефакта; семантика «publishable» и право waiver — у владельца. Решение оркестратора №20, не твой вопрос: reader-facing артефакт — выдача читателю через дверь платформы; этот пак строит МЕХАНИЗМ файла с двумя обязательными поведениями ниже, а лестница ратифицируется владельцем между этим паком и дверью — по твоему вопросу в отчёте (какие ступени писатель обязан различать, что печатать на титуле и в имени файла). Поэтому лестницу в коде не изобретай и в BookExport не добавляй; молчаливый полный файл на книге с любой дырой НЕДОПУСТИМ.

Делай РОВНО так: файл с любой дырой (pending · withheld · incomplete) либо не пишется — отказ с перечнем дыр (глава/юнит/причина), либо пишется с явной пометкой неполноты на титуле и видимым маркером на месте КАЖДОЙ дыры. Оба поведения обязаны существовать (одно по умолчанию, другое флагом) — какое по умолчанию и как выглядят пометка и маркер, решаешь и аргументируешь; словесная форма для читателя — данные пары, не литерал в Go (§3.5). Для ghost и drift контракт ничего не фиксирует — отказ или пометка на твой довод. Три ограничения на форму:

• ⛔ Не в снапшот. Загрузчик пака складывает байты КАЖДОГО присутствующего опционального файла в pack.Version() (backend/internal/lang/langpack.go:289-298=h.Write), а она входит в snapshot-id стадий (backend/internal/pipeline/snapshot.go:381=LangpackVersion): новый файл-данные по этому контракту = resnapshot = перекупка каждой книги с langpack_root. Читательские слова — факт РЕНДЕРА, не перевода: канал для них НЕ складывается в Version() (отдельный не-фолдимый файл рядом с паком или вне пака) — форму решаешь и аргументируешь. Доказательство командой: current_snapshot экспорта копии minirun до и после добавления твоего файла-данных — тот же. ⚠ На стенде сдвиг НЕВИДИМ: minirun уже под дрейфом, cmp двух прогонов его не ловит.
• ⛔ Книга без langpack (acceptance; runner.go:346 → пак nil) словесной формы не имеет по построению — а это единственная реальная посадка на withheld/incomplete. Там пометка и маркер — несловесные (номер главы/юнита, символ) либо отказ; что именно — реши и аргументируй. Словесный fallback в Go запрещён, langpack_root в копию — запрещён (§3.3).
• ⚠ Маркер дыры — НЕ в FinalText и не в export.go: провод платформы судит translated/withheld предикатом «текст непуст» (platform/internal/ingest/export.go:104=func unitState).

3.3 Синтетический заголовок — НЕ твоя развилка (делай РОВНО так)

Заголовок «Глава N» сегодня клеится ВНУТРЬ текста юнита — export.go:266, и ещё в ДВУХ точках waverun.go:647 и waverun.go:721 (третья — путь draft-only отгрузки). Инвариант, который они держат и который назван в самом коде: tmctl export и tmctl translate отгружают побайтово одинаковый текст.

⛔ Трогать ApplyHeading и любую из трёх точек ЗАПРЕЩЕНО. Дизайн глав НЕ ратифицирован (D39.122 п.2д: heading манифеста — ВРЕМЕННЫЙ рендер движка), а форма для него уже назначена: строка бэклога 160 «Структура глав, Этап 0», гейт которой пал словом владельца 15.08 (D39.136 п.3) — она едет ОТДЕЛЬНЫМ, следующим бэкенд-паком с мандатом максимального качества; отсрочка — решение оркестратора (очередь №20 ставит писателя первым), не твоё. Строка 201 — её родня и стоит «когда-нибудь (с 160)». Этот пак её не решает и не предвосхищает.

Что делать вместо: заголовок для оглавления — тот же детерминированный литерал, который Export УЖЕ держит в момент сборки записи: u.Members[0].Heading (export.go:266). Он приходит через readModelChunks (manifest.go:550) — из сайдкара ManifestChapter.Heading (manifest.go:108), когда тот есть, иначе из пере-нарезки; на обоих путях литерал один (проверено: экспорт minirun без сайдкара и с ним побайтово одинаков). ⚠ Сайдкар <project_db>.manifest.json (manifest.go:137) у minirun/acceptance/coldrun-a ОТСУТСТВУЕТ, loadManifest (manifest.go:436-443) на отсутствующий файл МОЛЧА отдаёт nil, а ChunkExport заголовка не несёт вовсе. Поэтому: писатель сайдкар НЕ читает, tmctl manifest НЕ требует и манифест побочно НЕ пишет. Донести заголовок до писателя — либо in-process (писатель в pipeline, рядом с Export), либо аддитивным полем ChunkExport (heading, omitempty — безопасно, §3.3-бис). Форма tm-export-v1 при этом не меняется, разбирать текст не надо. Если текст юнита начинается тем же заголовком — срезать ИЗВЕСТНЫЕ байты префикса (ApplyHeading — чистая склейка heading + "\n\n" + text, chunker.go:186-192), только при Heading != "", а не угадывать эвристикой.

⚠ Heading бывает "", и это ратифицированно легальное состояние (D39.100 п.1, К-3: зашитой формы «Глава N» не существует, легальна книга без глав вовсе; manifest.go:102-103). Два пути: книга без правила заголовка — acceptance/book.yaml не объявляет langpack_root (runner.go:346), и у неё "" у ВСЕХ 25 глав; глава без структурного маркера — глава 1 той же книги остаётся "" даже с правилом. ⛔ Не «чини» это добавлением langpack_root в копию: состав книги от этого не меняется (те же 37/0/20 — экспорт джойнит по (chapter, chunk_idx)), но правило заголовка меняет ЭКСПОРТНЫЙ ТЕКСТ — ApplyHeading наклеит «Глава N» поверх модельного заголовка в 24 юнитах из 37 («Глава 3\n\nГлава 3: Иди-…»), файл перестанет быть той книгой, что переводилась, а посадка «книга без правила» исчезнет. Что стоит в оглавлении при Heading == "" — реши сам и аргументируй, при двух запретах: никакого словесного литерала в Go («Глава», «Chapter», на любом языке) — только данные (номер главы числом, маркер из данных пары); модельные заголовки внутри прозы («Раздел второй…», «### Шестой раздел…» и — при Heading == "" — «Глава 3: …» у юнитов 3/0, 12/0, 25/0 acceptance) не извлекать и не править — это строка 160; срез префикса только по u.Members[0].Heading, никогда по слову «Глава». Пустой текст ссылки в nav — невалидный EPUB. ⚠ Если найдёшь причину, по которой так нельзя, — пинг, а не своё решение: вопрос гейчен владельцем.

3.3-бис Метаданных книги в BookExport НЕТ — учти до кода

BookExport несёт Version, BookID, TotalUnits, PendingUnits, GhostRows, ConfigDrift, CurrentSnapshot, Chunks — и ни заголовка, ни языка, ни автора. Поля юнита — ChunkExport (export.go:25-55): Chapter, ChunkIdx, SnapshotID, Disposition (ok|flagged|pending), FlagReason, Detail, FinalText, Source (только --pairs), DroppedMembers/DroppedReason; заголовка нет — он внутри FinalText (§3.3).

EPUB 3 требует ПЯТЬ вещей, не три: dc:identifier (на него ссылается unique-identifier пакета), dc:title, dc:language, <meta property="dcterms:modified"> в форме CCYY-MM-DDThh:mm:ssZ и nav-документ (properties="nav" в manifest). Фикстура chunktest несёт только dc:title — epubcheck даёт на ней 5 ошибок; она образец контейнера, не метаданных. ⛔ nav в spine НЕ класть: ingest.go читает каждый spine-документ как главу (проверено: nav в spine → лишняя глава), и круг §4 ломается. ⛔ dcterms:modified — не time.Now() (§3.1): константа-эпоха либо величина из данных экспорта (например, из CurrentSnapshot) — выбор аргументируй. dc:identifier — детерминированная строка от BookID.

Заголовок и язык достижимы из config.Book (book.go:25-27: Title, SourceLang, TargetLang). ⚠ Title — отображаемое имя книги, не заголовок на языке цели: на стенде у всех книг title: 蛊真人, из платформы приходит ввод пользователя или имя файла; поле входит в замороженный BriefHash (book.go:337-345). Бери как есть, назови ограничение в отчёте; ⛔ перевод названия не выдумывать (ни литералом, ни транслитерацией, ни платным вызовом) и title в book.yaml не менять (смена = re-bill). Автора в проекте нет вовсе — источника для dc:creator не существует, и выдумывать его не надо. ⛔ dc:language берётся из TargetLang, а не литералом: пары — данные. Решаешь сам: расширять ли BookExport/ChunkExport (⚠ добавление поля безопасно: DecodeExport платформы — json.Unmarshal без DisallowUnknownFields, platform/internal/ingest/export.go:78-80=func DecodeExport; полигон формы не проверяет; ПЕРЕНОС существующего поля — нет) или брать метаданные мимо него.

3.4 Куда пишется файл — размечено, не додумывай

cmd/tmctl сам файлов не пишет (греп os.Create|os.WriteFile по cmd/tmctl/*.go минус тесты пуст), но движок пишет их слоем ниже, и у них есть конвенция: сайдкары через pipeline.writeFileAtomic (backend/internal/pipeline/artifact.go:26=func writeFileAtomic; используют manifest.go:401, bankexport.go:152, mining.go) — место рядом с ProjectDB, запись атомарная, путь ПУБЛИКУЕТСЯ в конверте StatusArtifacts (status.go:115-145), и платформа берёт пути ТОЛЬКО оттуда (platform/internal/runner/artifacts.go:39=no bank read-out path; закон шва docs/architecture/17-seam-inbound-law.md §1 — движок владеет путями своей схемы, платформа путь не выводит сама). Приор (опровергается аргументом): файл книги — такой же движковый артефакт: детерминированное место рядом с ProjectDB, атомарная запись, строка в StatusArtifacts; флаг явного пути — сверх этого, не вместо. Реши и аргументируй: форма вызова — новый глагол tmctl или флаг у export (глаголы — замороженный список main.go:182; форму потом читает дверь платформы) · флаг пути или конвенция · поведение при существующем файле (перезапись или отказ — у бэкапа отказ, store/backup.go) · публикуешь ли путь в конверте уже в этом паке. Коды выхода — замороженный словарь (backend/cmd/tmctl/main.go:51-145=refusal band, запинен exitcontract_test.go): отказ §3.2 — новый pipeline.RefusalClass (refusal.go) с константой в полосе 10–19, с доводом; чисел вне 0–5/10–19 не заводить. Молча выбранная форма здесь дороже неверной: её потом читает платформенная дверь выдачи.

3.5 Границы

• ⛔ Платформу не трогать вообще. Её дверь — следующая работа, не твоя.
• ⛔ Формат tm-export-v1 не менять без явного довода: его потребляет полигон и платформа (аддитивные поля по §3.3-бис — не смена формы).
• ⛔ Пары языков — данные. Если твой писатель знает слово «Глава», «Оглавление» или порядок имени автора — это утечка.
• Внешние зависимости: EPUB это zip + XHTML, и стандартная библиотека это умеет (archive/zip, encoding/xml); норма — «least mechanism» (docs/architecture/12-go-style-notes.md §1, строка 24: сперва stdlib, только потом своё/зависимость). ⚠ Носителя STACK_DECISIONS у бэкенда НЕТ — файлы с этим именем лежат у фронта и платформы, это чужие зоны: новая зависимость = довод в записке-плане §6 и пинг оркестратору ДО go get.

4. Самопроверка ИСПОЛНЕНИЕМ (без неё работа не принята)

• ⚠ ДАННЫЕ — замерено на копиях 30.08 (HEAD 8977001), пере-прогони сам. В books/ нет ни одной книги, которую tmctl export берёт как есть, и ни одной без CONFIG-DRIFT.
  • coldrun-a НЕ переведена — не строй на ней доказательство. Только волна draft (20 строк chunk_status), финальной стадии нет ни у одного юнита; схема v14; после миграции экспорт даёт 14/14 pending и drift. Годна лишь как естественный образец «pending».
  • minirun (схема v10; chunk_status draft 20 / edit 14) — после миграции 14/14 ok, pending 0, config_drift: true (обе волны). Единственная «полная» реальная книга; заголовки есть (langpack_root задан → первые юниты начинаются «Глава N\n\n»). Рядом трекнуты export.json/export.txt — экспорт ТОЙ ЖЕ БД июльским бинарём (config_drift: false, старая форма без export_version): сегодняшний tmctl немигрированную v10 экспортировать отказывается (exit 13), так что это единственный до-миграционный оракул; после миграции final_text/snapshot_id/disposition обязаны совпасть 14/14 — покажи командой, это доказательство, что миграция и дрейф текст не тронули. Файлы не править.
  • acceptance (v7; chunk_status 57/57 строк — это НЕ юниты) — на HEAD экспорт даёт 37 юнитов, ghost_rows: 20, drift, 35 ok + withheld 1/0 + incomplete 10/0; нарезка сменилась с июля, «57» на HEAD не существует, восстанавливать не надо. Заголовков нет (§3.3). Это посадка сразу на ghost, drift, withheld и incomplete.
  • Дрейф на этом HEAD неустраним — разошлись Go-константы снапшота (версии chunker/classifier/ sanitizer/style_check) и промты; снять его может только платный перепрогон (--resnapshot = re-pay, ⛔ не делать). Следствие для §3.2 — в записку-план, не в конец работы: чистый бездрейфовый файл на реальной книге НЕДОСТИЖИМ; чистый путь и pending доказывай на синтетике (харнессы ниже), реальные книги — как посадки на drift/ghost/withheld/incomplete. Выбрал «отказ при дрейфе» по умолчанию — реального EPUB у тебя не будет: заяви это в плане с доводом.
  • ⛔ books/ — отдельный git-репозиторий со своим origin, .db в нём ТРЕКАЮТСЯ; работай на копии в песочнице — но cp -r каталога КОПИЕЙ НЕ ЯВЛЯЕТСЯ. book.yaml, pipeline*.yaml и pairs/*.yaml всех трёх книг несут АБСОЛЮТНЫЕ пути, и на этой машине они РЕЗОЛВЯТСЯ: /home/ubuntu/books — симлинк на оригинальный books-репозиторий, /home/ubuntu/projects/textmachine/… — ЧУЖОЙ ворктри (ветка polygon, живая сессия). LoadBook абсолютный путь не пере-рутит (backend/internal/config/book.go:173=filepath.IsAbs), tmctl migrate мигрирует book.ProjectDB на месте и кладёт backups/ рядом (migrate.go:83-84); даже read-only export/status открывают WAL и создают .lock/-wal/-shm рядом с оригиналом. Порядок: go build -o <песочница>/tmctl ./cmd/tmctl из backend/ → скопировать каталог книги + gu-zhenren/langpack-extend
    • сиды gu-zhenren/guzhenren-seed*.yaml + исходный txt в песочницу → переписать КАЖДЫЙ абсолютный путь в копиях (project_db первым, затем pipeline, source_file, glossary_seed, langpack_extend, models, langpack_root, pairs/zh-ru.yaml: prompts_root, pipeline.yaml: prompt_override и mining.contrast_path — последний формально: файла в этом дереве нет, его открывает только майнер, mining.go:58) на песочницу и на backend/ ЭТОГО ворктри → grep -rn --include='*.yaml' '/home/ubuntu/books\|/home/ubuntu/projects/textmachine/' <копия> обязан быть пуст (старые пути в run-*.log и в комментарии langpack-extend/zh/surnames-compound.txt движок не читает — не трогать) → только потом tmctl. Доказательство: git -C books status --short -- gu-zhenren до и после — одинаковый вывод, без новых backups/, .lock, -wal, -shm (весь books/ не сравнивай — параллельная полигон-сессия пишет в dovodka/ и chtenie-rol/; строки D gu-zhenren/*/*.db-wal/-shm стоят там ДО тебя — репозиторий трекает wal/shm).
  • Хирургия конфигов В КОПИИ (движок называет каждую причину сам, exit 10): у minirun и coldrun-a удалить ретайрнутые mined_delta:/mined_rejects: (D39.156 п.3); у acceptance в pipeline-acceptance.yaml убрать context.stm_depth/overlap_tokens и prompt: у обеих стадий (промты резолвятся конвенцией <prompts_root>/<пара>/<роль>.md) и положить рядом pairs/zh-ru.yaml (образец — minirun/pairs/, prompts_root на backend/prompts этого дерева). Все правки — списком в отчёт.
• Файл проходит валидатор EPUB — и это проверяется механически. Проверено 30.08: calibre/ ebook-convert, python-библиотек epub и CLI zip на машине нет, но java ЕСТЬ (/usr/bin/java, OpenJDK 21) и сеть доступна — epubcheck приносится одной командой в песочницу: curl -sL -o epubcheck.zip https://github.com/w3c/epubcheck/releases/download/v5.3.0/epubcheck-5.3.0.zip && unzip -q epubcheck.zip && java -jar epubcheck-5.3.0/epubcheck.jar <book>.epub (проверено: качается ~33 МБ, запускается, валидирует). Это официальный валидатор W3C — механический верификатор оси «издательский результат». Прогони им КАЖДЫЙ сданный EPUB, порог — 0 fatals / 0 errors, warnings перечисли в отчёте с диспозицией; ошибки чинить у писателя, не глушить. Jar живёт в песочнице — в репозиторий и в зависимости не попадает. Не удалось принести — в obstacle команда и её вывод, и тогда «проверено структурно, не валидатором» — не выдавай второе за первое. ⚠ Валидатор — не читалка: «валиден» ≠ «открылся»; читалки на машине нет, эту ось так и помечай.
• Круг замыкается — РАВЕНСТВОМ, не парсом. chunk.IngestEncoded(<твой.epub>, "", "") (epub-ветка языка и langpack не читает — ingest.go:77-82) и покажи командой: (а) len(doc.Chapters) == число глав книги — ингест кладёт в doc.Chapters КАЖДЫЙ XHTML-документ spine, пустой тоже (ingest.go:534; пустота лишь лишает его плотного номера, :540), поэтому nav/титул в spine не класть даже без текста, а глава без текста — легальная пустая глава; (б) абзацы каждой главы (разрез по пустым строкам, trim, пустые прочь — как splitParagraphs, chunker.go:458) совпадают с абзацами, которые положил писатель, с учётом решения §3.3 о заголовке. Абзац = свой блочный элемент (<p>); <br/> абзаца не даёт (blockTags, ingest.go:614); побайтово текст не совпадёт — сравнивай абзацы. err == nil сам по себе не доказывает ничего: вся книга одним документом «разбирается» одной главой.
• Детерминизм: два прогона в двух ПРОЦЕССАХ → cmp побайтно. Покажи команду и результат.
• Пять состояний §3.2 — по посадке на каждое: pending (coldrun-a или синтетика) · ghost, drift, withheld, incomplete (все четыре есть на acceptance) · чистая полная книга — только синтетика. Две посадки УЖЕ есть — не изобретай: backend/internal/pipeline/export_test.go TestExportManifestPending (:186) и TestExportDetectsConfigDrift (:229) на хелперах из runner_test.go. ⚠ Ghost-посадки в тестах НЕТ (греп GhostRows по *_test.go пуст) — строишь сам, отдельной строкой в отчёте. Golden-харнесс (golden_test.go) — гард wire пайплайна, не инструмент для твоего файла; TM_UPDATE_GOLDEN не трогать. Каждое состояние обязано отработать так, как ты решил, и это видно в файле или в отказе. Файл реальной книги, её копии и cmp-вывод — рабочее временное в песочнице: в отчёт идут команды и вывод; воспроизводимость на приёмке держит герметичный тест писателя в backend/ на синтетической книге (chunktest.BuildEPUB, образец герметичного Export — export_test.go).
• ⛔ Править или удалять тест ради зелени НЕДОПУСТИМО (D39.121). Это не абстракция: любой вариант, трогающий заголовок, красит backend/internal/chunk/chunker_heading_test.go:121, и самый дешёвый способ вернуть зелень — правка ассерта. Несогласие с тестом — пинг, а не правка.
• Дифф ^func Test — ИСПОЛНЕНИЕМ, не памятью: покажи командой, что ни один тест не исчез.
• Интервальная самоверификация (D39.121): пак длинный, поэтому в СЕРЕДИНЕ работы — проход субагента по готовой части против явных критериев, а не только в конце.
• make battery целиком, не go test: линтер идёт ДО тестов, и на этом уже попались двое. -race обязателен.
• Разрешаю субагентов (иначе дефолт харнесса тихо запретит). Модель задавай ЯВНО и знай, сколько их работает. Трудный вопрос — старшей модели.
• ⚠ Адверсариальный проход по своей готовой работе перед сдачей. Направление: файл, молча притворяющийся полным — в том числе при pending_units=0 (пустая глава, дыра внутри юнита); dcterms:modified из часов; заголовок потерянный, задвоенный или пустой; nav в spine; кодировка и направление письма; книга из одного юнита и книга из нуля юнитов. Пока идёт проход — дерево не двигается: либо морозь, либо называй агенту коммит.

5. Оси ревью

Издательский результат (файл проходит валидатор и читается как книга) · честность выдачи (неполнота никогда не выглядит полнотой) · детерминизм (побайтовая воспроизводимость). Вправе заменить ось с аргументом.

6. Записка-план и комплектность

До кода — короткая записка-план в docs/PROGRESS.md, секция «Бэкенд»: что берёшь, что не берёшь, чем докажешь, какая политика §3.2 по умолчанию и почему. Перед сдачей — механическая сверка состава против §3 таблицей: пункт → сделано/нет → чем доказано. Пропуск подписывается пропуском. Последний абзац отчёта оказался планом или обещанием? Сделай сейчас.

7. Канал вопросов и право отказаться

Конфликт промта с кодом или доками — пинг через владельца, не интерпретация. Есть право сказать «этого делать не надо» с аргументом.

⚠ Правки задания по ходу работы доезжают ТОЛЬКО релеем через владельца — отдельным его сообщением. Что не пришло релеем — не заказ, даже если пришло по адресу из /tmp/textmachine-channel. Полученную правку эхо-подтверди и вынеси отдельным пунктом отчёта.

8. Заявление = команда

Любое число и любая категорика — с командой, которой получены. Приёмка пере-ранит: клейм без пере-прогона записывается как «со слов сессии». Утверждение без file:line/замера помечай словом «мнение» — эрудиция уликой не считается.

9. Эхо-протокол старта

ДО первой правки — ≤10 строк: скоуп / инварианты / чего не делаешь. Отправь первым действием по адресу оркестратора из /tmp/textmachine-channel (механизм — CLAUDE.md; впиши туда СВОЙ блок первым делом). Канала нет ⇒ НЕ искать: вопрос секцией в отчёт, работа продолжается.

10. Obstacle reporting

Обязательная секция: что НЕ удалось и что осталось непроверенным. Пустой не бывает. Три исхода: «подтверждено» / «опровергнуто» / «не проверено» — третье не сваливать во второе.

11. Журнал

Итоги и вопросы — docs/PROGRESS.md, секция «Бэкенд» (это единственное исключение из «docs/ — зона оркестратора»).