@nitra/cursor 3.21.1 → 3.23.0

package/scripts/lib/docs/mirror-parity.md

@@ -0,0 +1,167 @@
+## Огляд
+
+Модуль `mirror-parity.mjs` забезпечує перевірку парності (parity) між «дзеркальними» файлами правил Cursor у `.cursor/rules/n-<id>.mdc` та їх канонічними джерелами у `npm/rules/<id>/<id>.mdc`. Ідея така: репозиторій містить два представлення одного й того ж правила:
+
+- канонічне джерело правила лежить у `npm/rules/<id>/<id>.mdc` (з можливими посиланнями на шаблони у тій самій теці);
+- дзеркало лежить у `.cursor/rules/n-<id>.mdc` і повинно бути результатом застосування трансформу `inlineTemplateLinks` до канону (тобто посилання на шаблони мають бути вставлені «інлайном»).
+
+Коли канонічний `.mdc` змінюють і забувають регенерувати дзеркало, виникає «дрейф» (drift). Цей модуль:
+
+- перелічує керовані дзеркала (ті, для яких знайдено канон);
+- обчислює очікуваний вміст дзеркала через ту саму трансформацію, що і синхронізатор;
+- виявляє ідентифікатори дрейфних правил (де `actual ≠ expected`).
+
+Модуль використовується одночасно і як гард у тестах (очікувано `drift === []`), і для разової регенерації дзеркал. Контекст беклогу — адаптація flow #10.
+
+## Експорти / API
+
+Модуль експортує три іменовані функції:
+
+- `listManagedMirrors(repoRoot)` — синхронна; повертає опис керованих дзеркал.
+- `expectedMirrorContent(canonicalPath)` — асинхронна (повертає `Promise<string>`); обчислює очікуваний вміст дзеркала.
+- `findMirrorDrift(repoRoot)` — асинхронна; повертає масив id правил із дрейфом, відсортований за зростанням.
+
+Жодних дефолтних експортів, побічних ефектів на рівні модуля немає (лише імпорти стандартних модулів і одного локального).
+
+## Функції
+
+### `listManagedMirrors(repoRoot)`
+
+Сигнатура: `function listManagedMirrors(repoRoot: string): { id: string, mirrorPath: string, canonicalPath: string }[]`
+
+Параметри:
+
+- `repoRoot` — абсолютний шлях до кореня репозиторію (директорія, у якій лежать `.cursor/` та `npm/`).
+
+Повертає масив об'єктів-описів дзеркал, де:
+
+- `id` — ідентифікатор правила без префіксу `n-` і без розширення `.mdc` (наприклад, для файлу `n-bun.mdc` → `bun`);
+- `mirrorPath` — абсолютний шлях до файлу дзеркала всередині `.cursor/rules/`;
+- `canonicalPath` — абсолютний шлях до канонічного `.mdc` всередині `npm/rules/<id>/`.
+
+Алгоритм:
+
+1. Будує шлях до `.cursor/rules`.
+2. Якщо такої директорії не існує (`existsSync` false) — повертає порожній масив (раннє повернення, безпечне для свіжих репо).
+3. Зчитує перелік файлів директорії синхронно (`readdirSync`).
+4. Фільтрує файли: повинні починатися з префіксу `'n-'` (константа `MIRROR_PREFIX`) і завершуватися розширенням `'.mdc'` (константа `MDC_EXT`).
+5. Мапить кожен файл у об'єкт із обчисленими шляхами: `id` отримується вирізанням префіксу і розширення (`f.slice(MIRROR_PREFIX.length, -MDC_EXT.length)`).
+6. Залишає лише ті записи, для яких реально існує канонічне джерело `canonicalPath` (друга фільтрація через `existsSync`). Це дозволяє пропускати «зовнішні» дзеркала, які не мають канону в монорепо.
+
+Side effects: лише читання директорії з диску (синхронні `existsSync`, `readdirSync`). Жодних записів, мережевих викликів, мутацій глобального стану.
+
+Помилки: якщо файлова система кине помилку під час `readdirSync` (наприклад, права доступу) — вона прокинеться вгору; для типового сценарію відсутності директорії `.cursor/rules` функція не падає (гард через `existsSync`).
+
+### `expectedMirrorContent(canonicalPath)`
+
+Сигнатура: `function expectedMirrorContent(canonicalPath: string): Promise<string>`
+
+Параметри:
+
+- `canonicalPath` — абсолютний шлях до канонічного `.mdc`-файлу (`npm/rules/<id>/<id>.mdc`).
+
+Повертає `Promise<string>` — очікуваний (нормалізований) текст дзеркала після інлайнінгу шаблонів. Хоча сама функція не використовує `async`/`await`, її результат типізовано як `Promise`, оскільки делегує виклик до `inlineTemplateLinks`, яка є асинхронною (її результат може бути thenable). Це означає, що споживач має `await`-нути повернене значення.
+
+Алгоритм:
+
+1. Синхронно зчитує вміст канонічного файлу як UTF-8 (`readFileSync(canonicalPath, 'utf8')`).
+2. Викликає `inlineTemplateLinks(content, dirname(canonicalPath))`, передаючи прочитаний текст та теку канону як base для розв'язання шляхів до шаблонів.
+3. Повертає результат трансформації.
+
+Side effects: одне читання з диску. Подальша поведінка щодо шаблонів інкапсульована в `inlineTemplateLinks` (див. її документацію). Контракт: цей же самий трансформ застосовує синк, тому очікуваний вміст детермінований по канону.
+
+Помилки: якщо файл за `canonicalPath` не існує або недоступний — `readFileSync` кине помилку. Викличні сторони мають гарантувати існування (`listManagedMirrors` уже фільтрує неіснуючі канони).
+
+### `findMirrorDrift(repoRoot)`
+
+Сигнатура: `async function findMirrorDrift(repoRoot: string): Promise<string[]>`
+
+Параметри:
+
+- `repoRoot` — абсолютний шлях до кореня репозиторію.
+
+Повертає `Promise<string[]>` — відсортований за зростанням масив `id` правил, де дзеркало розійшлося з очікуваним вмістом.
+
+Алгоритм:
+
+1. Заводить порожній масив `drift`.
+2. Послідовно (через `for...of`) обходить усі керовані дзеркала, отримані з `listManagedMirrors(repoRoot)`.
+3. Для кожного дзеркала `m`:
+   - `await`-ить очікуваний вміст через `expectedMirrorContent(m.canonicalPath)`;
+   - синхронно зчитує фактичний вміст файлу дзеркала `readFileSync(m.mirrorPath, 'utf8')`;
+   - якщо стрічки не дорівнюють — додає `m.id` до `drift`.
+4. Повертає `drift.sort()` (лексикографічне сортування).
+
+Side effects: тільки читання з диску. Не записує жодних файлів, не пише в лог.
+
+Зауваження щодо порівняння: рівність стрічок є точною (строге `!==` по UTF-8 тексту). Будь-яка різниця в пробілах, символах кінця рядка чи порядку інлайнених шаблонів буде розцінена як дрейф.
+
+## Залежності
+
+Стандартна бібліотека Node.js:
+
+- `node:fs` — `existsSync`, `readdirSync`, `readFileSync`. Усі виклики синхронні. Імпорт зроблено через `node:`-префікс для явної прив'язки до built-in модуля.
+- `node:path` — `dirname`, `join`. Використовуються для безпечного складання абсолютних шляхів і отримання батьківської теки канону.
+
+Локальні модулі:
+
+- `./inline-template-links.mjs` — імпорт іменованої функції `inlineTemplateLinks(content, baseDir)`. Це той самий трансформ, що його використовує синк дзеркал; саме завдяки спільному використанню досягається консистентність між «гардом дрейфу» і «генератором дзеркал».
+
+Зовнішніх npm-залежностей немає.
+
+Константи на рівні модуля:
+
+- `MIRROR_PREFIX = 'n-'` — префікс імені файлів дзеркал.
+- `MDC_EXT = '.mdc'` — розширення файлів правил Cursor.
+
+## Потік виконання / Використання
+
+Типові сценарії використання модуля:
+
+1. Тест-гард парності (CI). Споживач передає корінь репо й перевіряє, що дрейф порожній:
+
+   ```js
+   import { findMirrorDrift } from './mirror-parity.mjs'
+
+   const drift = await findMirrorDrift(repoRoot)
+   if (drift.length) {
+     throw new Error(`Mirror drift detected for: ${drift.join(', ')}`)
+   }
+   ```
+
+2. Разова регенерація дзеркал. Споживач отримує список керованих дзеркал і для кожного перезаписує файл дзеркала очікуваним вмістом:
+
+   ```js
+   import { writeFileSync } from 'node:fs'
+   import { listManagedMirrors, expectedMirrorContent } from './mirror-parity.mjs'
+
+   for (const m of listManagedMirrors(repoRoot)) {
+     const expected = await expectedMirrorContent(m.canonicalPath)
+     writeFileSync(m.mirrorPath, expected)
+   }
+   ```
+
+   (Сам модуль `mirror-parity.mjs` записів не виконує — це задача викличного скрипта.)
+
+Внутрішній потік виконання `findMirrorDrift`:
+
+1. Виклик `listManagedMirrors(repoRoot)`:
+   - перевірка існування `.cursor/rules`;
+   - читання списку файлів;
+   - фільтрація за префіксом `n-` і розширенням `.mdc`;
+   - обчислення `id`, `mirrorPath`, `canonicalPath`;
+   - відкидання дзеркал без канону.
+2. Послідовний обхід отриманих описів:
+   - читання канону → `inlineTemplateLinks` → очікуваний текст;
+   - читання дзеркала → порівняння;
+   - накопичення id з дрейфом.
+3. Сортування результату та повернення.
+
+Контрактна гарантія: якщо синк використовує ту ж саму функцію `inlineTemplateLinks` для генерації дзеркал, то регенерація закриває будь-який дрейф, виявлений `findMirrorDrift`. Якщо дрейф виявлено — він завжди вказує на людську помилку (зміна канону без регенерації) або на розбіжність версій трансформу.
+
+Обмеження:
+
+- Обхід послідовний (без `Promise.all`) — простіший контракт по помилках, але повільніший на великих наборах правил. Зважаючи на типову кількість правил у `.cursor/rules`, це не критично.
+- Усі читання файлів синхронні, попри асинхронну сигнатуру `findMirrorDrift` — асинхронність зумовлена тільки інтерфейсом `inlineTemplateLinks`.
+- Префікс `n-` зашитий константою — додавання інших префіксів дзеркал вимагатиме зміни модуля.
+- Зовнішні дзеркала (без канону в `npm/rules/<id>/`) автоматично пропускаються; модуль не повідомляє про них окремо.

package/scripts/lib/worktree.mjs

@@ -87,6 +87,32 @@ export function buildDescription({ branch, task, baseCommit, date }) {
   ].join('\n')
 }
 
+/** Поріг переліку файлів у нагадуванні: понад нього показуємо лише кількість. */
+const DIRTY_LIST_LIMIT = 10
+
+/**
+ * Нагадування про незакомічені зміни основного дерева, які **не** потрапляють
+ * у новий worktree (він створюється від HEAD, без брудного стану). До
+ * `limit` файлів — перелік шляхів; більше — лише підсумкова кількість, щоб не
+ * залити екран. Призначене для виводу одразу після `worktree add`.
+ * @param {string} porcelain вивід `git status --porcelain` основного дерева
+ * @param {number} [limit] поріг переліку (понад нього — лише кількість)
+ * @returns {string | null} текст нагадування або `null`, якщо дерево чисте
+ */
+export function buildDirtyNotice(porcelain, limit = DIRTY_LIST_LIMIT) {
+  // Порядок: XY + пробіл (3 символи) + шлях; для перейменування — `orig -> dest`.
+  const files = String(porcelain ?? '')
+    .split('\n')
+    .map(line => line.slice(3).trim())
+    .filter(Boolean)
+  if (files.length === 0) return null
+  const head = `⚠️  Основне дерево має ${files.length} незакомічених змін — вони НЕ потрапили в цей worktree (створено від HEAD).`
+  const tail = '   Закоміть потрібні файли, якщо worktree-скіл має їх бачити.'
+  if (files.length > limit) return `${head}\n${tail}`
+  const list = files.map(f => `   - ${f}`).join('\n')
+  return `${head}\n${list}\n${tail}`
+}
+
 /**
  * `.md`-описи без відповідного зареєстрованого worktree-checkout.
  * @param {string[]} descFiles абсолютні шляхи `.worktrees/*.md`

package/scripts/worktree-cli.mjs

@@ -2,7 +2,7 @@
  * CLI-оркестратор worktree-tool `n-cursor worktree` (виконавець конвенції `.worktrees/`).
  *
  * Підкоманди:
- *   add <branch> "<опис>"     — git worktree add .worktrees/<sanit> -b <branch> (від HEAD) + .md-опис
+ *   add <branch> "<опис>"     — git worktree add .worktrees/<sanit> -b <branch> (від HEAD) + .md-опис + нагадування про незакомічені зміни
  *   remove <branch> [--force] — прибрати checkout + .md (гілку лишає)
  *   list                      — git worktree list + вміст .md-описів
  *   prune                     — git worktree prune + видалити осиротілі .md
@@ -16,7 +16,13 @@ import { join } from 'node:path'
 import { cwd as processCwd } from 'node:process'
 
 import { cleanupFlowSiblings } from './dispatcher/lib/state-store.mjs'
-import { buildDescription, findOrphanDescFiles, firstFreeBranch, worktreePaths } from './lib/worktree.mjs'
+import {
+  buildDescription,
+  buildDirtyNotice,
+  findOrphanDescFiles,
+  firstFreeBranch,
+  worktreePaths
+} from './lib/worktree.mjs'
 
 const USAGE = [
   'Usage:',
@@ -110,6 +116,9 @@ function cmdAdd(rest, ctx) {
   if (chosen !== branch) {
     ctx.log(`ℹ️  гілка/worktree "${branch}" уже існує — обрано вільну назву "${chosen}"`)
   }
+  // Знімаємо статус ДО створення worktree: інакше щойно створений checkout/опис у `.worktrees/`
+  // потрапили б у `git status` (коли `.worktrees/` не в .gitignore) і дали б хибне нагадування.
+  const dirty = buildDirtyNotice(git(['status', '--porcelain'], ctx.cwd).stdout)
   const added = git(['worktree', 'add', paths.checkout, '-b', chosen], ctx.cwd)
   if (added.status !== 0) {
     ctx.logError(`worktree add не вдався: ${added.stderr.trim()}`)
@@ -120,6 +129,7 @@ function cmdAdd(rest, ctx) {
   writeFileSync(paths.descFile, md, 'utf8')
   ctx.log(`✅ worktree: ${paths.checkout}`)
   ctx.log(`   опис:    ${paths.descFile}`)
+  if (dirty) ctx.log(dirty) // нагадування про незакомічені зміни основного дерева (зняте ДО add)
   return 0
 }
 

package/skills/coverage-fix/SKILL.md

@@ -24,35 +24,46 @@ description: >-
 
 ## Workflow
 
-### Крок 1: Запусти coverage
+### Крок 0: Визнач команди (з `package.json#scripts`)
 
-```bash
-n-cursor coverage
-```
+Прочитай кореневий `package.json` і зафіксуй дві команди (перша що існує):
+
+- **coverage-команда**: `scripts["coverage"]` → виклик `bun run coverage`; fallback `n-cursor coverage`
+- **test-команда**: `scripts["test"]` → виклик `bun run test` (або те, що в скрипті); fallback `bun test`
 
-Або якщо є у `package.json#scripts`:
+Далі по тексту «coverage-команда» / «test-команда» = знайдені тут значення.
+
+### Крок 1: Згенеруй або переви́користай `COVERAGE.md`
+
+**Early-skip.** Якщо `COVERAGE.md` уже існує, свіжий (новіший за останню зміну source/тестів) і має секцію `## Вцілілі мутанти` — можеш одразу перейти до Кроку 2 без повторної генерації. Інакше — згенеруй звіт:
 
 ```bash
-bun run coverage
+n-cursor coverage   # або coverage-команда з Кроку 0
 ```
 
 Ця команда генерує `COVERAGE.md`. Якщо є survived mutants — COVERAGE.md матиме секцію `## Вцілілі мутанти` з JSON-блоком.
 
-### Крок 2: Перевір вцілілих
+### Крок 2: Прочитай компактний index вцілілих
 
-Прочитай `COVERAGE.md`. Знайди секцію `## Вцілілі мутанти`. Знайди огороджений блок ` ```json ` і розбери JSON-масив.
+> **Не читай `COVERAGE.md` сам.** Файл може важити мегабайти (секція `## Вцілілі
+мутанти` на сотні файлів) — його читання спалило б сотні тисяч токенів. Важкий
+> парсинг несе CLI; ти отримуєш лише крихітний index.
 
-Якщо секція відсутня або масив порожній — зупинись:
+```bash
+n-cursor coverage-fix index
+```
+
+Друкує компактний JSON-масив `[{ "file": "<path>", "mutants": <N> }]` (кілобайти, не мегабайти). Якщо `[]` — зупинись:
 
 ```
 ✓ Жодних вцілілих мутантів — mutation score повний. Coverage завершено.
 ```
 
-Запам'ятай `prevCount = масив.length`.
+Запам'ятай `prevCount = сума всіх mutants` (загальна кількість вцілілих мутантів).
 
-### Крок 3: Для кожного файлу — запускає Agent
+### Крок 3: Для кожного файлу — slice + Agent
 
-Згрупуй мутанти по полю `file`. Для кожної групи:
+Для кожного запису `{ file, mutants }` з index:
 
 **3a. Визнач test файл (завжди у `tests/` директорії):**
 
@@ -65,42 +76,20 @@ bun run coverage
    - Оновити відносні imports (тепер `../` рівень вгору до source)
 3. Жоден не знайдено → буде створено `<dir>/tests/<basename>.test.mjs`
 
-**3b. Сформуй промпт для Agent:**
+**3b. Отримай готовий зріз-промпт лише для цього файлу:**
 
+```bash
+n-cursor coverage-fix slice --file <file>
 ```
-Тобі дані вцілілі мутанти зі Stryker для файлу `<file>`.
-Ці мутанти вціліли, бо наявні тести НЕ вловили конкретні зміни коду.
-
-**Вихідний код** (`<file>`):
-\`\`\`
-<зміст source-файлу>
-\`\`\`
-
-**Наявні тести** (`<test-file>`):
-\`\`\`
-<зміст test-файлу або "файл ще не існує">
-\`\`\`
-
-**Вцілілі мутанти** (кожен — зміна коду що НЕ вловлена):
-<для кожного мутанта:>
-- Рядок <line>, колонка <col>: `<original>` → `<replacement>` (тип: <mutantType>)
-
-**Завдання:**
-Допиши мінімальні test-cases у файл `<test-file>` які вловлять кожен мутант.
-Правила:
-- НЕ видаляй і НЕ змінюй наявні тести
-- Стиль тестів — відповідно до наявного файлу (той самий фреймворк, describe/test)
-- Якщо файл ще не існує — створи `<dir>/tests/<basename>.test.mjs` з правильними імпортами.
-  Приклад: source `src/services/auth-store.js` → import `import { ... } from '../auth-store.js'`
-- Після написання запусти: `bun test <test-file>` і переконайся що тести проходять (виправ якщо падають, 1-2 спроби)
-```
 
-**3c. Запусти Agent** з цим промптом. Дочекайся завершення.
+CLI друкує самодостатній промпт **рівно для одного файлу**: список вцілілих мутантів цього файлу (рядок/колонка/`original → replacement`/тип) з контекстом ±3 рядки навколо кожного та фіксовані правила. Це і є «порція під когнітивне навантаження» одного субагента — нічого зайвого.
+
+**3c. Запусти Agent** з цим зрізом як промптом, дописавши один рядок про цільовий test-файл із 3a (`<dir>/tests/<basename>.test.mjs`, з правильними відносними imports). Дочекайся завершення.
 
 ### Крок 4: Перевір що всі тести проходять
 
 ```bash
-bun test
+bun test   # або test-команда з Кроку 0
 ```
 
 Якщо падають — поверни відповідний Agent з помилкою і попроси виправити.
@@ -108,15 +97,15 @@ bun test
 ### Крок 5: Запусти coverage і порівняй
 
 ```bash
-n-cursor coverage
+n-cursor coverage   # або coverage-команда з Кроку 0
+n-cursor coverage-fix index
 ```
 
-Прочитай новий `COVERAGE.md`. Розбери JSON-масив вцілілих.
-`newCount = новий масив.length`
+`newCount = сума mutants` зі свіжого index (знову — без читання `COVERAGE.md` вручну).
 
 **Рішення:**
 
-- `newCount < prevCount` AND iterations < 3 → повтор з Кроку 2 з оновленим масивом
+- `newCount < prevCount` AND iterations < 3 → повтор з Кроку 2 з оновленим index
 - `newCount >= prevCount` → конвергенція:
 
   ```

package/skills/docgen/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: docgen
 description: >-
-  Обходить проєкт і для кожного кодового файлу (js/mjs/ts/vue/py) пише вичерпну українську md-документацію у теку docs/ поряд із кодом — диспатчить окремого субагента на кожен файл, за правилами adr/ci4
+  Обходить проєкт і для кожного кодового файлу (js/mjs/ts/vue/py) пише лаконічну поведінкову українську md-документацію у теку docs/ поряд із кодом — диспатчить окремого субагента на кожен файл, за правилами adr/ci4
 ---
 
 # docgen — генерація документації по файлах
 
 ## Мета
 
-Для кожного кодового файлу проєкту створити вичерпну `.md`-документацію у теці `docs/`
+Для кожного кодового файлу проєкту створити лаконічну поведінкову `.md`-документацію у теці `docs/`
 **поряд із самим файлом** (`<dir>/docs/<stem>.md`). Документацію пише **окремий субагент**
 на кожен файл — не один прохід, а батч-диспатч. Джерело правди стилю — правила `adr` і
 `ci4` (`docs/explanation`/`docs/adr`-каталоги з тих правил **не застосовуємо** — доку
@@ -46,13 +46,10 @@ Tier 3 — лише після завершення всього Tier 2.
 npx @nitra/cursor docgen scan
 ```
 
-Команда друкує JSON-масив об'єктів:
+Команда друкує JSON-масив об'єктів. Усі шляхи в ньому — відносні до кореня проєкту:
 
 ```json
-[
-  { "sourcePath": "/abs/src/lib/foo.js", "relSource": "src/lib/foo.js",
-    "docPath": "/abs/src/lib/docs/foo.md", "exists": false }
-]
+[{ "sourcePath": "src/lib/foo.js", "docPath": "src/lib/docs/foo.md", "exists": false }]
 ```
 
 Розпарси JSON.
@@ -80,7 +77,7 @@ npx @nitra/cursor docgen scan
 Промпт кожного субагента (підстав `sourcePath` і `docPath`):
 
 ```
-Напиши вичерпну технічну документацію для одного файлу коду.
+Напиши лаконічну технічну документацію для одного файлу коду — орієнтовану на поведінку, не реалізацію.
 
 ФАЙЛ-ДЖЕРЕЛО: <sourcePath>
 ЗАПИСАТИ В: <docPath>
@@ -94,18 +91,32 @@ npx @nitra/cursor docgen scan
 - Мова — УКРАЇНСЬКА для всього тексту (заголовки, абзаци, таблиці). Code identifiers,
   шляхи, імена API, команди — лишай як у коді (зазвичай ASCII).
 - ЧИСТИЙ Markdown. Жодних HTML-обгорток (<div>/<span>/класів) — токен-ефективність.
-- Контекстна незалежність: кожна секція самодостатня. Явно повторюй імена сутностей
-  («функція `calculateTotal()`», «модуль `src/lib/foo.js`»). Заборонено «як вище»,
-  «ця функція», «той сервіс».
-- ВИЧЕРПНІСТЬ — опиши всю логіку файлу. Секції:
-  ## Огляд — призначення файлу, його роль, що дає.
-  ## Експорти / API — кожен експорт (функція/клас/компонент/константа).
-  ## Функції — для кожної: сигнатура, параметри (типи), що повертає, side effects.
-  ## Залежності — імпорти й зовнішні залежності та навіщо вони.
-  ## Потік виконання / Використання — як цей файл використовують; ключові гілки логіки.
-- Для .vue додай опис props, emits, slots, реактивного стану.
+- ФОКУС НА ПОВЕДІНЦІ, не реалізації. Пиши ЩО і НАВІЩО, а не як саме це зроблено.
+- НЕ перелічуй модулі стандартної бібліотеки (node:fs, node:path, node:crypto, python stdlib
+  тощо) — вони не несуть бізнес-значення. Зовнішні залежності (npm-пакети, внутрішні модулі)
+  згадуй лише якщо їхня роль не очевидна з контексту.
+- НЕ перелічуй внутрішні назви допоміжних функцій/змінних — описуй їхню роль і поведінку.
+  Імена публічних exports згадуй лише коли export — справжня точка інтеграції, яку кличуть
+  ззовні. Для дрібних/листкових модулів з однією відповідальністю опиши роль поведінково,
+  БЕЗ сигнатур, таблиць типів і переліку параметрів — це деталі реалізації.
+- Контекстна незалежність: кожна секція самодостатня. Уникай «як вище», «ця функція», «той сервіс».
+- Секції (включай лише доречні — порожніх не вигадуй):
+  ## Огляд — 1-3 речення: що файл робить і навіщо він існує (роль у системі). Згадай
+    ключову семантику, якщо вона визначає сенс файлу (opt-in/gate, кеш, ідемпотентність тощо).
+  ## Поведінка — покроковий алгоритм у бізнес-термінах (не деталі реалізації).
+    Нумерований список: що відбувається, умови, гілки логіки. Якщо файл керується
+    конфігом чи форматом даних — наведи короткий приклад (тільки реальний з коду).
+  ## Публічний API — ЛИШЕ якщо модуль має нетривіальну зовнішню поверхню, яку називають
+    споживачі. Для кожного export: назва + що робить. Без сигнатур і таблиць типів.
+    Не дублюй ## Поведінка. Для модуля з однією функцією-предикатом цю секцію пропусти.
+  ## Де використовується — де в системі цей файл вживається (якщо відомо з коду).
+  ## Гарантії поведінки — інваріанти й крайові випадки: що гарантовано (read-only,
+    не кидає винятків, fail-safe-значення за замовчуванням, безпечна обробка поганих даних)
+    і що стається при відсутніх ресурсах чи некоректному вводі. Пропусти, якщо таких гарантій немає.
+- Для .vue додай ## Інтерфейс компонента — props (типи, defaults), emits, slots, реактивний стан.
 - НЕ вигадуй деталей, яких немає в коді.
-- Мета — Rebuild Test: за цим документом можна відтворити логіку файлу.
+- Мета — Behavior Test: читач розуміє, що робить файл і як він вписується в систему,
+  без потреби читати реалізацію.
 
 Поверни лише підтвердження, що файл <docPath> записано.
 ```
@@ -122,9 +133,14 @@ npx @nitra/cursor docgen modules
 
 ```json
 [
-  { "moduleRoot": "/abs/npm/rules/adr", "relRoot": "npm/rules/adr",
-    "slug": "npm-rules-adr", "docPath": "/abs/npm/rules/adr/docs/ARCHITECTURE.md",
-    "members": ["npm/rules/adr/index.mjs"], "exists": false }
+  {
+    "moduleRoot": "/abs/npm/rules/adr",
+    "relRoot": "npm/rules/adr",
+    "slug": "npm-rules-adr",
+    "docPath": "/abs/npm/rules/adr/docs/ARCHITECTURE.md",
+    "members": ["npm/rules/adr/index.mjs"],
+    "exists": false
+  }
 ]
 ```
 
@@ -138,7 +154,7 @@ module-summary **завжди регенерується** (це агрегат
 ФАЙЛИ МОДУЛЯ (members): <members>
 
 Кроки:
-1. Прочитай файлові доки членів модуля. <member> — relSource відносно кореня проєкту
+1. Прочитай файлові доки членів модуля. <member> — sourcePath відносно кореня проєкту
    (= поточний CWD); його файлова дока — <CWD>/<dir>/docs/<stem>.md. За потреби зазирни
    в самі файли.
 2. Створи теку для <docPath>, якщо її немає.
@@ -201,3 +217,8 @@ Tier 3 (домени): <D> доменних доків у docs/.
 - Не комітити автоматично — користувач вирішує, коли комітити згенеровану доку.
 - Scanner ігнорує `node_modules`, `dist`, `.git`, `__pycache__`, `coverage`, `.cursor`,
   `.claude`, усі теки `docs/`, а також `*.test.*` / `*.spec.*` / `*.d.ts`.
+  Кореневий repo `docs/` — system-wide only: file-level docs туди не пишуться, і Tier 1
+  має трактувати цей корінь як повністю нецільовий.
+- Список glob-ів для ignore живе в окремому snippet-модулі
+  `npm/skills/docgen/js/docgen-ignore.mjs` (`DOCGEN_IGNORE_GLOBS`).
+  Scanner лише читає цей список.

package/skills/docgen/bench/etalon/firebase_hosting.md

@@ -0,0 +1,19 @@
+# firebase_hosting.mjs
+
+## Огляд
+
+Перевірка-концерн правила abie: у підкаталогах першого рівня репозиторію не повинно бути артефактів Firebase Hosting (`.firebaserc`, `firebase.json`, `.firebase/`), бо `abie.mdc` забороняє Firebase Hosting. Сам корінь репозиторію не перевіряється — там ці імена можуть належати суміжним проєктам.
+
+## Поведінка
+
+1. Прочитати список елементів кореня репозиторію. Якщо каталог не читається — зафіксувати помилку (fail) і завершитися.
+2. Відібрати підкаталоги першого рівня, пропустивши `.git` і `node_modules`.
+3. У кожному такому підкаталозі перевірити наявність заборонених імен: файлів `.firebaserc`, `firebase.json` і каталогу `.firebase/`. Кожна знахідка — окремий fail.
+4. Якщо жодного порушення не знайдено — зафіксувати pass.
+5. Повернути підсумковий exit-код.
+
+## Гарантії поведінки
+
+- Read-only: лише перелічує й перевіряє існування шляхів.
+- Помилка читання кореня не валить процес винятком, а стає fail.
+- Перевіряється лише перший рівень; корінь і глибші рівні поза охопленням.

package/skills/docgen/bench/etalon/k8s-tree.md

@@ -0,0 +1,24 @@
+# k8s-tree.mjs
+
+## Огляд
+
+Обхід Kubernetes-дерева для перевірок abie з кешуванням на час одного прогону. Знаходить YAML під сегментом `k8s/` і визначає каталоги з `Deployment`. Перший виклик платить за обхід; наступні концерни прогону беруть із кешу.
+
+## Поведінка
+
+1. Пошук маніфестів: рекурсивно обійти дерево, відібравши `.yaml`/`.yml` під сегментом `k8s/`; `.github/` свідомо пропускається. Результат відсортований.
+2. Каталоги з Deployment: розпарсити передані YAML, відібрати `kind: Deployment`, зібрати унікальні каталоги.
+3. Кешування: обидві операції кешуються module-level singleton-ом за ключем із входів; повтор без I/O.
+4. Пошкоджені YAML за замовчуванням мовчки пропускаються; репортер передає викликач.
+
+## Публічний API
+
+- `findK8sYamlFiles` — відсортований список YAML під `k8s/` (з кешем, пропуск `.github/`).
+- `collectDeploymentDirs` — множина каталогів із Deployment (кеш, опц. репортер помилок).
+
+## Гарантії поведінки
+
+- Read-only щодо проєкту.
+- Стійкість до пошкоджених YAML: помилкові документи пропускаються, обхід не переривається.
+- Детермінований вивід (стабільне сортування).
+- Кеш у межах прогону; повторні виклики безкоштовні.

package/skills/docgen/bench/etalon/overlay-paths.md

@@ -0,0 +1,24 @@
+# overlay-paths.mjs
+
+## Огляд
+
+Набір чистих path-хелперів для overlay-перевірок правила abie: класифікація шляхів (ua-overlay проти base-шару), виведення каталогу пакета з overlay-шляху, умовні питання правила (чи потрібен HTTPRoute, чи є Deployment). Уся логіка — над рядками/шляхами та перевіркою існування файлів; YAML не парситься.
+
+## Поведінка
+
+- ua-overlay: шлях закінчується на `ua/kustomization.yaml`; base-шар — за сегментом `base/`.
+- Каталог пакета: з `…/k8s/ua/kustomization.yaml` виділяється батько `k8s/`; без збігу — немає результату.
+- HTTPRoute-gate: вимога лише для Vite-пакетів (є `vite.config.{js,mjs,ts}`).
+- Deployment: чи хоч один каталог із Deployment лежить у `k8s/` цього пакета.
+- base-шар: yaml під `<пакет>/k8s/` і не в `ua/`.
+- Шляхи нормалізуються до posix (`\`→`/`).
+
+## Публічний API
+
+- `isUaKustomizationPath`, `abiePackageDirFromK8sOverlay`, `abieOverlayRequiresHttpRouteByVite`, `abieOverlayK8sTreeHasDeployment`, `isAbieK8sBaseYamlPath`, `isK8sYamlInAbiePackageExcludingUaOverlay`.
+
+## Гарантії поведінки
+
+- Read-only, без побічних ефектів.
+- Невідповідність шаблону → негативний/порожній результат, не виняток.
+- Незалежність від ОС (розділювачі зводяться до `/`).

package/skills/docgen/js/docgen-ignore.mjs

@@ -0,0 +1,54 @@
+/**
+ * Глоби, які `docgen` завжди ігнорує.
+ *
+ * Це окремий snippet-модуль: список правиться тут, scanner лише читає його
+ * через predicate. Патерни пишуться в posix-формі відносно кореня проєкту.
+ */
+import picomatch from 'picomatch'
+
+/** Базовий список glob-ів для `docgen` ignore. */
+export const DOCGEN_IGNORE_GLOBS = Object.freeze([
+  '**/node_modules/**',
+  '**/dist/**',
+  '.git/**',
+  '**/__pycache__/**',
+  '**/coverage/**',
+  '.cursor/**',
+  '.claude/**',
+  '.pi/**',
+  '.pi-template/**',
+  '.worktrees/**',
+  '**/benchmarks/**',
+  '**/demo/**',
+  '**/docs/**'
+])
+
+const IGNORE_MATCHERS = DOCGEN_IGNORE_GLOBS.map(glob => picomatch(glob, { dot: true }))
+
+/**
+ * Нормалізує відносний шлях до posix-формату для glob-matching.
+ * @param {string} relPath відносний шлях із path.relative(...)
+ * @returns {string} posix-вигляд шляху
+ */
+function toPosixRelPath(relPath) {
+  return relPath.split('\\').join('/')
+}
+
+/**
+ * Перевіряє, чи шлях має бути пропущений `docgen`.
+ * Для `kind = 'dir'` це працює і на піддерево каталогу, тож glob на кшталт
+ * `**\\/demo/**` спрацьовує на `demo/x` під час рекурсивного обходу.
+ * @param {string} relPath відносний шлях від кореня проєкту
+ * @param {'path'|'dir'} [kind='path'] тип перевірки
+ * @returns {boolean} `true`, якщо шлях ігнорується
+ */
+export function isDocgenIgnored(relPath, kind = 'path') {
+  if (typeof relPath !== 'string' || relPath.length === 0) {
+    return false
+  }
+  const posixRelPath = toPosixRelPath(relPath)
+  if (kind === 'dir') {
+    return IGNORE_MATCHERS.some(match => match(posixRelPath) || match(`${posixRelPath}/__docgen__`))
+  }
+  return IGNORE_MATCHERS.some(match => match(posixRelPath))
+}