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

23 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 от него зависит 1 0/0/1 ⬜
Б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 15 0/4/11 ⬜
Б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 вне исторических записей = 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:282 больше не предлагает 238/239 как свободную работу; литералы очереди пере-считаны скриптом (counts.py), не руками; counts.py --check зелёный (голова сдвинется — сверить все три носителя).

Б2 — Переезд ОТРАБОТАВШЕГО промта (git mv) — раньше Б4, т.к. N075 от него зависит
Находки: N075
Приёмка: 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
Приёмка: N002/N003 — обе ветви 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
Приёмка: N032 — гвоздь НЕ строить, он построен; §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 — тела под ⚠-баннерами, анти-оверфлаг: не лезть, кроме случаев, где содержимое расходится с шапкой; N063 — §8 целиком НЕ сносить.

Б9 — Корневые и онбординг: CLAUDE.md, README, STACK, glossary, product-requirements
Находки: N050, N051, N052, N054, N068, N069, N070, N083, N084, 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 ТЕМ ЖЕ коммитом.

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

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

  • 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). Пока формулировка стоит, следующая смена повторит откат. Формулировку задаёт владелец — сам не переписываю.