docs: update a lot of plans, readmes, descriptions

docs/agent-workflow.md

@@ -1,46 +1,31 @@
 # Workflow для агентов
 
-> Статус: **active**. Подробная процедура работы с репозиторием; краткие
-> обязательные правила остаются в `AGENTS.md`. Этот документ не заменяет source
-> of truth конкретной подсистемы.
+> Статус: **active**. Порядок исследования, изменения и проверки. Обязательные
+> инварианты — в `AGENTS.md`, этот документ не заменяет source of truth
+> подсистемы.
 
 ## 1. Подготовка к задаче
 
-1. Прочитать `AGENTS.md` и `docs/README.md`.
+1. Прочитать `AGENTS.md` и выбрать документ по карте «что читать под задачу».
 2. Найти релевантный активный план, backlog или checklist.
 3. Проверить `git status`: не перезаписывать чужие незакоммиченные изменения.
-4. Найти существующие типы, константы, helpers и тестовые паттерны до создания
-   нового определения.
-5. Определить границу изменения:
-   - production UI — `web/src/routes/**` и `web/src/lib/components/**`;
-   - shared — `web/src/lib/core/**` и `web/src/lib/theme.svelte.ts`.
-
-Изменение shared-кода требует проверки production-потребителей. Не добавлять
-исключения линтера ради отдельных модулей без записи в baseline.
+4. Определить границу изменения: production UI, shared-модуль или инфраструктура
+   — `AGENTS.md`, раздел «Границы изменений». Изменение shared-кода требует
+   проверки production-потребителей.
+5. Не добавлять исключения линтера ради отдельных модулей без записи в baseline.
 
 ## 2. Порядок изменения
 
 - Сначала исправляются тесты или контракт, который фиксирует неверное поведение,
   затем production-код — если это не отдельная продуктовая задача.
-- Один PR решает одну проблему и не объединяет lint, i18n, UI и архитектурный
-  рефакторинг без необходимости.
-- Изменения держатся небольшими и атомарными, примерно до 500 строк или меньше.
-- Не добавлять комментарии, которые пересказывают код. Комментарий объясняет
-  причину решения или фиксирует неочевидный инвариант.
-- Не коммитить изменения автоматически: коммит делает разработчик после ревью.
+- Не начинать следующий этап плана в том же шаге: изменение атомарное, ревью
+  идёт между шагами (раздел 6).
 
 ## 3. Проверки
 
-Команды и их область применения перечислены в `AGENTS.md`; точная матрица и
-текущая политика warnings/errors поддерживаются в `docs/quality-gates.md`.
-
-| Изменение                                               | Минимальная проверка                                   |
-| ------------------------------------------------------- | ------------------------------------------------------ |
-| Только Markdown                                         | `pnpm check:docs`                                      |
-| TypeScript/Svelte                                       | `pnpm --dir web check`, `pnpm --dir web test`          |
-| Lint-конфиг или custom rule                             | `pnpm --dir web test:rules`, `pnpm --dir web lint:all` |
-| Маршрут, загрузка, результат, download, тема или локаль | `pnpm --dir web test:e2e`                              |
-| Перед релизом                                           | полный quality gate из плана Q1                        |
+Матрица «изменение → минимальный набор проверок», состав `pnpm verify`, политика
+warnings и чтение CI — в `docs/quality-gates.md`. Здесь только то, что относится
+к работе агента.
 
 `lint:all` может завершиться успешно при warnings. Это не означает чистый
 baseline: нужно отдельно показать число errors, warnings и token warnings.
@@ -56,75 +41,47 @@ E2E запускается отдельно от быстрых проверок
 
 - Playwright-прогоны запускаются только по явной команде пользователя: один
   прогон за раз, без циклов повторов и без фонового запуска.
-- Локально `workers: 1` (`web/playwright.config.ts`). Browser matrix из четырёх
-  проектов проходит медленно, зато не забирает память и не мешает работе
-  пользователя. Скорость проверки уступает отзывчивости компьютера.
+- Локально `workers: 1` (`web/playwright.config.ts`). Browser matrix проходит
+  медленно, зато не забирает память и не мешает работе пользователя. Скорость
+  проверки уступает отзывчивости компьютера.
 - Нельзя запускать тяжёлый прогон параллельно с другим прогоном или в момент,
   когда пользователь работает с приложением.
 - Диагностика флаков идёт от меньшего к большему: один spec, один проект,
   `--workers=1`, и только затем полный прогон.
 - Таймауты не подбираются под конкретную машину. Если проверка падает из-за
   нехватки ресурсов, это фиксируется как ограничение окружения, а не лечится
-  увеличением `expect.timeout`.
+  увеличением `expect.timeout` (обоснование — `docs/decisions.md`, раздел 7).
 - При необходимости повторного прогона сначала спрашивается пользователь.
 
 ## 4. Работа с тестами
 
+Политика locator-ов, запрещённые зависимости, fixtures, browser matrix и
+`test.fixme` — в `docs/testing-strategy.md`. Здесь только рабочая рутина:
+
 - Поведенческий тест проверяет пользовательский контракт, а не текущую
   реализацию.
-- Сначала предпочитать `role`, `aria-*`, label, stable id или href.
-- `data-testid` ограничен source/result/verdict/empty-state; общие
-  locator-паттерны собраны в `web/e2e/helpers/page.ts`, policy — в
-  `docs/testing-strategy.md`.
-- `data-testid` использовать только там, где семантического locator нет.
+- Спецификация вызывает общие операции из `web/e2e/helpers/page.ts`, а не
+  повторяет raw-селекторы.
 - Не фиксировать абсолютное число инструментов, если проверка не связана с этим
   инвариантом.
-- Точные переводы проверять в словарях и i18n helpers; в e2e проверять поведение
-  и отдельный locale smoke.
-- `test.fixme` допускается только для зарегистрированной проблемы или явного
-  тестового долга, с ссылкой на backlog или checklist. После исправления тест и
-  его issue обновляются вместе.
 - Новые fixtures должны быть воспроизводимыми и не требовать ручного создания
   больших бинарных файлов.
 
 ## 5. Документация
 
-Источник истины выбирается по теме:
-
-- обязательное поведение агента — `AGENTS.md`;
-- индекс и карта документов — `docs/README.md`;
-- качество и точные команды — `docs/quality-gates.md`;
-- тестовая архитектура — `docs/testing-strategy.md`;
-- lint implementation — `web/eslint-plugins/README.md`;
-- продуктовые решения — backlog и активные планы.
-
-Не дублировать длинные объяснения в нескольких файлах. Если правило требует
-пояснения, в `AGENTS.md` оставить короткую понятную формулировку и ссылку на
-подробный документ.
-
-### Архивирование завершённых документов
-
-- Если план или исследование больше не является рабочим источником, перенести
-  файл в `docs/archive/`.
-- В начало файла добавить `Статус`, `Архивирован`, `Удалить после` и причину.
-- Архив хранить 30 дней для быстрой справки; после срока удалить после проверки
-  ссылок. Если решение понадобится снова, использовать git history.
-- Не переносить активный план в архив только потому, что он пока не начат.
+Порядок работы с документами и карта источников истины — `docs/README.md`.
+Архивирование — `docs/archive/README.md`.
 
 ## 6. Протокол ревью между шагами
 
 После каждого шага плана агент:
 
-1. останавливается и не начинает следующий Q-этап;
+1. останавливается и не начинает следующий этап;
 2. перечисляет изменённые файлы и принятые решения;
 3. указывает выполненные проверки и их фактический результат;
 4. отдельно перечисляет warnings, fixme, долги и вопросы;
 5. ждёт подтверждения на продолжение.
 
-Коммит и пуш делает разработчик. После пуша агент проверяет результат CI и
-сообщает его вместе с локальными проверками, включая случай, когда нужный job не
-запускался: статусы смотрятся по отдельным job, потому что общий conclusion
-прогона с `continue-on-error` у `e2e` остаётся зелёным. Процедура описана в
-`docs/quality-gates.md`.
-
-Следующий шаг начинается только после ревью текущего изменения.
+Коммит и пуш делает разработчик. Следующий шаг начинается только после ревью
+текущего изменения; после пуша результат CI читается по процедуре из
+`docs/decisions.md`, раздел 10.