dsh-desktop-kit 1.0.0 → 2.0.0

package/skills/project-deep-dive/references/tool-and-process.md

@@ -0,0 +1,86 @@
+# API project_memory и детали анализа
+
+> Часть навыка project-deep-dive. ≈2 950 токенов. Читать, когда: нужны полная таблица действий и аргументов, детали шагов анализа, форма отчёта или антипаттерны.
+
+## 1. Хранилище и API
+
+Хранилище: `%USERPROFILE%\.dsh\projects-memory\<slug>\` — `PROJECT.md`, `ARCHITECTURE.md`, `CODE-MAP.md`, `INVARIANTS.md`, `GOTCHAS.md`, `RUNBOOK.md`, `JOURNAL/YYYY-MM.md`, `INDEX.json`.
+
+Сигнатура: `project_memory(action, project?, file?, content?, query?, root?, name?, mode?, maxChars?)`. В текущей сборке у `register` есть необязательный `stack` — короткое описание стека.
+
+| 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 секции по каркасам из `section-templates.md`.
+- `append_journal` сам выбирает `JOURNAL/YYYY-MM.md` по текущему месяцу.
+- `update_section` — единственный способ писать секции; `INDEX.json` руками не правь — иначе рассинхронизируются индекс и свежесть.
+
+## 2. Детали восьми шагов
+
+1. **Статус и проект.** `status` до чтения файлов. Проект найден — запомни slug. Нет проекта — `register`. Несколько кандидатов или непонятно, о каком проекте речь, — **спроси пользователя**, не угадывай. Досье устарело — предупреди сразу; устаревшие факты в новых секциях помечай `[устарело]`.
+2. **Что уже известно.** Прочитай существующие секции (`read`, `maxChars` 6000–8000), чтобы не дублировать и не противоречить. Новый факт спорит со старым — перепроверь по коду: победивший запиши, проигравший пометь `[устарело]`.
+3. **Разведка (только чтение).** Источники по порядку: `AGENTS.md` → `README*` → манифесты → структура каталогов → git. Манифесты и конфиги: `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`. Рецепты — `recon-commands.md`. Не запускай миграции, seed, деплой, install и другие изменяющие команды.
+4. **Трассировка потоков.** Веди цепочку «точка входа → маршрут → обработчик → домен → данные → тесты». Фиксируй не всё подряд, а то, что объясняет: как запустить, где бизнес-логика, где данные, что легко сломать. Команды — `recon-commands.md`.
+5. **Сборка секций.** Порядок: `PROJECT` → `ARCHITECTURE` → `CODE-MAP` → `INVARIANTS` → `GOTCHAS` → `RUNBOOK`. Каждая секция — отдельный `update_section`; после записи прочитай её обратно (`read`). Минимумы: `PROJECT` 8–15 строк, `ARCHITECTURE` 15+, `CODE-MAP` 10+ записей, `INVARIANTS` 5+, `GOTCHAS` 3+, `RUNBOOK` 5+ команд. Малый проект — минимумы пропорционально ниже, блоки те же.
+6. **Метки достоверности.** `[проверено]` — прочитано в файле или подтверждено выводом команды, рядом `path:line`. `[выведено]` — логический вывод (соглашение фреймворка, косвенная связь), прямого источника нет. `[устарело]` — было верно в прошлой версии/ветке, требует перепроверки. Ссылка — `относительный/путь:строка`; копировать код, логи и дампы нельзя.
+7. **Журнал.** Значимую сессию зафиксируй `append_journal` (сжато, по шаблону навыка `project-memory-maintenance`): что анализировали, что выяснили, какие решения, что осталось.
+8. **Отчёт.** Не пропускай «Неясно»: перечисли каждую записанную секцию, каждый проверенный факт со ссылкой и каждый неясный пункт.
+
+## 3. Каркасы секций (сжато)
+
+- `PROJECT`: что делает; стек и версии; репозиторий и прод; как поднять; статус и владелец.
+- `ARCHITECTURE`: слои и модули; поток данных текстом; очереди/крон; внешние сервисы; ключевые решения.
+- `CODE-MAP`: таблица «область | путь | зачем»; точки входа; модели/схема; тесты; конфиги.
+- `INVARIANTS`: нумерованные «нельзя», каждое с причиной и способом проверки.
+- `GOTCHAS`: симптом → причина → обход; отдельная ловушка — отдельный пункт.
+- `RUNBOOK`: окружение; установка; запуск; тесты; сборка; деплой; откат; бэкап; где логи.
+
+Полные шаблоны с примерами — `section-templates.md`.
+
+## 4. Форма отчёта
+
+```markdown
+## Записано в досье
+- PROJECT — ...
+- ARCHITECTURE — ...
+
+## Проверено
+- [проверено] ... (path:line)
+
+## Неясно / требует проверки
+1. ...
+2. ...
+
+## Дальше
+- ...
+```
+
+## 5. Антипаттерны
+
+- Копировать целые файлы, конфиги, миграции и логи «чтобы было».
+- Сохранять `.env`, дампы, токены, персональные данные.
+- Отправлять код/конфиги в веб-поиск или внешние API «для уточнения».
+- Писать «очевидно», «скорее всего» без метки `[выведено]`.
+- Заполнять шаблон пунктами без доказательств.
+- Править файлы досье и `INDEX.json` руками.
+- Начинать анализ без `status`.
+- Оставлять старые факты без пометки и заявлять о свежести досье.
+- Складывать всё в одну гигантскую секцию вместо ссылок на файлы.
+
+## 6. Связанное
+
+- Постоянное ведение памяти — `project-memory-maintenance` (журнал, дедупликация, свежесть).
+- Процесс разработки — `dev-workflow`; планирование — `requirements-and-planning`; финальное ревью — `code-review-checklist`.

package/skills/project-memory-maintenance/SKILL.md

@@ -1,170 +1,55 @@
 ---
 name: project-memory-maintenance
-description: "Правила ведения локальной памяти проектов через project_memory: журнал после каждой значимой сессии, обновление секций досье, дедупликация поиском, лимиты размера, свежесть INDEX.json."
-whenToUse: "После любой значимой сессии в проекте (до финального ответа), при изменении архитектуры, инвариантов или команд, при найденной ловушке, при устаревании досье и по просьбе «запомни это»."
+description: "Ведение памяти проектов через project_memory: журнал сессий, секции досье, дедупликация, лимиты, свежесть INDEX.json."
+whenToUse: "После значимой сессии (до ответа), при изменении архитектуры/инвариантов/команд, найденной ловушке, устаревании досье, просьбе «запомни это»."
 user-invocable: true
 ---
 
-# PROJECT-MEMORY-MAINTENANCE — ведение памяти проекта
-
-> Память полезна, только если она актуальна, не дублируется и не превращается в свалку.
-> Хранилище локальное: `%USERPROFILE%\.dsh\projects-memory\<slug>\`.
-> Содержимое проекта не отправляется в сеть никогда.
+# Project-memory-maintenance
 
 ## 0. Контракт
+1. Журнал — после значимой сессии, до ответа.
+2. В секции — долговечное; ход работы — в журнал.
+3. Перед записью `search`; дубликат — в существующий.
+4. Секреты, PII, код, дампы — не в досье, журнале, `INDEX.json`.
+5. Только `project_memory`; файлы не правь.
 
-1. Журнал пишется **после каждой значимой сессии**, до финального ответа пользователю.
-2. В секции досье попадают только долговечные факты; ход работы — в журнал.
-3. Перед записью — `search`: дубликат дописывай в существующий пункт, а не создавай новый.
-4. В досье, журнале и `INDEX.json` нет секретов, PII, копий кода и дампов.
-5. Пиши только через `project_memory`; файлы хранилища руками не редактируй.
-
-## 1. API (кратко)
-
-Сигнатура: `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` | в начале и в конце сессии | — |
-| `list` | если нужно найти проект | — |
-| `read` | перед правкой секции | `project`, `file`, `maxChars` |
-| `search` | перед любой записью (дедуп) | `project`, `query`, `maxChars` |
-| `append_journal` | после сессии | `project`, `content` |
-| `update_section` | долговечный факт | `project`, `file`, `content`, `mode` |
-| `register` | новый проект | `name`, `root` (+ `stack`) |
-
-- `file` — `PROJECT`, `ARCHITECTURE`, `CODE-MAP`, `INVARIANTS`, `GOTCHAS`, `RUNBOOK`, `JOURNAL`.
-- `mode` — `replace` (по умолчанию) или `append`.
-- `project` по умолчанию — проект текущей сессии; при работе с чужим проектом указывай slug явно.
-- `maxChars` ограничивает вывод `read` (500–30000, по умолчанию 12000); не выкачивай досье целиком без нужды.
-
-## 2. Что считать значимой сессией
+## 1. Что значимо и API
+- Значимо: код/схема, решение, исправленный баг с проверкой, инвариант/ловушка, деплой, deep-dive; тривиальное — нет (сомневаешься — короткая запись).
+- API: `project_memory(...)`; `file` — секция, `mode` — replace/append, `maxChars` 500–30000.
 
-Да:
-- изменение кода/конфига/схемы данных;
-- архитектурное или продуктовое решение;
-- найденная и исправленная ошибка, подтверждённая проверкой;
-- новый инвариант или ловушка, которые должны пережить сессию;
-- деплой, откат, смена окружения или команд запуска;
-- глубокий анализ проекта (`project-deep-dive`).
+## 2. Конец сессии
+1. `status` — проект/свежесть.
+2. `search` 1–3 темы с синонимами (`maxChars=4000`).
+3. `append_journal` в `JOURNAL/YYYY-MM.md`; связанные шаги — одна запись.
+4. `update_section` — только долговечное, одна секция — один вызов.
+5. `read` 1–2 секции, гейт, отчёт.
 
-Нет:
-- тривиальный вопрос, чтение файла без выводов;
-- повторное обсуждение уже записанного;
-- неудачная попытка без нового знания.
+## 3. Журнал
+`## YYYY-MM-DD — <сессия>` + 5 пунктов: делали, выявили, решения, проверки, осталось; все обязательны (пусто — «нет»), 1–3 строки. Без кода/логов/дампов/чата; «выявили» — факты, «проверки» — запуски и результат, «осталось» — шаги/риски. Секреты: «ошибка с DB_PASSWORD (значение не сохранено)».
 
-Сомневаешься — пиши короткую запись в журнал: лишняя строка дешевле потерянного знания.
+## 4. Секции
+`PROJECT` — стек/пути/прод/статус (не история); `ARCHITECTURE` — компоненты/потоки (не алгоритмы); `CODE-MAP` — модули/маршруты (не код); `INVARIANTS` — жёсткие правила (не советы); `GOTCHAS` — ловушки с симптомом (не банальности); `RUNBOOK` — команды/деплой (не архитектура); `JOURNAL` — сессии (не дампы/секреты).
 
-## 3. Журнал: когда и как
+`append` — добавить, `replace` — перестроить (сначала `read`). Один факт — одно место; в двух секциях — `path:line`.
 
-Пиши `append_journal` в конце каждой значимой сессии (файл `JOURNAL/YYYY-MM.md` текущего месяца).
-Несколько связанных шагов в одной сессии — одна запись, а не десять.
+## 5. Дедупликация и лимиты
+1–3 термина (модуль, команда, ошибка, синонимы); `search` каждый; найдено — `read` + дополни, нет — добавь; после — `read`: дубля, секрета, мёртвой ссылки нет.
+Секция ≤ 40 KB; пункт 1–3 строки; детали — `docs`/README, в секции `path:line`. Раздуто — вынеси, оставь ссылки; журнал по месяцам, повторяющиеся выводы — в секции.
 
-Точный шаблон записи:
-```markdown
-## YYYY-MM-DD — <краткое название сессии>
-- Что делали: ...
-- Что выявили: ...
-- Решения: ...
-- Проверки: ...
-- Осталось: ...
-```
+## 6. Свежесть и INDEX.json
+`INDEX.json` — машинный, руками нельзя. `lastAnalyzedAt` — только полный анализ; `git.branch`/`head` — на чём; `confidence` — высокая/средняя/низкая по `[проверено]`/смеси/`[устарело]`.
+`status` в начале; branch/HEAD разошлись — устарело: перечитай, обнови, старое помечай. Полный анализ — коммит в отчёт; частичная правка не выглядит полной. `confidence` — по тегам. Расхождение `status` — в отчёт, файл не правь.
 
-Правила:
-- Вызов: `project_memory(action="append_journal", project="<slug>", content="<запись>")`.
-- Все пять пунктов обязательны; если пункт пуст — пиши «нет», не удаляй его.
-- 1–3 строки на пункт; без копий кода, логов, дампов и пересказа чата.
-- «Что выявили» — факты, меняющие понимание проекта (причина, зависимость, ловушка).
-- «Проверки» — что реально запускалось и результат: тесты, линтер, сборка, ручной сценарий, тест на копии.
-- «Осталось» — конкретные следующие шаги или риски; «нет» допустимо.
-- Секреты и PII вырезай: «ошибка с `DB_PASSWORD` (значение не сохранено)».
-- Подробный шаблон и примеры — `references/journal-template.md`.
-
-## 4. Правила обновления секций
-
-| Секция | Обновляй, когда | Не пиши сюда |
+## 7. Куда грузить дальше
+| Нужно | Файл | ≈токенов |
 |---|---|---|
-| `PROJECT` | сменились стек, пути, прод, владелец, статус | историю сессий (это журнал) |
-| `ARCHITECTURE` | новые/удалённые компоненты, границы, потоки, внешние сервисы | детали реализации алгоритмов |
-| `CODE-MAP` | новый модуль, маршрут, точка входа; сдвинулись якоря | код целиком |
-| `INVARIANTS` | новое жёсткое правило, подтверждённое тестом или пользователем | советы и вкусовые предпочтения |
-| `GOTCHAS` | каждая неочевидная ловушка с симптомом | банальности «проверяй null» |
-| `RUNBOOK` | изменились команды, окружение, деплой, откат | объяснение архитектуры |
-| `JOURNAL` | каждая значимая сессия | дампы, секреты, чат |
-
-- `mode="append"` — добавляешь пункт; `mode="replace"` — перестраиваешь или чистишь секцию (сначала `read`).
-- Долговечный факт = верен через месяц и вне контекста сегодняшней задачи.
-- Один факт — одно место. Нужен в двух секциях — дай ссылку `path:line`, а не копию.
-- Подробные правила по каждой секции — `references/section-rules.md`.
-
-## 5. Дедупликация: поиск до записи
-
-1. Сформулируй 1–3 термина по теме (имя модуля, команда, текст ошибки, синонимы: «очереди/jobs/queue»).
-2. По каждому: `project_memory(action="search", project="<slug>", query="<термин>", maxChars=4000)`.
-3. Нашёл — `read` секцию и дополни существующий пункт; не создавай второй.
-4. Не нашёл — добавь новый пункт.
-5. После записи — `read` секцию: дубля нет, секрета нет, ссылка существует.
-
-Запрещено: дублировать один факт в журнале и нескольких секциях; писать почти одинаковые пункты разными словами.
-
-## 6. Лимиты размера
-
-- Каждая секция ≤ 40 KB. Приближаешься к лимиту — сокращай до выводов и ссылок.
-- 1 пункт — 1–3 строки; без воды, повторов и пересказа кода.
-- Подробности, таблицы и длинные списки — в reference-файлы проекта (`docs/`, `references/`, README); в секции — ссылка `path:line`.
-- `JOURNAL/` уже разделён по месяцам: не раздувай месяц, повторяющиеся выводы своди в секции.
-- Раздутая секция — признак того, что в досье тащат детали реализации; перенеси их в проект и оставь ссылки.
-
-## 7. Свежесть и INDEX.json
-
-`INDEX.json` — машинный файл хранилища; вручную не редактируется. Значимые поля:
-- `lastAnalyzedAt` — когда досье проанализировано целиком (а не косметически поправлено);
-- `git.branch`, `git.head` — ветка и коммит, на которых сделан анализ;
-- `confidence` — сводная уверенность: высокая при ключевых `[проверено]`, средняя при смеси, низкая при заметном `[устарело]`.
-
-Правила:
-- В начале сессии `status`; сравни `git.head`/ветку с текущими:
-  `git -C <root> rev-parse --abbrev-ref HEAD` и `git -C <root> rev-parse --short HEAD`.
-- Расходятся — досье устарело: перечитай затронутые секции, обнови факты, старые пометь `[устарело]`.
-- Полный анализ (`project-deep-dive`) — в отчёте укажи, на каком коммите он сделан; частичная правка не должна выглядеть как полный анализ.
-- `confidence` повышай только новыми `[проверено]`; понижай при `[устарело]` и большом объёме `[выведено]`.
-- Если после записи `status` показывает неактуальные поля — это расхождение инструмента: зафиксируй в отчёте и сообщи, но `INDEX.json` руками не правь.
-
-## 8. Порядок конца сессии (5 шагов)
-
-1. `status` — проект и свежесть.
-2. `search` по темам сессии (1–3 запроса).
-3. `append_journal` — запись по шаблону §3.
-4. `update_section` — только долговечные факты, одна секция — один вызов.
-5. `read` 1–2 изменённые секции и проверка по чек-листу §9; в отчёт — что записано.
-
-## 9. Финальный чек-лист
-
-- [ ] `status` вызван, проект определён.
-- [ ] `search` был до записи, дублей нет.
-- [ ] Журнал записан по шаблону, все пять пунктов на месте.
-- [ ] Секции обновлены только долговечными фактами.
-- [ ] Секретов, PII и копий кода нет.
-- [ ] У ключевых утверждений метка `[проверено]`/`[выведено]`/`[устарело]` и ссылка `path:line`.
-- [ ] Секции ≤ 40 KB; детали вынесены в references.
-- [ ] Свежесть в порядке: `git.head` соответствует анализу, устаревшее помечено.
-- [ ] Пользователю перечислено, что записано.
-
-## 10. Антипаттерны
-
-- Писать в досье после каждого шага: журнал — да, секции — нет.
-- Дублировать один факт в нескольких секциях и журнале.
-- Копировать код, логи, дампы, переписку.
-- Секреты и PII в журнале («пароль ...», «токен ...»).
-- Править файлы досье и `INDEX.json` руками.
-- Превращать `PROJECT.md` в дневник.
-- Заявлять полный анализ после косметической правки.
-- Раздувать секцию до огромного размера вместо ссылок.
-- Записывать одноразовые детали, которые не переживут сессию.
-
-## 11. Связанное
-
-- Первичный анализ проекта — `project-deep-dive`.
-- Процесс разработки — `dev-workflow`; финальное ревью — `code-review-checklist`.
+| API, чек-лист, антипаттерны | `references/api-and-checklist.md` | ≈2 600 |
+| Журнал: шаблон | `references/journal-template.md` | ≈1 100 |
+| Правила секций | `references/section-rules.md` | ≈1 750 |
+
+## 8. Гейт перед сдачей
+- [ ] `status`; проект; `search` до записи, дублей нет.
+- [ ] JOURNAL дописан (5 пунктов); досье обновлено; `git.head` сверен; старое помечено.
+- [ ] Нет секретов/PII/кода; теги/`path:line`; ≤ 40 KB.
+- [ ] В отчёт — что записано.

package/skills/project-memory-maintenance/references/api-and-checklist.md

@@ -0,0 +1,99 @@
+# API, критерии, лимиты и чек-лист памяти
+
+> Часть навыка project-memory-maintenance. ≈2 600 токенов. Читать, когда: нужны полная таблица `project_memory`, критерии значимой сессии, лимиты, свежесть `INDEX.json`, финальный чек-лист или антипаттерны.
+
+## 1. API
+
+Сигнатура: `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` | в начале и в конце сессии | — |
+| `list` | если нужно найти проект | — |
+| `read` | перед правкой секции | `project`, `file`, `maxChars` |
+| `search` | перед любой записью (дедуп) | `project`, `query`, `maxChars` |
+| `append_journal` | после сессии | `project`, `content` |
+| `update_section` | долговечный факт | `project`, `file`, `content`, `mode` |
+| `register` | новый проект | `name`, `root` (+ `stack`) |
+
+- `file` — `PROJECT`, `ARCHITECTURE`, `CODE-MAP`, `INVARIANTS`, `GOTCHAS`, `RUNBOOK`, `JOURNAL`.
+- `mode` — `replace` (по умолчанию) или `append`.
+- `project` по умолчанию — проект текущей сессии; при работе с чужим проектом указывай slug явно.
+- `maxChars` ограничивает вывод `read` (500–30000, по умолчанию 12000); не выкачивай досье целиком без нужды.
+- `root` — абсолютный путь, `name` — slug в kebab-case, `stack` — короткое описание стека.
+- `append_journal` пишет в `JOURNAL/YYYY-MM.md` текущего месяца; `update_section` — единственный способ писать секции.
+
+## 2. Что считать значимой сессией
+
+Да:
+- изменение кода/конфига/схемы данных;
+- архитектурное или продуктовое решение;
+- найденная и исправленная ошибка, подтверждённая проверкой;
+- новый инвариант или ловушка, которые должны пережить сессию;
+- деплой, откат, смена окружения или команд запуска;
+- глубокий анализ проекта (`project-deep-dive`).
+
+Нет:
+- тривиальный вопрос, чтение файла без выводов;
+- повторное обсуждение уже записанного;
+- неудачная попытка без нового знания.
+
+Сомневаешься — пиши короткую запись в журнал: лишняя строка дешевле потерянного знания.
+
+## 3. Дедупликация, лимиты, свежесть
+
+Дедупликация:
+1. Сформулируй 1–3 термина по теме (имя модуля, команда, текст ошибки, синонимы: «очереди/jobs/queue»).
+2. По каждому: `project_memory(action="search", project="<slug>", query="<термин>", maxChars=4000)`.
+3. Нашёл — `read` секцию и дополни существующий пункт; не создавай второй.
+4. Не нашёл — добавь новый пункт.
+5. После записи — `read` секцию: дубля нет, секрета нет, ссылка существует.
+
+Лимиты:
+- Каждая секция ≤ 40 KB. Приближаешься к лимиту — сокращай до выводов и ссылок.
+- 1 пункт — 1–3 строки; без воды, повторов и пересказа кода.
+- Подробности, таблицы и длинные списки — в reference-файлы проекта (`docs/`, `references/`, README); в секции — ссылка `path:line`.
+- `JOURNAL/` уже разделён по месяцам: не раздувай месяц, повторяющиеся выводы своди в секции.
+- Раздутая секция — признак того, что в досье тащат детали реализации; перенеси их в проект и оставь ссылки.
+
+Свежесть и `INDEX.json`:
+- `INDEX.json` — машинный файл хранилища; вручную не редактируется.
+- `lastAnalyzedAt` — когда досье проанализировано целиком (а не косметически поправлено).
+- `git.branch`, `git.head` — ветка и коммит, на которых сделан анализ.
+- `confidence` — сводная уверенность: высокая при ключевых `[проверено]`, средняя при смеси, низкая при заметном `[устарело]`.
+- В начале сессии `status`; сравни `git.head`/ветку с текущими: `git -C <root> rev-parse --abbrev-ref HEAD` и `git -C <root> rev-parse --short HEAD`.
+- Расходятся — досье устарело: перечитай затронутые секции, обнови факты, старые пометь `[устарело]`.
+- Полный анализ (`project-deep-dive`) — в отчёте укажи, на каком коммите он сделан; частичная правка не должна выглядеть как полный анализ.
+- `confidence` повышай только новыми `[проверено]`; понижай при `[устарело]` и большом объёме `[выведено]`.
+- Если после записи `status` показывает неактуальные поля — это расхождение инструмента: зафиксируй в отчёте, но `INDEX.json` руками не правь.
+
+## 4. Финальный чек-лист
+
+- [ ] `status` вызван, проект определён.
+- [ ] `search` был до записи, дублей нет.
+- [ ] Журнал записан по шаблону, все пять пунктов на месте.
+- [ ] Секции обновлены только долговечными фактами.
+- [ ] Секретов, PII и копий кода нет.
+- [ ] У ключевых утверждений метка `[проверено]`/`[выведено]`/`[устарело]` и ссылка `path:line`.
+- [ ] Секции ≤ 40 KB; детали вынесены в references.
+- [ ] Свежесть в порядке: `git.head` соответствует анализу, устаревшее помечено.
+- [ ] Пользователю перечислено, что записано.
+
+## 5. Антипаттерны
+
+- Писать в досье после каждого шага: журнал — да, секции — нет.
+- Дублировать один факт в нескольких секциях и журнале.
+- Копировать код, логи, дампы, переписку.
+- Секреты и PII в журнале («пароль ...», «токен ...»).
+- Править файлы досье и `INDEX.json` руками.
+- Превращать `PROJECT.md` в дневник.
+- Заявлять полный анализ после косметической правки.
+- Раздувать секцию до огромного размера вместо ссылок.
+- Записывать одноразовые детали, которые не переживут сессию.
+
+## 6. Связанное
+
+- Первичный анализ проекта — `project-deep-dive`.
+- Процесс разработки — `dev-workflow`; финальное ревью — `code-review-checklist`.

package/skills/project-memory-maintenance/references/journal-template.md

@@ -1,5 +1,7 @@
 # Шаблон журнала проекта
 
+> Часть навыка project-memory-maintenance. ≈1 100 токенов. Читать, когда: нужен точный шаблон записи, требования к пяти пунктам, пример или антипримеры.
+
 Журнал — хронология значимых сессий. Файл: `JOURNAL/YYYY-MM.md` (месяц определяется датой записи).
 Пишется действием `append_journal`, не вручную.
 

package/skills/project-memory-maintenance/references/section-rules.md

@@ -1,5 +1,7 @@
 # Правила обновления секций досье
 
+> Часть навыка project-memory-maintenance. ≈1 750 токенов. Читать, когда: обновляешь конкретную секцию досье и нужны границы «что писать / что не писать», структура и правила устаревания.
+
 Общие принципы для всех секций:
 - Только долговечные факты: верны через месяц и вне сегодняшнего контекста.
 - Ссылка `path:line` вместо копии кода; одно утверждение — один источник.

package/skills/release-and-deploy/SKILL.md

@@ -1,39 +1,53 @@
 ---
 name: release-and-deploy
-description: "Универсальный выпуск и выкатка — версионирование, сборка артефакта, checksums, безопасный деплой, smoke-проверки, откат."
-whenToUse: "При подготовке релиза/обновления любого проекта и при выкатке на сервер."
+description: "Выпуск и выкатка: SemVer, immutable-артефакт, SHA-256 checksums, бэкап, деплой штатным скриптом, smoke и откат."
+whenToUse: "Перед подготовкой релиза, сборкой артефакта, выкаткой на сервер, обновлением с миграциями и когда нужен план отката."
 user-invocable: true
 ---
 
 # Релиз и выкатка (универсально)
 
-## Принципы
-- Артефакт собирается **один раз** и выкатывается неизменным (immutable release).
-- Версия — по SemVer/правилам проекта: feature → minor, fix → patch, breaking → major; фиксируется в артефакте и на сервере.
-- Перед выкаткой — бэкап БД/файлов и известный план отката.
-- Выкатка — контролируемая: maintenance-режим на время миграций, smoke после.
-
-## Сборка
-1. Все проверки зелёные: линтер, статанализ, тесты (unit/feature), E2E/UI для интерфейса.
-2. Не включать в артефакт: `.env`, `vendor/`, `node_modules/`, сборки, `storage/`, `.git`.
-3. **Checksums** (SHA-256) артефакта; записать в `checksums.txt`.
-4. Зафиксировать состав изменений (CHANGELOG/RELEASE-NOTES): что изменилось, миграции, риски.
-
-## Выкатка
-1. Проверить целостность артефакта (`sha256sum`).
-2. Бэкап БД + файлов + текущего кода (для отката).
-3. Применить артефакт по штатной процедуре проекта.
-4. Зависимости/сборка — только как в штатном скрипте (не руками вразнобой).
-5. Миграции — аддитивные; при риске maintenance-режим.
-6. Перезапустить процессы (очереди, php-fpm, воркеры), сбросить/собрать кэши.
-7. Smoke: ключевые URL, вход, основная функция, логи без ошибок.
-
-## Откат
-- Код: предыдущий артефакт/папка/тег.
-- БД: восстановление из бэкапа — только если релиз менял данные/схему.
-- Снять maintenance, повторить smoke, сообщить пользователям.
-
-## После релиза
-- Наблюдать логи/метрики 15–30 минут; проверить фоновые задачи.
-- Записать факт выкатки и результат проверок в память проекта/CHANGELOG.
-- Старые артефакты хранить до подтверждения стабильности (потом чистить).
+## 0. Когда применять
+- Готовишь релиз: версия, артефакт, checksums, тег, release notes.
+- Просят «задеплой», обновить стенд или прод.
+- В обновлении есть миграции/данные — сначала `pg-upgrade-verify`.
+- После выкатки нужны smoke и решение «оставить или откатить».
+
+## 1. Главное
+
+**Версия и артефакт**
+- SemVer/правила проекта: feature → minor, fix → patch, breaking → major. Версия — в артефакте, на сервере и в CHANGELOG.
+- Артефакт собирается **один раз** и выкатывается неизменным; пересборка = новая версия и sha256.
+- Без `.env*`, `vendor/`, `node_modules/`, сборок, `storage/`, `.git`, дампов и PII (если проект не требует иного).
+- Проверить состав и отсутствие секретов; SHA-256 — в `checksums.txt` (`sha256sum` / `Get-FileHash -Algorithm SHA256`).
+- CHANGELOG/RELEASE-NOTES: изменения, миграции, риски, план отката.
+
+**Перед выкаткой**
+- Зелёные: линтер, статанализ, unit/feature, E2E/UI; baseline не хуже.
+- Бэкап БД, файлов и текущего кода; копия читается (`pg_restore -l`, пробное восстановление) и хранится вне сервера.
+- Свободное место, maintenance-окно и выполнимый план отката.
+- Миграции проверены на копии (`pg-upgrade-verify`) и аддитивны; при риске — maintenance.
+
+**Выкатка**
+- Сверить checksums: `sha256sum -c checksums.txt`.
+- Применять штатным скриптом; зависимости, сборку и кэши не делать вразнобой.
+- Перезапустить очереди/воркеры/php-fpm, сбросить и собрать кэши, проверить права на `storage`.
+- Smoke: версия/health, `/login` и вход, ключевой сценарий записи, старые данные, админ и пользователь, логи без ошибок, очередь жива.
+
+**Откат**
+- Код: предыдущий артефакт/папка/тег. БД: только если менялись данные/схема — из проверенного дампа и с подтверждением.
+- Снять maintenance, повторить smoke, сообщить пользователям, зафиксировать причину.
+
+**После**
+- Наблюдать логи, метрики и фоновые задачи 15–30 минут; старые артефакты хранить до стабильности.
+- Записать версию, sha256, smoke и откат в память/CHANGELOG.
+
+## 2. Куда грузить дальше
+`git-and-ci` — ветки/теги/CI; `pg-upgrade-verify` — проверка на копии живой БД; `database-safety` / `service-desk-db-safety` — бэкап; `service-desk-release` — проектный tgz + `deploy/update.sh`.
+
+## 3. Гейт перед сдачей
+- [ ] Версия, CHANGELOG и sha256 сверены с артефактом.
+- [ ] Бэкап читается и лежит вне сервера; откат выполним.
+- [ ] Миграции прогнаны на копии; выкатка — штатным скриптом.
+- [ ] Smoke: версия, вход, ключевой сценарий, старые данные, админ + пользователь, логи/очередь.
+- [ ] Факт выкатки записан.