textmachine/docs/DOC_CLEANUP_PLAN.md

238 lines
28 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ПЛАН РАЗБОРА ТЕХДОЛГА ДОКУМЕНТАЦИИ — заказ владельца 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б), а не техдолг
доков; держать его критерием «техдолг закрыт» нельзя — он бесконечен по определению.
## Источники
- [`DOC_REVISION_FINDINGS.md`](DOC_REVISION_FINDINGS.md) — **реестр ред.2**, 130 находок с уликами.
- [`DOC_REVISION_REFUTED.md`](DOC_REVISION_REFUTED.md) — 7 снятых. ⚠ **Чинить нельзя**: починка
вернёт дефект.
## Дисциплина разбора (жёсткая)
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` 1956 и 273483 · `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 строго строк 118 и затронутых `| 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 и 98104 одним касанием.
**Б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 — абзац 251253 снести, оставив ОДНУ отсылку вверх (не второй носитель); 255258 не сносить, только зачин; N006 — формулировка «атомарно ПОФАЙЛОВО, пара не транзакционна»; N129 — координаты пере-грепнуть (6 из 7 в реестре промахиваются). Объявление = строка в `platform/docs/platform-PROGRESS.md` ТЕМ ЖЕ коммитом.
**Б14 — РАЗДЕЛЕНА НАТРОЕ по вердикту контролёра (сначала найденное, углы — по трём адресам)**
Довод контролёра, принят: найденное — 130 утверждений с уликой в носителях, которые читает каждая
сессия; углы — мегабайт НЕИЗВЕСТНОГО состояния, и чинить неизвестное без ревизии значит править
«по впечатлению» — ровно та ошибка, ради которой воркфлоу и строился.
- **Б14а → влито в Б4.** `docs/PROGRESS.md` строки 1956 и 273483 правятся ТЕМ ЖЕ касанием, что
шапка: запись пака 296371 несёт пинги, которые нота Б1 обязана поглотить (N001 `:344`,
N002/N003 `:306`), а блок «ОТКРЫТО НА №21» (3642) с исполненными п.13 и ложной строкой 42
нельзя оставлять под только что починенной шапкой.
**Приёмка:** каждый буллет 1956 сверен с D39.180/182/184; секция 273371 уезжает в
`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` §14, §5.25.5 не открывались.
- **Классы, которых воркфлоу не заказывал по построению:** дубли БЕЗ расхождения · вес контекста
в байтах на маршруте онбординга · сироты (входящие ссылки спрашивались только как гард) ·
забаннированное историческое (анти-оверфлаг объявил его легитимным — а это самый большой класс
кандидатов на вынос) · весь `archive/` (213 файлов) · не-`.md` носители (puml, комментарии кода
и yaml) · зонные трекеры.
## Что вынесено ИЗ плана
**Планы доработок в бэкенд и платформу (заказ 0б)** — отдельная работа, не критерий закрытия
техдолга доков. Носитель — CURRENT-STATE.
**Хвост лендинга ресёрча.** Очередь п.5 велит новой смене лендить файл, лендинг которого владелец
01.09 откатил (`162ab9b`). Пока формулировка стоит, следующая смена повторит откат.
**Формулировку задаёт владелец — сам не переписываю.**