docs: update a lot of plans, readmes, descriptions

2026-11-13 17:08:20 +00:00 · 2026-09-27 09:10:26 +05:00
parent 9c6f223b13
commit 82207c82f2
47 changed files with 1029 additions and 4615 deletions
@@ -1,89 +1,56 @@
 # Документация проекта

-> Статус: **active**. Это индекс документов и карта источников истины для
-> разработчиков и агентов. Подробные правила находятся в самих документах, а
-> обязательный краткий контракт — в `AGENTS.md`.
+> Статус: **active**. Индекс документов. Обязательный краткий контракт — в
+> `AGENTS.md`, подробные правила — в самих документах.

 ## Порядок чтения

-1. `AGENTS.md` — команды и обязательные инварианты.
+1. `AGENTS.md` — команды, инварианты и карта «что читать под задачу».
 2. Этот файл — выбрать актуальный документ по теме.
 3. Соответствующий план или checklist темы.
 4. Исходники, конфигурация и тесты рядом с изменяемым кодом.

 ## Активные документы

-| Документ                           | Роль                                                 | Статус |
-| ---------------------------------- | ---------------------------------------------------- | ------ |
-| `AGENTS.md`                        | Краткий обязательный контракт для агента             | active |
-| `docs/agent-workflow.md`           | Подробный порядок исследования, изменения и проверки | active |
-| `docs/testing-strategy.md`         | Locator, fixture, i18n и fixme-policy для e2e        | active |
-| `docs/quality-gates.md`            | Команды проверки, warnings и CI                      | active |
-| `docs/backlog.md`                  | Продуктовые, UX- и инфраструктурные задачи           | active |
-| `docs/roadmap.md`                  | Общие направления развития                           | active |
-| `docs/plan-seo.md`                 | SEO/GEO-план                                         | active |
-| `docs/plan-platform.md`            | PWA/API/WASM-план                                    | active |
-| `docs/checklist-manual-testing.md` | Ручная приёмка production UI                         | active |
-| `docs/tools-map.md`                | Живая карта инструментов                             | active |
-| `web/eslint-plugins/README.md`     | Детали custom lint rules и token policy              | active |
-| `docs/archive/README.md`           | Правила архивирования и удаления старых документов   | active |
+| Документ                           | Когда читать                                       | Статус |
+| ---------------------------------- | -------------------------------------------------- | ------ |
+| `AGENTS.md`                        | Всегда: контракт агента                            | active |
+| `docs/architecture.md`             | Слои, поток данных, новый инструмент/поле/маршрут  | active |
+| `docs/quality-gates.md`            | Какие проверки запускать, пороги, coverage, CI     | active |
+| `docs/decisions.md`                | Правка самих гейтов; чтение CI после пуша          | active |
+| `docs/agent-workflow.md`           | Порядок работы, нагрузка на машину, протокол ревью | active |
+| `docs/testing-strategy.md`         | Правка e2e: locator-ы, fixtures, browser matrix    | active |
+| `docs/backlog.md`                  | Продуктовые, UX- и инфраструктурные задачи         | active |
+| `docs/roadmap.md`                  | Направления развития, фазы 1–10                    | active |
+| `docs/tools-map.md`                | Актуальный список инструментов против реестра      | active |
+| `docs/tools-audit.md`              | Сырые UX/UI-находки по инструментам (вход аудита)  | active |
+| `docs/plan-fields-audit-fixes.md`  | Разбивка аудита на волны правок                    | draft  |
+| `docs/plan-seo.md`                 | SEO/GEO-план                                       | active |
+| `docs/plan-platform.md`            | API/PWA/шрифты-план                                | active |
+| `docs/checklist-manual-testing.md` | Ручная приёмка production UI                       | active |
+| `web/eslint-plugins/README.md`     | Правка lint-правил, токенов и их конфигов          | active |
+| `docs/archive/README.md`           | Архивирование и удаление старых документов         | active |

-`docs/archive/` содержит временную историческую справку и не является текущим
-источником критериев приёмки. Для старых документов действует срок хранения 30
-дней; после него их удаляют, а при необходимости достают из git history.
+`docs/plan-domain.local.md` исключён из git через `.gitignore` (выбранное имя
+домена не должно попасть в историю до покупки). Ссылки на него в `plan-seo.md` и
+`backlog.md` при клонировании репозитория не разрешаются — это ожидаемо.

-## Где хранить новую информацию
+## Правила

- Поведение, которое агент обязан соблюдать сразу, — кратко в `AGENTS.md`.
- Точные команды, параметры скриптов и критерии качества — в
-  `docs/quality-gates.md` или в README соответствующей подсистемы.
- Архитектура, потоки данных и границы модулей — в отдельном architecture-плане
-  или документе, не дублируя существующие планы.
- Реализация lint-правил, fixtures и технические детали ESLint — в
-  `web/eslint-plugins/README.md` и исходниках правил.
- Продуктовые решения и ручная приёмка — в backlog, плане и checklist.
-
-У документа должен быть один источник истины: остальные файлы ссылаются на него,
-а не пересказывают. Подробные материалы хранятся в `docs/`, чтобы не засорять
-корень репозитория. Не создавать отдельные `docs/commands.md`,
-`docs/known-issues.md` или копию backlog: команды принадлежат `quality-gates`,
-известные проблемы — backlog и checklist. `README.md` в корне остаётся кратким
-обзором продукта, а не вторым руководством агента.
-
-Новый документ создаётся только когда темы нет в существующем файле; иначе
-обновляется источник истины. Активный документ имеет статус (`draft`, `active`,
-`completed`) и понятную область применения.
-
-Подробные материалы хранятся в `docs/`, а не в корне. Новый файл создаётся
-только если темы нет в существующем документе; иначе обновляется источник
-истины.
-
-## Текущий baseline
-
- production registry содержит 122 инструмента;
- `pnpm --dir web check` проходит без ошибок и предупреждений;
- `pnpm --dir web test` — 46 test files / 534 tests, включая тесты token audit,
-  PostCSS HCT-плагина и правил линтинга;
- `pnpm --dir web test:rules` — 5 test files / 104 tests;
- `pnpm --dir web lint:all` — 0 errors, 0 i18n warnings и 0 unused design tokens
-  от token audit;
- coverage `src/lib` — statements 91.77%, branches 83.3%, functions 74.31%,
-  lines 92.53% при порогах 90 / 82 / 72 / 91;
- `pnpm verify` проходит;
- `pnpm --dir web test:e2e` — 276 тестов в четырёх проектах: 276 passed, 0
-  skipped, 0 failed. Отказ декодера битого PNG зафиксирован per-engine в
-  `web/e2e/png-fixtures.spec.ts`.
-
-Состав проверок и их семантика описаны в `docs/quality-gates.md`, тестовая
-архитектура — в `docs/testing-strategy.md`. Baseline обновляется здесь при
-изменении любого из гейтов.
-
-## Правила актуальности
-
- У активного документа есть статус: `draft`, `active`, `completed` или
-  `archived`.
- Ссылки на конкретный файл или команду проверяются при изменении источника
-  истины.
- Архивный документ не возвращается в live-критерии без явной сверки.
- После каждого шага плана агент останавливается, показывает изменённые файлы,
-  проверки и нерешённые решения, и ждёт ревью.
+- У каждой темы ровно один владелец: остальные документы ссылаются на него, а не
+  пересказывают. Новый документ создаётся, только если темы нет в существующем.
+- У документа есть статус (`draft`, `active`, `completed`, `archived`) и
+  понятная область применения. Ссылки на конкретный файл или команду проверяются
+  при изменении источника истины.
+- Подробные материалы живут в `docs/`, а не в корне. Не создавать отдельные
+  `docs/commands.md` или `docs/known-issues.md`: команды принадлежат
+  `quality-gates`, известные проблемы — backlog и checklist. `README.md` в корне
+  остаётся кратким обзором продукта, а не вторым руководством агента.
+- Ссылаясь на инструмент по id, сверять id с реестром (`web/src/lib/registry/`):
+  исторические названия в старых планах не действуют.
+- `docs/backlog.md` содержит только открытые задачи: выполненные удаляются, а
+  критичные для проекта факты из них переносятся в тематический документ.
+- `docs/archive/` — временная историческая справка, не источник критериев
+  приёмки; срок хранения 30 дней, файлы восстановимы из git history.
+- Протокол «остановиться и показать изменения» — `docs/agent-workflow.md`,
+  раздел 6.