@nitra/cursor 3.22.0 → 3.23.1

package/scripts/lib/docs/list-rule-ids.md

@@ -0,0 +1,156 @@
+# list-rule-ids.mjs
+
+## Огляд
+
+Модуль `list-rule-ids.mjs` — невелика бібліотечна утиліта, призначена для перебору директорій-правил у каталозі `npm/rules/` та повернення відсортованого алфавітно списку ідентифікаторів правил, які реально містять виконуваний модуль `fix.mjs`.
+
+Логіка модуля побудована навколо архітектурної інваріанти проєкту: після так званої «атомарної міграції» кожне валідне правило **зобов'язане** мати файл `fix.mjs` у власній директорії `rules/<id>/`. Будь-яка піддиректорія без `fix.mjs` вважається або «не-правилом» (службова тека), або заглушкою-чернеткою — і ігнорується. Прихованих директорій (імена, що починаються з `.`) також не існує в результаті.
+
+Додатково модуль підтримує опційне точкове фільтрування одним конкретним `id`, що використовується CLI-флагом `--rule abie` для прогону команд у режимі «тільки одне правило».
+
+Модуль повністю асинхронний (використовує `node:fs/promises`), не має зовнішніх npm-залежностей і не виконує жодних побічних ефектів окрім читання директорії та перевірки наявності файлу через `existsSync`.
+
+## Експорти / API
+
+Файл експортує одну іменовану функцію:
+
+| Експорт       | Тип              | Призначення                                                                                                                       |
+| ------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `listRuleIds` | `async function` | Повертає `Promise<string[]>` зі списком id правил, відфільтрованим за наявністю `fix.mjs` і опційним рівнянням до конкретного id. |
+
+Експорту за замовчуванням немає.
+
+## Функції
+
+### `listRuleIds(bundledRulesDir, filter)`
+
+#### Сигнатура
+
+```js
+export async function listRuleIds(bundledRulesDir, filter)
+```
+
+JSDoc-типи:
+
+```
+@param {string} bundledRulesDir — абсолютний шлях до `npm/rules/`
+@param {string} [filter]       — id одного правила (через `--rule abie`)
+@returns {Promise<string[]>}    — відсортовані алфавітно id
+```
+
+#### Параметри
+
+- **`bundledRulesDir`** (`string`, обовʼязковий) — абсолютний шлях до кореневої теки правил, найчастіше `npm/rules/` (наприклад, `/path/to/repo/npm/rules`). Передбачається, що шлях існує і є директорією; модуль не валідує його окремо — будь-яка помилка з `fs.readdir` пробрасується далі промісом.
+- **`filter`** (`string | undefined`, опційний) — точна назва правила, до якої потрібно звузити список. Якщо параметр не передано (`undefined`), повертаються всі знайдені id. Якщо передано, у результат потрапляють лише ті id, що _точно_ рівні `filter`. Часткові збіги, регулярні вирази або кейс-незалежність не підтримуються.
+
+#### Повертає
+
+`Promise<string[]>` — масив рядків-ідентифікаторів правил, відсортованих алфавітно за допомогою `Array.prototype.toSorted` із компаратором `a.localeCompare(b)`. Сортування _стабільне_ для оригінального методу і коректне для Unicode-локалей.
+
+Можливі сценарії результату:
+
+- Порожній масив `[]` — якщо в `bundledRulesDir` немає жодної директорії з `fix.mjs`, або якщо `filter` не збігається з жодним наявним id.
+- Масив з одного елемента — типово при заданому `filter`.
+- Повний відсортований список усіх правил — у випадку відсутності `filter`.
+
+#### Алгоритм / послідовність кроків
+
+1. Викликається `readdir(bundledRulesDir, { withFileTypes: true })` — отримуємо масив `Dirent`-обʼєктів (а не просто рядків імен), що дає змогу одразу перевіряти тип запису без додаткових `stat`-викликів.
+2. Залишаються лише записи, для яких одночасно:
+   - `e.isDirectory()` — це саме директорія;
+   - `!e.name.startsWith('.')` — імʼя не починається з крапки (відсікаються приховані теки на кшталт `.git`, `.cache`, тощо).
+3. Записи перетворюються на голі імена (`.map(e => e.name)`).
+4. Фільтрація на наявність `fix.mjs` — для кожного `id` синхронно перевіряється `existsSync(join(bundledRulesDir, id, 'fix.mjs'))`. Директорії без цього файлу відсіюються як «not-a-rule або заглушка».
+5. Фільтрація за `filter` — якщо параметр визначений, залишаються лише id, рівні `filter`; інакше пропускаються всі.
+6. Сортування `toSorted((a, b) => a.localeCompare(b))` — повертає новий масив без мутації проміжного.
+
+#### Side effects
+
+- **Дискові читання**: `readdir` (асинхронний обхід директорії) та `existsSync` (синхронні перевірки наявності файлу для кожного кандидата). Винятки I/O пробрасуються відхиленим промісом.
+- **Жодних записів, мережевих викликів, мутацій глобального стану, логування** — функція є read-only і чистою щодо побічних ефектів окрім згаданих читань ФС.
+- Використання `existsSync` у циклі — це _синхронні_ виклики всередині асинхронної функції; вони виконуються послідовно, але без `await`. Для типового розміру каталогу `npm/rules/` (десятки правил) це непомітна вартість.
+
+#### Гранітні випадки
+
+- Якщо `bundledRulesDir` не існує — `readdir` відхиляє проміс з `ENOENT`.
+- Якщо в директорії є символічні посилання — поведінка залежить від того, що повертає `Dirent.isDirectory()`; ця функція покладається на штатну семантику Node.js.
+- Якщо `filter` переданий як порожній рядок `''` — він _не_ є `undefined`, тому фільтр буде застосовано (`id === ''`), і результат майже напевно буде порожнім.
+- Файл `fix.mjs` як директорія: малоймовірний випадок, але `existsSync` поверне `true` для будь-якого існуючого запису з цим імʼям; модуль не розрізняє файл і теку.
+
+## Залежності
+
+### Вбудовані модулі Node.js
+
+| Модуль             | Імпортований символ | Використання                                                 |
+| ------------------ | ------------------- | ------------------------------------------------------------ |
+| `node:fs`          | `existsSync`        | Синхронна перевірка наявності `fix.mjs` у кожному кандидаті. |
+| `node:fs/promises` | `readdir`           | Асинхронний обхід `bundledRulesDir` з `withFileTypes: true`. |
+| `node:path`        | `join`              | Безпечне зʼєднання сегментів шляху до `fix.mjs`.             |
+
+### Зовнішні npm-залежності
+
+Немає.
+
+### Внутрішні залежності
+
+Файл не імпортує жодних інших модулів проєкту. Сам по собі він використовується як бібліотечна функція з інших скриптів у `npm/scripts/` (CLI-обгортки, які приймають флаг `--rule`).
+
+## Потік виконання / Використання
+
+### Контекст у проєкті
+
+`listRuleIds` — це фундамент будь-якого скрипту, який «робить щось для кожного правила»: лінт, авто-фікс, генерація звіту, перевірка покриття, нормалізація ADR тощо. Замість того щоб кожному скрипту самостійно перелічувати теки в `npm/rules/`, всі вони викликають цю функцію та отримують однаковий, відсортований, відфільтрований список — це гарантує детермінованість порядку обробки правил.
+
+Архітектурно файл підкріплює інваріант «`fix.mjs` обовʼязковий»: будь-яка тека без нього автоматично невидима для всіх споживачів. Це дає змогу тримати у `rules/` допоміжні підтеки (наприклад, шаблони, шаред-файли) без ризику, що вони будуть оброблені як правило.
+
+### Приклад використання
+
+```js
+import { listRuleIds } from './lib/list-rule-ids.mjs'
+import { resolve } from 'node:path'
+
+const bundledRulesDir = resolve(import.meta.dirname, '../../rules')
+
+// 1. Всі правила.
+const all = await listRuleIds(bundledRulesDir)
+// → ['abie', 'changelog', 'feedback', ...]
+
+// 2. Тільки одне правило (з CLI-флагу --rule abie).
+const ruleFlag = process.argv.includes('--rule') ? process.argv[process.argv.indexOf('--rule') + 1] : undefined
+
+const subset = await listRuleIds(bundledRulesDir, ruleFlag)
+// → ['abie']  якщо ruleFlag === 'abie' і таке правило існує
+// → []        якщо ruleFlag не відповідає жодному правилу
+```
+
+### Інтеграція з CLI
+
+Типовий патерн виклику в скриптах проєкту:
+
+1. Скрипт парсить `process.argv` (часто через `mri`/`minimist` або вручну), отримує опційний `--rule <id>`.
+2. Викликає `listRuleIds(rulesDir, ruleFromArgv)` і чекає на результат.
+3. Ітерується по отриманому масиву і виконує цільову дію (fix/check/коверідж) для кожного id.
+
+### Послідовність виконання при виклику
+
+```
+listRuleIds(dir, filter)
+   │
+   ├─ readdir(dir, withFileTypes:true) ── async ──▶ [Dirent...]
+   │
+   ├─ .filter(isDirectory && !startsWith('.'))
+   ├─ .map(e => e.name)
+   ├─ .filter(existsSync(<id>/fix.mjs))      ◀── sync I/O loop
+   ├─ .filter(filter === undefined || id === filter)
+   ├─ .toSorted(localeCompare)
+   │
+   ▼
+Promise<string[]>  (відсортовані id)
+```
+
+### Очікувані помилки
+
+- `ENOENT` / `ENOTDIR` від `readdir` — якщо переданий `bundledRulesDir` неіснуючий або не є директорією. Викликач має або переконатися в коректності шляху перед викликом, або обгорнути виклик у `try/catch`.
+- `EACCES` — якщо немає прав на читання теки.
+
+Усі інші помилки (відсутність окремого `fix.mjs`, відсутність відповідності `filter`) семантично не є помилками — вони лише звужують повернений масив.

package/scripts/lib/docs/load-cursor-config.md

@@ -0,0 +1,147 @@
+# load-cursor-config.mjs
+
+## Огляд
+
+Утилітарний модуль для читання конфігураційного файлу `.n-cursor.json` з кореня репозиторію. Призначений для використання check-скриптами, що обходять файлову систему й мають виключати певні каталоги зі сканування.
+
+Наразі експортує лише одну публічну функцію — `loadCursorIgnorePaths(root)`, яка повертає нормалізовані абсолютні posix-шляхи з масиву `ignore` у конфізі. Якщо конфіг відсутній, пошкоджений, або поле `ignore` має невалідний формат — функція повертає порожній масив без кидання винятків (fail-soft підхід).
+
+Модуль свідомо **не валідує** структуру конфігу повністю — це робота окремої перевірки (наприклад, через `v8r`). Тут перевіряється лише наявність і тип поля `ignore` та його елементів.
+
+Шлях до конфігу зашитий константою `CONFIG_FILE = '.n-cursor.json'` й читається з кореня репозиторію, переданого через параметр `root`.
+
+## Експорти / API
+
+| Експорт                 | Тип                                                | Призначення                                                          |
+| ----------------------- | -------------------------------------------------- | -------------------------------------------------------------------- |
+| `loadCursorIgnorePaths` | `async function (root: string): Promise<string[]>` | Зчитати й нормалізувати список ігнорованих шляхів з `.n-cursor.json` |
+
+Внутрішні (не експортовані) сутності:
+
+| Сутність      | Тип                                          | Призначення                                                        |
+| ------------- | -------------------------------------------- | ------------------------------------------------------------------ |
+| `CONFIG_FILE` | `string` (константа `'.n-cursor.json'`)      | Ім'я конфіг-файлу в корені репозиторію                             |
+| `toAbsPosix`  | `function (root: string, p: string): string` | Нормалізатор шляху до абсолютного posix-формату без trailing-slash |
+
+## Функції
+
+### `toAbsPosix(root, p)`
+
+Внутрішня (приватна для модуля) функція-нормалізатор шляху.
+
+- **Сигнатура:** `function toAbsPosix(root: string, p: string): string`
+- **Параметри:**
+  - `root` — абсолютний корінь репозиторію (використовується для розв'язання відносних шляхів).
+  - `p` — шлях з конфігу; може бути відносним або абсолютним.
+- **Повертає:** абсолютний posix-шлях (роздільник `/`) без жодного завершального `/`.
+- **Алгоритм:**
+  1. Конвертує `p` у рядок через `String(p)` і прибирає пробіли по краях через `trim()`.
+  2. Якщо результат вже абсолютний (`isAbsolute`), використовує його як є; інакше — резолвить відносно `root` через `resolve(root, trimmed)`.
+  3. Замінює нативний роздільник платформи (`sep`) на `/` (через `split(sep).join('/')`) — на Windows це конвертує `\` у `/`.
+  4. У циклі видаляє всі завершальні `/` (нормалізація `foo/bar//` → `foo/bar`).
+- **Side effects:** немає (чиста функція над аргументами).
+
+### `loadCursorIgnorePaths(root)`
+
+Публічна async-функція — точка входу модуля.
+
+- **Сигнатура:** `async function loadCursorIgnorePaths(root: string): Promise<string[]>`
+- **Параметри:**
+  - `root` — абсолютний шлях до кореня репозиторію, де очікується `.n-cursor.json`.
+- **Повертає:** `Promise<string[]>` — масив абсолютних posix-шляхів без trailing-slash; може бути порожнім.
+- **Алгоритм (fail-soft):**
+  1. Обчислює абсолютний шлях до конфіг-файлу через `join(root, CONFIG_FILE)`.
+  2. Якщо файлу немає на диску (`existsSync` повернув `false`) — повертає `[]`.
+  3. Намагається прочитати файл через `readFile(file, 'utf8')` й розпарсити його як JSON. Якщо парсинг кидає виняток (битий JSON, помилка читання тощо) — `catch` повертає `[]`.
+  4. Дістає поле `ignore` з розпарсеного об'єкта через optional chaining (`raw?.ignore`). Якщо поле не є масивом (`Array.isArray` повернув `false`) — повертає `[]`.
+  5. Ітерує по `list`, для кожного елемента:
+     - якщо це не рядок — пропускає;
+     - тримить пробіли; якщо рядок став порожнім — пропускає;
+     - інакше додає в результат `toAbsPosix(root, v)`.
+  6. Повертає накопичений масив `out`.
+- **Side effects:**
+  - Синхронний `existsSync` на дисковий файл `<root>/.n-cursor.json`.
+  - Асинхронне читання того ж файлу через `readFile` (тільки якщо `existsSync` повернув `true`).
+  - Жодних записів, мережевих викликів чи мутацій глобального стану.
+- **Обробка помилок:**
+  - Файл не існує → `[]`.
+  - Файл існує, але JSON битий або `readFile` падає → `[]` (через `try/catch`).
+  - `ignore` не масив, або взагалі відсутнє → `[]`.
+  - Нестрингові або порожні після `trim()` елементи масиву → мовчки пропускаються.
+
+## Залежності
+
+### Node.js built-ins
+
+| Модуль             | Імпортовані сутності                   | Використання                                                                                                             |
+| ------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `node:fs`          | `existsSync`                           | Синхронна перевірка наявності `.n-cursor.json` перед читанням                                                            |
+| `node:fs/promises` | `readFile`                             | Асинхронне читання вмісту конфіг-файлу як UTF-8                                                                          |
+| `node:path`        | `isAbsolute`, `join`, `resolve`, `sep` | Перевірка абсолютності, склейка шляху до конфігу, розв'язання відносних шляхів, заміна платформного роздільника на posix |
+
+### Зовнішні залежності
+
+Жодних — лише стандартна бібліотека Node.js.
+
+### Конфігураційні артефакти
+
+- `.n-cursor.json` у корені репозиторію — джерело правди для `ignore` (опціональне поле, масив рядків).
+
+## Потік виконання / Використання
+
+### Типовий сценарій виклику
+
+Викликач (наприклад, check-скрипт) передає абсолютний корінь репозиторію й отримує перелік каталогів, які слід виключити з обходу.
+
+```js
+import { loadCursorIgnorePaths } from './load-cursor-config.mjs'
+
+const root = process.cwd() // або інший абсолютний корінь
+const ignored = await loadCursorIgnorePaths(root)
+// ignored: ['/abs/path/.worktrees', '/abs/path/node_modules', ...]
+
+// Далі при обході файлів пропускаємо ті, що під будь-яким із ignored:
+function isIgnored(absPosixPath) {
+  return ignored.some(ig => absPosixPath === ig || absPosixPath.startsWith(ig + '/'))
+}
+```
+
+### Очікуваний формат `.n-cursor.json`
+
+```json
+{
+  "ignore": [".worktrees", "node_modules", "/abs/path/to/skip"]
+}
+```
+
+Інші поля у файлі допустимі — їх ігнорує цей модуль (валідація схеми — окрема відповідальність).
+
+### Послідовність кроків усередині `loadCursorIgnorePaths`
+
+1. `join(root, '.n-cursor.json')` → шлях до конфігу.
+2. `existsSync(file)` → якщо `false`, ранній вихід з `[]`.
+3. `readFile + JSON.parse` у `try/catch` → при будь-якій помилці `[]`.
+4. `Array.isArray(raw?.ignore)` → якщо `false`, `[]`.
+5. Лінійний прохід по `ignore`-елементах: фільтр по типу й непорожності, нормалізація через `toAbsPosix(root, v)`.
+6. Повернення масиву `out`.
+
+### Інваріанти результату
+
+- Усі шляхи — **абсолютні**.
+- Усі шляхи — у **posix-форматі** (роздільник `/`), навіть на Windows.
+- Жоден шлях не має **завершального `/`**.
+- Порядок шляхів — відповідає порядку в `ignore` (вхідні дублікати **не дедуплікуються**).
+- За жодних умов функція не кидає винятки — повертає `[]` як єдиний "поганий" результат.
+
+### Тестування (Rebuild Test)
+
+Перевірка контрактів модуля:
+
+- Файлу немає → `loadCursorIgnorePaths(root)` резолвиться у `[]`.
+- Файл є, але JSON битий → `[]`.
+- Файл є, але `ignore` відсутнє/не масив → `[]`.
+- `ignore` містить нестрингові елементи й порожні рядки — вони відфільтровані; рядкові — нормалізовані до абсолютного posix-шляху без trailing-slash.
+- Відносний шлях у `ignore` (наприклад `"node_modules"`) перетворюється на `<root>/node_modules` у posix-формі.
+- Абсолютний шлях у `ignore` зберігається як є (з можливою конверсією `\` → `/`).
+- На Windows шляхи з `\` конвертуються у `/`.
+- Trailing `/` (один або кілька) видаляються.

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
 }