@nitra/cursor 5.3.4 → 5.4.0

package/scripts/lib/docs/discover-check-rules-from-cursor.md

@@ -1,163 +1,31 @@
 ---
 docgen:
   source: npm/scripts/lib/discover-check-rules-from-cursor.mjs
-  crc: 5e312e3e
+  crc: 9a6916e1
+  score: 100
 ---
 
 # discover-check-rules-from-cursor.mjs
 
 ## Огляд
 
-Модуль `discover-check-rules-from-cursor.mjs` визначає, які саме id правил повинні бути запущені командою `npx @nitra/cursor fix`, коли користувач викликає її **без аргументів**. Він узгоджує два джерела:
+Файл зчитує базові імена файлів `.mdc` у директорії `.cursor/rules/` та генерує список ідентифікаторів правил для `npx @nitra/cursor fix`, використовуючи перевірку через JS-концерн або policy з `target.json`.
 
-1. **Файлова система проєкту** — базові імена `*.mdc` у директорії `.cursor/rules/` (тобто правила, які реально присутні у конкретному репо).
-2. **Реєстр пакета** — список id правил, для яких у пакеті `@nitra/cursor` існує programmatic перевірка (JS-концерн або policy з `target.json`); цей список зазвичай приходить із функції `discoverCheckableRules`.
+## Поведінка
 
-Результат — впорядкований унікальний масив id, у якому:
+MANAGED_RULE_FILE_PREFIX Визначає префікс керованих правил пакета у файлах `.cursor/rules/`.
 
-- порядок диктується порядком файлів `*.mdc` у директорії правил (як їх передали ззовні, зазвичай відсортованими);
-- залишаються лише ті id, для яких у пакеті є реальна перевірка;
-- видалено префікс `n-`, оскільки внутрішня команда `check <id>` оперує «короткими» id (наприклад, `bun`, а не `n-bun`).
+mdcBasenameToCheckId Перетворює базове ім'я `.mdc` у id правила для `check <id>`.
 
-Файл містить чисті pure-функції без побічних ефектів — без `fs`, без `process`, без I/O. Все читання директорії правил і реєстру здійснюється викликачем; цей модуль лише поєднує два готових списки.
+discoverCheckRulesFromCursorRules Будує впорядкований список id перевірок за файлами правил на диску, фільтруючи їх за наявністю у доступних перевірок.
 
-## Експорти / API
+## Публічний API
 
-Модуль має три публічних експорти у форматі ES modules (`.mjs`):
+MANAGED_RULE_FILE_PREFIX — визначає префікс для керованих правил у директорії `.cursor/rules/`.
+mdcBasenameToCheckId — трансформує базове ім'я файлу `.mdc` у ідентифікатор правила для функції `check`.
+discoverCheckRulesFromCursorRules — створює відсортований список ідентифікаторів перевірок на основі файлів правил з курсору.
 
-| Експорт                             | Тип        | Призначення                                                                                      |
-| ----------------------------------- | ---------- | ------------------------------------------------------------------------------------------------ |
-| `MANAGED_RULE_FILE_PREFIX`          | `string`   | Константа `'n-'` — префікс імен файлів `.mdc`, які вважаються «керованими» пакетом.              |
-| `mdcBasenameToCheckId`              | `function` | Перетворює базове ім'я `*.mdc` (із розширенням або без) у id для CLI-команди `check`.            |
-| `discoverCheckRulesFromCursorRules` | `function` | Будує впорядкований список id перевірок як перетин «доступних у пакеті» та «присутніх на диску». |
+## Гарантії поведінки
 
-Усі експорти — іменовані (`export const` / `export function`); default-export відсутній.
-
-## Функції
-
-### `mdcBasenameToCheckId(mdcBasename)`
-
-**Сигнатура:**
-
-```js
-export function mdcBasenameToCheckId(mdcBasename: string): string
-```
-
-**Параметри:**
-
-- `mdcBasename` — рядок, який може бути:
-  - чистим базовим іменем файлу, наприклад `'n-bun.mdc'` або `'my-rule.mdc'`;
-  - відносним/абсолютним шляхом, наприклад `'.cursor/rules/n-bun.mdc'` (функція сама візьме сегмент після останнього `/`).
-
-**Поведінка:**
-
-1. Якщо у вхідному рядку є символ `/`, береться підрядок після останнього `/` — таким чином приймаються як «чисті» імена, так і шляхи.
-2. Якщо отриманий рядок закінчується на `.mdc`, розширення відсікається.
-3. Якщо те, що залишилось, починається з `MANAGED_RULE_FILE_PREFIX` (`'n-'`), цей префікс також знімається.
-4. Повертається отриманий «короткий» id.
-
-**Повертає:**
-
-- `string` — id, придатний для команди `check <id>`. Приклади:
-  - `'n-bun.mdc'` → `'bun'`
-  - `'.cursor/rules/n-vue.mdc'` → `'vue'`
-  - `'my-rule.mdc'` → `'my-rule'`
-  - `'n-text'` (без розширення) → `'text'`
-
-**Side effects:** немає. Функція суто детермінована, не звертається до файлової системи, не мутує аргументи.
-
-**Крайні випадки:**
-
-- Backslashes (`\\`) як роздільник шляху **не** розпізнаються — функція оперує лише `/`. Це безпечно для шляхів, які прийшли від утиліт на кшталт `fs.readdir`, що повертають базові імена, або з `path.posix`-стилю.
-- Якщо вхід уже без `.mdc`, він обробляється тим самим алгоритмом (просто пропускається крок зняття розширення).
-- Якщо файл, прибравши `.mdc`, дорівнює саме `'n-'`, повернеться порожній рядок — це не очікувана реальна ситуація, бо керованих правил із порожнім id не буває.
-
-### `discoverCheckRulesFromCursorRules(available, mdcBasenames)`
-
-**Сигнатура:**
-
-```js
-export function discoverCheckRulesFromCursorRules(
-  available: string[],
-  mdcBasenames: string[],
-): string[]
-```
-
-**Параметри:**
-
-- `available` — масив id, які пакет уміє перевіряти (програмні перевірки JS-концерну або policy з `target.json`). Зазвичай — результат `discoverCheckableRules` із сусіднього модуля `discover-checkable-rules.mjs`. Очікується алфавітний порядок, але алгоритм не залежить від нього.
-- `mdcBasenames` — масив базових імен файлів `*.mdc`, які реально присутні у `.cursor/rules/` поточного проєкту. Очікується, що масив уже відсортований викликачем (порядок цього масиву визначає порядок результату).
-
-**Поведінка:**
-
-1. Створюється `Set` `seen` для дедуплікації результату.
-2. Створюється масив `ordered` для збереження порядку входу `mdcBasenames`.
-3. Для кожного `basename`:
-   - обчислюється id через `mdcBasenameToCheckId(basename)`;
-   - якщо id присутній у `available` **і** ще не доданий — додається в `ordered` та позначається у `seen`.
-4. Повертається `ordered`.
-
-**Повертає:**
-
-- `string[]` — впорядкований масив унікальних id перевірок:
-  - **тільки** ті, що одночасно (а) мають programmatic-перевірку в пакеті і (б) представлені файлом `*.mdc` у `.cursor/rules/`;
-  - порядок диктується `mdcBasenames` (тобто реальним порядком файлів у директорії, як його передав викликач);
-  - кожен id зустрічається не більше одного разу.
-
-**Side effects:** немає. Функція pure, не читає диск, не мутує аргументи (`Set`/`Array` створюються локально).
-
-**Крайні випадки:**
-
-- Якщо `mdcBasenames` порожній — повертається `[]`.
-- Якщо жоден `id`, отриманий з імен `.mdc`, не присутній у `available` — повертається `[]` (типово для проєктів, де `.cursor/rules/` містить лише сторонні правила без programmatic-перевірок у пакеті).
-- Дублікати у `mdcBasenames` (наприклад, два файли, що дають один і той самий id після відсікання префікса) включаються лише один раз.
-
-## Залежності
-
-- **Зовнішні (npm/Node):** немає. Файл не використовує жодних імпортів — ні з Node core (`fs`, `path` тощо), ні з npm-пакетів.
-- **Внутрішні (проєкт):** немає прямих імпортів. Очікується, що:
-  - аргумент `available` формується сусіднім модулем `discover-checkable-rules.mjs` (експорт `discoverCheckableRules`);
-  - аргумент `mdcBasenames` формується викликачем читанням `.cursor/rules/` (через `fs.readdirSync`/`fs.promises.readdir` із подальшим фільтром `.endsWith('.mdc')` та сортуванням).
-
-Така архітектура свідомо відокремлює I/O від чистої логіки: цей модуль легко тестувати без файлової системи.
-
-## Потік виконання / Використання
-
-Типовий сценарій — `npx @nitra/cursor fix` без аргументів. CLI-входу потрібно вирішити, які id перевірок запустити за замовчуванням; для цього він:
-
-1. Отримує список програмно перевірюваних правил пакета (`available = discoverCheckableRules(...)`).
-2. Читає директорію `.cursor/rules/` поточного проєкту й відбирає файли з розширенням `.mdc` (`mdcBasenames`), сортує їх.
-3. Викликає `discoverCheckRulesFromCursorRules(available, mdcBasenames)` і отримує **підсумковий** список id.
-4. Для кожного id послідовно запускає команду `check <id>` (наприклад, через `run-rule-cli.mjs`).
-
-Приклад інлайн-використання (псевдокод викликача):
-
-```js
-import { readdirSync } from 'node:fs'
-import { discoverCheckableRules } from './discover-checkable-rules.mjs'
-import { discoverCheckRulesFromCursorRules } from './discover-check-rules-from-cursor.mjs'
-
-const available = discoverCheckableRules(/* … */)
-const mdcBasenames = readdirSync('.cursor/rules')
-  .filter(f => f.endsWith('.mdc'))
-  .sort()
-const idsToRun = discoverCheckRulesFromCursorRules(available, mdcBasenames)
-// idsToRun: наприклад, ['adr', 'bun', 'ci4', 'text', 'vue']
-```
-
-Приклад трансформації імен:
-
-| Файл у `.cursor/rules/`    | id після `mdcBasenameToCheckId` | Потрапляє у результат?                             |
-| -------------------------- | ------------------------------- | -------------------------------------------------- |
-| `n-bun.mdc`                | `bun`                           | Так, якщо `available.includes('bun')`              |
-| `n-vue.mdc`                | `vue`                           | Так, якщо `available.includes('vue')`              |
-| `my-rule.mdc`              | `my-rule`                       | Лише якщо пакет реєструє `my-rule` як перевірюване |
-| `.cursor/rules/n-text.mdc` | `text`                          | Так, якщо `available.includes('text')`             |
-| `n-bun.mdc` (двічі)        | `bun`                           | У результаті — один раз                            |
-
-Таким чином модуль є тонким, але критичним «клейовим» шаром між:
-
-- **диском проєкту** (що користувач реально хоче перевіряти, судячи з вмісту `.cursor/rules/`)
-- **реєстром пакета** (що пакет фізично вміє перевіряти автоматично).
-
-Файл свідомо тримається без I/O і без зовнішніх залежностей, щоб залишатись повністю детермінованим і легко покритим юніт-тестами (див. сусідню директорію `tests/`).
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/scripts/lib/docs/rule-predicates.md

@@ -1,30 +1,33 @@
+---
+docgen:
+  source: npm/scripts/lib/rule-predicates.mjs
+  crc: 71fba574
+  score: 95
+---
+
 # rule-predicates.mjs
 
 ## Огляд
 
-Цей файл містить набір предикатів, які використовуються для автоматичного визначення правил. Ці предикати дозволяють перевіряти наявність файлів, вміст source-коду та інформацію з репозиторіїв, щоб виявляти потенційні порушення правил. Він забезпечує механізм для автоматизованого пошуку та виявлення правил на основі даних.
+Реєстр незводимих до даних предикатів для автодетекту правил. Предикати використовують наявність файлів або вмісту для визначення умов. Умови, що вимагають парсингу залежностей чи сканування вмісту, читають дані з різних джерел. Виклик диспетчується через `auto-rules.mjs` за іменем предиката.
 
 ## Поведінка
 
-1.  **Ініціалізація перевірки репозиторію:** Отримує URL репозиторію з кореневого `package.json` або з `meta.json.repository`. Перевіряє, чи URL існує і чи містить він вказаний маркер.
-2.  **Перевірка залежностей у дереві:** Для кожного `package.json` у дереві репозиторію, перебирає всі пакети в залежностях. Якщо пакет має вказаний маркер, повертає `true`. Ігнорує директорії `node_modules`, `.git`, `.next` та `.turbo`.
-3.  **Перевірка вкладених `package.json`:** Для кореневого `package.json` перевіряє, чи є в будь-якому вкладеному `package.json` відсутній `vite` у секції `devDependencies`. Ігнорує директорії `node_modules`, `.git`, `.next` та `.turbo`.
-4.  **Перевірка фактів:** Якщо надано факти, перевіряє наявність `hasGqlTaggedTemplates` та `hasHasuraConfig`. Якщо `hasGqlTaggedTemplates` має значення `true`, повертає `true`. Якщо `hasHasuraConfig` має значення `true`, повертає `true`.
-5.  **Перевірка наявності `bun`:** Якщо надано факти, перевіряє наявність `hasBunSqlImport`. Якщо `hasBunSqlImport` має значення `true`, повертає `true`.
-6.  **Перевірка залежностей `pg`:** Якщо надано факти, перевіряє наявність `pg`, `pg-format` або `mysql2` у залежностях. Якщо будь-яка з цих залежностей присутня, повертає `true`.
-7.  **Перевірка вкладеного `package.json` без `vite`:** Отримує кореневий `package.json`. Перебирає всі вкладені `package.json` (крім кореневого). Якщо вкладений `package.json` не містить `vite` у `devDependencies`, повер
+1. repoUrlMarker: Перевіряє, чи містить URL репозиторію вказаний маркер.
+2. depInAnyPackageJson: Перевіряє наявність пакетів у залежностях.
+3. gqlTaggedTemplate: Перевіряє наявність літерала gql.
+4. hasuraConfigMarker: Перевіряє наявність маркера в конфігурації.yaml.
+5. jsBunDbSignal: Перевіряє наявність залежностей або імпорту SQL з Bun.
+6. nestedPackageWithoutVite: Перевіряє наявність пропущеного пакету у devDependencies.
 
 ## Публічний API
 
-RULE_PREDICATES — Зберігає предикати та їх реалізації. Використовується для виклику через `meta.json.auto.predicate`.
+RULE_PREDICATES — Реєстр предикатів: імʼя → реалізація. Виклик за `meta.json.auto.predicate`.
 
 ## Гарантії поведінки
 
-- Функція повертає результат виконання предиката.
-- Результат може бути істинним або хибним.
-- При виникненні помилки, результат завжди хибний.
-- Не враховує наявність `.git` та `node_modules` у файловій системі.
-- Не використовує кешування.
-- Не генерує винятків.
-- Аргументи предиката можуть бути значеннями, отриманими з файлів `meta.json`, шляхів у файловій системі або URL-адрес.
-- Результат залежить від вмісту та структури зазначених джерел.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.
+- Не звертається до мережі.

package/scripts/lib/docs/run-rule-cli.md

@@ -1,33 +1,29 @@
 ---
 docgen:
   source: npm/scripts/lib/run-rule-cli.mjs
-  crc: ab1715f2
+  crc: 21a7b19a
+  score: 100
 ---
 
 # run-rule-cli.mjs
 
 ## Огляд
 
-Цей файл є самостійним CLI-запускомком для правила, який дозволяє запускати правила з файлів `.n-cursor.json` та виконувати їхні дії. Він забезпечує інтеграцію з інструментом `cursor`, імітуючи старий `npx @nitra/cursor fix <id>`. Файл виконує перевірку whitelist, генерує summary та повертає агрегований код виходу.
+Файл є автономним CLI-запускачем для одного правила. Він читає конфігурацію з `.n-cursor.json`, перевіряє, чи існує запис для заданого ID у конфігурації, друкує звіт про перевірку та повертає агрегований код виходу.
 
 ## Поведінка
 
-1.  Визначає ID правила на основі шляху директорії правила.
-2.  Зчитує конфігурацію з файлу `.n-cursor.json`.
-3.  Перевіряє, чи правило включено в конфігурації. Якщо ні, пропускає перевірку та повертає код успіху (0).
-4.  Виводить інформаційне повідомлення про початок перевірки правила.
-5.  Створює або отримує кеш для обходу файлової структури.
-6.  Запускає стандартний процес перевірки правила, передаючи кеш.
-7.  Отримує код завершення процесу перевірки правила.
-8.  Виводить підсумковий результат перевірки (успіх або невдача).
-9.  Повертає код завершення процесу перевірки правила.
+1.  Викликається для запуску правила.
+2.  Читає конфігурацію з `.n-cursor.json`.
+3.  Перевіряє наявність правила у whitelist.
+4.  Якщо правило не дозволено, друкує повідомлення про пропуск.
+5.  Якщо правило дозволено, друкує повідомлення про перевірку правила.
+6.  Використовує кеш для перевірки.
+7.  Викликає функцію для виконання стандартного правила з кешем.
+8.  Повертає агрегований код виходу.
 
 ## Гарантії поведінки
 
-- Запускає правило з файлу `fix.mjs`.
-- Читає файл `.n-cursor.json` для конфігурації правила.
-- Перевіряє, чи правило включено в whitelist.
-- Виводить підсумкову інформацію про результат виконання.
-- Повертає код завершення, що відображає загальний статус виконання.
-- Кешує результати для уникнення повторного виконання, поки не змінено конфігурацію або не було перезапущено.
-- Не здійснює жодних мережевих запитів.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/scripts/lib/docs/run-rule.md

@@ -1,38 +1,31 @@
 ---
 docgen:
   source: npm/scripts/lib/run-rule.mjs
-  crc: 94f3ac44
+  crc: 27060842
+  score: 95
 ---
 
 # run-rule.mjs
 
 ## Огляд
 
-Цей файл є оркестратором правил, що запускається з командного рядка. Він застосовує правила, визначаючи та виконуючи концерни, а також політичні концерни, використовуючи кешування для підвищення ефективності. Файл забезпечує централізований спосіб виконання правил та збору результатів.
+Файл слугує оркестратором правила. Він координує виконання перевірок, включаючи перевірку гейту, JS-концернів та policy-концернів.
 
 ## Поведінка
 
-- `runTemplateSubsetConcern`: Перевіряє файл-концерт за допомогою шаблону, повертаючи 0, якщо все ОК, або 1, якщо є порушення.
-- `evaluateAppliesGate`: Викликає функцію `applies` з `js/applies.mjs`, якщо вона існує та повертає `true`.
-- `runPolicyConcern`: Запускає policy-концерт через `runConftestBatch`, повертаючи 0, якщо все ОК, або 1, якщо є порушення.
-- `runRule`: Оркеструє правила, викликаючи `evaluateAppliesGate`, JS-концерни та policy-концерни, об'єднуючи exit-коди.
+runTemplateSubsetConcern
+Перевіряє відповідність фактичного файлу канонічному шаблону.
+
+runRule
+Оркеструє виконання правила, включаючи перевірку гейту, JS-концернів та policy-концернів.
 
 ## Публічний API
 
-- runTemplateSubsetConcern — Перевірка відповідності шаблонів: порівнює конфігурацію шаблонів з фактичним файлом, забезпечуючи дотримання правил.
-- runRule — Запуск правила: виконує послідовність дій, включаючи перевірку концернів, і застосовує політику.
+- runTemplateSubsetConcern — Snippet-driven перевірка концерну (`target.json:"check":"template"`): звіряє канон з фактичним файлом за допомогою глибокого підмножинного перевірки. Усі канонічні поля/елементи обов'язкові, зайві дозволені. Масиви співпадають за наявністю (незалежно від порядку). Зміна сніпета негайно впливає на примусовість.
+- runRule — Запускає одне правило: applies-гейт → JS-концерни → policy-концерни.
 
 ## Гарантії поведінки
 
-- `applies-гейт` викликає `applies` з `js/applies.mjs`.
-- `applies` повертає `false` — виводить `✅ правило не застосовне` і завершує.
-- `JS-концерни` викликають `applies` після `applies-гейт`.
-- `JS-концерни` можуть викликати `check` для виведення контексту.
-- `Policy-концерни` викликають `runConftestBatch`.
-- `resolveTargetFiles` кешує результати `walkCache` між `JS-концернами`.
-- `createCheckReporter` у `Policy-концерни` OR-ює exit-коди.
-- Exit-код правила — 0 або 1.
-- `runTemplateSubsetConcern` запускає підмножину шаблонів.
-- `runRule` запускає правило.
-- Кеш використовується для зберігання результатів `resolveTargetFiles` у межах прогону.
-- Немає взаємодії з мережею.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/scripts/lib/docs/run-standard-rule.md

@@ -1,30 +1,27 @@
 ---
 docgen:
   source: npm/scripts/lib/run-standard-rule.mjs
-  crc: aeb5299a
+  crc: c1ae8f0e
+  score: 90
 ---
 
 # run-standard-rule.mjs
 
 ## Огляд
 
-Цей файл забезпечує публічний інтерфейс для оркестрування правил. Він обігріває виклик `discoverOneRule` до виконання правил, керуючи їхнім виконанням на основі контексту та політики. Це централізована точка інтеграції для запуску правил, забезпечуючи дедуплікацію та кешування для оптимізації продуктивності.
+Файл інкапсулює оркестрацію виконання правил. Він забезпечує запуск правила через визначений шлях, ізолюючи його виконання у блоці `withLock` для уникнення паралельних запусків.
 
 ## Поведінка
 
-1.  Отримує шлях до директорії правила.
-2.  Визначає ідентифікатор правила з назви директорії.
-3.  Отримує дані правила з директорії правила.
-4.  Отримує або створює кеш для прогону.
-5.  Запускає виконання правила, використовуючи отримані дані та кеш.
-6.  Забезпечує унікальний лок для паралельного запуску правила.
-7.  Повертає код успіху (0) або код помилки (1) в залежності від результатів виконання правила.
+1.  Отримання шляху до правила
+2.  Визначення ідентифікатора правила
+3.  Охоплення виконання у блоці блокування
+4.  Пошук правила
+5.  Отримання кешу проходу
+6.  Запуск виконання правила
 
 ## Гарантії поведінки
 
-- Виконання правил інкапсулює логіку `discoverOneRule` та `runRule`.
-- Виконання правил відбувається всередині блоку `withLock`.
-- Виконання правил дедублюється на основі стану git-дерева.
-- Різні правила можуть виконуватися паралельно.
-- Кеш використовується для зберігання результатів виконання правил в межах одного прогону.
-- Не допускається локальна логіка всередині правил. Розширення поведінки реалізується через опції контексту.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/scripts/lib/docs/sync-gitignore-worktree.md

@@ -1,31 +1,28 @@
+---
+docgen:
+  source: npm/scripts/lib/sync-gitignore-worktree.mjs
+  crc: e691c42b
+  score: 95
+---
+
 # sync-gitignore-worktree.mjs
 
 ## Огляд
 
-Файл забезпечує, що кореневий `.gitignore` проєкту ігнорує локальні git-worktree. Він гарантує, що всі артефакти, пов'язані з worktree, правильно включені в `.gitignore`, забезпечуючи консистентність та уникнення непередбачуваних проблем. Це ключовий компонент системи завжди-активного flow/worktree-tooling.
+syncGitignoreWorktree
+Додає запис `.worktrees/` до кореневого `.gitignore`. Функція викликається для синхронізації локальних git-worktree з конфігурацією. Функція приймає шлях до кореня проєкту-споживача. Функція повертає результат, що вказує на успішність запису.
 
 ## Поведінка
 
-1.  Визначає корінь проєкту.
-2.  Перевіряє наявність в кореневому файлі `.gitignore` запису, що відповідає каталогу `.worktrees/`.
-3.  Якщо запису немає, викликає утиліту для додавання запису `.worktrees/` до `.gitignore`.
-4.  Утиліта додає запис, якщо його ще немає, інакше не робить нічого.
-5.  Повертає значення `true`, якщо запис було додано, інакше `false`.
+1. Виклик функції для додавання запису `.worktrees/` до кореневого `.gitignore`.
+2. Передача шляху до кореня проєкту-споживача.
+3. Повернення результату, що вказує на успішність запису.
 
 ## Публічний API
 
-syncGitignoreWorktree — Синхронізує файл `.gitignore` в каталозі `worktrees` з кореневим файлом `.gitignore`.
+syncGitignoreWorktree — Додає `.worktrees/` до `.gitignore` у кореневому файлі.
 
 ## Гарантії поведінки
 
-- Гарантує, що кореневий `.gitignore` проєкту ігнорує локальні git-worktree (`.worktrees/`).
-- Викликається з дефолтного sync (`npx \@nitra/cursor`) окремим top-level кроком.
-- Не викликається в контексті `syncClaudeConfig`.
-- `.worktrees/` є артефактом завжди-активного flow/worktree-tooling.
-- Один запис `.worktrees/` покриває каталог worktree та всі sibling-файли в ньому.
-- Запис безумовний, без гейта за `.n-cursor.json`-правилами.
-- Продюсер артефактів — завжди-активний flow.
-- Делегує наявній idempotent+append-only утиліті `ensureGitignoreEntries`.
-- `ensureGitignoreEntries` не перезаписує/не видаляє наявні рядки.
-- `ensureGitignoreEntries` створює `.gitignore`, якщо нема.
-- Не використовує кешування.
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

package/scripts/lib/rule-predicates.mjs

@@ -21,7 +21,7 @@ const IGNORED_DIR_NAMES = new Set(['node_modules', '.git', '.next', '.turbo'])
  * @param {string[]} keys імена пакетів
  * @returns {Promise<boolean>} true, якщо знайдено хоч один
  */
-async function anyDepInTree(root, keys) {
+function anyDepInTree(root, keys) {
   const wanted = new Set(keys)
   /**
    * Чи package.json за `abs` оголошує будь-який пакет із `wanted` у `dependencies`.

package/scripts/sync-claude-config.mjs

@@ -33,7 +33,9 @@ import { join } from 'node:path'
 /** Маркер PostToolUse fix-hook'а (`npx --no \@nitra/cursor post-tool-use-fix`). */
 export const MANAGED_HOOK_COMMAND_MARKER = '@nitra/cursor post-tool-use-fix'
 /** Маркер doc-files staleness-hook'ів (PostToolUse `--hook` і Stop-гейт `--git`). */
-export const DOC_FILES_HOOK_COMMAND_MARKER = '@nitra/cursor doc-files check'
+export const DOC_FILES_HOOK_COMMAND_MARKER = '@nitra/cursor lint-doc-files'
+/** Legacy-маркер старих doc-files hook'ів (`doc-files check`) — cleanup при ресинку наявних інсталяцій. */
+export const LEGACY_DOC_FILES_HOOK_COMMAND_MARKER = '@nitra/cursor doc-files check'
 /** Legacy-маркер старого Stop-hook'а — лишаємо для cleanup-у при оновленні існуючих інсталяцій. */
 export const LEGACY_STOP_HOOK_COMMAND_MARKER = '@nitra/cursor stop-hook'
 /** Маркер ADR Stop-hook'а — підрядок шляху до bash-скрипта capture-decisions. */
@@ -51,6 +53,7 @@ export const CURSOR_ADR_NORMALIZE_HOOK_COMMAND_MARKER = '.claude/hooks/normalize
 export const MANAGED_HOOK_COMMAND_MARKERS = Object.freeze([
   MANAGED_HOOK_COMMAND_MARKER,
   DOC_FILES_HOOK_COMMAND_MARKER,
+  LEGACY_DOC_FILES_HOOK_COMMAND_MARKER,
   LEGACY_STOP_HOOK_COMMAND_MARKER,
   ADR_HOOK_COMMAND_MARKER,
   ADR_NORMALIZE_HOOK_COMMAND_MARKER

package/scripts/utils/docs/with-lock.md

@@ -1,25 +1,32 @@
+---
+docgen:
+  source: npm/scripts/utils/with-lock.mjs
+  crc: 21848085
+  score: 95
+---
+
 # with-lock.mjs
 
 ## Огляд
 
-Цей файл реалізує механізм захисту від одночасного виконання критичних операцій, забезпечуючи атомарний lock та дедуплікацію даних для інтенсивних команд. Він використовується для запобігання конфліктів при одночасному виконанні операцій, які можуть призвести до пошкодження даних або непередбачуваних результатів. Механізм гарантує, що кожен прогін операцій виконується без повторень та з атомарним lock.
+Файл реалізує механізм захисту важких команд через атомарне блокування та унікалізацію результатів. Функції дозволяють перевіряти можливість повторного використання результату з кешу та виконувати команду через серіалізований механізм. Механізм використовує `mkdirSync-based lock` та `sha256-dedup` з TTL.
 
 ## Поведінка
 
-- `shouldDedup`: Перевіряє, чи можна повторно використати кешований результат, враховуючи код виходу, відбитковий дерева та час завершення.
-- `withLock`: Встановлює lock-директорію, запускає вказану функцію, кешує результат та повторно використовує його, якщо можливо, з використанням дедуплікації за відбитком.
+shouldDedup
+Перевіряє можливість повторного використання результату з кешу.
+
+withLock
+Серіалізує важку команду через атомарний lock та dedup.
 
 ## Публічний API
 
-- shouldDedup — Перевіряє, чи можна використовувати попередньо обчислену відповідь для уникнення повторних обчислень.
-- withLock — Забезпечує унікальність виконання важкої операції за допомогою блокування та перевірки на основі відбитків.
+shouldDedup — Чи можна пропустити повторний прогін за кешованим result.json.
+withLock — Серіалізує важку команду через атомарний lock і dedup за fingerprint.
 
 ## Гарантії поведінки
 
-- **Атомарність:** Операції lock та dedup виконуються як атомарні дії.
-- **Захист від помилок:** У разі виникнення помилки, функція повертає `false` та `null`.
-- **Детектування неактивного PID:** Перевіряється, чи процес, що утримує lock, все ще активний.
-- **Дедуплікація з обмеженням часу:** Проводиться дедуплікація за допомогою SHA256 з обмеженням часу (TTL).
-- **Кешування:** Результати прогону кешуються для прискорення наступних проходів.
-- **Відсутність винятків:** Функції не викликають винятків.
-- **Створення директорій:** Використовується `mkdirSync` для створення директорій.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Кешує результати в межах одного прогону.
+- Не звертається до мережі.

package/scripts/utils/with-lock.mjs

@@ -126,9 +126,11 @@ export async function withLock(key, runFn, opts = {}) {
     /* result.json не існує або пошкоджений */
   }
 
-  const onSignal = () => {
+  // Після release лок ре-рейзиться той самий сигнал: `once` вже зняв обробник,
+  // тож процес завершується дефолтною дією з коректним кодом (130/143)
+  const onSignal = signal => {
     release()
-    process.exit(130)
+    process.kill(process.pid, signal)
   }
   process.once('SIGINT', onSignal)
   process.once('SIGTERM', onSignal)

package/skills/doc-aggregate/SKILL.md

@@ -29,10 +29,10 @@ Tier 3 — **один** субагент-синтезатор після зав
 - Файлові доки мають бути свіжі. Перевір і за потреби онови перед агрегацією:
 
 ```bash
-npx @nitra/cursor doc-files check --git
+npx @nitra/cursor lint-doc-files --git
 ```
 
-Якщо багато застарілих — спершу прожени `npx @nitra/cursor doc-files gen`.
+Якщо багато застарілих — спершу прожени `npx @nitra/cursor fix-doc-files`.
 
 ## Крок 1: Tier 2 — module-summary
 

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

@@ -1,9 +1,9 @@
 /**
- * Re-export спільного списку ignore-глобів зі скіла doc-files.
+ * Re-export спільного списку ignore-глобів із правила doc-files.
  *
- * Канонічне джерело — `npm/skills/doc-files/js/docgen-ignore.mjs`: обидва скіли
- * (file-level доки і агрегати) мусять бачити однакове дерево кодових файлів,
- * інакше агрегат посилатиметься на файли без док (або навпаки). Залежність
- * спрямована doc-aggregate → doc-files за ADR про розбиття docgen.
+ * Канонічне джерело — `npm/rules/doc-files/js/docgen-ignore.mjs`: скіл doc-aggregate
+ * і правило doc-files мусять бачити однакове дерево кодових файлів, інакше агрегат
+ * посилатиметься на файли без док (або навпаки). Залежність спрямована
+ * doc-aggregate → doc-files за ADR про розбиття docgen.
  */
-export * from '../../doc-files/js/docgen-ignore.mjs'
+export * from '../../../rules/doc-files/js/docgen-ignore.mjs'

package/skills/doc-aggregate/js/docs/docgen-ignore.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/skills/doc-aggregate/js/docgen-ignore.mjs
-  crc: 8821af65
+  crc: 5faaffd0
 ---
 
 # docgen-ignore