@nitra/cursor 3.22.0 → 3.23.1

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))
+}

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

@@ -1,27 +1,35 @@
 /**
  * docgen scanner — детермінований обхід проєкту для скілу `docgen`.
  *
- * Друкує JSON-список кодових файлів із обчисленим `docPath` (тека `docs/` поряд із
- * джерелом). Рішення про overwrite/skip приймає скіл — scanner лише лістить і ставить
- * прапор `exists`. LLM/мережі тут немає: уся генерація доки — у субагентах скілу.
+ * Друкує JSON-список кодових файлів із відносними `sourcePath`/`docPath`
+ * (тека `docs/` поряд із джерелом). Рішення про overwrite/skip приймає скіл —
+ * scanner лише лістить і ставить прапор `exists`. LLM/мережі тут немає: уся
+ * генерація доки — у субагентах скілу.
  */
 // eslint-disable-next-line unicorn/import-style
 import path from 'node:path'
 import { existsSync, readdirSync, statSync } from 'node:fs'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { isDocgenIgnored } from './docgen-ignore.mjs'
 
 /** Кодові розширення, для яких генеруємо документацію. */
 const SOURCE_EXTENSIONS = new Set(['.js', '.mjs', '.ts', '.vue', '.py'])
 
-/** Теки, які scanner ніколи не заходить (включно з самими `docs/`). */
-const IGNORED_DIRS = new Set([
-  'node_modules', 'dist', '.git', '__pycache__', 'coverage', '.cursor', '.claude', 'docs'
-])
-
 /** `*.test.*`, `*.spec.*` — тести, документувати не треба. */
 const TEST_FILE_RE = /\.(?:test|spec)\.[^.]+$/u
 
+/**
+ * Чи корінь має system-wide docs layout.
+ * Такий корінь зарезервований під репозиторні docs/adr, docs/explanation тощо,
+ * тому file-level docs у нього не пишемо.
+ * @param {string} root абсолютний корінь обходу
+ * @returns {boolean} true — корінь system-wide docs
+ */
+function isSystemWideDocsRoot(root) {
+  return existsSync(path.join(root, 'docs', 'adr')) || existsSync(path.join(root, 'docs', 'explanation'))
+}
+
 /**
  * Чи є файл кодовим джерелом для документування.
  * @param {string} fileName базове ім'я файлу
@@ -35,8 +43,9 @@ export function isSourceFile(fileName) {
 
 /**
  * Обчислює шлях md-документа для кодового файлу: тека `docs/` поряд із джерелом.
+ * Якщо `sourcePath` відносний, `docPath` теж відносний; якщо абсолютний — абсолютний.
  * @param {string} sourcePath шлях до джерела (відносний або абсолютний)
- * @returns {string} шлях до `<dir>/docs/<stem>.md`
+ * @returns {string} шлях до `<dir>/docs/<stem>.md` у тому ж просторі шляхів
  */
 export function docPathForSource(sourcePath) {
   const dir = path.dirname(sourcePath)
@@ -49,7 +58,7 @@ export function docPathForSource(sourcePath) {
  * Синхронний `readdirSync` — детермінований порядок і простий рекурсивний обхід без
  * гонок; обсяг дерева проєкту це дозволяє.
  * @param {string} root абсолютний корінь обходу
- * @returns {Array<{sourcePath:string, relSource:string, docPath:string, exists:boolean}>} список кандидатів
+ * @returns {Array<{sourcePath:string, docPath:string, exists:boolean}>} список кандидатів з відносними шляхами
  */
 export function scanForDocgen(root) {
   const results = []
@@ -66,16 +75,19 @@ export function scanForDocgen(root) {
     }
     for (const entry of entries) {
       const fullPath = path.join(dir, entry.name)
+      const relPath = path.relative(root, fullPath)
       if (entry.isDirectory()) {
-        if (IGNORED_DIRS.has(entry.name)) continue
+        if (isDocgenIgnored(relPath, 'dir')) continue
         walk(fullPath)
       } else if (entry.isFile() && isSourceFile(entry.name)) {
-        const docPath = docPathForSource(fullPath)
+        if (isSystemWideDocsRoot(root) && path.dirname(relPath) === '.') continue
+        const sourcePath = relPath.split(path.sep).join('/')
+        if (isDocgenIgnored(sourcePath)) continue
+        const docPath = docPathForSource(sourcePath)
         results.push({
-          sourcePath: fullPath,
-          relSource: path.relative(root, fullPath),
+          sourcePath,
           docPath,
-          exists: existsSync(docPath)
+          exists: existsSync(path.join(root, docPath))
         })
       }
     }
@@ -95,12 +107,15 @@ export function slugForModule(root, moduleRoot) {
   const rel = path.relative(root, moduleRoot)
   // корінь репо: фіксований sentinel 'root'
   if (rel === '') return 'root'
-  return rel.split(path.sep).join('-').replaceAll(/[^\w-]+/gu, '-')
+  return rel
+    .split(path.sep)
+    .join('-')
+    .replaceAll(/[^\w-]+/gu, '-')
 }
 
 /**
  * Знаходить корені модулів — теки з `package.json` (корінь завжди модуль).
- * Ті ж IGNORED_DIRS, тож `package.json` у node_modules тощо не враховується.
+ * Ті ж ignore-glob правила, тож `package.json` у службових деревах не враховується.
  * @param {string} root абсолютний корінь обходу
  * @returns {string[]} абсолютні шляхи коренів модулів
  */
@@ -117,8 +132,9 @@ export function findModuleRoots(root) {
     }
     for (const entry of entries) {
       const fullPath = path.join(dir, entry.name)
+      const relPath = path.relative(root, fullPath)
       if (entry.isDirectory()) {
-        if (IGNORED_DIRS.has(entry.name)) continue
+        if (isDocgenIgnored(relPath, 'dir')) continue
         walk(fullPath)
       } else if (entry.isFile() && entry.name === 'package.json' && dir !== root) {
         roots.push(dir)
@@ -150,17 +166,17 @@ export function nearestModuleRoot(filePath, moduleRoots) {
  * Лістить логічні модулі проєкту з членами-файлами і docPath module-summary.
  * Модулі без кодових файлів пропускаються.
  * @param {string} root абсолютний корінь обходу
- * @returns {Array<{moduleRoot:string, relRoot:string, slug:string, docPath:string, members:string[], exists:boolean}>} модулі (members — relSource-и, відносні від root)
+ * @returns {Array<{moduleRoot:string, relRoot:string, slug:string, docPath:string, members:string[], exists:boolean}>} модулі (members — sourcePath-и, відносні від root)
  */
 export function scanForModules(root) {
   const files = scanForDocgen(root)
   const moduleRoots = findModuleRoots(root)
   const byRoot = new Map()
   for (const file of files) {
-    const moduleRoot = nearestModuleRoot(file.sourcePath, moduleRoots)
+    const moduleRoot = nearestModuleRoot(path.join(root, file.sourcePath), moduleRoots)
     if (moduleRoot === null) continue
     if (!byRoot.has(moduleRoot)) byRoot.set(moduleRoot, [])
-    byRoot.get(moduleRoot).push(file.relSource)
+    byRoot.get(moduleRoot).push(file.sourcePath)
   }
 
   const results = []

package/skills/llm-patch/SKILL.md

@@ -71,6 +71,14 @@ description: >-
   з одним рядком пояснення кожна.
 - **Реальні обмеження,** які не виводяться з коду: версії в репо-споживачі,
   inflight-міграції, breaking-change політика, зовнішні залежності.
+- **Change-file flow,** якщо завдання змінює файли у пакетному workspace (код,
+  правила, скіли, конфіги, тести — не лише `docs/`): промпт має вимагати
+  `npx @nitra/cursor change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<опис>" [--ws <шлях>]`
+  і `npx @nitra/cursor fix changelog`. **Ніколи** не інструктуй ручне редагування
+  `CHANGELOG.md` чи bump `version` — це робить release flow / CI (деталь —
+  `.cursor/rules/n-changelog.mdc`, не дублюй її текст). Якщо потрібна реліз-нота —
+  це change-файл `<ws>/.changes/<timestamp>-<rand>.md` з `bump:` і `section:`,
+  який створює саме `change` CLI, а не редагування файлу вручну.
 - **Як перевірити** — конкретні команди й специфічні до завдання сигнали
   успіху.
 
@@ -185,6 +193,11 @@ description: >-
   агенту**, не людині. Використовуй "зроби", "онови", "додай".
 - **Без секцій-пустушок:** якщо немає `Обмежень` чи `Симптому` — пропусти
   секцію цілком.
+- **Без ручного changelog/version у промпті:** не формулюй у виводі інструкції
+  на кшталт "додати запис у `CHANGELOG.md`", "bump `version` вручну" чи
+  "оновити `package.json#version`". Зміни у workspace фіксуються винятково
+  через change-file flow (`npx @nitra/cursor change …` → `npx @nitra/cursor fix changelog`);
+  `version`/`CHANGELOG.md` формує CI.
 - **Не вмикай у промпт:** секрети, `.env`, `node_modules`, бінарні файли,
   довгі логи, дампи `tree`, повні JSON конфігів, цитати існуючих
   helpers/функцій з CWD.
@@ -219,17 +232,25 @@ description: >-
 # Точки правки
 
 - `package.json:18` — `engines.node`
-- `CHANGELOG.md` — додати запис; bump `version` (minor)
+
+# Що треба зробити
+
+- Підняти `engines.node` до `>=25`; якщо peer `eslint ^9` несумісний —
+  підняти range.
+- Зафіксувати зміну change-файлом (НЕ редагувати `CHANGELOG.md` чи `version`
+  вручну): `npx @nitra/cursor change --bump minor --section Changed --message "engines.node >=25"`.
 
 # Обмеження
 
-- Дотриматись `.cursor/rules/n-js-lint.mdc`.
+- Дотриматись `.cursor/rules/n-js-lint.mdc` і `.cursor/rules/n-changelog.mdc`
+  (зміни у workspace = change-файл, не ручний CHANGELOG/version bump).
 - Якщо `eslint ^9` офіційно не підтримує Node 25 — підняти peer range.
 
 # Як перевірити
 
 - `bun test` — зелений
 - `node -p "require('./package.json').engines.node"` → `>=25`
+- `npx @nitra/cursor fix changelog` → exit `0`
 ```
 ````