dsh-desktop-kit 1.0.0 → 2.0.1

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

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

@@ -1,48 +1,67 @@
 ---
 name: pg-upgrade-verify
-description: "Универсальная проверка обновления на копии живой PostgreSQL-базы — до/после без риска для прода."
-whenToUse: "Перед выкаткой любого обновления, которое трогает схему БД, сиды или данные; для доказательства, что данные не потеряны."
+description: "Проверка обновления на копии живой PostgreSQL-базы: до/после, контрольные суммы, схема и smoke — без риска для прода."
+whenToUse: "Перед выкаткой обновления со схемой, миграциями, сидами или данными; когда нужно доказать, что данные не потеряны."
 user-invocable: true
 ---
 
 # Проверка обновления на копии живой БД (PostgreSQL)
 
-Цель: доказать, что после обновления данные существующей базы не изменились и приложение работает.
+Цель: доказать, что обновление не изменило данные и приложение работает. **Только на копии.**
 
-## 1. Подготовка
-1. Отдельная БД: `servicedesk_upgrade_test` (никогда не боевая!).
-2. Развернуть **старую** версию кода в отдельную папку (распаковать архив старой версии).
-3. Скопировать `vendor` из рабочей копии (если `composer.lock` совпадает) — так быстрее и без сети.
-4. `.env`: указать `DB_DATABASE=servicedesk_upgrade_test`, `APP_URL=http://localhost`, `APP_KEY` через `php artisan key:generate`.
-5. `php artisan migrate --force` + `db:seed --force` + при наличии `DemoDataSeeder`.
-6. Добавить «живые» данные: по 1–3 строки в ключевые таблицы (tickets, comments, attachments, assets, consumables, stock_moves, kb_articles, activity_logs, ticket_reads).
+## 0. Когда применять
+- Обновление меняет схему, миграции, сиды или данные.
+- Нужно доказать «до/после», что записи не потеряны.
+- Перед релизом.
 
-## 2. Зафиксировать «до»
+## 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' t, count(*) FROM tickets UNION ALL SELECT 'users', count(*) FROM users /* ... */;
+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 t;
+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`).
-
-## 3. Имитация обновления
-1. Наложить новый код поверх папки старой версии (`tar -xzf new.tgz -C <папка>`).
-2. `php artisan backup:run` (если используется) — проверить, что копия создалась.
-3. `php artisan migrate --force` (ожидаемо «Nothing to migrate», если миграций нет).
-4. `php artisan db:seed --force`.
-5. Обновить `APP_VERSION` в `.env` (как делает `deploy/update.sh`).
-
-## 4. Зафиксировать «после» и сравнить
-- Повторить SQL из п.2 → сравнить количества и md5 (должны совпасть; допустимый рост — только журналы от самих команд backup/seed).
-- Smoke: `/login` 200, вход, `/tickets` 200 со старыми номерами, `/tickets/{id}/edit` — старые комментарии/вложения видны.
-- `php artisan migrate:status | grep -c Ran` — все миграции Ran.
-
-## 5. Убрать за собой
-- Удалить тестовую БД (`DROP DATABASE servicedesk_upgrade_test`) и папку теста.
-- Артефакты «до/после» — в память/отчёт: `...\memory\projects\<проект>\tests\`.
-- Записать вывод в `SESSIONS.md`.
-
-## Важно
-- Не запускать на боевой БД; не использовать `migrate:fresh`.
-- Если контрольные суммы разошлись — остановиться, не выкатывать, искать причину в миграциях/сидерах.
+Сохранить в `_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

@@ -1,170 +1,45 @@
 ---
 name: project-deep-dive
-description: "Глубокий анализ проекта с запоминанием в локальное досье через project_memory: разведка, архитектура, карта кода, инварианты, ловушки, runbook, теги достоверности и честный отчёт."
-whenToUse: "Пользователь просит «глубоко проанализируй / разберись и запомни <проект>», вызвана команда /remember, досье отсутствует или устарело (старый lastAnalyzedAt или другой git HEAD), либо предстоит крупная работа в незнакомом проекте."
+description: "Глубокий анализ проекта с записью в локальное досье project_memory: разведка, архитектура, карта кода, инварианты, ловушки, runbook, теги достоверности и честный отчёт."
+whenToUse: "Просьба «глубоко проанализируй / разберись и запомни проект», /remember, досье отсутствует или устарело, либо впереди крупная работа в незнакомом проекте."
 user-invocable: true
 ---
 
-# PROJECT-DEEP-DIVE — анализ проекта и запоминание
-
-> Цель: понять проект настолько, чтобы дальше работать в нём без повторной разведки.
-> Результат — досье в `%USERPROFILE%\.dsh\projects-memory\<slug>\` и отчёт: что записано,
-> что проверено, что осталось неясным. Досье хранит выводы и ссылки, а не копии кода.
-
-## 0. Контракт (нарушать нельзя)
-
-1. **Первый вызов — `project_memory(action="status")`**, до чтения файлов проекта: он определяет проект, наличие и свежесть досье.
-2. **Никогда не отправляй содержимое проекта в сеть.** Ни `web_fetch`, ни `web_search`, ни внешние API не получают код, конфиги, пути, имена серверов, фрагменты БД и журналы. Анализ только локальный.
-3. **Никогда не сохраняй секреты и PII.** Пароли, токены, ключи, строки подключения, e-mail, телефоны, ФИО, адреса не попадают ни в досье, ни в журнал. Допустимо указать только имя переменной или файла: «секрет в `.env`, `DB_PASSWORD`».
-4. **Секции пишутся только через `update_section`.** Файлы досье и `INDEX.json` вручную не редактируй — иначе рассинхронизируются индекс и свежесть.
-5. **Финальный ответ обязан перечислить:** какие секции записаны, какие факты проверены, что осталось неясным. Отчёт без пункта «неясно» — признак поверхностного анализа.
-
-## 1. Когда применять
-
-- Просьба «глубоко проанализируй / разберись и запомни <проект>», «составь досье», «введи в курс».
-- Команда `/remember`: объём средний — `PROJECT`, `ARCHITECTURE`, `CODE-MAP`, `RUNBOOK`.
-- Перед крупной работой в незнакомом проекте: сначала досье, потом правки (см. `dev-workflow`, `requirements-and-planning`).
-- Досье устарело: `lastAnalyzedAt` старше ~30 дней, `git.head` в INDEX.json не равен текущему `git rev-parse HEAD`, сменилась ветка.
-- Не применять: точечный вопрос по одному файлу; разовая правка при актуальном досье.
-
-## 2. Инструмент project_memory
-
-Сигнатура: `project_memory(action, project?, file?, content?, query?, root?, name?, mode?, maxChars?)`.
-В текущей сборке инструмента у `register` есть также необязательный `stack` — короткое описание стека.
-Хранилище: `%USERPROFILE%\.dsh\projects-memory\<slug>\` — `PROJECT.md`, `ARCHITECTURE.md`, `CODE-MAP.md`, `INVARIANTS.md`, `GOTCHAS.md`, `RUNBOOK.md`, `JOURNAL/YYYY-MM.md`, `INDEX.json`.
-
-| action | Что делает | Обязательные аргументы | Пример |
-|---|---|---|---|
-| `status` | состояние хранилища, досье и свежести | — | `project_memory(action="status")` |
-| `register` | регистрирует проект | `name`, `root` (+ `stack`) | `project_memory(action="register", name="my-app", root="C:\work\my-app", stack="Laravel 13 / PostgreSQL")` |
-| `list` | список проектов | — | `project_memory(action="list")` |
-| `read` | читает файл досье | `project`, `file` | `project_memory(action="read", project="my-app", file="ARCHITECTURE", maxChars=8000)` |
-| `search` | ищет по досье перед записью | `query` | `project_memory(action="search", project="my-app", query="очереди")` |
-| `append_journal` | дописывает сессию в `JOURNAL/YYYY-MM.md` | `project`, `content` | `project_memory(action="append_journal", project="my-app", content="...")` |
-| `update_section` | записывает секцию досье | `project`, `file`, `content`, `mode` | `project_memory(action="update_section", project="my-app", file="ARCHITECTURE", content="...", mode="replace")` |
-
-- `file` — только `PROJECT`, `ARCHITECTURE`, `CODE-MAP`, `INVARIANTS`, `GOTCHAS`, `RUNBOOK`, `JOURNAL`.
-- `mode` — `replace` (секция перезаписывается целиком, по умолчанию) или `append` (дописать в конец).
-- `maxChars` — ограничение вывода `read` (500–30000, по умолчанию 12000); целиком досье не выкачивай.
-- `root` — абсолютный путь к корню проекта; `name` — slug в kebab-case (`service-desk`); `stack` — короткое описание стека при `register`.
-- `project` по умолчанию — проект текущей сессии; чужой проект указывай явно.
-- `content` — markdown секции по каркасам из §4.
-
-## 3. Процесс (8 шагов)
-
-### Шаг 1. Статус и проект
-`project_memory(action="status")`.
-- Проект найден — запомни slug и переходи к Шагу 2.
-- Нет проекта — `project_memory(action="register", name="<slug>", root="<абсолютный путь>")`.
-- Несколько кандидатов или непонятно, о каком проекте речь, — **спроси пользователя**, не угадывай.
-- Досье устарело — предупреди сразу; устаревшие факты в новых секциях помечай `[устарело]`.
-
-### Шаг 2. Что уже известно
-Прочитай существующие секции (`read` с `maxChars=6000–8000`). Цель — не дублировать и не противоречить.
-Новый факт спорит со старым — перепроверь по коду: победивший запиши, проигравший пометь `[устарело]`.
-
-### Шаг 3. Разведка (только чтение)
-Источники по порядку: `AGENTS.md` → `README*` → манифесты → структура каталогов → git.
-```powershell
-$root = "C:\path\to\project"
-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
-Get-ChildItem $root -Name
-```
-Манифесты и конфиги: `composer.json`, `package.json`, `pnpm-workspace.yaml`, `pyproject.toml`, `requirements.txt`, `go.mod`, `Cargo.toml`, `pom.xml`, `docker-compose.yml`, `Dockerfile`, `Makefile`, `.env.example`, `phpunit.xml`, `vite.config.*`, `tsconfig.json`.
-Дальше — `references/recon-commands.md` (рецепты для Laravel/PHP, JS/TS, Bitrix, generic).
-
-### Шаг 4. Трассировка потоков
-Веди цепочку «точка входа → маршрут → обработчик → домен → данные → тесты». Команды:
-```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)/"
-```
-Фиксируй не всё подряд, а то, что объясняет: как запустить, где бизнес-логика, где данные, что легко сломать.
-
-### Шаг 5. Сборка секций
-Порядок записи: `PROJECT` → `ARCHITECTURE` → `CODE-MAP` → `INVARIANTS` → `GOTCHAS` → `RUNBOOK`.
-Каждая секция — отдельный `update_section`; после записи прочитай её обратно (`read`).
-
-| Секция | Минимум | Обязательные блоки |
+# 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. Куда грузить дальше
+| Нужно | Файл | ≈токенов |
 |---|---|---|
-| `PROJECT` | 8–15 строк | назначение; стек и версии; где лежит (копия, прод); запуск; статус |
-| `ARCHITECTURE` | 15+ строк | компоненты и границы; точки входа; поток данных; внешние зависимости; ключевые решения |
-| `CODE-MAP` | 10+ записей | область → путь → зачем; сервисы; конфиги; тесты |
-| `INVARIANTS` | 5+ правил | правило → почему → как проверить → ссылка `path:line` |
-| `GOTCHAS` | 3+ ловушки | симптом → причина → обход |
-| `RUNBOOK` | 5+ команд | запуск; тесты; сборка; деплой и откат; бэкап; диагностика |
-
-Малый проект (один скрипт/сервис) — минимумы пропорционально ниже, но блоки те же. Подробные каркасы — `references/section-templates.md`.
-
-### Шаг 6. Метки достоверности и ссылки
-- `[проверено]` — прочитано в файле или подтверждено выводом команды; рядом ссылка `path:line`.
-- `[выведено]` — логический вывод (соглашение фреймворка, косвенная связь); прямого источника в коде нет.
-- `[устарело]` — было верно в прошлой версии/ветке; требует перепроверки.
-- Ссылка — всегда `относительный/путь:строка`; копировать код, логи и дампы в досье нельзя.
-
-### Шаг 7. Журнал
-Значимую сессию зафиксируй `append_journal` (сжато, по шаблону из `project-memory-maintenance`): что анализировали, что выяснили, какие решения, что осталось.
-
-### Шаг 8. Отчёт пользователю
-```markdown
-## Записано в досье
-- PROJECT — ...
-- ARCHITECTURE — ...
-
-## Проверено
-- [проверено] ... (path:line)
-
-## Неясно / требует проверки
-1. ...
-2. ...
-
-## Дальше
-- ...
-```
-Перечисли **каждую** записанную секцию и **каждый** неясный пункт. Не замалчивай сомнения.
-
-## 4. Каркасы секций (сжато)
-
-- `PROJECT`: что делает; стек и версии; репозиторий и прод; как поднять; статус и владелец.
-- `ARCHITECTURE`: слои и модули; поток данных текстом; очереди/крон; внешние сервисы; ключевые решения.
-- `CODE-MAP`: таблица «область | путь | зачем»; точки входа; модели/схема; тесты; конфиги.
-- `INVARIANTS`: нумерованные «нельзя», каждое с причиной и способом проверки.
-- `GOTCHAS`: симптом → причина → обход; отдельная ловушка — отдельный пункт.
-- `RUNBOOK`: окружение; установка; запуск; тесты; сборка; деплой; откат; бэкап; где логи.
-
-Полные шаблоны с примерами — `references/section-templates.md`.
-
-## 5. Гейт качества (перед сдачей)
-
-- [ ] `status` вызван первым, проект определён (slug зафиксирован).
-- [ ] Существующие секции прочитаны, дублей нет.
-- [ ] Каждая записанная секция отправлена отдельным `update_section` и прочитана обратно.
-- [ ] Секретов и PII нет: перечитанный текст не содержит значений паролей/токенов/персональных данных.
-- [ ] У ключевых утверждений есть метка достоверности и ссылка `path:line`.
-- [ ] Код и логи не скопированы в досье.
-- [ ] Минимумы по объёму соблюдены; каждая секция ≤ 40 KB.
-- [ ] Противоречия разобраны; устаревшее помечено `[устарело]`.
-- [ ] Отчёт содержит «Записано» и «Неясно».
-- [ ] В сеть ничего из проекта не уходило.
-
-## 6. Антипаттерны
-
-- Копировать целые файлы, конфиги, миграции и логи «чтобы было».
-- Сохранять `.env`, дампы, токены, персональные данные.
-- Отправлять код/конфиги в веб-поиск или внешние API «для уточнения».
-- Писать «очевидно», «скорее всего» без метки `[выведено]`.
-- Заполнять шаблон пунктами без доказательств.
-- Править файлы досье и `INDEX.json` руками.
-- Начинать анализ без `status`.
-- Оставлять старые факты без пометки и заявлять о свежести досье.
-- Складывать всё в одну гигантскую секцию вместо ссылок на файлы.
-
-## 7. Связанное
-
-- Постоянное ведение памяти — `project-memory-maintenance` (журнал, дедупликация, свежесть).
-- Процесс разработки — `dev-workflow`; планирование — `requirements-and-planning`; финальное ревью — `code-review-checklist`.
+| Разведка, трассировка, 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

@@ -1,5 +1,7 @@
 # Разведка проекта: команды и источники
 
+> Часть навыка project-deep-dive. ≈2 000 токенов. Читать, когда: нужны команды разведки по стеку, трассировка потоков, проверка git-свежести или критерий `[проверено]`.
+
 > Только чтение. Ничего не запускай на изменение (миграции, seed, деплой, install) ради досье.
 > Если `rg` нет — используй инструменты `glob`/`grep` или `Get-ChildItem -Recurse`.
 > Значения `.env` не читай: имена переменных бери из `.env.example` или из кода.
@@ -25,6 +27,16 @@ rg --files $root -g '!node_modules' -g '!vendor' -g '!dist' -g '!build' -g '!.gi
 - Манифесты: `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'

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

@@ -1,5 +1,7 @@
 # Шаблоны секций досье
 
+> Часть навыка project-deep-dive. ≈1 450 токенов. Читать, когда: заполняешь секции досье или собираешь обязательный отчёт; нужны примеры формы, минимумы и структура блоков.
+
 > Правило: ссылки `path:line` вместо кода; метка достоверности у ключевых утверждений;
 > объём секции ≤ 40 KB; содержимое — выводы, а не дампы.
 > Примеры ниже — образец формы, а не текст для копирования.