@7n/rules 1.0.0

package/scripts/utils/worktree-fingerprint.mjs

@@ -0,0 +1,33 @@
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+
+/**
+ * Fingerprint поточного стану git-робочого дерева.
+ * @param {typeof import('child_process').spawnSync} [spawn] sync-виклик git (ін'єкція для тестів)
+ * @returns {string|null} sha256-hex (64 символи) або null, якщо не в git-репо
+ */
+export function worktreeFingerprint(spawn = spawnSync) {
+  /**
+   * @param {string[]} args аргументи підкоманди git
+   * @returns {string} stdout git-команди
+   */
+  function git(args) {
+    const r = spawn('git', args, { encoding: 'utf8' })
+    if (r.status !== 0 || r.error) throw new Error(`git ${args[0]} failed`)
+    return r.stdout
+  }
+
+  try {
+    const commitHash = git(['rev-parse', 'HEAD']).trim()
+    const diffText = git(['diff', 'HEAD'])
+    // -z: NUL-розділення без C-екранування. Без нього імена з не-ASCII символами
+    // повертаються у `"..."` формі, і `git hash-object` не знаходить файл → throw → fingerprint=null.
+    const untrackedRaw = git(['ls-files', '-z', '--others', '--exclude-standard'])
+    const untrackedFiles = untrackedRaw.split('\0').filter(Boolean)
+    const pairs = untrackedFiles.map(f => `${f}:${git(['hash-object', f]).trim()}`).toSorted()
+    const raw = [commitHash, diffText, ...pairs].join('\n')
+    return createHash('sha256').update(raw).digest('hex')
+  } catch {
+    return null
+  }
+}

package/skills/adr-normalize/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: n-adr-normalize
+description: >-
+  Ручний запуск ADR-нормалізації — обхід порогу й min-interval, прогон одного
+  батчу чернеток через LLM, перегляд результату через git diff
+version: '1.0'
+---
+
+# n-adr-normalize — ручна нормалізація ADR-чернеток
+
+Скіл запускає `.claude/hooks/normalize-decisions.sh` поза звичайним Stop-hook-тригером. Корисно, коли:
+
+- Поріг `ADR_NORMALIZE_THRESHOLD` ще не досягнуто, але хочеш почистити inbox.
+- Минулого разу LLM відмовився, тепер минув ще не весь `ADR_NORMALIZE_MIN_INTERVAL_HOURS` — хочеш повторити одразу.
+- Спочатку треба побачити, що саме LLM зробить (`ADR_NORMALIZE_DRY=1`).
+
+## Передумови
+
+- Правило `adr` увімкнене у `.n-rules.json` (`"adr"` у `rules`).
+- `.claude/hooks/normalize-decisions.sh` існує (`npx @7n/rules` поклав його сюди).
+- У `PATH` доступний `claude` або `cursor-agent` (інакше скрипт мовчки вийде).
+- У `docs/adr/` є чернетки — файли з `session: …` у YAML frontmatter.
+
+## Кроки
+
+1. **Dry-run** (не міняє файли, лише пише план у `.claude/hooks/normalize-decisions.log`):
+
+   ```bash
+   ADR_NORMALIZE_THRESHOLD=0 \
+   ADR_NORMALIZE_MIN_INTERVAL_HOURS=0 \
+   ADR_NORMALIZE_DRY=1 \
+     bash .claude/hooks/normalize-decisions.sh
+   ```
+
+   Потім переглянь план: `tail -100 .claude/hooks/normalize-decisions.log`.
+
+2. **Реальний прогон одного батчу** (за замовчуванням до 30 чернеток):
+
+   ```bash
+   ADR_NORMALIZE_THRESHOLD=0 \
+   ADR_NORMALIZE_MIN_INTERVAL_HOURS=0 \
+     bash .claude/hooks/normalize-decisions.sh
+   ```
+
+3. **Перегляд результату** — скрипт нічого не комітить:
+
+   ```bash
+   git status docs/adr/
+   git diff docs/adr/
+   ```
+
+   Видалені файли — `delete`-операція. Нові файли `<timestamp>-<slug>.md` (timestamp-префікс чернетки збережено) — `rewrite`. Модифіковані clean-файли — `merge-into`.
+
+4. **Прийняти / відкотити:**
+   - Прийняти все: `git add docs/adr/ && git commit -m "adr: normalize batch"`.
+   - Відкотити конкретний файл: `git checkout -- docs/adr/<file>` (для `rewrite` цього мало — треба ще `git restore --staged` і `rm` нового).
+   - Відкотити весь батч: `git checkout -- docs/adr/ && git clean -f docs/adr/` (видалить і untracked rewrite-результати).
+
+5. **Повторити для наступного батчу**, якщо чернеток ще багато. Кожен запуск обробляє до `ADR_NORMALIZE_BATCH` файлів (default 10, найстарші за часовою позначкою у назві).
+
+## Tuning через ENV
+
+- `ADR_NORMALIZE_BATCH=30` — більший батч (менше викликів LLM, більше токенів за раз).
+- `ADR_NORMALIZE_MODEL=opus` — інша модель `claude -p`.
+- `ADR_NORMALIZE_CURSOR_MODEL=…` — інша модель для cursor-agent fallback.
+- `ADR_NORMALIZE_SKIP_TOOLING_ONLY=0` — вимкнути structural skip для tooling-only сесій (default `1`). Корисно лише якщо хочеш зберегти чернетки навіть для правок у `.cspell.json` / `CHANGELOG.md` / `version`-bump-ів.
+
+## Якщо щось пішло не так
+
+- LLM повернув криву JSON → у логу буде `invalid JSON response (first 200 chars): …`. Запусти ще раз — нерідко це разовий збій.
+- Скрипт виходить миттєво без логу → перевір `ADR_NORMALIZE_RUNNING` у env (recursion guard) і чи репо не у стані merge/rebase.
+- Перейменування зробило дублі імен (`<timestamp>-<slug>-2.md`) → це нормально, скрипт детермінований; під час review можна обʼєднати руками й видалити `-2`.
+- ADR-чернетки видаляються мовчки → це structural tooling-only skip. Перевір лог: `tail .claude/hooks/normalize-decisions.log | grep tooling-only`. Для діагностики на capture-стороні: `tail .claude/hooks/capture-decisions.log | grep tooling-only`. Аби тимчасово вимкнути — `ADR_NORMALIZE_SKIP_TOOLING_ONLY=0 bash .claude/hooks/normalize-decisions.sh`.

package/skills/adr-normalize/main.json

@@ -0,0 +1 @@
+{ "auto": ["adr"], "worktree": true }

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: brainstorming
+description: >-
+  Фасилітація структурованої генерації ідей для будь-якої теми — продуктові фічі, архітектурні рішення, бізнес-стратегія, назви, маркетинг, вирішення проблем. ОБОВ'ЯЗКОВО використовуй цей skill, коли користувач каже "давай побрейнштормимо", "накидай ідей", "хочу подумати над X", "які є варіанти для...", просить допомогти придумати щось з нуля, або коли задача явно на стадії "ще не зрозуміло що робити" (на відміну від "вже зрозуміло що робити, допоможи зробити"). Не використовуй для чистого уточнення вимог до вже визначеної фічі (це просто уточнюючі питання, без техніки генерації) і не використовуй, якщо користувач вже приніс готове рішення і просить його реалізувати.
+version: '1.0'
+---
+
+# Brainstorming
+
+Твоя роль змінюється по ходу сесії. На генерації (кроки 1-3) ти — фасилітатор: створюєш умови, в яких з'являється багато ідей (мінімум 40-60 перед тим як щось відкидати), не тиснеш власною думкою, щоб не звузити простір ідей заздалегідь. На організації та дії (кроки 4-5) ти — **реальний співавтор рішення**: формуєш власну обґрунтовану позицію, відкрито її висловлюєш і, якщо бачиш кращий варіант ніж обраний користувачем, кажеш про це прямо й аргументовано — а не мовчки погоджуєшся. Фінальне слово завжди за користувачем, але процес — це дебати двох рівноправних голосів, а не диктовка одного через мовчазне підтвердження іншого.
+
+Кількісна ціль важлива: найцінніші ідеї часто зʼявляються після 30-ї, коли очевидні варіанти вже вичерпані. Не зупиняйся на 5-10 ідеях і не переходь одразу до "оцінки" — спочатку об'єм, потім якість.
+
+## Хард-гейт
+
+**НЕ переходь до реалізації, коду, чи фінального рішення, поки сесія не пройшла: контекст → техніка → генерація → організація → дія.** Навіть якщо тема здається простою ("просто дай мені 3 варіанти назви") — швидко пройди скорочену версію процесу (можна об'єднати кроки, але не пропускати кількісну генерацію).
+
+## Процес
+
+### 1. Контекст (одне питання за раз)
+
+Перш ніж обирати техніку, зрозумій:
+
+- Яка саме тема/проблема (дай користувачу сформулювати своїми словами, не переформульовуй за нього передчасно)
+- Для чого результат — продукт, презентація, внутрішнє рішення, назва, стратегія
+- Чи є обмеження (бюджет, дедлайн, технічний стек, аудиторія)
+- Чи є вже ідеї, які треба врахувати/не повторювати
+- **Тип фінального результату** (визначає крок 6): архітектурне/технічне рішення → **ADR**; підготовка фічі до реалізації (треба структурувати обсяг роботи, а не просто обрати ідею) → **специфікація**; усе інше (назва, маркетинг, стратегія, список ідей без формального оформлення) → **ADR** теж, але як легкий запис рішення-reference (див. крок 6). Якщо з теми не очевидно — постав це окремим питанням з двома-трьома варіантами.
+
+Питай по одному, віддавай перевагу варіантам вибору (multiple choice), але відкрите питання теж ок, якщо тема творча.
+
+### 2. Вибір техніки
+
+Запропонуй користувачу обрати, або сам обери найбільш підходящу і скажи чому:
+
+- **SCAMPER** — Substitute/Combine/Adapt/Modify/Put to other use/Eliminate/Reverse. Добре для покращення існуючого продукту/фічі/процесу.
+- **Mind-mapping** — розгалуження від центральної теми. Добре, коли тема широка і невизначена.
+- **Role-storming** — генеруй ідеї "від імені" різних персонажів (скептичний CFO, ледачий користувач, конкурент, дитина). Добре для стрес-тесту та несподіваних кутів.
+- **Random stimulus** — випадкове слово/образ як тригер асоціацій. Добре, коли команда/людина застрягла на очевидному.
+- **"5 чому" / root-cause** — якщо тема насправді проблема, а не ідея, спочатку копни причину.
+- **Progressive flow** — комбінація технік по черзі (розширення → звуження → розширення), для довгих сесій.
+
+Якщо користувач не має преференцій — постав одне питання з опціями замість вибору самому наосліп.
+
+### 3. Генерація (кількість перш ніж якість)
+
+- Веди сесію технікою з кроку 2: ставиш провокаційні питання, пропонуєш неочевидні напрямки, добудовуєш ідеї користувача ("а що якщо навпаки?", "а якщо прибрати обмеження X?").
+- На відміну від чистого фасилітатора — можеш і сам пропонувати ідеї, не тільки витягувати з користувача. Але позначай явно, коли ідея твоя, а коли користувача, щоб не було плутанини хто що придумав.
+- Не оцінюй і не відкидай ідеї на цьому етапі, навіть очевидно слабкі — записуй усі, оцінка потім.
+- Веди список ідей у робочому вигляді (нумерований), онови користувача про прогрес ("маємо 25, ще трохи").
+
+### 4. Організація — почни формувати власну позицію
+
+- Згрупуй ідеї в теми/кластери.
+- Познач дублікати і схожі ідеї як варіації одної.
+- Для кожного кластера — 1-2 речення чому він цікавий/що об'єднує.
+- Попроси користувача або сам запропонуй пріоритизацію (напр. за критеріями: ефект/зусилля, ризик, відповідність цілі).
+- Поки організовуєш — оціни кластери власним професійним поглядом (ризики, реалістичність, відповідність контексту з кроку 1). Це підготовка до кроку 5, ще не саме заперечення — тут просто фіксуєш для себе, який кластер здається сильнішим і чому.
+
+### 5. Дія — сформуй рекомендацію, доведи сесію до спільного рішення
+
+- Топ-3-5 ідей отримують: короткий наступний крок і як зрозуміти що ідея "зайшла" (success signal).
+- **Перш ніж питати вибір користувача, сформулюй власну рекомендацію з обґрунтуванням**: "Моя рекомендація — <варіант>, тому що <2-3 причини з кроку 4>". Це обов'язково, не опційно — саме тут ти переходиш від фасилітатора до співавтора.
+- Запитай, який варіант обирає користувач. **Якщо він обирає інше, ніж твоя рекомендація** — не погоджуйся мовчки: скажи прямо, що бачиш ризик/суперечність/кращу альтернативу, і аргументуй. Одна ітерація заперечення — виклав контраргумент, вислухав відповідь, далі приймаєш рішення користувача незалежно від результату (без зациклення на переконуванні).
+- **Не закінчуй сесію на списку кандидатів.** Мета кроку 5 не "показати опції", а **зафіксувати рішення** (твоя рекомендація + фінальний вибір користувача, навіть якщо вони розійшлись), яке піде у крок 6.
+- Після того як рішення явно підтверджено, запитай, чи користувач хоче:
+  - зупинитись на цьому (документ кроку 6 — фінальний артефакт сесії)
+  - перейти до глибшої деталізації (тоді це вже окрема задача, не brainstorming)
+  - продовжити ще один раунд генерації (рішення ще не остаточне)
+
+### 6. Збереження сесії — ADR або специфікація, залежно від типу з кроку 1
+
+Сесія завжди закінчується формальним документом, а не просто повідомленням у чаті — який саме, визначає тип результату з кроку 1.
+
+#### 6a. Архітектурне/технічне рішення, назва, стратегія, реф-список ідей → ADR (MADR v4)
+
+Зберігай у `docs/adr/<YYYYMMDD-HHMMSS>-<slug-теми>.md` (timestamp — момент запису, slug — латинізована коротка назва теми) — той самий формат, що й у решті `docs/adr/`.
+
+```markdown
+---
+type: ADR
+title: "<тема сесії>"
+---
+
+# <тема сесії>
+
+**Status:** Accepted
+**Date:** YYYY-MM-DD
+
+## Context and Problem Statement
+
+<коротко з кроку 1: тема, для чого результат, обмеження>
+
+## Considered Options
+
+- <кластер/ідея 1 — 1 речення>
+- <кластер/ідея 2 — 1 речення>
+- <кластер/ідея 3 — 1 речення>
+
+## Decision Outcome
+
+Chosen option: "<варіант, який користувач явно підтвердив на кроці 5>", because <обґрунтування з кроку 4-5>. <Якщо рекомендація фасилітатора з кроку 5 розійшлась із вибором користувача — додай речення: "Facilitator recommended <варіант>, because <причина>; user chose <обраний варіант> instead.">.
+
+### Consequences
+
+- Good, because <очікувана користь / success signal>.
+- Bad, because <ризик, компроміс, або "сесія не виявила підтверджених негативних наслідків">.
+
+## More Information
+
+Усі ідеї сесії (сирий список, для трасування рішення):
+1. ...
+2. ...
+
+Відкладені кластери: <кластери, що не увійшли до Considered Options, коротко чому>.
+Відкриті питання: <якщо лишились>.
+```
+
+- **Status** — завжди `Accepted`: крок 5 вимагає явного підтвердження варіанта саме для того, щоб ADR фіксував ухвалене рішення, а не відкриту пропозицію. Якщо користувач так і не звузив вибір до конкретного варіанта (лишились рівноцінні кандидати) — це ознака того, що сесію рано завершувати; поверни її на крок 5, а не пиши `Proposed` як обхідний шлях.
+- **Considered Options** — це не весь сирий список (40-60 ідей), а звужені кластери/топ-кандидати з кроку 4; сирий список іде в `More Information`, щоб не загубити обсяг роботи, але не захаращувати Decision Outcome.
+- Якщо тека `docs/adr/` відсутня — створи. Після запису — запропонуй git commit (`docs(adr): brainstorm session <slug>`), але не роби commit без підтвердження користувача.
+
+#### 6b. Підготовка фічі до реалізації → фінальна специфікація
+
+Зберігай у `docs/specs/YYYY-MM-DD-<slug-теми>.md`, **українською** (код/шляхи/API-назви — англійською). Формат — як у решті `docs/specs/`: без MADR-секцій, натомість структура "проблема → ухвалені рішення → деталі реалізації", готова передаватись у розробку без додаткового уточнення.
+
+```markdown
+# <тема сесії>
+
+**Дата:** YYYY-MM-DD
+**Статус:** погоджено — готово до реалізації
+**Зв'язані документи:** <якщо є — інші specs/ADR/доки, на які спирається рішення>
+
+## 1. Проблема / Мета
+
+<коротко з кроку 1: що не так зараз, що має вийти в результаті, обмеження>
+
+## 2. Ухвалені рішення
+
+| # | Питання | Рішення |
+|---|---|---|
+| А | <питання, яке розв'язав крок 4-5> | <обраний варіант і коротке обґрунтування; якщо рекомендація фасилітатора розійшлась з вибором користувача — вкажи обидві позиції: "рекомендовано X через Y, обрано Z через W"> |
+| Б | ... | ... |
+
+## 3. Деталі реалізації
+
+<розгорни ухвалені рішення в конкретику, потрібну розробнику: файли/модулі, що зачіпаються, послідовність кроків, edge cases з генерації (крок 3), що варто врахувати>
+
+## Відкриті питання
+
+- <якщо лишились — сформулюй явно, не приховуй невизначеність>
+```
+
+- **"Ухвалені рішення"** заповнюються з явних виборів кроку 5 — якщо якесь питання лишилось відкритим, воно йде в "Відкриті питання", а не вигадується заднім числом.
+- Розділ "Деталі реалізації" — це міст до окремого dev-design/implementation-flow: специфікація фіксує **що** і **чому**, конкретний **як** (код, план кроків реалізації) — вже за межами brainstorming-сесії.
+- Якщо тека `docs/specs/` відсутня — створи. Після запису — запропонуй git commit (`docs(spec): brainstorm session <slug>`), але не роби commit без підтвердження користувача.
+
+## Принципи
+
+- **Об'єм перед фільтром.** Не давай собі (чи користувачу) зупинитись рано.
+- **Одне питання за раз** на етапі контексту — не заваль користувача списком питань.
+- **Явно розділяй чиї ідеї** — твої vs користувача — для чесності сесії.
+- **YAGNI на етапі дії** — фінальний список коротший ніж хочеться, топ-3-5, не топ-20.
+- **Сесія закінчується рішенням, не списком опцій.** Крок 5 — не опційний; без явного підтвердження варіанта користувачем крок 6 писати рано.
+- **Фасилітатор на генерації, співавтор на дії.** До кроку 4 не тисни власною думкою — це звужує простір ідей. З кроку 4 — навпаки, мовчазна згода зі слабким вибором користувача це ведмежа послуга: скажи, що думаєш, аргументуй, але не зациклюйся на одному запереченні.

package/skills/brainstorming/main.json

@@ -0,0 +1 @@
+{ "auto": "завжди", "worktree": false }

package/skills/doc-aggregate/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: doc-aggregate
+description: >-
+  Агрегуюча документація за запитом: module-summary на кожен логічний модуль (docs/ARCHITECTURE.md) і доменні доки бізнес-процесів у кореневій docs/ — синтез поверх готових файлових док (doc-files), батч-диспатч субагентів у worktree
+version: '1.0'
+---
+
+# doc-aggregate — агрегуюча документація (за запитом)
+
+## Мета
+
+Синтезувати документацію вищого рівня поверх **готових файлових док** (їх підтримує
+обовʼязковий скіл `doc-files`). Два рівні, строго послідовно:
+
+1. **Tier 2 — module-summary**: `<module_root>/docs/ARCHITECTURE.md`, субагент на модуль.
+2. **Tier 3 — доменні доки**: `docs/<домен>.md` у кореневій `docs/`, субагент-синтезатор
+   виділяє бізнес-домени й пише файл на кожен домен.
+
+Агрегат ніколи не випереджає джерело: Tier 3 — лише після завершення всього Tier 2.
+Цей скіл викликається **за запитом** (не обовʼязковий крок задачі).
+
+## ⚠️ Паралелізм
+
+Tier 2 — батчами **по 5** субагентів одночасно (кожен пише свій файл, гонок немає).
+Tier 3 — **один** субагент-синтезатор після завершення всього Tier 2.
+
+## Передумова
+
+- Доступний `npx @7n/rules`.
+- Файлові доки мають бути свіжі. Перевір і за потреби онови перед агрегацією:
+
+```bash
+npx @7n/rules lint doc-files --no-fix
+```
+
+Якщо багато застарілих — спершу прожени `npx @7n/rules lint doc-files` (fix-by-default).
+
+## Крок 1: Tier 2 — module-summary
+
+Зібрати список воркспейсів з кореневого `package.json`:
+
+```bash
+node -e "const p=JSON.parse(require('fs').readFileSync('package.json','utf8')); console.log(JSON.stringify(p.workspaces))"
+```
+
+Для кожного воркспейсу `<ws>`:
+
+- `relRoot` = `<ws>` (напр. `npm`, `demo`)
+- `docPath` = `<ws>/docs/ARCHITECTURE.md`
+- `members` — кодові файли (`.mjs .ts .vue .py`, крім тестів) у `<ws>/`
+
+module-summary **завжди регенерується**. Розбий воркспейси на батчі по 5 і диспатч субагентів.
+Промпт кожного (підстав `relRoot`, `docPath`, `members`):
+
+```
+Напиши module-summary для одного логічного модуля.
+
+МОДУЛЬ: <relRoot>
+ЗАПИСАТИ В: <docPath>
+ФАЙЛИ МОДУЛЯ (members): <members>
+
+Кроки:
+1. Прочитай файлові доки членів модуля. <member> — sourcePath відносно кореня проєкту
+   (= поточний CWD); його файлова дока — <CWD>/<dir>/docs/<stem>.md. За потреби зазирни
+   в самі файли.
+2. Створи теку для <docPath>, якщо її немає.
+3. Запиши markdown у <docPath> за тими ж правилами стилю, що й файлова дока
+   (українська, чистий Markdown, контекстна незалежність, без HTML).
+
+Секції module-summary:
+## Огляд модуля — призначення модуля <relRoot>, його роль у проєкті.
+## Ключові файли — список із кліковими посиланнями (відносними до розташування цього
+   ARCHITECTURE.md) на члени модуля та їхні файлові доки.
+## Публічний API — що модуль експортує назовні.
+## Внутрішній потік — як компоненти модуля взаємодіють.
+## Підмодулі — вкладені модулі, якщо є.
+
+Поверни лише підтвердження, що файл <docPath> записано.
+```
+
+## Крок 2: Tier 3 — доменні доки
+
+Після завершення **всіх** module-summary диспатч **одного** субагента-синтезатора.
+У промпт підстав конкретний перелік шляхів module-summary (`<module_root>/docs/ARCHITECTURE.md`
+кожного модуля з виводу `doc-aggregate modules`), а не інструкцію їх шукати. Промпт:
+
+```
+Синтезуй доменну документацію бізнес-процесів проєкту.
+
+ДЖЕРЕЛА (module-summary, читай усі): <перелік шляхів ARCHITECTURE.md, підставлений вище>
+
+Кроки:
+1. Прочитай усі module-summary.
+2. Виділи бізнес-домени та процеси (можуть перетинати межі модулів). Доменів може бути багато.
+3. Для КОЖНОГО домену запиши окремий файл docs/<домен>.md у кореневій docs/:
+   - назва файлу — короткий kebab-slug домену;
+   - не перезаписуй файлові доки кореневих файлів у docs/ (напр. app.md, eslint.config.md):
+     якщо слаґ домену збігається з іменем такого файлу — додай суфікс -domain
+     (напр. app-domain.md). Інакше пиши docs/<домен>.md як є;
+   - опиши бізнес-процес домену з кліковими відносними посиланнями на module-summary, конкретні файли й директорії.
+
+Правила стилю — ті ж (українська, чистий Markdown, контекстна незалежність, без HTML).
+
+Поверни перелік створених файлів docs/<домен>.md.
+```
+
+## Крок 3: Підсумок
+
+```
+✓ doc-aggregate завершено.
+Tier 2 (модулі): <M> module-summary.
+Tier 3 (домени): <D> доменних доків у docs/.
+```
+
+Перелічи файли з помилками (субагент впав або не записав `docPath`), якщо такі є.
+Помилка одного модуля не зупиняє решту.
+
+## Нотатки
+
+- Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
+- Файлові доки (Tier 1) — окремий обовʼязковий скіл `doc-files`; цей скіл їх не пише, лише агрегує.

package/skills/doc-aggregate/js/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/skills/doc-aggregate/js
+resource: npm/skills/doc-aggregate/js/
+---
+
+# npm/skills/doc-aggregate/js
+
+| Файл                                  | Тип       |
+| ------------------------------------- | --------- |
+| [docgen-ignore.mjs](docgen-ignore.md) | JS Module |

package/skills/doc-aggregate/main.json

@@ -0,0 +1 @@
+{ "worktree": true }

package/skills/doc-files/.changes/260612-0002.md

@@ -0,0 +1,6 @@
+---
+bump: minor
+section: Added
+---
+
+doc-files: підтримка Rust (.rs) — SOURCE_EXTENSIONS, target/-ignore, extractFactsRust, units-rs

package/skills/doc-files/.changes/260612-0006.md

@@ -0,0 +1,6 @@
+---
+bump: patch
+section: Fixed
+---
+
+мовно-нейтральний текст returnsFalsyOnFail (false/null/Err); units-rs: тести + docs

package/skills/doc-files/.changes/260612-0008.md

@@ -0,0 +1,6 @@
+---
+bump: patch
+section: Added
+---
+
+Rust .rs: тести units-rs, doc units-rs.md, мовно-нейтральний текст гарантії returnsFalsyOnFail

package/skills/doc-files/.changes/260612-0012.md

@@ -0,0 +1,6 @@
+---
+bump: patch
+section: Added
+---
+
+Rust (.rs): тести extractFactsRust у docgen-extract.test.mjs — exports, tauri::command, struct/enum, markers, header, desc

package/skills/doc-files/.changes/260612-0031.md

@@ -0,0 +1,6 @@
+---
+bump: patch
+section: Changed
+---
+
+стале-доки після Rust: оновлено CRC для docgen-prompts, docgen-scan, units-rs; додано units-js.md; тести extractFacts(.rs)

package/skills/doc-files/.changes/260612-0036.md

@@ -0,0 +1,6 @@
+---
+bump: patch
+section: Added
+---
+
+docs: units.md (docgen для units.mjs — фасад Rust/JS)

package/skills/doc-files/.changes/260612-0114.md

@@ -0,0 +1,6 @@
+---
+bump: patch
+section: Added
+---
+
+doc-files: регенерація всіх stale doc-файлів; manifests.mjs (303KB) → docgen-ignore

package/skills/doc-files/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: doc-files
+description: >-
+  Обовʼязковий крок задачі (як lint): для кожного зміненого/нового кодового файлу (js/mjs/ts/vue/py) JS-оркестрована генерація лаконічної поведінкової української md-документації у теку docs/ поряд із кодом, зі звіркою застарілості за CRC у frontmatter
+version: '1.0'
+---
+
+# doc-files — файлова документація (обовʼязковий крок)
+
+## Мета
+
+Для кожного кодового файлу проєкту тримати **актуальну** лаконічну поведінкову `.md`-документацію
+у теці `docs/` **поряд із самим файлом** (`<dir>/docs/<stem>.md`). Це **обовʼязковий крок кожної
+задачі** — як `lint`: після зміни коду його дока має бути перегенерована.
+
+Застарілість визначається **детерміновано за CRC**: кожна дока несе у frontmatter контрольну
+суму байтів джерела на момент генерації. Дока **застаріла**, якщо її немає або
+`crc(поточне джерело) ≠ crc у frontmatter`.
+
+```markdown
+---
+docgen:
+  source: src/lib/foo.js
+  crc: a3f1c9e0
+---
+
+## Огляд
+
+…
+```
+
+## Оркестрацію веде JS, не модель; конвеєр — local-only
+
+Уся важка робота — черга, батчинг, виклики LLM і штамп CRC — живе у JS-оркестрації
+`lint doc-files`. **Ти не диспатчиш субагентів і не тримаєш сотні файлів у контексті**
+— тому навіть масовий перший прогін усього репо не «заморює». Цей скіл **тонкий**: твоє завдання —
+запустити генерацію і прочитати підсумок.
+
+Конвеєр **суто локальний** (ADR `260610-2228`): будь-який файл генерується локальною
+моделлю (`omlx/…` напряму), хмарних ескалацій немає. Якщо det-оцінка нижча за поріг —
+дока все одно пишеться з **degraded-маркером** (`score`/`issues` у frontmatter, CRC свіжий),
+а перегенерація таких док — окремою командою пізніше.
+
+## Передумова
+
+- Поточна директорія — корінь проєкту (`requireRoot`), не worktree.
+- Доступний `npx @7n/rules`.
+
+## Workflow
+
+### Крок 1: Генерація застарілих/відсутніх док
+
+```bash
+npx @7n/rules lint doc-files
+```
+
+Команда запускає doc-files лінтер у fix-режимі (весь репо): перевіряє omlx
+(preflight: «сервер лежить» / «модель не влазить у пам'ять зайнятої машини» /
+«потрібен API-ключ» → одна зрозуміла зупинка замість лавини «✗») → фільтрує застарілі
+(`stale`) → генерує локальною моделлю → пише доку зі **свіжим CRC** (і degraded-маркером,
+якщо не дотягнула) → друкує прогрес і підсумок.
+
+### Крок 2: Підтвердження
+
+Дочекайся підсумку `✓ OK: <N>  ⚠ degraded: <D>  ✗ Err: <E>`. Якщо є помилки — перелічи
+проблемні файли. Exit-код `1` означає, що хоча б один файл не згенерувався (або не пройшов
+preflight). Degraded — не помилка: дока існує, CRC свіжий.
+
+## Правила стилю документа (за adr/ci4)
+
+- Мова — **УКРАЇНСЬКА** для всього тексту. Code identifiers, шляхи, імена API, команди — як у коді.
+- **Чистий Markdown.** Жодних HTML-обгорток. Єдиний виняток — машинний `docgen:`-frontmatter із CRC.
+- **Фокус на ПОВЕДІНЦІ, не реалізації.** ЩО і НАВІЩО, а не як саме зроблено.
+- Не перелічуй модулі стандартної бібліотеки і внутрішні назви допоміжних функцій.
+- Кожна секція самодостатня (без «як вище», «ця функція»).
+- Секції (лише доречні): `## Огляд`, `## Поведінка`, `## Публічний API`, `## Де використовується`,
+  `## Гарантії поведінки`; для `.vue` — `## Інтерфейс компонента`.
+- Не вигадуй деталей, яких немає в коді.
+
+## Нотатки
+
+- Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
+- Scanner ігнорує `node_modules`, `dist`, `.git`, `__pycache__`, `coverage`, `.cursor`, `.claude`,
+  усі теки `docs/`, а також `*.test.*` / `*.spec.*` / `*.d.ts`. Кореневий repo `docs/` —
+  system-wide only: file-level docs туди не пишуться. Список glob-ів — `docgen-ignore.mjs`.
+- Агрегуюча документація (module-summary, доменні доки) — окремий скіл `doc-aggregate`, за запитом.

package/skills/doc-files/main.json

@@ -0,0 +1 @@
+{ "auto": "завжди", "worktree": false, "requireRoot": true }