200 lines
23 KiB
Markdown
200 lines
23 KiB
Markdown
# ПЛАН РАЗБОРА ТЕХДОЛГА ДОКУМЕНТАЦИИ — заказ владельца 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 от него зависит | 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`). Пока формулировка стоит, следующая смена повторит откат.
|
||
**Формулировку задаёт владелец — сам не переписываю.**
|