@rt-tools/agent-kit 0.2.0 → 0.4.0

package/assets/patterns/angular-patterns-state.md

@@ -0,0 +1,101 @@
+---
+name: angular-patterns-state
+kind: pattern
+rule: angular-patterns
+description: Паттерн правила angular-patterns. Брать при объявлении состояния и потоков в классе Angular — готовые сигналы, производные значения, состояние сервиса, долгоживущая подписка с источником действия. Не брать для раскладки файла компонента — это правило component-structure.
+---
+
+# Состояние и потоки
+
+Паттерн правила `angular-patterns`. Что при этом должно быть верно — закон
+`docs/constitution/frontend-application.md`.
+
+## Когда брать
+
+- Объявляется состояние компонента или сервиса.
+- Появляется поток, на который надо подписаться.
+- Значение считается из другого значения.
+
+## Сигнальный API входов и выходов
+
+```typescript
+public readonly data: InputSignal<Item[]> = input.required<Item[]>();
+public readonly isMobile: InputSignal<boolean | undefined> = input<boolean>();
+public readonly save: OutputEmitterRef<void> = output<void>();
+
+protected readonly myButton: Signal<ElementRef | undefined> = viewChild<ElementRef>('button');
+```
+
+Декораторов `@Input()`, `@Output()`, `@ViewChild()`, `@ContentChild()` и их множественных пар
+в дереве нет.
+
+## Производное значение — `computed`, а не эффект
+
+```typescript
+protected readonly items: WritableSignal<Item[]> = signal<Item[]>([]);
+protected readonly itemCount: Signal<number> = computed((): number => this.items().length);
+protected readonly hasItems: Signal<boolean> = computed((): boolean => this.itemCount() > 0);
+```
+
+```typescript
+✗ effect((): void => { this.count.set(this.items().length); });
+✓ protected readonly count: Signal<number> = computed((): number => this.items().length);
+```
+
+Геттера в компоненте не заводить: он пересчитывается на каждой перерисовке, и цена его не
+видна ни в одном месте кода.
+
+## Состояние сервиса
+
+Наружу — только чтение:
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class DomainStateService {
+    readonly #items: WritableSignal<Item[]> = signal<Item[]>([]);
+
+    public readonly items: Signal<Item[]> = this.#items.asReadonly();
+    public readonly itemCount: Signal<number> = computed((): number => this.#items().length);
+
+    public addItem(item: Item): void {
+        this.#items.update((items: Item[]): Item[] => [...items, item]);
+    }
+}
+```
+
+## Подписка объявляется один раз
+
+Метод действия толкает значение в источник, подписка живёт в конструкторе:
+
+```typescript
+readonly #loadSource: Subject<void> = new Subject<void>();
+readonly #destroyRef: DestroyRef = inject(DestroyRef);
+
+constructor() {
+    this.#loadSource
+        .pipe(
+            switchMap((): Observable<IPromoCode.ListResult> => this.#api.getList(this.#query())),
+            takeUntilDestroyed(this.#destroyRef)
+        )
+        .subscribe();
+}
+
+protected reload(): void {
+    this.#loadSource.next();
+}
+```
+
+Оператор выбирается по тому, что делать с предыдущим запросом: список берёт последний ответ
+(`switchMap`), кнопка не плодит дублей (`exhaustMap`), соседние строки идут независимо
+(`mergeMap`).
+
+## Частые промахи
+
+- `.subscribe()` внутри метода: правило линтера отбивает, а вместе с ним отбивается и гонка
+  ответов на быстрых нажатиях.
+- Подписка без `takeUntilDestroyed`: она переживает владельца и держит уничтоженный экран в
+  памяти.
+- Поле-поток без суффикса `Source`: поток и значение в коде становятся неотличимы.
+- `inject()` вместо параметров конструктора — везде, включая базовые классы.
+- `untracked()` там, где эффекту не нужна зависимость от сигнала: без него эффект просыпается
+  на каждое чужое изменение.

package/assets/patterns/api-layer-pair.md

@@ -0,0 +1,88 @@
+---
+name: api-layer-pair
+kind: pattern
+rule: api-layer
+description: Паттерн правила api-layer. Брать при заведении или правке слоя api фронтового домена — готовые фасад и сервис, вход выборки, конвертер страницы, типы порядка и отбора в неймспейсе сущности. Не брать для модели и её маппера — это паттерн entity-models-new.
+---
+
+# Фасад и сервис домена
+
+Паттерн правила `api-layer`. Что при этом должно быть верно — закон
+`docs/constitution/frontend-application.md`.
+
+## Когда брать
+
+- Заводится слой `api` нового домена.
+- Список переводится на общую выборку.
+- Появляется новая процедура, за которой ходит экран.
+
+## Фасад
+
+Принимает запрос контракта, отдаёт ответ контракта, ожидание заворачивает в поток. Ни выборки,
+ни перевода моделей в нём нет:
+
+```typescript
+@Injectable({ providedIn: 'root' })
+export class PromoCodeApiFacade implements IListApiFacade<
+    MessageInitShape<typeof ListPromoCodesRequestSchema>,
+    ListPromoCodesResponse,
+    GetPromoCodeResponse
+> {
+    readonly #client: Client<typeof PricingService> = injectConnectClient(PricingService);
+
+    public getList(request: MessageInitShape<typeof ListPromoCodesRequestSchema>): Observable<ListPromoCodesResponse> {
+        return from(this.#client.listPromoCodes(request));
+    }
+}
+```
+
+Метод, которого у домена нет, не объявляется: список читают все, правят не все.
+
+## Сервис
+
+Принимает доменные модели, отдаёт их же. Тип контракта до стора и шаблона не доходит:
+
+```typescript
+export class PromoCodeApiService implements IListApiService<
+    IPromoCode.State,
+    EPromoCodeSortProperty,
+    EPromoCodeFilterProperty,
+    IPromoCode.Draft
+> {
+    public getList(query: IPromoCode.Query): Observable<IPromoCode.ListResult> {
+        return this.#facade
+            .getList({ query: this.#queryMapper.mapTo(query) })
+            .pipe(
+                map((response: ListPromoCodesResponse): IPromoCode.ListResult =>
+                    convertPaginationApiModelToStateModel((item: PromoCodeInfo): IPromoCode.State => this.#mapper.mapFrom(item), response)
+                )
+            );
+    }
+}
+```
+
+`getList` принимает выборку и больше ничего: объект, к которому привязан список, тип фида,
+состояние подписки — это условия отбора, и лежат они в `filterModel`.
+
+## Типы выборки в неймспейсе сущности
+
+```typescript
+export type Query = IList.Query.State<EPromoCodeSortProperty, EPromoCodeFilterProperty>;
+export type ListResult = IList.Result.State<IPromoCode.State, EPromoCodeSortProperty, EPromoCodeFilterProperty>;
+```
+
+Перечисления `EPromoCodeSortProperty` и `EPromoCodeFilterProperty` объявляются в модели рядом с
+сущностью и повторяют набор имён, по которым сортирует и отбирает сервер этого домена.
+
+## Частые промахи
+
+- Промежуточный объект между ответом и моделью: ответ ложится в конвертер целиком.
+- Выборка из своего запроса вместо применённой из ответа: умолчание сервера и отброшенное им
+  условие экран иначе не увидит.
+- Второй вход рядом с выборкой (`propertyId`, `feedType`): отбор, живущий отдельно, не виден ни
+  стору, ни адресу.
+- Голая `string` в поле порядка: имя, по которому сервер не сортирует, компилируется и падает
+  запросом.
+- Один класс на две сущности: подмена источника одной потянет за собой правку другой.
+- Промисный сервис в новом сторе: основа списочного стора работает потоками.
+- Своя копия общих мапперов страницы, порядка и отбора — её ловит `npm run check:dupes`.

package/assets/patterns/browser-verification-measure.md

@@ -0,0 +1,86 @@
+---
+name: browser-verification-measure
+kind: pattern
+rule: browser-verification
+description: Паттерн правила browser-verification. Брать, когда вывод о вёрстке надо подкрепить числом — готовые замеры, разбивка вычисленного значения по всем узлам, узкий экран через iframe, ловушки инструмента computer. Не брать для подъёма стенда — это паттерн browser-verification-stand.
+---
+
+# Замер вместо взгляда
+
+Паттерн правила `browser-verification`. Что при этом должно быть верно — закон
+`docs/constitution/verifiability.md`.
+
+## Когда брать
+
+- Правилась вёрстка, и надо подтвердить результат.
+- Экран выглядит не так, а искать нечего: поиск по коду отвечает «чисто».
+- Проверяется узкий экран.
+
+## Вывод подкрепляется числом
+
+`getComputedStyle`, `getBoundingClientRect`, контраст, совпадение центров, попадание во
+вьюпорт. «Выглядит нормально» результатом проверки не является.
+
+Замер отвечает только на тот вопрос, который задали. Совпадение перечисленных свойств ничего
+не говорит о правиле, которого в списке замера нет: строки попапа профиля сошлись с образцом
+по отступам, кеглю и скруглению, а фон на наведении образец в этом месте не красит вовсе —
+полноширинная подсветка держалась два круга при верных числах. Если исходники образца
+доступны, расхождение ищется чтением, а замер остаётся проверкой результата.
+
+Вид элемента, которого сегодня не видно ни на одном экране, замером не подтверждается, и
+правило о нём остаётся гипотезой.
+
+## Значение, которого в коде нет
+
+Гарнитуру, `line-height`, цвет и `appearance` элементам формы задаёт браузер, и в дереве этих
+значений нет. Поиск по коду на такой дефект отвечает «чисто», линт и сборка молчат. Ищется
+разбивкой вычисленного значения по всем узлам страницы, а не замером у пары элементов:
+
+```javascript
+[...document.querySelectorAll('*')].reduce((acc, el) => {
+    const key = getComputedStyle(el).fontFamily;
+    acc[key] = (acc[key] ?? 0) + 1;
+    return acc;
+}, {});
+```
+
+Так на дашборде админки нашёлся 91 контрол из 106, набранный не той гарнитурой, и 13 из 87 на
+главной сайта. Счёт годится любому наследуемому свойству: смотрится не одно значение, а число
+узлов с неожиданным.
+
+## Узкий экран
+
+`resize_window` не работает, когда Chrome в полноэкранном режиме: инструмент рапортует успех,
+`innerWidth` не меняется, медиазапросы остаются десктопными. Узкие ширины проверять во
+вложенном iframe нужной ширины — внутри него `matchMedia` считается от рамки; при
+`width: 375px` и `border: 2px` внутренний `innerWidth` равен 371.
+
+Правка числа элементов в контейнере — это правка раскладки: она проверяется при 375, а не
+только кодами ответа.
+
+## Ловушки инструмента `computer`
+
+- Координаты клика — координаты **скриншота**, а не CSS-пиксели: при вьюпорте 2560 скриншот
+  приходит шириной 1568, и клик по «увиденной» координате уходит мимо, давая ложный сигнал.
+  Пересчитывать по фактическому масштабу либо целиться через `find`.
+- Область `zoom` должна целиком лежать внутри вьюпорта.
+- Между кликами обязателен `await`: синхронный цикл «кликнул — прочитал DOM» читает состояние
+  до перерисовки и возвращает устаревшие значения.
+- `select_browser` протухает через 300 секунд. На длинной проверке это срабатывает посреди
+  работы — это не сбой стенда, повторить вызов и продолжить. Закреплённый профиль — тот, что записан в дереве, идентификатор `062b17db-ae82-4264-927c-e9904d0dd5be`.
+
+## Поведение роутера воспроизводится нажатиями
+
+Подстановка адреса, `history.pushState` с `popstate` и заход по прямой ссылке поднимают
+приложение заново, и накопленного состояния — открытого аутлета, гарда прошлой панели — у него
+нет. Чистый проход по адресам читается как «дефект не подтверждается»: панель ленты событий
+застревала на первом же нажатии из меню и трижды прошла проверку адресами.
+
+## Частые промахи
+
+- Комментарий в конфиге — гипотеза наравне с прочими. Утверждение о вытеснении записи кэша
+  продержалось три круга состязательного разбора кода и было опровергнуто одним `curl`.
+- Вывод «дефекта нет, это кэш» закрывает разбор, поэтому принимается только после проверки на
+  чистой сборке.
+- Дефект в клиентском чанке от компиляции до правки выглядит как дефект кода: признак
+  дев-сборки — имена бандла без хеша.

package/assets/patterns/browser-verification-stand.md

@@ -0,0 +1,143 @@
+---
+name: browser-verification-stand
+kind: pattern
+rule: browser-verification
+description: Паттерн правила browser-verification. Брать, когда нужен честный стенд — прод-сборка сайта, стенд админки, стенд под настоящим nginx, вход в админку, разбор того, что висит на порту. Не брать для замеров вёрстки — это паттерн browser-verification-measure.
+---
+
+# Честный стенд
+
+Паттерн правила `browser-verification`. Что при этом должно быть верно — закон
+`docs/constitution/verifiability.md`.
+
+## Когда брать
+
+- Проверяется то, чего на дев-сервере не видно: разметка от сервера, локали, кэш,
+  перенаправления, заголовки, размер бандла.
+- Порт отвечает не тем, чего ждали.
+- Нужен вход в админку.
+
+## Сначала — что отвечает на порту
+
+До первого запроса, а не после непонятного ответа:
+
+```bash
+lsof -nP -iTCP:{{apiPort}} -sTCP:LISTEN
+```
+
+На {{apiPort}} регулярно висит собранный артефакт из прошлой сессии
+(`node -r dotenv/config dist/apps/api/main.js`): он отвечает 200 старым кодом, а процедуры,
+заведённой в ветке, у него нет вовсе. Таких процессов бывает несколько, и снимать надо все —
+по PID из `lsof`, каждый: `pkill` по шаблону `nx serve api` не попадает ни в один.
+
+## Прод-сборка сайта
+
+```bash
+npx nx build site
+PORT={{prodSitePort}} node dist/apps/site/server/server.mjs
+```
+
+Это не дев-сервер: гард ловит `nx|ng serve`, пакетные раннеры и статические серверы, а запуск
+собранного сервера пропускает.
+
+## Стенд админки
+
+```bash
+npx nx build admin --base-href=/
+```
+
+Без `--base-href` стенд отдаёт пустую страницу без ошибок в консоли. Стенду, на котором нужен
+Angular DevTools, нужна ещё и dev-конфигурация (`--configuration=development`): прод-сборка не
+публикует `window.ng`. Выводы о размере бандла и минификации на такой сборке делать нельзя.
+
+Сессия кладётся в `localStorage['vm.admin.token']` **строкой JSON** (`JSON.stringify(token)`),
+иначе приложение её не прочитает. Токен не подписывается руками, а берётся у живого API:
+`POST /<область>.v1.AuthService/Login`. Команду с паролем классификатор блокирует — обходить не
+надо, спрашивать разрешение у владельца.
+
+Взять уже открытую сессию нельзя: чтение `localStorage['vm.admin.token']` из браузера
+блокируется. Оба пути к своему стенду упираются в пароль, поэтому остаётся третий — смотреть
+на админке владельца, где вход уже сделан. Свой стенд нужен, только когда проверяют
+прод-сборку, `--base-href` или конфиг nginx; чтобы просто посмотреть экраны, он не нужен.
+
+## Стенд API
+
+Собранный артефакт поднимается на свободном порту, а не на {{apiPort}}: на {{apiPort}} отвечает API
+владельца, и окружение у него не то, которое проверяется.
+
+```bash
+npx nx build api
+env -u JWT_SECRET NODE_ENV=production API_PORT={{prodApiPort}} DATABASE_URL=… node dist/apps/api/main.js
+```
+
+Переменные окружения задаются в самой команде, по одной на проверяемый случай. Отказ на
+старте — такой же результат проверки, как ответ 200: приложение, упавшее в фабрике
+провайдера, порт не слушает вовсе, и это видно по `lsof`, а не по тексту в консоли.
+
+Процедура зовётся полным именем, как её объявляет контракт:
+
+```bash
+curl -sS -X POST http://localhost:{{prodApiPort}}/<область>.v1.AuthService/GetMe \
+    -H 'content-type: application/json' -H "authorization: Bearer $TOKEN" -d '{}'
+```
+
+Токен подписывается руками только там, где проверяется сама подпись: доказать, что отладочный
+ключ принимается, другого пути не имеет. Во всех остальных случаях токен берётся у живого API
+входом — рукописный скрывает расхождение состава притязаний.
+
+## Стенд под настоящим nginx
+
+Кэш, перенаправления и заголовки живут в `deploy/nginx.conf`, а не в приложении. Любой вывод
+про `301`, `Cache-Control` и `X-Cache-Status` делается только здесь:
+
+```bash
+docker run -d --name <префикс>-stand-nginx \
+  --add-host api:host-gateway --add-host ssr:host-gateway \
+  -p {{dockerSitePort}}:80 -p {{dockerAdminPort}}:8081 \
+  -v "$PWD/deploy/nginx/main.conf:/etc/nginx/nginx.conf:ro" \
+  -v "$PWD/deploy:/etc/nginx/conf.d:ro" \
+  -v "$PWD/dist/apps/admin/browser:/usr/share/nginx/html/admin:ro" \
+  nginx:1.27-alpine
+```
+
+- Конфиг монтируется **каталогом**, а не одиночным файлом: редактор пересоздаёт файл,
+  контейнеру остаётся обрезанная копия, и `nginx -t` внутри падает на «unexpected end of file»
+  при целом файле снаружи. Лечится пересозданием контейнера, а не правкой конфига.
+- Главный конфиг подставляется отдельной строкой: он лежит в `deploy/nginx/`, а не рядом с
+  `nginx.conf`, — файл с расширением `.conf` в смонтированном каталоге попал бы в `include`
+  и уронил бы nginx на директиве `user`. Без него стенд поднимается на конфиге образа, и
+  предел соединений на воркер там свой.
+- Сервер отдачи страниц отвечает `400` на чужой `Host`: все запросы идут с
+  `-H "Host: localhost"`.
+- Переменные окружения стенда обязаны смотреть на процессы стенда. `CACHE_REFRESH_URL`,
+  направленный на {{sitePort}}, сбрасывает кэш мимо того процесса, который держит справочник
+  перенаправлений в памяти, — исправный механизм при этом выглядит сломанным.
+
+## Дерево для сравнения
+
+Сказать «это сломала правка» можно, только если видно, что до правки было иначе. Проверяют это
+вторым деревом, а не по памяти:
+
+```bash
+git worktree add ../<префикс>-base <коммит>   # ветка задачи не трогается
+pnpm install --frozen-lockfile         # из ../<префикс>-base: node_modules у него свои
+```
+
+- Для сравнения берут не главную ветку, а последний коммит, на котором дерево собирается:
+  главная бывает сломана, и тогда «до» и «после» различаются не из-за правки. Собирается ли
+  коммит — проверяют сборкой, а не тем, что он в главной ветке.
+- Стенд второго дерева поднимают на своих портах: {{sitePort}}, {{adminPort}} и {{apiPort}} заняты владельцем, а {{ssrPort}}
+  занимать нельзя — стенд разработчика ходит по имени `ssr:{{ssrPort}}`.
+- Оба стенда держат поднятыми одновременно: если сравнивать по памяти между двумя запусками,
+  заметишь только то, что успел запомнить.
+
+## Частые промахи
+
+- Свой дев-сервер не поднимать: сайт на {{sitePort}}, админка на {{adminPort}}, API на {{apiPort}} уже подняты
+  владельцем, и второй экземпляр отбивается гардом.
+- **Общая сборка глушит все три дев-сервера владельца, а не только API.** После
+  `nx run-many -t build` ложатся и сайт на {{sitePort}}, и админка на {{adminPort}}. Собирать надо то, что
+  проверяешь (`npx nx build site`), а не всё дерево. Если серверы легли, поднять их обратно
+  агент не может — мешает гард, поэтому владельцу говорят об этом сразу, а не в конце сессии.
+- Порт {{ssrPort}} занимать осторожно: стенд разработчика на {{sitePort}} ходит по тому же имени `ssr:{{ssrPort}}`
+  через `host-gateway`, и пока на нём висит чужой процесс, стенд отдаёт чужую сборку.

package/assets/patterns/component-structure-new.md

@@ -0,0 +1,99 @@
+---
+name: component-structure-new
+kind: pattern
+rule: component-structure
+description: Паттерн правила component-structure. Брать при заведении или правке *.component.ts — готовый декоратор с порядком свойств, группировка импортов, раскладка полей класса, договорённости шаблона и qa-dataid. Не брать для состояния и потоков — это паттерн angular-patterns-state.
+---
+
+# Файл компонента
+
+Паттерн правила `component-structure`. Что при этом должно быть верно — закон
+`docs/constitution/frontend-application.md`.
+
+## Когда брать
+
+- Заводится новый компонент.
+- Правится декоратор, список импортов или шаблон существующего.
+
+## Декоратор: порядок свойств
+
+```typescript
+@Component({
+    selector: '<префикс>-component-name', // 1. селектор
+    templateUrl: './component-name.component.html', // 2. шаблон
+    styleUrl: './component-name.component.scss', // 3. стиль, в единственном числе
+    changeDetection: ChangeDetectionStrategy.OnPush, // 4. стратегия перерисовки
+    imports: [
+        // 5. импорты, группами
+        // angular
+        FormsModule,
+
+        // rt-tools
+        BlockDirective,
+        ElemDirective,
+
+        // components
+        SomeChildComponent,
+    ],
+    providers: [], // 6. провайдеры
+    host: { class: '<префикс>-component-name' }, // 7. привязки хоста
+})
+export class ComponentNameComponent {
+    readonly #someService: SomeService = inject(SomeService);
+
+    public readonly data: InputSignal<Item[]> = input.required<Item[]>();
+    public readonly save: OutputEmitterRef<void> = output<void>();
+
+    protected readonly myButton: Signal<ElementRef | undefined> = viewChild<ElementRef>('button');
+    protected readonly items: WritableSignal<Item[]> = signal<Item[]>([]);
+    protected readonly itemCount: Signal<number> = computed((): number => this.items().length);
+}
+```
+
+Группирующие комментарии в `imports` обязательны: `// angular`, `// rt-tools`,
+`// components`, `// directives`, `// pipes`.
+
+## Шаблон
+
+- Самозакрывающиеся теги у компонентов без содержимого: `<<префикс>-gallery />`.
+- Лишних обёрток нет — корнем работает `:host`, класс блока приходит с `host: { class: … }`.
+- Сложный шаблон объявляет блок `<ng-container rtBlock="component-name">` в корне.
+- Один компонент в обеих ветках `@if` — это условная привязка:
+
+```html
+<!-- ✗ -->
+@if (isRangeMode()) { <<префикс>-calendar [rangeMode]="true" /> } @else { <<префикс>-calendar [rangeMode]="false" /> }
+
+<!-- ✓ -->
+<<префикс>-calendar [rangeMode]="isRangeMode()" />
+```
+
+- Прокрутка по документу — через роутер, а не `href="#id"`:
+
+```html
+<a fragment="booking" [routerLink]="[]">…</a>
+```
+
+## `qa-dataid` — на каждый интерактивный элемент
+
+```html
+<button vmButton qa-dataid="calendar-retry-prices" type="button" (click)="retryPrices.emit()">Повторить</button>
+<div rtElem="grid" qa-dataid="admin-calendar-grid"></div>
+```
+
+- Значение — kebab-case по смыслу элемента, без имени компонента-обёртки: `calendar-day`,
+  `booking-submit`.
+- Уникальность — в пределах экрана; повторяющиеся элементы списка носят один якорь и
+  различаются через `data-*` (`[attr.data-iso]`, `[attr.data-state]`).
+- Декоративный элемент помечается `qa-skip` на самом теге.
+
+## Частые промахи
+
+- `selector: 'app-component'` вместо `<префикс>-component`.
+- `styleUrls: ['./component.scss']` вместо `styleUrl` — множественное число здесь не то.
+- Вызов метода в биндинге: `{{ getTotal() }}` отбивается линтером. Замена — `computed()`, а
+  там, где значение приходит из контекста шаблона, — чистый пайп.
+- Обёртка, которая существует только чтобы быть flex- или grid-контейнером вокруг всех детей:
+  её раскладка уезжает на `:host`.
+- Глубокий относительный импорт между либами вместо `@<область>/<семья>/<домен>/<слой>`.
+- Своя разметка вместо готового компонента кита — правило `reuse-first`.

package/assets/patterns/dependencies-upgrade.md

@@ -0,0 +1,65 @@
+---
+name: dependencies-upgrade
+kind: pattern
+rule: dependencies
+description: Паттерн правила dependencies. Брать при подъёме версий пакетов — выбор верхней границы по peer-диапазонам, порядок проверок, граница переформатирования после обновления форматтера, разбор новых правил линтера. Не брать для ветки, коммита и PR — это паттерн git-workflow-commit.
+---
+
+# Подъём версий
+
+Паттерн правила `dependencies`. Что при этом должно быть верно — закон
+`docs/constitution/delivery.md`.
+
+## Когда брать
+
+- Поднимается версия любого пакета.
+- Пришло предупреждение об уязвимости в транзитивной зависимости.
+- После установки посыпались замечания линтера или переформатировалось дерево.
+
+## Верхнюю границу задают peer-диапазоны
+
+```bash
+npm view @angular/compiler-cli@22.1.0 peerDependencies
+npm view typescript versions --json | tail -5
+```
+
+Пакет поднимают до последней версии, которая ещё попадает в peer-диапазон каждого, кто от него
+зависит, а не до последней в реестре. Проверять приходится по одному пакету: `autoInstallPeers:
+true` молча доставляет недостающее, и конфликт peer-диапазонов установку не останавливает.
+
+## Порядок
+
+1. `package.json` — точные номера, ни одного `^` и `~`.
+2. `pnpm install`; снимок едет тем же коммитом.
+3. `npx nx run-many -t build -p site admin api` — сборка **до** линтеров: о несовместимости
+   типов она говорит одной строкой, а линтер на том же дереве даёт сотню замечаний, и
+   настоящая причина в них теряется.
+4. `npm run lint` и `npm run stylelint`.
+5. Тесты — правило `testing`. После смены версии Playwright сначала
+   `npx playwright install chromium`.
+6. Обход экранов в браузере — правило `browser-verification`: если пакет рисует вёрстку, смену
+   его версии тесты не покрывают.
+
+## Переформатирование
+
+Обновлённый форматтер меняет все файлы дерева. Что из этого оставлять, решает не размер дифа,
+а то, чьё форматирование проверяет линтер: `.ts` и `.html` — `eslint.config.mjs`, `.scss` —
+`stylelint.config.js`. Остальное переформатируется потом, вместе с правкой, которая эти файлы
+и так трогает: полный прогон изменил 883 файла, из которых проверяются 85, и осмысленные
+правки в такой куче не разглядеть.
+
+## Новые правила линтера
+
+Правило, которое запрещает приём, принятый в этом дереве, выключают один раз в конфиге и
+пишут рядом причину. Правило, которое право по существу, обходят точечным
+`eslint-disable-next-line` — тоже с причиной. Смешивать нельзя: выключенное в конфиге без
+причины через месяц выглядит забытым, а шестьдесят пять точечных обходов одного правила —
+списком того, что надо было выключить один раз.
+
+## Частые промахи
+
+- `pnpm install` не двигает пакет, если он назван в `overrides`: строка из списка держит
+  прежнюю версию, а установка проходит без ошибок.
+- Линтеры до сборки — лишний круг: разбираешь замечания, которых после сборки не будет.
+- Обновление, попавшее в ветку с другой задачей, откатится только вместе с ней: у обновления
+  зависимостей своя задача и своя ветка.