heaven/textmachine
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
textmachine/docs/DOC_CLEANUP_PLAN.md

28 KiB
Raw Blame History

ПЛАН РАЗБОРА ТЕХДОЛГА ДОКУМЕНТАЦИИ — заказ владельца 01.09.2026

⚠ РЕДАКЦИЯ 2. Редакция 1 ОТКЛОНЕНА контролёром (Fable 5.1) и переписана. Что он нашёл и что исправлено — раздел «Почему ред.1 отклонена». Главное: реестр находок был собран с дефектом атрибуции, и план исполнялся бы по чужим поправкам.

⚠ ВРЕМЕННЫЙ РАБОЧИЙ ДОКУМЕНТ. По закрытию последнего батча уезжает в archive/ вместе с реестром. Держать его в живых доках после закрытия — сделать ровно то, против чего он заказан.

Заказ владельца дословно: свести находки в план и идти по нему · привести документацию в хороший порядок · с бэклогом ПООСТОРОЖНЕЕ · спилить лишнее, актуализировать · старое и откровенно лишнее выкинуть, актуальное оставить и НЕ ПОТЕРЯТЬ · старые решения и мусор спиливать, чтобы не забивать контекст сессиям · касается фронтовой, платформенной и бэкенд-документации (прямая санкция на чужие зоны, 01.09).

Контроль исполнения — агент модели Fable 5.1, поднят по оригинальному воркфлоу ревью (получил скрипт воркфлоу и сырой журнал 30 агентов). Контекст у него сквозной и не стирается. После КАЖДОГО коммита я предъявляю коммит, он сверяет с реестром и выносит вердикт. Мой самоотчёт закрытием не считается. Пинг-понг идёт, пока ОБЕ стороны не скажут «закрыто».

Почему ред.1 отклонена (находки контролёра, все проверены моей командой)

  1. Реестр собран с дефектом атрибуции. Вердикты опровергателей присваивались по паре (файл, строка), а на одной строке сидит до ШЕСТИ находок (docs/PROGRESS.md:3 — шесть). Все они получали поправку ПОСЛЕДНЕЙ. Затронуто 10 находок. Цена, если бы пошёл по ред.1: переписал бы docs/README.md:29, которую ДВА опровергателя независимо велели не трогать; снял бы с листа владельца живое обязательство (N076); искал бы в docs/ файл, который уже в архиве (N075). Исправлено: матч по дословной цитате, 82 вердикта на 82 разные находки, дублей 0.
  2. N015 носила чужой вердикт «ПОДТВЕРЖДЕНО», не выносившись на пере-суд. Исправлено: honest «НА ПЕРЕ-СУД НЕ ВЫНОСИЛАСЬ».
  3. Улики были обрезаны на ~700 знаках, и в хвостах терялись именно положительные контроли; разбор опровергателей (reasoning, 82 вердикта с уликами) в реестр не попадал вовсе. Исправлено: реестр без капа, с разбором.
  4. Б13 ред.1 был батчем на ПОТЕРЮ: три позиции из четырёх противоречили выводам ревизии (platform/docs/p8-review/ цитируется боевым тестом spendbound_test.go; backend/docs/SEAM_* — носитель D39.158 ссылается на них пятью местами; MONEY_HONESTY_REPORT назначен носителем живого остатка строки 232). Осталась ОДНА законная позиция — переезд отработавшего промта.
  5. Б9 «баннеры ИЛИ архив» — «или архив» снят: 01/04/06 цитирует Go-код десятком мест.
  6. «Планы доработок в бэкенд и платформу» вынесены из плана: это заказ (0б), а не техдолг доков; держать его критерием «техдолг закрыт» нельзя — он бесконечен по определению.

Источники

Дисциплина разбора (жёсткая)

  1. Поправка опровергателя ПЕРВИЧНА. Где в находке стоит «⚠ ПОПРАВКА ОПРОВЕРГАТЕЛЯ» — исполняется она, а не «Предложенное действие». Поправка есть у 67 из 130, и часть ПРОТИВОПОЛОЖНА исходному действию.
  2. Не вписывать новые голые file:line — сгниют так же. Форма: токен-якорь файл:строка=`подстрока` либо ссылка на символ. Прямо требуют десять поправок.
  3. Вес находки не одинаков. «НА ПЕРЕ-СУД НЕ ВЫНОСИЛАСЬ» = проверена одним агентом = наряд на перепроверку. Верифицировать своей командой ДО правки.
  4. Не потерять. Перед удалением абзаца/строки/дока — грепнуть отличительный токен и назвать адрес, куда уехало содержимое. Удаление без адреса = потеря.
  5. Бэклог — осторожно. Строка закрывается ТОЛЬКО с предъявленным в коде лекарством. ID строк стабильны навсегда, на них ссылаются доки: закрытая строка уезжает в D-ноту с номером решения.
  6. Чужие зоны. Санкция владельца — на ДОКУМЕНТАЦИЮ; код чужих зон не трогаю. Объявление = строка в зонном журнале ТЕМ ЖЕ коммитом (иначе зона не увидит).
  7. Гейты перед каждым коммитом: counts.py --check и --lint, git status на чужое, коммит только явным списком путей.
  8. ⛔ Соседний worktree /home/ubuntu/projects/textmachine — НЕ ТРОГАТЬ ВООБЩЕ (указание владельца 01.09): ни чтением, ни git -C. books/ — симлинк туда же.

Порядок и зависимости (требование контролёра)

  • Б0 идёт первым: факт «канон 0.9.0» размазан по пяти батчам; пять коммитов дали бы четыре промежуточных состояния, где часть носителей врёт.
  • Б2 (переезд промта) — до Б4: N075 даёт развилку «перенести файл ИЛИ переписать текст». Если Б4 выберет текст, а Б2 потом перенесёт файл — текст снова ложь.
  • Б1 — одна нота на четыре строки (194/238/239/240): это одно событие, лендинги 31.08.
  • Б6 после Б4: якоря реестра 13 ссылаются на строки бэклога.

Батчи

Батч Предмет Находок бл/maj/min Статус
Б0 СКВОЗНОЙ: «канон 0.9.0» одним касанием — требование контролёра 2.2 7 0/6/1 ✅ ЗАКРЫТ
Б1 Блокеры бэклога + строка 240: ОДНА нота на четыре строки 4 3/1/0 ✅ ЗАКРЫТ
Б2 Переезд ОТРАБОТАВШЕГО промта (git mv) — раньше Б4, т.к. N075 от него зависит 2 0/0/2 ⬜
Б3 Денежный путь 15-money-path.md (+ парная правка 17:101 по N004) 7 2/3/2 ⬜
Б4 Шапка журнала и остальной бэклог 14 0/7/7 ⬜
Б5 Контракт API 14 8 0/4/4 ⬜
Б6 Реестр загейченных триггеров 13 8 0/5/3 ⬜
Б7 Шов и эмиттер 16, 17 11 0/8/3 ⬜
Б8 Движковые арх-доки 03, 09, 10, 12 16 0/4/12 ⬜
Б9 Корневые и онбординг: CLAUDE.md, README, STACK, glossary, product-requirements 14 0/4/10 ⬜
Б10 Ранние арх-доки 01/04/06 — ТОЛЬКО баннеры, архив СНЯТ (контролёр 4.2) 6 0/1/5 ⬜
Б11 ЧУЖАЯ ЗОНА: бэкенд-доки — баннеры, НЕ архив (N074 corrected) 10 0/6/4 ⬜
Б12 ЧУЖАЯ ЗОНА: фронт-доки (три неприкасаемых) 15 0/8/7 ⬜
Б13 ЧУЖАЯ ЗОНА: платформенные доки 8 1/4/3 ⬜
Б14 Углы вне ОБЕИХ сеток: PROGRESS 19–56 и 273–483 · ORCHESTRATOR_SESSION_PROMPT.md (32 КБ, не аудирован никем) · 05-decisions-index.md статусы · шапка D-лога · platform/BACKLOG.md · platform-PROGRESS.md (415 КБ) · DEFECT_REGISTER.md (782 КБ) · docs/POLYGON_* — — ⬜
Б15 Явный мусор: байт-дубль промта P0 в двух архивах · frontend/docs/API_CONTRACT_{DRAFT,INPUT}.md (78 КБ с баннером «не читать» в ЖИВОМ каталоге) · 16-events-emitter §5–§6 · 14-README §6б/6в — — ⬜
Б16 Шапки статуса у research/** и experiments/** (60 файлов): тела НЕ трогать (D23.3), только датированная строка статуса там, где её нет — — ⬜
Б17 Пинги зонам по МЁРТВЫМ УКАЗАТЕЛЯМ В КОДЕ (не доки, правит зона): artifact.go:11 · backup.go:28 · pgstore/books.go:776 · languages.ts:3-8 · tmctl/main.go:72 · store/ledger.go:172 · cheapgates.go:34 · pipeline.puml:72 — — ⬜

Критерии приёмки по батчам

Б0 — СКВОЗНОЙ: «канон 0.9.0» одним касанием — требование контролёра 2.2
Находки: N013, N022, N026, N034, N053, N056, N108
Приёмка: grep -rn '0\.8\.0' docs/ CLAUDE.md --exclude-dir=archive минус D-лог и реестр нот = 0, оставшиеся хиты предъявляются ПОИМЁННО с пометкой «историческое»; docs/README.md:29 НЕ тронута (два опровергателя независимо: это корректная историческая запись о D39.169); README:26 уже несёт 0.9.0 — не дублировать.

Б1 — Блокеры бэклога + строка 240: ОДНА нота на четыре строки
Находки: N001, N002, N003, N021
Приёмка: grep -c '^| 194 \|^| 238 \|^| 239 \|^| 240 ' docs/PROGRESS.md = 0; тело ноты несёт ВСЕ четыре номера, оба опровержения N001 (ось «сдвиг снапшота» И «не входят в число согласия»), экземпляры A6, A7+A12, обе половины улики 240 с оговоркой про local-заглушку; docs/PROGRESS.md:277 (было :282) больше не предлагает 238/239 как свободную работу; литералы очереди пере-считаны скриптом (counts.py), не руками; counts.py --check зелёный (голова сдвинется — сверить все три носителя).

Б2 — Переезд ОТРАБОТАВШЕГО промта (git mv) — раньше Б4, т.к. N075 от него зависит
Находки: N075, N084 (перенесена из Б9: критерий README.md:25 — поправка опровергателя именно к ней)
Приёмка: git show --stat = ровно rename + docs/README.md; после — grep -rn 'docs/BACKEND_COLDRUN_V16' даёт только исторические носители (архивный отчёт, D-лог, реестр нот), COLDRUN_V16_REPORT:51 НЕ тронут (тело архивного отчёта); обе протухшие половины строки README.md:25 поправлены («развилка НА ВЛАДЕЛЬЦЕ» → закрыта 31.08; «отчёт ждёт лендинга» → заленджен); ⚠ литерал «86 живых доков» в CURRENT-STATE уменьшится — counts.py его НЕ сторожит, править руками или снять.

Б3 — Денежный путь 15-money-path.md (+ парная правка 17:101 по N004)
Находки: N004, N005, N039, N040, N041, N113, N114
Приёмка: N005 (не N002/N003 — те в Б1, испр. по замечанию контролёра) — обе ветви run abandon описаны; провенанс чисел заменён с июльских на замер холодного прогона с явной датой; N004 требует парной правки 17-seam-inbound-law.md:101 ТЕМ ЖЕ коммитом, иначе класс E воспроизводится.

Б4 — Шапка журнала и остальной бэклог
Находки: N014, N015, N016, N017, N018, N019, N020, N076, N077, N078, N079, N080, N081, N082
Приёмка: diff строго строк 1–18 и затронутых | N |; строка 11 (лист владельца) неизменна; N076 — исполняется ТОЛЬКО первая половина, снятие пункта с листа владельца ЗАПРЕЩЕНО; N016 — НЕ закрывать, переписать (живой остаток — цена доведённой книги); N017 — уровень ноты, не строки; N019 — писать связку $0.436110 / проекция $1.1377 / отток ≈$1.44; N020 — СУЗИТЬ строку 232, не закрывать; на каждую снятую фразу — адрес, куда уехала.

Б5 — Контракт API 14
Находки: N035, N036, N037, N038, N109, N110, N111, N112
Приёмка: N036 — команду убрать целиком (не менять «0 → 26»), хвост §7 тем же коммитом; N035 — первую половину 981 не трогать, §6в только ⚠-указателем; греп отличительных токенов снесённых абзацев в цели указателя.

Б6 — Реестр загейченных триггеров 13
Находки: N029, N030, N031, N032, N033, N105, N106, N107
Приёмка: counts.py --lint до/после: проблем 0, счётчик «сверено ПО СОДЕРЖИМОМУ» вырос ровно на число мигрированных, число якорей в файле не уменьшилось; N029 — стрелка «→ ЗАКРЫТО D39.82, см. строку 16», сводку свипа НЕ переписывать; N030 и N107 — строки 72 и 98–104 одним касанием.

Б7 — Шов и эмиттер 16, 17
Находки: N042, N043, N044, N045, N046, N047, N048, N049, N115, N116, N117
Приёмка: N046 — форма якоря mining.go:243-244=re-seed the bank with the auto rows; N047 — атрибуция D39.159 п.7 и пере-суд «строки 139»; N048 — ОБЕ строки таблицы (97 и 103); N049 — хвост с PD-427; N044/N115 — StreamVersion 1.2; N045 — двенадцать якорей в токен-форме. (Прежний критерий про N032 снят: N032 живёт в Б6, испр. по замечанию контролёра.) §5–§6 дока 16 сам себя баннирует как отработанный хендофф, внешних ссылок ноль — кандидат на вынос в archive/reports/ с указателем (решение объявить, не делать молча).

Б8 — Движковые арх-доки 03, 09, 10, 12
Находки: N023, N024, N027, N028, N092, N093, N095, N096, N097, N098, N099, N100, N101, N102, N103, N104
Приёмка: 09 §1/§2/§4 — тела под ⚠-баннерами, анти-оверфлаг: не лезть, кроме мест, где содержимое расходится с шапкой; N027 — буллет 09:144-145 сносится ЦЕЛИКОМ; N092 — отображение dc6ea8e=7954325 · a32ec2e=e861541 · волна 2=214e005; N098 — минимальная пометка, НЕ третий носитель; N104 — без списка восьми file:line. (Прежний критерий про N063 снят: N063 живёт в Б12, испр. по замечанию контролёра.)

Б9 — Корневые и онбординг: CLAUDE.md, README, STACK, glossary, product-requirements
Находки: N050, N051, N052, N054, N068, N069, N070, N083, N085, N086, N087, N118, N119, N120
Приёмка: CLAUDE.md — правка канона владельца: каждая формулировка предъявляется владельцу до коммита; docs/README.md:29 не трогать (см. Б0).

Б10 — Ранние арх-доки 01/04/06 — ТОЛЬКО баннеры, архив СНЯТ (контролёр 4.2)
Находки: N025, N088, N089, N090, N091, N094
Приёмка: ⚠ «или архив» СНЯТ контролёром: ни 01, ни 04, ни 06 не кандидаты — их цитирует Go-код (ingest.go, ruby.go, migrate.go, cheapgates.go, coverage.go, book.go, memory.go, memseed.go), а 01 назначен носителем Р5/Р8 самим D-логом. Только ⚠-баннеры на месте.

Б11 — ЧУЖАЯ ЗОНА: бэкенд-доки — баннеры, НЕ архив (N074 corrected)
Находки: N007, N008, N009, N010, N011, N012, N071, N072, N073, N074
Приёмка: N074 corrected: SEAM_* НЕ переносить — SEAM_PACK_FINDINGS.md (носитель D39.158) ссылается на них в пяти местах; MONEY_HONESTY_REPORT §4.5 назначен носителем живого остатка строки 232 — не архивировать; лечение = датированные ⚠-баннеры. N008/N009 — часть лекарства в коде (artifact.go, backup.go, pipeline.puml) ⇒ ПИНГ зоне, не касание. Строка в docs/PROGRESS.md секции «Бэкенд» тем же коммитом.

Б12 — ЧУЖАЯ ЗОНА: фронт-доки (три неприкасаемых)
Находки: N055, N057, N058, N059, N060, N061, N062, N063, N121, N122, N123, N124, N125, N126, N127
Приёмка: ⛔ НЕ трогать: зеркало frontend/docs/api-contract/openapi.yaml (отставание РАТИФИЦИРОВАНО D39.142 п.5 на время фриза), src/api/schema.ts (генерируемый), src/mock/handlers.ts (код). N057 не переписывать в «закрыта»; N122 не менять пример на живой; N124/N048 — хронику зонного журнала задним числом НЕ править. Объявление = строка в frontend/docs/frontend-PROGRESS.md ТЕМ ЖЕ коммитом.

Б13 — ЧУЖАЯ ЗОНА: платформенные доки
Находки: N006, N064, N065, N066, N067, N128, N129, N130
Приёмка: N065 — абзац 251–253 снести, оставив ОДНУ отсылку вверх (не второй носитель); 255–258 не сносить, только зачин; N006 — формулировка «атомарно ПОФАЙЛОВО, пара не транзакционна»; N129 — координаты пере-грепнуть (6 из 7 в реестре промахиваются). Объявление = строка в platform/docs/platform-PROGRESS.md ТЕМ ЖЕ коммитом.

Б14 — РАЗДЕЛЕНА НАТРОЕ по вердикту контролёра (сначала найденное, углы — по трём адресам)

Довод контролёра, принят: найденное — 130 утверждений с уликой в носителях, которые читает каждая сессия; углы — мегабайт НЕИЗВЕСТНОГО состояния, и чинить неизвестное без ревизии значит править «по впечатлению» — ровно та ошибка, ради которой воркфлоу и строился.

  • Б14а → влито в Б4. docs/PROGRESS.md строки 19–56 и 273–483 правятся ТЕМ ЖЕ касанием, что шапка: запись пака 296–371 несёт пинги, которые нота Б1 обязана поглотить (N001 :344, N002/N003 :306), а блок «ОТКРЫТО НА №21» (36–42) с исполненными п.1–3 и ложной строкой 42 нельзя оставлять под только что починенной шапкой. Приёмка: каждый буллет 19–56 сверен с D39.180/182/184; секция 273–371 уезжает в archive/PROGRESS-2026-08-backend.md ТОЛЬКО ПОСЛЕ ноты Б1.
  • Б14б → ОТДЕЛЬНАЯ РЕВИЗИЯ, запущена параллельно, правки после Б9. docs/ORCHESTRATOR_SESSION_PROMPT.md (32 КБ, не аудирован никем) · статусы 05-decisions-index.md · шапка живого D-лога (карта актуальности + эрраты). Тот же протокол: команда + положительный контроль. Правки идут вместе с корневыми доками, не раньше найденного.
  • Б14в → ПОСЛЕДНИМИ, после Б13. platform-PROGRESS.md (415 КБ) · DEFECT_REGISTER.md (782 КБ) · platform/BACKLOG.md · docs/POLYGON_*. Лечение — не правка, а НАРЕЗКА по зонной конвенции слайсов (archive/platform-PROGRESS-P*.md): при верной нарезке потеря содержимого невозможна. Писать 415 КБ чужого журнала ДО того, как зона увидела объявления Б13, — плохой порядок.

Б15 — явный мусор. Приёмка (требование контролёра): на КАЖДЫЙ переносимый файл — список входящих ссылок и адрес каждой после переезда. Для frontend/docs/API_CONTRACT_{DRAFT,INPUT}.md — пере-углубление относительных путей по D39.80. Для 14-README §6б/6в две ссылки (D-лог:558 и реестр:216) ОСТАЮТСЯ ⇒ на месте нужна заглушка-указатель, а не пустота.

Б16 — шапки статуса research/experiments. Тела НЕ трогать (D23.3). Приёмка — команда:

for f in docs/research/*.md docs/experiments/*.md; do head -12 "$f" \
  | grep -qiE 'ревью-шапка|ревю-шапка|⚠|статус|superseded|отработан|принят' || echo "$f"; done

→ пусто. Отдельно: 12-failure-modes-ja.md и 12-failure-modes-zh.md не имеют ни одной входящей ссылки во всём дереве — по норме НЕ архив, но шапка обязательна.

Б17 — пинги зонам по мёртвым указателям В КОДЕ. Приёмка: пинг = строка зонного журнала, называющая файл, символ и что именно неверно. Кода не трогать вовсе.

Карта ДЫР самой ревизии — записываю честно, а не молчу

Ревизоры сами назвали, чего не проверили. План это НЕ закрывает; пункты числятся как «не проверено» (что не равно «опровергнуто»):

  • 30 строк бэклога веса «скоро» не проверены ни одним агентом: 2, 4, 18, 46, 109, 113, 114, 119, 120, 121, 134, 136, 140, 142, 143, 150, 167, 172, 182, 183, 188, 191, 207, 210, 216, 219, 224, 225, 49, 55. Плюс ~120 строк «когда-нибудь» проверены выборочно (16 из них).
  • 18 пунктов строки 243 не проверены.
  • В реестре триггеров 13 проверено 59 якорей из 100+.
  • 14-api-contract/README.md прочитан частями; openapi.yaml — только грепами.
  • SEAM_PACK_FINDINGS.md — НЕ_УСПЕЛ. D15.2 — сверено два якоря из десятков.
  • FRONTEND_PLAN.md §1–4, §5.2–5.5 не открывались.
  • Классы, которых воркфлоу не заказывал по построению: дубли БЕЗ расхождения · вес контекста в байтах на маршруте онбординга · сироты (входящие ссылки спрашивались только как гард) · забаннированное историческое (анти-оверфлаг объявил его легитимным — а это самый большой класс кандидатов на вынос) · весь archive/ (213 файлов) · не-.md носители (puml, комментарии кода и yaml) · зонные трекеры.

Что вынесено ИЗ плана

Планы доработок в бэкенд и платформу (заказ 0б) — отдельная работа, не критерий закрытия техдолга доков. Носитель — CURRENT-STATE.

Хвост лендинга ресёрча. Очередь п.5 велит новой смене лендить файл, лендинг которого владелец 01.09 откатил (162ab9b). Пока формулировка стоит, следующая смена повторит откат. Формулировку задаёт владелец — сам не переписываю.