dsh-desktop-kit 0.0.0-stage → 2.0.0

package/skills/dev-workflow/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: dev-workflow
+description: "Универсальный процесс разработки: разведка, план, безопасные правки, проверки, ревью, релиз, память и Definition of Done."
+whenToUse: "В начале любой задачи по коду, данным, конфигам или релизу: какой порядок шагов и какие проверки нельзя забыть."
+user-invocable: true
+---
+
+# Универсальный процесс разработки
+
+> ≈1 450 токенов. Ядро процесса для любого проекта; этапы и расширенный DoD — §2.
+
+## 0 Когда применять
+- Любая задача по коду, данным, конфигам, инфраструктуре или релизу — даже «мелкая правка».
+- Сначала триаж навыков (`skills-router`), затем шаги по §1; проектные скиллы уточняют этот.
+- Исследование или текст без правок — профильный скилл и его гейты.
+
+## 1 Главное
+
+**Шаг 0 — триаж (обязателен).** `skills-router`: тип работы → все применимые скиллы — до разведки и правок.
+
+**Этапы — всегда в этом порядке:**
+1. **Разведка:** память проекта, затронутые файлы/маршруты/модели, риски, критерии приёмки.
+2. **План:** шаги и способ проверки; крупная задача — todo и договорённость с командой.
+3. **Бэкап/безопасность:** git или копия файлов, для БД — дамп; заранее решить, как откатывать.
+4. **Реализация:** минимальные локальные правки, чужие зоны не трогать, держать инварианты.
+5. **Проверки:** линтер, статанализ, тесты (unit/feature), E2E/UI и визуальная проверка при задетом интерфейсе.
+6. **Ревью:** `code-review-checklist` — данные, доступ, безопасность, тесты, стиль, дифф.
+7. **Документация/версия:** документация и CHANGELOG, версия — по правилам проекта.
+8. **Релиз:** `release-and-deploy` — артефакт → проверка → выкатка → smoke → откат.
+9. **Память:** итог (что сделано, как проверено, риски) — в память проекта.
+
+**Принципы.** Сначала понять — потом менять; одна задача — один связный дифф; чужие зоны не ломать; необратимое (удаление данных, деплой, публикация) — только с явного разрешения; застрял — `debugging-playbook`; ключевые факты — в память, длинные сессии — компактить.
+
+## 2 Куда грузить дальше
+| Когда нужно | Файл | ≈токенов |
+|---|---|---|
+| Этапы: входы, артефакты, стоп-условия, ошибки | references/stages.md | ≈2 000 |
+| Полный DoD, гейты по типам работ, шаблон отчёта | references/definition-of-done.md | ≈1 000 |
+| Память, контекст, границы, необратимые действия | references/memory-and-boundaries.md | ≈950 |
+
+## 3 Гейт перед сдачей
+- [ ] Скиллы загружены и использованы; гейты перечислены в отчёте.
+- [ ] Критерии приёмки выполнены; проверено вживую, не только тестами.
+- [ ] Тесты: существующие зелёные, новые падают без правки.
+- [ ] Линтер и статанализ без новых ошибок; в диффе нет секретов, отладки и случайных файлов.
+- [ ] UI — скриншоты «до/после», 1440/390, light/dark.
+- [ ] Данные защищены (бэкап, аддитивные миграции), план отката есть.
+- [ ] Документация, версия и память проекта обновлены.

package/skills/dev-workflow/references/definition-of-done.md

@@ -0,0 +1,44 @@
+# Definition of Done и шаблон отчёта
+
+> Часть навыка dev-workflow. ≈1 000 токенов. Читать, когда: закрываешь задачу, готовишь отчёт или принимаешь чужую работу.
+
+## 1. Полный чек-лист
+- [ ] Применимые скиллы загружены на старте и реально использованы; гейты перечислены в отчёте.
+- [ ] Критерии приёмки выполнены и проверены вживую.
+- [ ] Тесты: существующие зелёные, новые добавлены и падают без правки.
+- [ ] Линтер и статанализ без новых ошибок.
+- [ ] UI (если задет): скриншоты «до/после», 1440/390, light/dark; axe critical/serious = 0.
+- [ ] Нет секретов, отладочного кода и случайных файлов в диффе.
+- [ ] Данные защищены: бэкап, аддитивные миграции, известный откат.
+- [ ] Документация и CHANGELOG обновлены.
+- [ ] Версия поднята по правилам проекта.
+- [ ] Память проекта обновлена: итог, риски, следующие шаги.
+- [ ] Необратимые и внешние действия согласованы.
+
+## 2. Гейты по типу работы
+
+| Тип | Обязательные гейты |
+|---|---|
+| Код/бэкенд | тесты, линтер, статанализ, ревью, версия |
+| UI/вёрстка | скриншоты 1440/768/390, обе темы, axe, адаптив |
+| БД/миграции | бэкап до, проверка на копии, откат, инварианты |
+| Релиз/деплой | артефакт, checksums, smoke, план отката |
+| SEO/контент | мета, структура, schema, ссылки, проверка фактов |
+| Плагин/инфраструктура | изоляция, конфиг, совместимость, откат |
+
+## 3. Шаблон отчёта
+```
+1. Что сделано — 2–5 пунктов, без пересказа кода.
+2. Как проверено — команды, тесты, скриншоты, ручные сценарии.
+3. Гейты — какие скиллы и проверки пройдены, что не применимо и почему.
+4. Риски и ограничения — честно, включая непроверенное.
+5. Дальше — что осталось и рекомендации.
+```
+
+## 4. Признаки, что сдавать рано
+- «Работает у меня» без воспроизводимой проверки.
+- Скриншоты только desktop и только светлой темы.
+- Тесты не запускались или упали, а «потом починим».
+- В диффе секреты, дампы, `.env`, случайные файлы.
+- Не описан путь отката для миграции или деплоя.
+- В отчёте нет гейтов — непонятно, что именно проверено.

package/skills/dev-workflow/references/memory-and-boundaries.md

@@ -0,0 +1,31 @@
+# Память, границы и необратимые действия
+
+> Часть навыка dev-workflow. ≈950 токенов. Читать, когда: работаешь в чужом или большом проекте, нужно сохранить контекст или принять рискованное решение.
+
+## 1. Память проекта
+- В начале: прочитать досье и журнал проекта; не угадывать архитектуру по именам файлов.
+- В конце: записать итог — что сделано, как проверено, риски, следующий шаг, нужные команды.
+- Писать факты, а не эмоции: решения, ловушки, инварианты, пути к артефактам.
+- Секреты, пароли, токены и персональные данные в память не писать.
+- Не дублировать одно и то же: обновлять существующую секцию, а не плодить копии.
+
+## 2. Контекст
+- Длинная сессия → компактить; ключевые факты — в память до сжатия.
+- Читать только нужные фрагменты больших файлов, не грузить всё «на всякий случай».
+- Ссылки на артефакты (скриншоты, отчёты, логи) — вместо их содержимого в чате.
+
+## 3. Границы
+- Не менять чужие зоны без причины; если правка неизбежна — сказать об этом в отчёте.
+- Соблюдать соглашения проекта (структура, стиль, команды), даже если «так красивее».
+- Одна задача — один связный дифф; не смешивать рефакторинг и фичу.
+- Проектные скиллы уточняют универсальные; при конфликте — проектный, но не в ущерб безопасности и данным.
+
+## 4. Необратимые действия
+- Удаление данных, `migrate:fresh/reset`, `db:wipe`, `TRUNCATE`, деплой, публикация, рассылка — только с явного разрешения.
+- Перед действием: бэкап, проверка окружения (прод или тест), понятный откат.
+- Сомневаешься — остановись и спроси; «потом восстановим» — не план.
+
+## 5. Команда
+- Договариваться о границах файлов и модулей до правок.
+- В отчёте — что изменилось и что проверять коллеге.
+- Не менять молча общие конфиги, CI и зависимости.

package/skills/dev-workflow/references/stages.md

@@ -0,0 +1,67 @@
+# Этапы разработки — подробно
+
+> Часть навыка dev-workflow. ≈2 000 токенов. Читать, когда: нужен полный разбор этапов — что на входе, что на выходе, где остановиться и какие ошибки типичны.
+
+## Шаг 0. Триаж
+- Вход: формулировка задачи.
+- Действия: `skills-router` → тип работы → все применимые скиллы (планирование, UI, SEO, БД, тесты, безопасность, релиз, проектные).
+- Выход: список загруженных скиллов и объяснение, зачем они — в плане или первом сообщении.
+- Стоп-условие: задача непонятна → вопросы, а не догадки.
+
+## 1. Разведка
+- Прочитать память проекта (досье, журнал), правила проекта (`AGENTS.md`), найти затронутые файлы, маршруты, модели, миграции.
+- Понять текущее поведение фактами: тесты, логи, скриншот, запрос к БД — что реально происходит.
+- Отметить риски: данные, доступ, прод, деньги, публичный контент, необратимость.
+- Выход: список файлов и зон, риски, критерии приёмки.
+
+## 2. План
+- Короткий список шагов; для крупного — todo и, если есть, договорённость с командой или заказчиком.
+- Для каждой правки: как проверим — тест, скриншот, запрос, ручной сценарий.
+- План должен быть проверяемым: «сделать X, чтобы Y стал Z».
+
+## 3. Бэкап и безопасность
+- Git: рабочая ветка, понятный коммит до крупных правок; проект без git — копия затрагиваемых файлов.
+- БД: дамп (`pg_dump -Fc`), проверка окружения и `migrate:status`; миграции — аддитивные, с планом отката.
+- Секреты не выносить в код и логи; `.env` не менять без необходимости и пересборки конфига.
+- Выход: известный путь отката.
+
+## 4. Реализация
+- Минимальные локальные правки в затронутых зонах; не переписывать чужое «по пути».
+- Соблюдать инварианты проекта и стиль файла; новую зависимость — только с причиной.
+- Валидация на границе, транзакции для связанных записей, права проверять на сервере.
+- Не оставлять отладочный код, `console.log`, закомментированные блоки.
+
+## 5. Проверки
+- Линтер и статанализ — без новых ошибок; существующие не «чинить» мимоходом.
+- Тесты: unit/feature; новые тесты падают без правки и проходят с ней.
+- E2E/UI, если задет интерфейс; визуальные скриншоты 1440/390, light/dark.
+- Ручная проверка сценария вживую: тесты не заменяют глаза и реальные данные.
+- Выход: вывод команд и скриншоты в отчёте.
+
+## 6. Ревью
+- `code-review-checklist`: данные, доступ, ввод/вывод, секреты, тесты, дифф, стиль.
+- Прочитать свой дифф целиком, как чужой: нет лишних файлов, форматирования и случайностей.
+- Проверить поведение на ошибках: пустые данные, отказ сети, неверный ввод.
+
+## 7. Документация и версия
+- Обновить документацию/CHANGELOG, если поведение или конфиг изменились.
+- Версия — по правилам проекта (пакет, `APP_VERSION`, тег); миграции — в инструкции.
+- В память — то, что понадобится позже: решения, ловушки, команды.
+
+## 8. Релиз
+- `release-and-deploy`: сборка артефакта, checksums, безопасная выкатка, smoke-проверки, план отката.
+- Перед выкаткой — бэкап и проверка на копии; после — ключевые сценарии и логи.
+- Необратимые операции и прод — только с явного разрешения.
+
+## 9. Память
+- Итог: что сделано, как проверено, какие риски остались, что дальше.
+- Записать в память проекта (досье/журнал) без секретов и лишних деталей.
+
+## Типичные ошибки
+- Застрял: сузить проблему, собрать факты, написать минимальное воспроизведение, затем `debugging-playbook`.
+- Начал править без триажа и чтения памяти → сломал инвариант.
+- Правки «заодно» в чужих зонах → неожиданный дифф и баги.
+- Тесты не запускал или проверял только счастливый путь.
+- Миграция без бэкапа и отката; destructive-команда на боевой БД.
+- «Проверил вживую» = открыл страницу один раз без мобильного и тёмной темы.
+- Забыл версию, документацию и память — следующий заход начинается с нуля.

package/skills/git-and-ci/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: git-and-ci
+description: "Git и CI: гигиена репозитория, ветки, атомарные коммиты, теги релизов, pre-commit, пайплайн и защита секретов."
+whenToUse: "При init репозитория, коммитах, ветках, тегах, настройке или отладке CI, перед релизом и при утечке секрета в историю."
+user-invocable: true
+---
+
+# Git и CI (универсально)
+
+## 0. Когда применять
+- Создаёшь репозиторий, `.gitignore`, первый коммит.
+- Коммитишь, ветвишься, мержишь, ставишь тег.
+- Настраиваешь/чинишь CI или pre-commit.
+- Секрет попал в дифф/историю; нужен откат опубликованного.
+
+## 1. Главное
+
+**Репозиторий**
+- `.gitignore` до первого коммита: зависимости, сборки, `.env*`, runtime, IDE, дампы; lock-файлы — в git.
+- Перед коммитом: `git status --short`, `git diff --check`, `git diff --stat`; в индекс — только осознанные файлы.
+- Не коммитить: `vendor/`, `node_modules/`, `public/build`, `storage/`-рантайм, дампы, PII.
+
+**Ветки и коммиты**
+- `main` — стабильная и защищённая; работа — в `feature/<кратко>` / `fix/<кратко>`.
+- Коммиты атомарные: «что и зачем» (`feat:`, `fix:`, `chore:`); форматирование и функционал — раздельно.
+- Полный дифф перед коммитом: секреты, `dd`/`dump`, отладка, случайные файлы.
+- Тег — аннотированный `vX.Y.Z` на проверенном коммите: `git tag -a vX.Y.Z -m "..."`, `git push origin vX.Y.Z`; опубликованный не двигать.
+
+**Перед коммитом**
+1. Линтер по изменённым файлам.
+2. Статанализ без новых ошибок.
+3. Тесты unit/feature; E2E для UI.
+4. Дифф на секреты/отладку/мусор; `--no-verify` — только в аварии.
+
+**CI**
+1. Checkout + кэш зависимостей (без секретов).
+2. Установка из lock, неинтерактивно.
+3. Линтер + статанализ.
+4. Тесты на реальной СУБД (service-контейнер) с baseline.
+5. Сборка ассетов.
+6. E2E; при падении — скриншоты/логи.
+7. По тегу — артефакт и `checksums.txt`.
+
+CI гоняет те же команды, что локально; `main` — только с зелёным пайплайном и ревью.
+
+**История**
+- `git log --oneline`, `git diff main...HEAD` перед ревью.
+- Опубликованное — `git revert`; `git reset` — только локально; force-push — лишь своя ветка с `--force-with-lease`, никогда `main`.
+- Большие бинарники/дампы — не в git.
+- Секрет в истории скомпрометирован: ротировать и чистить историю (`git filter-repo`/BFG) с предупреждением команды.
+
+## 2. Куда грузить дальше
+`release-and-deploy` — версия, артефакт, checksums, выкатка; `code-review-checklist` — ревью; `security-review` — секреты; `service-desk-release` — проектный релиз.
+
+## 3. Гейт перед сдачей
+- [ ] `.gitignore` актуален; status/дифф без мусора, секретов и PII.
+- [ ] Ветка и сообщение коммита отражают суть; форматирование отдельно.
+- [ ] Линтер, статанализ, тесты зелёные; для UI — E2E.
+- [ ] Тег на проверенном коммите; CI на `main` зелёный.
+- [ ] Секрет ротирован, история очищена.

package/skills/pg-upgrade-verify/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: pg-upgrade-verify
+description: "Проверка обновления на копии живой PostgreSQL-базы: до/после, контрольные суммы, схема и smoke — без риска для прода."
+whenToUse: "Перед выкаткой обновления со схемой, миграциями, сидами или данными; когда нужно доказать, что данные не потеряны."
+user-invocable: true
+---
+
+# Проверка обновления на копии живой БД (PostgreSQL)
+
+Цель: доказать, что обновление не изменило данные и приложение работает. **Только на копии.**
+
+## 0. Когда применять
+- Обновление меняет схему, миграции, сиды или данные.
+- Нужно доказать «до/после», что записи не потеряны.
+- Перед релизом.
+
+## 1. Главное
+
+**Правила**
+- Тестовая БД `servicedesk_upgrade_test` и отдельная папка; боевая БД, `migrate:fresh` и `db:wipe` — запрещены.
+- Перед командами проверь `.env` (`DB_DATABASE=servicedesk_upgrade_test`, `APP_ENV=local`, `APP_URL=http://localhost`).
+- Дамп с PII — локально, не в git/отчёт.
+
+**Подготовка**
+1. Отдельная БД `servicedesk_upgrade_test` (не боевая).
+2. Развернуть **старую** версию в отдельную папку.
+3. `vendor` — из рабочей копии при совпадении `composer.lock`.
+4. `.env`: тестовая БД, `APP_URL=http://localhost`, `APP_KEY` — `key:generate`.
+5. `php artisan migrate --force` + `db:seed --force` (+ `DemoDataSeeder`).
+6. «Живые» данные: 1–3 строки в `tickets`, `ticket_comments`, `ticket_attachments`, `assets`, `consumables`, `stock_moves`, `kb_articles`, `activity_logs`, `ticket_reads`.
+7. Лучше — дамп боевой БД в тестовую; без него — п. 2–6.
+
+**«До»**
+```sql
+SELECT 'tickets', count(*) FROM tickets UNION ALL SELECT 'users', count(*) FROM users;
+SELECT 'tickets_max', max(id)||'/'||max(number) FROM tickets;
+SELECT 'tickets_checksum', md5(string_agg(t::text,'|' ORDER BY id)) FROM tickets;
+SELECT 'comments_checksum', md5(coalesce(string_agg(c::text,'|' ORDER BY id),'')) FROM ticket_comments c;
+```
+Сохранить в `_upgrade-before.txt`; снять схему: `pg_dump --schema-only -d servicedesk_upgrade_test -f before-schema.sql`.
+
+**Имитация**
+1. Наложить новый код: `tar -xzf new.tgz -C <папка>`.
+2. Изменился `composer.lock` → `composer install --no-dev`; UI → `npm ci && npm run build`.
+3. `php artisan backup:run` (если используется) — копия создалась.
+4. `php artisan migrate --force` (ожидаемо «Nothing to migrate»).
+5. `php artisan db:seed --force`.
+6. `APP_VERSION` в `.env` (как `deploy/update.sh`).
+
+**«После»**
+- Повторить SQL и `pg_dump -s`: counts/max/md5 совпадают, схема — только новые объекты; рост — лишь журналы backup/seed.
+- Smoke: `/login` 200 и вход, `/tickets` 200 со старыми номерами, `/tickets/{id}/edit` — старые комментарии/вложения.
+- `migrate:status` — все `Ran`; лог чист.
+- Расхождение → стоп, не выкатывать, искать причину в миграциях/сидерах.
+
+**Уборка**
+- `DROP DATABASE servicedesk_upgrade_test`; удалить папку теста.
+- Артефакты — в `...\memory\projects\<проект>\tests\`; запись в `SESSIONS.md`.
+
+## 2. Куда грузить дальше
+`database-safety` — общие правила; `service-desk-db-safety` — бэкап; `release-and-deploy` / `service-desk-release` — выкатка.
+
+## 3. Гейт перед сдачей
+- [ ] Тестовая БД/папка; `.env` проверен, прод не затронут.
+- [ ] «До/после» сняты: counts, max, md5, схема; расхождений нет.
+- [ ] Smoke: вход, `/tickets`, старые данные; `migrate:status` — `Ran`.
+- [ ] Тестовая БД/папка удалены; отчёт записан в память.

package/skills/project-deep-dive/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: project-deep-dive
+description: "Глубокий анализ проекта с записью в локальное досье project_memory: разведка, архитектура, карта кода, инварианты, ловушки, runbook, теги достоверности и честный отчёт."
+whenToUse: "Просьба «глубоко проанализируй / разберись и запомни проект», /remember, досье отсутствует или устарело, либо впереди крупная работа в незнакомом проекте."
+user-invocable: true
+---
+
+# Project-deep-dive — ядро
+> ≈1 600 токенов. Понимание проекта → локальное досье; детали — по ссылкам.
+
+## 0. Контракт
+1. `project_memory(action="status")` — первым, до чтения проекта.
+2. Только локально: код, конфиги, пути, серверы, БД и логи не уходят в `web_fetch`/`web_search`/внешние API.
+3. Секреты и PII (пароли, токены, ключи, DSN, e-mail, телефоны, ФИО, адреса) не пишем; можно «секрет в `.env`, `DB_PASSWORD`».
+4. Секции — только `update_section`; досье и `INDEX.json` руками не правь.
+5. Финал: записанные секции + проверенные факты + «неясно»; без последнего отчёт неполон.
+
+## 1. Когда и API
+- «Глубоко проанализируй/запомни», «составь досье», `/remember` (`PROJECT`, `ARCHITECTURE`, `CODE-MAP`, `RUNBOOK`); перед крупной работой в незнакомом проекте.
+- Устарело: `lastAnalyzedAt` >~30 дней, `git.head` ≠ HEAD, другая ветка. Не нужно при актуальном досье и точечном вопросе.
+- API: `project_memory(...)`; `status` → `register(name, root, stack?)` → `read`/`search` → `update_section`/`append_journal`; `file` — секция досье, `mode` — replace/append, `maxChars` 500–30000 (12000), `project` — текущий по умолчанию.
+
+## 2. Алгоритм
+1. **Статус.** `status`; нет проекта — `register`; неясно — спроси, не угадывай; устарело — предупреди, старое помечай `[устарело]`.
+2. **Известное.** `read` (6000–8000), не дублируй; конфликт — перепроверь код: победитель в досье, проигравший `[устарело]`.
+3. **Разведка.** Только чтение: `AGENTS.md` → `README*` → манифесты → структура → git; изменяющих команд нет.
+4. **Потоки.** Вход → маршрут → обработчик → домен → данные → тесты; фиксируй только объясняющее запуск, логику, данные и хрупкие места.
+5. **Секции.** `PROJECT` → `ARCHITECTURE` → `CODE-MAP` → `INVARIANTS` → `GOTCHAS` → `RUNBOOK`; каждая отдельным `update_section` + `read`. Минимумы: 8–15 строк / 15+ / 10+ записей / 5+ / 3+ / 5+ команд; малый проект — пропорционально.
+6. **Теги.** `[проверено]` — источник + `path:line`; `[выведено]` — логический вывод; `[устарело]` — было верно раньше. Без кода, логов и дампов.
+7. **Журнал.** Значимую сессию — `append_journal` по шаблону `project-memory-maintenance` (5 пунктов).
+8. **Отчёт.** «Записано» (каждая секция), «Проверено» (факты), «Неясно» (каждый пункт), «Дальше».
+
+## 3. Куда грузить дальше
+| Нужно | Файл | ≈токенов |
+|---|---|---|
+| Разведка, трассировка, git, `[проверено]` | `references/recon-commands.md` | ≈2 000 |
+| Каркасы секций, примеры, форма отчёта | `references/section-templates.md` | ≈1 450 |
+| Полный API, детали шагов, антипаттерны | `references/tool-and-process.md` | ≈2 950 |
+
+## 4. Гейт перед сдачей
+- [ ] `status` первым, slug определён; секции прочитаны, дублей нет.
+- [ ] Каждая секция — `update_section` + `read`; минимумы и ≤ 40 KB.
+- [ ] Нет секретов/PII (перечитано), кода, логов и дампов.
+- [ ] Теги и `path:line`; противоречия разобраны, старое помечено.
+- [ ] JOURNAL дописан; отчёт: «Записано» и «Неясно»; в сеть ничего.

package/skills/project-deep-dive/references/recon-commands.md

@@ -0,0 +1,90 @@
+# Разведка проекта: команды и источники
+
+> Часть навыка project-deep-dive. ≈2 000 токенов. Читать, когда: нужны команды разведки по стеку, трассировка потоков, проверка git-свежести или критерий `[проверено]`.
+
+> Только чтение. Ничего не запускай на изменение (миграции, seed, деплой, install) ради досье.
+> Если `rg` нет — используй инструменты `glob`/`grep` или `Get-ChildItem -Recurse`.
+> Значения `.env` не читай: имена переменных бери из `.env.example` или из кода.
+
+## 0. Подготовка
+```powershell
+$root = "C:\path\to\project"     # абсолютный путь, проверить Test-Path
+Test-Path (Join-Path $root "AGENTS.md")
+Test-Path (Join-Path $root ".git")
+```
+
+## 1. Универсальный минимум (любой стек)
+```powershell
+Get-ChildItem $root -Name
+git -C $root rev-parse --abbrev-ref HEAD
+git -C $root rev-parse --short HEAD
+git -C $root log -5 --oneline
+git -C $root status --short
+rg --files $root -g '!node_modules' -g '!vendor' -g '!dist' -g '!build' -g '!.git' | Select-Object -First 300
+```
+- `AGENTS.md` — правила работы в проекте (читать первым).
+- `README*`, `docs/`, `CONTRIBUTING*` — заявленный процесс; проверяй кодом, а не верь на слово.
+- Манифесты: `composer.json`, `package.json`, `pnpm-lock.yaml`, `yarn.lock`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `Dockerfile`, `docker-compose.yml`, `Makefile`, `.env.example`.
+- CI: `.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile` — какие проверки реально гоняются.
+
+## 1a. Трассировка потоков
+Цепочка: точка входа → маршрут → обработчик → домен → данные → тесты. Фиксируй только то, что объясняет запуск, бизнес-логику, данные и хрупкие места.
+```powershell
+rg -n "Route::|router\.|app\.(get|post)|urlpatterns" $root -g '!node_modules' -g '!vendor'
+rg --files $root | rg "migrations|schema|models|entities"
+rg -n "class \w+(Service|Controller|Handler|Repository)\b" $root -g '!vendor' -g '!node_modules'
+rg -n "process\.env|config\(|ENV\[|getenv\(" $root -g '!node_modules' -g '!vendor'
+rg --files $root | rg "(^|/)(tests?|spec|__tests__|phpunit|playwright)/"
+```
+
+## 2. Laravel / PHP
+```powershell
+rg -n "Route::|->group\(|middleware\(" routes app -g '*.php'
+rg -n "class \w+Controller|class \w+Service|class \w+Repository|function handle" app -g '*.php'
+php artisan about            # безопасно: версии и окружение
+php artisan route:list --except-vendor
+php artisan migrate:status
+rg --files database/migrations
+rg -n "validate\(|Validator::|FormRequest|authorize\(" app -g '*.php'
+rg -n "DB::transaction|lockForUpdate|queue|dispatch\(" app -g '*.php'
+rg --files tests; rg -n "class \w+Test" tests -g '*.php'
+```
+- Модули/провайдеры: `config/`, `app/Providers/`, `bootstrap/app.php` (Laravel 11+).
+- Тесты: `php artisan test`, `php scripts/test.php`, `make test` — фиксируй команду из README/AGENTS, но не запускай полный прогон ради анализа.
+- Не выполняй `migrate:fresh`, `db:wipe`, `db:seed`, `config:cache` и прочие изменяющие команды.
+
+## 3. JS / TS (Node, React, Vite, Next)
+```powershell
+Get-Content (Join-Path $root "package.json") -Raw | ConvertFrom-Json | Select-Object -ExpandProperty scripts
+rg -n "process\.env\.|import\.meta\.env\." $root -g '!node_modules' -g '*.{ts,tsx,js,jsx}'
+rg --files $root -g '!node_modules' | rg "(^|/)(src|app|pages|routes|components|store|lib|services)/"
+rg -n "createRoot|Router|createBrowserRouter|NextPage|defineConfig" $root -g '!node_modules' -g '!dist'
+rg --files $root -g '!node_modules' | rg "\.(test|spec)\.(ts|tsx|js|jsx)$"
+```
+- Точки входа: `src/main.*`, `src/index.*`, `app/layout.*`, `pages/api/`.
+- Сборка/проверки: скрипты `build`, `lint`, `typecheck`, `test` из `package.json`.
+
+## 4. Bitrix / Aspro
+- Файлы сайта обычно только на сервере: фиксируй, что локально есть (`local/`, `bitrix/templates/aspro-*`), а что нет.
+- `local/php_interface/init.php`, `local/templates/<шаблон>/`, `bitrix/templates`, компоненты `local/components`, инфоблоки — по названиям и вызовам.
+- Не трогай ядро `bitrix/`; не запускай агенты, кеш-сбросы, обновления без разрешения.
+
+## 5. Python / Go / прочее
+- Python: `pyproject.toml`, `manage.py` (Django), `main.py`, роуты Flask/FastAPI (`@app.get`, `APIRouter`), `alembic/versions`.
+- Go: `go.mod`, `main.go`, `internal/`, `cmd/`, `*_test.go`.
+
+## 6. Свежесть и git
+```powershell
+git -C $root rev-parse --abbrev-ref HEAD
+git -C $root rev-parse HEAD
+git -C $root log -1 --format="%h %ad %s" --date=short
+git -C $root tag --sort=-v:refname | Select-Object -First 5
+```
+- Сравни с `INDEX.json` досье (`status`): другой `git.head`/ветка — досье устарело.
+- `lastAnalyzedAt` старше ~30 дней — предупреди пользователя.
+
+## 7. Что считать `[проверено]`
+- Прочитал файл и увидел реализацию — да, со ссылкой `path:line`.
+- Запустил безопасную read-only команду (`git`, `route:list`, `--version`) и увидел вывод — да.
+- Вывел из соглашений фреймворка без прямого источника — только `[выведено]`.
+- Изменил проект ради проверки — так делать нельзя: досье не повод править код.

package/skills/project-deep-dive/references/section-templates.md

@@ -0,0 +1,104 @@
+# Шаблоны секций досье
+
+> Часть навыка project-deep-dive. ≈1 450 токенов. Читать, когда: заполняешь секции досье или собираешь обязательный отчёт; нужны примеры формы, минимумы и структура блоков.
+
+> Правило: ссылки `path:line` вместо кода; метка достоверности у ключевых утверждений;
+> объём секции ≤ 40 KB; содержимое — выводы, а не дампы.
+> Примеры ниже — образец формы, а не текст для копирования.
+
+## PROJECT
+```markdown
+## Назначение
+- ... [проверено] (README.md:3)
+## Стек и версии
+- PHP 8.5, Laravel 13, PostgreSQL 18 (composer.json:8, .env.example:1)
+## Где лежит
+- Рабочая копия: C:\... ; прод: <сервер>, <путь> [выведено]
+## Запуск
+- ... (README.md:15)
+## Статус и владелец
+- ... [проверено]/[устарело]
+```
+Минимум 8–15 строк: назначение, стек, расположение, запуск, статус.
+
+## ARCHITECTURE
+```markdown
+## Компоненты и границы
+- <модуль> — отвечает за ..., границы: ... (modules/X/..., app/...)
+## Точки входа
+- HTTP: routes/... ; CLI: ... ; крон: ...
+## Поток данных
+1. запрос -> middleware -> контроллер (path:line) -> сервис (path:line) -> БД
+## Внешние зависимости
+- ... [проверено] (config/services.php:12)
+## Ключевые решения
+- Почему так: ... [выведено] / подтверждено тестом (tests/...:40)
+```
+15+ строк; если схема сложная — текстом или mermaid-блоком, без копий кода.
+
+## CODE-MAP
+```markdown
+| Область | Путь | Зачем |
+|---|---|---|
+| HTTP-маршруты | routes/web.php:1 | публичные и админ-маршруты |
+| Бизнес-логика | app/Services/...:1 | ... |
+| Модели/схема | app/Models, database/migrations | ... |
+| UI | resources/views, themes/... | ... |
+| Тесты | tests/Feature/... | ... |
+| Конфиги | config/... | ... |
+```
+10+ записей; для каждого пути — назначение, а не пересказ кода.
+
+## INVARIANTS
+```markdown
+1. Миграции только аддитивные; старые не редактировать.
+   - Почему: прод обновляется поверх живой БД.
+   - Проверка: git diff database/migrations в релизе.
+   - Источник: AGENTS.md:42 [проверено]
+```
+5+ пунктов; одно правило — один номер; обязательно «почему» и «как проверить».
+
+## GOTCHAS
+```markdown
+### <симптом одной строкой>
+- Симптом: ... [проверено] (path:line)
+- Причина: ...
+- Обход: ...
+- Риск, если игнорировать: ...
+```
+3+ ловушки; никаких «на всякий случай» — только реально встреченные или доказанные кодом.
+
+## RUNBOOK
+Разделы: `## Окружение`, `## Установка`, `## Запуск`, `## Тесты`, `## Сборка`, `## Деплой и откат`, `## Бэкап`, `## Диагностика`.
+Команды — отдельными блоками PowerShell по разделу, например:
+
+    # установка
+    ...
+    # тесты
+    ...
+
+5+ команд; команды копируй из README/AGENTS/CI, а не сочиняй; для опасных — пометка «не запускать на проде».
+
+## Отчёт пользователю (обязательная форма)
+```markdown
+## Записано в досье
+- PROJECT — <сколько фактов/строк, что главное>
+- ARCHITECTURE — ...
+- CODE-MAP — ...
+- INVARIANTS — ...
+- GOTCHAS — ...
+- RUNBOOK — ...
+
+## Уверенность
+- [проверено]: ключевые факты — <перечислить>
+- [выведено]: <что выведено и почему>
+- [устарело]: <что требует перепроверки>
+
+## Неясно / требует проверки
+1. <вопрос> — как проверить
+2. ...
+
+## Дальше
+- <следующий шаг>
+```
+Не сокращай «Неясно» до одной фразы и не прячь её в конце.