@nitra/cursor 12.8.5 → 12.8.7

package/scripts/auto-rules.mjs

@@ -1,7 +1,7 @@
 /**
- * Автовизначення правил для `.n-cursor.json` за meta-даними з `npm/rules/<id>/meta.json`.
+ * Автовизначення правил для `.n-cursor.json` за meta-даними з `npm/rules/<id>/main.json`.
  *
- * Основна роль: `discoverRuleAutoActivation` читає `npm/rules/<id>/meta.json`, виводить
+ * Основна роль: `discoverRuleAutoActivation` читає `npm/rules/<id>/main.json`, виводить
  * `AUTO_RULE_ORDER` (алфавітно) і `AUTO_RULE_DEPENDENCIES` з meta, а потім для кожного правила
  * обчислює spec активації через `specMatches`: `always` — безумовно; `glob` — перевірка
  * файлів через `globToRegex`; `predicate` — незводимий предикат із реєстру `RULE_PREDICATES`
@@ -11,7 +11,7 @@
  *
  * Враховує винятки `disable-rules`: елементи зі списку не додаються автоматично.
  *
- * Автодетект скілів — у `./auto-skills.mjs` (умови — у `npm/skills/<skill>/meta.json`).
+ * Автодетект скілів — у `./auto-skills.mjs` (умови — у `npm/skills/<skill>/main.json`).
  * `mergeConfigWithAutoDetected` нижче приймає вже виявлені rules і skills і вливає
  * їх у конфіг із поправкою на legacy-id (`migrateRuleIds`).
  */
@@ -45,7 +45,7 @@ const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
 const RULES_DIR = join(PACKAGE_ROOT, 'rules')
 
 /**
- * Скан `npm/rules/<id>/meta.json` → мапа id → RuleAutoSpec (лише правила з розпізнаним auto).
+ * Скан `npm/rules/<id>/main.json` → мапа id → RuleAutoSpec (лише правила з розпізнаним auto).
  * @param {string} [rulesDir] override для тестів
  * @returns {Record<string, import('./lib/rule-meta.mjs').RuleAutoSpec>} мапа автоактивації
  */
@@ -205,7 +205,7 @@ async function processFileEntry(absPath, root, facts) {
  * Обходить дерево проєкту, збираючи content-факти для предикатів автоувімкнення.
  *
  * `hasRegoFile` і `hasTempoDir` лишаються для зворотної сумісності з прямими читачами
- * фактів (тести, зовнішній код); саме автоувімкнення тепер data-driven через meta.json.
+ * фактів (тести, зовнішній код); саме автоувімкнення тепер data-driven через main.json.
  * @param {string} root абсолютний шлях кореня репозиторію
  * @returns {Promise<{
  *   hasBunSqlImport: boolean,
@@ -350,7 +350,7 @@ function specMatches(spec, ctx) {
 }
 
 /**
- * Визначає авто-правила згідно з `rules/<rule>/meta.json`.
+ * Визначає авто-правила згідно з `rules/<rule>/main.json`.
  * @param {object} params параметри аналізу
  * @param {string} params.root абсолютний шлях до кореня репозиторію
  * @param {string[]} params.availableRules перелік доступних правил з пакету

package/scripts/auto-skills.mjs

@@ -1,7 +1,7 @@
 /**
- * Автовизначення skills для `.n-cursor.json` за умовами з `npm/skills/<skill>/meta.json`.
+ * Автовизначення skills для `.n-cursor.json` за умовами з `npm/skills/<skill>/main.json`.
  *
- * `meta.json` — джерело правди (а не hardcoded мапа). Підтримуються три варіанти:
+ * `main.json` — джерело правди (а не hardcoded мапа). Підтримуються три варіанти:
  *
  *  - `auto: "завжди"` — скіл активується незалежно від інших правил
  *    (приклади: `fix`, `lint`, `llm-patch`, `publish-telegram`).
@@ -26,7 +26,7 @@ const SKILLS_DIR = join(PACKAGE_ROOT, 'skills')
  */
 
 /**
- * Сканує `npm/skills/<id>/meta.json`. Скіли без `meta.json` або без розпізнаного
+ * Сканує `npm/skills/<id>/main.json`. Скіли без `main.json` або без розпізнаного
  * `auto` не потрапляють у результат — їх вмикають лише вручну в конфізі.
  * @param {string} [skillsDir] override для тестів
  * @returns {Record<string, SkillAutoSpec>} мапа `skillId → spec`

package/scripts/docs/auto-rules.md

@@ -3,48 +3,34 @@ type: JS Module
 title: auto-rules.mjs
 resource: npm/scripts/auto-rules.mjs
 docgen:
-  crc: d50b922f
+  crc: ba75c709
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 90
 ---
 
-Файл читає метадані з `npm/rules/<id>/meta.json` для автоматичного визначення порядку та залежностей правил. Він обчислює spec активації для кожного правила, використовуючи дані з `RULE_PREDICATES` з `lib/rule-predicates.mjs`, визначає активні правила, обчислює залежності та об'єднує конфігурацію з виявленими правилами та поправками на legacy-id. Код спирається на конфіги `.n-cursor.json`, `meta.json` та `package.json`.
+## Огляд
 
-## Поведінка
-
-discoverRuleAutoActivation
-Читає meta-дані з файлів npm/rules/<id>/meta.json для визначення автоактивації правил.
-
-AUTO_RULE_ORDER
-Повертає алфавітний порядок для правил.
+Автоматично визначає правила та скіли для конфігурації `.n-cursor.json`, скануючи мета-дані з `npm/rules/<id>/main.json` та аналізуючи структуру проєкту, зокрема `package.json`. Система виводить `AUTO_RULE_ORDER` (алфавітно) та `AUTO_RULE_DEPENDENCIES` для кожного правила. Для кожного правила обчислюється специфікація активації (`specMatches`), яка може бути безумовною (`always`), заснованою на шаблонах файлів (`glob`), або предикатною. Процес враховує винятки (`disable-rules`) та виконує транзитивне розгортання залежностей. Збираються контент-факти (GQL, bun-sql, hasura) для точного застосування правил. Також відбувається автоматичне виявлення скілів з `./auto-skills.mjs`, після чого всі виявлені правила та скіли зливаються у конфіг, враховуючи міграцію ID.
 
-AUTO_RULE_DEPENDENCIES
-Повертає граф залежностей між правилами.
-
-collectAutoRuleFacts
-Збирає контент-факти для предикатів, включаючи сканування GQL, Bun SQL та налаштувань Hasura.
-
-detectAutoRules
-Визначає активні правила на основі spec, перевіряючи їх проти згенерованих фактів.
+## Поведінка
 
-mergeConfigWithAutoDetected
-Доповнює конфігурацію, додаючи визначені автоправила та налаштування, з урахуванням legacy-ID; за наявності `availableRules`/`availableSkills` ще й відсіює з `rules`/`skills` неактуальні id, яких немає у пакеті (повертає їх у полі `pruned`).
+discoverRuleAutoActivation сканує директорію `rules` та виявляє мета-дані для автоматичного визначення правил.
+AUTO_RULE_ORDER надає стабільний алфавітний порядок для всіх правил, виявлених під час автоматичного визначення.
+AUTO_RULE_DEPENDENCIES визначає транзитивні залежності між правилами, виявленими під час автоматичного визначення.
+collectAutoRuleFacts обходить дерево проєкту, збираючи контент-факти про наявність певних структур (наприклад, GQL, Hasura, Rego).
+detectAutoRules визначає список правил, які мають бути активні, на основі мета-даних правил та зібраних контент-фактів, враховуючи виключення.
+mergeConfigWithAutoDetected об'єднує конфігурацію користувача з результатами автоматичного визначення правил та скілів, прибираючи з конфігу ті елементи, яких більше немає у пакеті.
 
 ## Публічний API
 
-discoverRuleAutoActivation — Скан `npm/rules/<id>/meta.json` → мапа id → RuleAutoSpec (лише правила з розпізнаним auto).
-AUTO_RULE_ORDER — Стабільний алфавітний порядок (замість хардкод-масиву).
-AUTO_RULE_DEPENDENCIES — Граф залежностей із meta (Type C) — замість хардкод-константи.
-collectAutoRuleFacts — Обходить дерево проєкту, збираючи content-факти для предикатів автоувімкнення.
-hasRegoFile — Флаг наявності файлу Rego.
-hasTempoDir — Флаг наявності директорії Tempo.
-hasBunSqlImport — Булеве значення про імпорт BunSQL.
-hasGqlTaggedTemplates — Булеве значення про наявність GQL-тегів.
-hasHasuraConfig — Булеве значення про конфігурацію Hasura.
+discoverRuleAutoActivation — Зчитує `main.json` для кожного правила у `npm/rules/<id>/` та створює список правил, які можуть активуватися автоматично.
+AUTO_RULE_ORDER — Визначає порядок застосування автоматичних правил за алфавітом.
+AUTO_RULE_DEPENDENCIES — Створює граф залежностей між автоматичними правилами, використовуючи метадані.
+collectAutoRuleFacts — Сканує структуру проєкту та збирає факти про вміст, необхідні для визначення, які автоматичні правила активувати.
+detectAutoRules — Визначає, які автоматичні правила доступні на основі файлу `main.json` кожного правила.
+mergeConfigWithAutoDetected — Обновлює конфігурацію, додаючи автоматично виявлені правила, і очищає список доступних правил/навичок від тих, що більше не існують у пакеті, фіксуючи видалені ID у полі `pruned`.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Свідомо пропускає шляхи: `.git`, `node_modules`.
-- Не звертається до мережі.

package/scripts/docs/auto-skills.md

@@ -3,175 +3,30 @@ type: JS Module
 title: auto-skills.mjs
 resource: npm/scripts/auto-skills.mjs
 docgen:
-  crc: 44328898
+  crc: 374d78b5
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Модуль `npm/scripts/auto-skills.mjs` відповідає за **автовизначення (auto-activation) скілів** для файлу конфігурації `.n-cursor.json`. Він сканує директорію `npm/skills/` і для кожного скілу читає його `meta.json`, щоб визначити, чи має скіл активуватися автоматично — завжди або лише за наявності певних виявлених auto-правил (rules).
+## Огляд
 
-Ключова ідея модуля: **`meta.json` — єдине джерело правди**. У коді немає жорстко прописаної мапи відповідностей між скілами та правилами; усе зчитується з метаданих скіла. Раніше використовувався hardcoded `AUTO_SKILL_ORDER`, тепер він обчислюється динамічно — експорт залишено для зворотної сумісності.
+Визначає, які скіли мають автоматично активуватися, скануючи `npm/skills/` та аналізуючи `main.json` кожного скілу. Логіка активації базується на конфігурації скілу: скіл може активуватися завжди (`auto: "завжди"`), якщо всі перелічені правила виявлені (`auto: ["rule", …]`), або бути opt-in, якщо поле `auto` відсутнє у `main.json`. Це забезпечує, що визначення автоматичної активації скілів є детермінованим, оскільки `main.json` є джерелом правди. Результати сканування використовуються для встановлення `AUTO_SKILL_ORDER` та `AUTO_SKILL_RULE_DEPENDENCIES`, що впливає на роботу з `.n-cursor.json`.
 
-Підтримуються три формати поля `auto` у `meta.json`:
+## Поведінка
 
-- `auto: "завжди"` — скіл активується незавжди, незалежно від інших правил. Приклади за коментарями у файлі: `fix`, `lint`, `llm-patch`, `publish-telegram`.
-- `auto: ["rule", …]` — скіл активується, якщо **усі** перелічені правила вже виявлено auto-rules-модулем. Приклади за коментарями: `adr-normalize` залежить від `["adr"]`, `taze` — від `["bun"]`.
-- поле `auto` відсутнє або формат не розпізнано — скіл лише opt-in (тільки через `.n-cursor.json:skills`).
+discoverSkillAutoActivation сканує директорію `npm/skills/` і визначає специфікації автоматичної активації скілів на основі вмісту `main.json` кожного скілу.
+AUTO_SKILL_ORDER надає стабільний алфавітний порядок усіх скілів, які мають визначену автоматичну активацію.
+AUTO_SKILL_RULE_DEPENDENCIES надає мапу скілів, які залежать від певних правил, для забезпечення зворотної сумісності.
+detectAutoSkills визначає, які скіли мають бути автоматично активовані, порівнюючи доступні скіли з виявленими правилами та специфікаціями активації.
 
-Сканування `npm/skills/` виконується **синхронно під час завантаження модуля**: це дає детермінізм результату і узгоджується з sync-API сусіднього модуля `auto-rules.mjs`. Результат кешується на час життя процесу (`SKILL_AUTO_ACTIVATION`).
+## Публічний API
 
-## Експорти / API
+discoverSkillAutoActivation — Знаходить скіли, які мають файл `main.json` у відповідній директорії, і які мають автоматичну активацію.
+AUTO_SKILL_ORDER — Забезпечує фіксований алфавітний порядок скілів, що автоматично активуються, для підтримки старої версії.
+AUTO_SKILL_RULE_DEPENDENCIES — Створює список скілів, що автоматично активуються і мають визначені правила залежностей.
+detectAutoSkills — Виявляє скіли, які мають автоматичну активацію на основі вмісту файлу `auto.md` у директорії скілу.
 
-Модуль експортує:
+## Гарантії поведінки
 
-| Символ                                                                 | Тип                                           | Призначення                                                              |
-| ---------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------ |
-| `discoverSkillAutoActivation(skillsDir?)`                              | function                                      | Сканує директорію зі скілами та повертає мапу `skillId → SkillAutoSpec`. |
-| `AUTO_SKILL_ORDER`                                                     | `readonly string[]` (frozen)                  | Стабільний алфавітний список id скілів, які мають авто-активацію.        |
-| `AUTO_SKILL_RULE_DEPENDENCIES`                                         | `Readonly<Record<string, readonly string[]>>` | Лише ті скіли, у яких `auto: [rule, …]` — мапа `skillId → rules[]`.      |
-| `detectAutoSkills({ availableSkills, detectedRules, disableSkills? })` | function                                      | Обчислює фінальний список авто-скілів за станом середовища.              |
-
-Тип `SkillAutoSpec` (визначається JSDoc-typedef):
-
-```js
-/** @typedef {{ always: true } | { rules: readonly string[] }} SkillAutoSpec */
-```
-
-Тобто кожен скіл, що пройшов парсинг, або має `always: true`, або несе масив `rules`.
-
-## Функції
-
-### `discoverSkillAutoActivation(skillsDir = SKILLS_DIR)`
-
-**Сигнатура:**
-
-```js
-function discoverSkillAutoActivation(skillsDir?: string): Record<string, SkillAutoSpec>
-```
-
-**Параметри:**
-
-- `skillsDir` _(string, optional)_ — шлях до директорії зі скілами. За замовчуванням — `SKILLS_DIR = join(PACKAGE_ROOT, 'skills')`, де `PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))` (тобто корінь npm-пакету). Параметр існує для override у тестах.
-
-**Повертає:** `Record<string, SkillAutoSpec>` — мапа `skillId (== ім'я піддиректорії) → spec`.
-
-**Поведінка:**
-
-1. Якщо `skillsDir` не існує — повертається порожній обʼєкт `{}`.
-2. Інакше викликається `readdirSync(skillsDir, { withFileTypes: true })`.
-3. Для кожного запису:
-   - пропускаються файли (не директорії) та все, що починається з `.` (наприклад, приховані).
-   - читається `meta.json` через `readSkillMetaRaw(...)`; якщо raw-обʼєкт відсутній (`null`/`undefined`) — скіл пропускається.
-   - поле `raw.auto` пропускається через `parseSkillAutoSpec(...)`; якщо розпізнано — записується в `out[entry.name]`.
-4. Скіли без розпізнаного `auto` **не потрапляють у результат** — вони можуть бути ввімкнені лише вручну через `.n-cursor.json:skills`.
-
-**Side effects:** sync I/O — `existsSync`, `readdirSync`, читання `meta.json` усередині `readSkillMetaRaw`. Інших побічних ефектів немає.
-
-### `detectAutoSkills({ availableSkills, detectedRules, disableSkills })`
-
-**Сигнатура:**
-
-```js
-function detectAutoSkills(params: {
-  availableSkills: string[],
-  detectedRules: string[],
-  disableSkills?: string[],
-}): { skills: string[] }
-```
-
-**Параметри:**
-
-- `availableSkills` _(string[])_ — перелік id скілів, доступних у поточній збірці пакету (без префіксу `n-`). Будь-який скіл, який є в `SKILL_AUTO_ACTIVATION`, але відсутній у `availableSkills`, **не активується**.
-- `detectedRules` _(string[])_ — id правил, що їх виявив auto-rules-крок; використовується як множина "виявлених" залежностей для специфікацій `{ rules: [...] }`.
-- `disableSkills` _(string[], optional)_ — список id скілів із `.n-cursor.json` із прапором `disable-skills`. За замовчуванням — заморожений пустий масив `DEFAULT_DISABLED_LIST`.
-
-**Повертає:** `{ skills: string[] }` — список id активованих скілів у **стабільному алфавітному порядку** (через `AUTO_SKILL_ORDER.filter(...)`).
-
-**Алгоритм:**
-
-1. Нормалізує `availableSkills` у `Set` (lowercase, trim).
-2. Будує `Set` із `disableSkills` та `detectedRules`.
-3. Для кожної пари `[skillId, spec]` у `SKILL_AUTO_ACTIVATION`:
-   - якщо скіл не входить у `normalizedSkills` або входить у `disableSkillsSet` — пропуск.
-   - якщо `spec` має `always: true` **або** усі `spec.rules` присутні в `detectedRulesSet` — скіл додається до результуючого `detected`.
-4. Фінальний список будується через `AUTO_SKILL_ORDER.filter(id => detected.has(id))`, що гарантує детермінований алфавітний порядок та фільтрацію тільки тих id, які реально мають spec.
-
-**Side effects:** немає — функція чиста. Використовує тільки заздалегідь обчислений `SKILL_AUTO_ACTIVATION` і `AUTO_SKILL_ORDER`.
-
-## Внутрішні константи модуля
-
-- `PACKAGE_ROOT` — корінь npm-пакету: `dirname(dirname(fileURLToPath(import.meta.url)))`. Тобто два рівні вгору від `npm/scripts/auto-skills.mjs` → `npm/`.
-- `SKILLS_DIR` — `join(PACKAGE_ROOT, 'skills')`, тобто `npm/skills/`.
-- `SKILL_AUTO_ACTIVATION` — результат `discoverSkillAutoActivation()` під час імпорту модуля; кеш на час процесу.
-- `AUTO_SKILL_ORDER` — `Object.freeze(Object.keys(SKILL_AUTO_ACTIVATION).toSorted(localeCompare))`. Заморожений алфавітний список усіх скілів з auto-spec.
-- `AUTO_SKILL_RULE_DEPENDENCIES` — `Object.freeze(Object.fromEntries(...))`: похідна view, де лишаються тільки записи зі spec-формою `{ rules }`. Призначена для зворотної сумісності й для автодоку.
-- `DEFAULT_DISABLED_LIST` — `Object.freeze([])`, дефолтне значення для параметра `disableSkills`.
-
-## Залежності
-
-**Node.js стандартні модулі:**
-
-- `node:fs` — `existsSync`, `readdirSync` (синхронне сканування директорії).
-- `node:path` — `dirname`, `join`.
-- `node:url` — `fileURLToPath` (для отримання абсолютного шляху модуля з `import.meta.url`).
-
-**Локальні модулі:**
-
-- `./lib/skill-meta.mjs` — імпортуються:
-  - `readSkillMetaRaw(skillPath)` — читає сирий обʼєкт `meta.json` за шляхом до директорії скілу.
-  - `parseSkillAutoSpec(raw.auto)` — нормалізує значення `auto` у `SkillAutoSpec` (`{ always: true }`, `{ rules: [...] }` або `null`).
-
-**Файлова система (рантайм-залежності):**
-
-- Очікується наявність директорії `npm/skills/` із піддиректоріями `<skillId>/meta.json`. Відсутність директорії оброблена коректно (повертається `{}`).
-
-## Потік виконання / Використання
-
-### Завантаження модуля (init phase)
-
-1. `PACKAGE_ROOT` і `SKILLS_DIR` обчислюються на основі `import.meta.url`.
-2. Викликається `discoverSkillAutoActivation()` — це **синхронне** I/O під час імпорту: читається `npm/skills/`, з кожної піддиректорії — `meta.json`. Результат зберігається у `SKILL_AUTO_ACTIVATION`.
-3. `AUTO_SKILL_ORDER` і `AUTO_SKILL_RULE_DEPENDENCIES` похідні від цього кешу — обчислюються одноразово і заморожуються.
-
-### Виклик `detectAutoSkills` (runtime)
-
-Зазвичай викликається на етапі генерації / валідації `.n-cursor.json`. Послідовність:
-
-1. Зовнішній код визначає `availableSkills` (зі стану пакету / маніфесту) та `detectedRules` (через сусідній auto-rules pipeline).
-2. Опціонально передає `disableSkills` із конфігу користувача.
-3. Функція повертає `{ skills: [...] }` — фінальний відсортований список id, готовий до запису у конфіг.
-
-### Приклад використання
-
-```js
-import { detectAutoSkills, AUTO_SKILL_ORDER, AUTO_SKILL_RULE_DEPENDENCIES } from './auto-skills.mjs'
-
-const { skills } = detectAutoSkills({
-  availableSkills: ['fix', 'lint', 'adr-normalize', 'taze', 'publish-telegram'],
-  detectedRules: ['adr', 'bun'],
-  disableSkills: ['publish-telegram']
-})
-
-// skills буде у стабільному алфавітному порядку:
-// напр. ['adr-normalize', 'fix', 'lint', 'taze']
-// (publish-telegram вимкнено через disableSkills)
-```
-
-### Контракти й інваріанти
-
-- **Детермінізм:** порядок результату повністю визначається `AUTO_SKILL_ORDER`, який є `localeCompare`-сортованим snapshot-ом на момент імпорту.
-- **Безпека до відсутніх скілів:** скіли, доступні у `SKILL_AUTO_ACTIVATION`, але не присутні у `availableSkills`, ніколи не активуються.
-- **Кеш:** перечитати `npm/skills/` без перезавантаження модуля неможливо — функція `discoverSkillAutoActivation` тут лише для прямого виклику з тестів (передаючи інший `skillsDir`).
-- **Опт-аут:** `disableSkills` має пріоритет над `auto`-активацією.
-
-## Rebuild Test
-
-Уявімо, що файл загублено. За цим описом його можна відновити так:
-
-1. ESM-модуль із Node-імпортами `existsSync, readdirSync` із `node:fs`, `dirname, join` із `node:path`, `fileURLToPath` із `node:url`.
-2. Імпорт `parseSkillAutoSpec, readSkillMetaRaw` із `./lib/skill-meta.mjs`.
-3. Константи `PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))`, `SKILLS_DIR = join(PACKAGE_ROOT, 'skills')`.
-4. Експортована функція `discoverSkillAutoActivation(skillsDir = SKILLS_DIR)`: якщо `!existsSync(skillsDir)` → `{}`; інакше readdirSync з `withFileTypes`, ітерувати, пропускати не-директорії та `name.startsWith('.')`, читати `readSkillMetaRaw(join(skillsDir, entry.name))`, пропускати falsy, парсити `parseSkillAutoSpec(raw.auto)`, додавати в `out[entry.name]` тільки якщо парсер повернув spec.
-5. Константа модуля `SKILL_AUTO_ACTIVATION = discoverSkillAutoActivation()`.
-6. Експорт `AUTO_SKILL_ORDER = Object.freeze(Object.keys(SKILL_AUTO_ACTIVATION).toSorted((a,b) => a.localeCompare(b)))`.
-7. Експорт `AUTO_SKILL_RULE_DEPENDENCIES = Object.freeze(Object.fromEntries(Object.entries(SKILL_AUTO_ACTIVATION).filter(([, spec]) => 'rules' in spec).map(([id, spec]) => [id, spec.rules])))`.
-8. Константа `DEFAULT_DISABLED_LIST = Object.freeze([])`.
-9. Експортована функція `detectAutoSkills({ availableSkills, detectedRules, disableSkills = DEFAULT_DISABLED_LIST })`: побудувати `normalizedSkills = new Set(availableSkills.map(s => s.trim().toLowerCase()))`, `disableSkillsSet`, `detectedRulesSet`; пройти `Object.entries(SKILL_AUTO_ACTIVATION)`, пропустити коли скіл не у `normalizedSkills` або у `disableSkillsSet`, інакше додати до `detected` якщо `'always' in spec` або `spec.rules.every(d => detectedRulesSet.has(d))`; повернути `{ skills: AUTO_SKILL_ORDER.filter(id => detected.has(id)) }`.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/scripts/docs/index.md

@@ -6,20 +6,20 @@ resource: npm/scripts/
 
 # npm/scripts
 
-| Файл | Тип |
-|---|---|
-| [auto-rules.mjs](auto-rules.md) | JS Module |
-| [auto-skills.mjs](auto-skills.md) | JS Module |
-| [build-agents-commands.mjs](build-agents-commands.md) | JS Module |
-| [cli-entry.mjs](cli-entry.md) | JS Module |
-| [coverage-fix-extract.mjs](coverage-fix-extract.md) | JS Module |
-| [coverage-fix.mjs](coverage-fix.md) | JS Module |
+| Файл                                                                                | Тип       |
+| ----------------------------------------------------------------------------------- | --------- |
+| [auto-rules.mjs](auto-rules.md)                                                     | JS Module |
+| [auto-skills.mjs](auto-skills.md)                                                   | JS Module |
+| [build-agents-commands.mjs](build-agents-commands.md)                               | JS Module |
+| [cli-entry.mjs](cli-entry.md)                                                       | JS Module |
+| [coverage-fix-extract.mjs](coverage-fix-extract.md)                                 | JS Module |
+| [coverage-fix.mjs](coverage-fix.md)                                                 | JS Module |
 | [ensure-nitra-cursor-dev-dependencies.mjs](ensure-nitra-cursor-dev-dependencies.md) | JS Module |
-| [post-tool-use-check.mjs](post-tool-use-check.md) | JS Module |
-| [post-tool-use-fix.mjs](post-tool-use-fix.md) | JS Module |
-| [rename-yaml-extensions.mjs](rename-yaml-extensions.md) | JS Module |
-| [skills-cli.mjs](skills-cli.md) | JS Module |
-| [sync-claude-config.mjs](sync-claude-config.md) | JS Module |
-| [sync-setup-bun-deps-action.mjs](sync-setup-bun-deps-action.md) | JS Module |
-| [upgrade-nitra-cursor-and-install.mjs](upgrade-nitra-cursor-and-install.md) | JS Module |
-| [worktree-cli.mjs](worktree-cli.md) | JS Module |
+| [post-tool-use-check.mjs](post-tool-use-check.md)                                   | JS Module |
+| [post-tool-use-fix.mjs](post-tool-use-fix.md)                                       | JS Module |
+| [rename-yaml-extensions.mjs](rename-yaml-extensions.md)                             | JS Module |
+| [skills-cli.mjs](skills-cli.md)                                                     | JS Module |
+| [sync-claude-config.mjs](sync-claude-config.md)                                     | JS Module |
+| [sync-setup-bun-deps-action.mjs](sync-setup-bun-deps-action.md)                     | JS Module |
+| [upgrade-nitra-cursor-and-install.mjs](upgrade-nitra-cursor-and-install.md)         | JS Module |
+| [worktree-cli.mjs](worktree-cli.md)                                                 | JS Module |

package/scripts/lib/docs/index.md

@@ -6,40 +6,40 @@ resource: npm/scripts/lib/
 
 # npm/scripts/lib
 
-| Файл | Тип |
-|---|---|
-| [assert-project-root.mjs](assert-project-root.md) | JS Module |
-| [changed-files.mjs](changed-files.md) | JS Module |
-| [check-mdc-template-refs.mjs](check-mdc-template-refs.md) | JS Module |
-| [check-reporter.mjs](check-reporter.md) | JS Module |
-| [diff-added-lines.mjs](diff-added-lines.md) | JS Module |
+| Файл                                                                        | Тип       |
+| --------------------------------------------------------------------------- | --------- |
+| [assert-project-root.mjs](assert-project-root.md)                           | JS Module |
+| [changed-files.mjs](changed-files.md)                                       | JS Module |
+| [check-mdc-template-refs.mjs](check-mdc-template-refs.md)                   | JS Module |
+| [check-reporter.mjs](check-reporter.md)                                     | JS Module |
+| [diff-added-lines.mjs](diff-added-lines.md)                                 | JS Module |
 | [discover-check-rules-from-cursor.mjs](discover-check-rules-from-cursor.md) | JS Module |
-| [discover-checkable-rules.mjs](discover-checkable-rules.md) | JS Module |
-| [ensure-tool.mjs](ensure-tool.md) | JS Module |
-| [generated-markdown.mjs](generated-markdown.md) | JS Module |
-| [gha-workflow.mjs](gha-workflow.md) | JS Module |
-| [inline-template-links.mjs](inline-template-links.md) | JS Module |
-| [list-project-rules-mdc.mjs](list-project-rules-mdc.md) | JS Module |
-| [list-rule-ids.mjs](list-rule-ids.md) | JS Module |
-| [load-cursor-config.mjs](load-cursor-config.md) | JS Module |
-| [mirror-parity.mjs](mirror-parity.md) | JS Module |
-| [read-n-cursor-config-lite.mjs](read-n-cursor-config-lite.md) | JS Module |
-| [resolve-target-files.mjs](resolve-target-files.md) | JS Module |
-| [root-notice.mjs](root-notice.md) | JS Module |
-| [rule-meta-helpers.mjs](rule-meta-helpers.md) | JS Module |
-| [rule-meta.mjs](rule-meta.md) | JS Module |
-| [rule-predicates.mjs](rule-predicates.md) | JS Module |
-| [run-conftest-batch.mjs](run-conftest-batch.md) | JS Module |
-| [run-lint-step.mjs](run-lint-step.md) | JS Module |
-| [run-lint.mjs](run-lint.md) | JS Module |
-| [run-rule-cli.mjs](run-rule-cli.md) | JS Module |
-| [run-rule.mjs](run-rule.md) | JS Module |
-| [run-standard-lint.mjs](run-standard-lint.md) | JS Module |
-| [run-standard-rule.mjs](run-standard-rule.md) | JS Module |
-| [skill-meta.mjs](skill-meta.md) | JS Module |
-| [sync-gitignore-worktree.mjs](sync-gitignore-worktree.md) | JS Module |
-| [template.mjs](template.md) | JS Module |
-| [timing-summary.mjs](timing-summary.md) | JS Module |
-| [workspaces.mjs](workspaces.md) | JS Module |
-| [worktree-notice.mjs](worktree-notice.md) | JS Module |
-| [worktree.mjs](worktree.md) | JS Module |
+| [discover-checkable-rules.mjs](discover-checkable-rules.md)                 | JS Module |
+| [ensure-tool.mjs](ensure-tool.md)                                           | JS Module |
+| [generated-markdown.mjs](generated-markdown.md)                             | JS Module |
+| [gha-workflow.mjs](gha-workflow.md)                                         | JS Module |
+| [inline-template-links.mjs](inline-template-links.md)                       | JS Module |
+| [list-project-rules-mdc.mjs](list-project-rules-mdc.md)                     | JS Module |
+| [list-rule-ids.mjs](list-rule-ids.md)                                       | JS Module |
+| [load-cursor-config.mjs](load-cursor-config.md)                             | JS Module |
+| [mirror-parity.mjs](mirror-parity.md)                                       | JS Module |
+| [read-n-cursor-config-lite.mjs](read-n-cursor-config-lite.md)               | JS Module |
+| [resolve-target-files.mjs](resolve-target-files.md)                         | JS Module |
+| [root-notice.mjs](root-notice.md)                                           | JS Module |
+| [rule-meta-helpers.mjs](rule-meta-helpers.md)                               | JS Module |
+| [rule-meta.mjs](rule-meta.md)                                               | JS Module |
+| [rule-predicates.mjs](rule-predicates.md)                                   | JS Module |
+| [run-conftest-batch.mjs](run-conftest-batch.md)                             | JS Module |
+| [run-lint-step.mjs](run-lint-step.md)                                       | JS Module |
+| [run-lint.mjs](run-lint.md)                                                 | JS Module |
+| [run-rule-cli.mjs](run-rule-cli.md)                                         | JS Module |
+| [run-rule.mjs](run-rule.md)                                                 | JS Module |
+| [run-standard-lint.mjs](run-standard-lint.md)                               | JS Module |
+| [run-standard-rule.mjs](run-standard-rule.md)                               | JS Module |
+| [skill-meta.mjs](skill-meta.md)                                             | JS Module |
+| [sync-gitignore-worktree.mjs](sync-gitignore-worktree.md)                   | JS Module |
+| [template.mjs](template.md)                                                 | JS Module |
+| [timing-summary.mjs](timing-summary.md)                                     | JS Module |
+| [workspaces.mjs](workspaces.md)                                             | JS Module |
+| [worktree-notice.mjs](worktree-notice.md)                                   | JS Module |
+| [worktree.mjs](worktree.md)                                                 | JS Module |

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

@@ -3,31 +3,31 @@ type: JS Module
 title: mirror-parity.mjs
 resource: npm/scripts/lib/mirror-parity.mjs
 docgen:
-  crc: 5e366df1
+  crc: 093ff2bb
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 90
 ---
 
 ## Огляд
 
-Модуль порівнює вміст дзеркал правил (`.cursor/rules/n-<id>.mdc`) з канонічними версіями (`npm/rules/<id>/<id>.mdc`), які містять застосовані трансформації (трансформ, що застосовує `readBundledRuleContent` $\to$ `inlineTemplateLinks`). Він визначає список керованих дзеркал, формує очікуваний вміст для кожного дзеркала та виявляє дрейф — відхилення фактичного вмісту від очікуваного.
+Модуль забезпечує паритет дзеркал правил, порівнюючи вміст `.cursor/rules/n-<id>.mdc` з канонічним вмістом `npm/rules/<id>/<id>.mdc`. Він визначає, які дзеркала відстежувати, формує очікуваний вміст цих дзеркал після застосування шаблонів (трансформу, що застосовує `readBundledRuleContent` $\rightarrow$ `inlineTemplateLinks`), та виявляє дрейф, що виникає, коли канонічний `.mdc` змінюється без регенерації дзеркала.
 
 ## Поведінка
 
 listManagedMirrors
-Визначає список керованих дзеркал правил, які мають відповідне канонічне джерело у `npm/rules`.
+Визначає список керованих дзеркал правил, що мають канонічне джерело у `npm/rules`.
 
 expectedMirrorContent
 Формує очікуваний вміст дзеркала, застосовуючи трансформації до канонічного файлу.
 
 findMirrorDrift
-Виявляє ідентифікатори дзеркал, чий фактичний вміст відрізняється від очікуваного вмісту, отриманого з канону.
+Виявляє ідентифікатори дзеркал, чий фактичний вміст відрізняється від очікуваного.
 
 ## Публічний API
 
-listManagedMirrors — перераховує керовані дзеркала, які мають визначене канонічне джерело.
-expectedMirrorContent — визначає бажаний вміст дзеркала, використовуючи канон із вбудованими шаблонами.
-findMirrorDrift — знаходить ідентифікатори дзеркал, у яких фактичний вміст відрізняється від очікуваного.
+listManagedMirrors — перераховує керовані дзеркала, які мають визначене основне джерело.
+expectedMirrorContent — визначає бажаний вміст дзеркала, використовуючи шаблонне заміщення даних.
+findMirrorDrift — знаходить ідентифікатори дзеркал, чий фактичний вміст відрізняється від очікуваного.
 
 ## Гарантії поведінки
 

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

@@ -3,30 +3,30 @@ type: JS Module
 title: rule-meta.mjs
 resource: npm/scripts/lib/rule-meta.mjs
 docgen:
-  crc: 36aea8cb
+  crc: 8eca71d2
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Парсер інтерпретує метадані правил, що знаходяться у `npm/rules/<id>/meta.json`. Він реалізує data-driven логіку для визначення умов активації кожного детектора. Специфікації активації (`auto`) нормалізуються на основі вмісту `meta.json`, підтримуючи чотири типи: константа `RULE_ALWAYS` ("завжди"), залежності від інших правил, шаблони за допомогою `glob`, або незводимі предикати. Парсер не виконує операцій запису у файлову систему чи бази даних і забезпечує безпечну роботу, перехоплюючи помилки.
+Файл зчитує метадані правил з `npm/rules/<id>/main.json`. Він нормалізує специфікації активації (`auto`) та області застосування (`lint`). Специфікація `main.json.auto` може мати чотири форми: константу `RULE_ALWAYS` ("завжди"), масив залежних правил, об'єкт з шаблоном `glob` або об'єкт з предикатом. Це забезпечує механізм для визначення умов активації правила на основі конфігурації `main.json`.
 
 ## Поведінка
 
-RULE_ALWAYS — константа, що позначає безумовну активацію правила.
-parseRuleAutoSpec — Нормалізує значення поля `auto` з метаданих правила у дискриміновану специфікацію активації.
-parseRuleLintSpec — Нормалізує значення поля `lint` з метаданих правила у специфікацію області застосування детектора.
-readRuleMetaRaw — Читає та парсить вміст `main.json` з каталогу правила, повертаючи його як об'єкт або `null` у разі помилки чи відсутності файлу.
+RULE_ALWAYS — Константа, що позначає безумовну активацію правила.
+parseRuleAutoSpec — Нормалізує значення поля `auto` з `main.json` у дискриміновану специфікацію активації правила.
+parseRuleLintSpec — Нормалізує значення поля `lint` з `main.json` у специфікацію області застосування детектора.
+readRuleMetaRaw — Зчитує та парсить вміст `main.json` з каталогу правила, повертаючи його як об'єкт або `null` у разі помилки чи відсутності файлу.
 
 ## Публічний API
 
-RULE_ALWAYS — константа, що вказує на безумовну активацію.
-parseRuleAutoSpec — перетворює налаштування автоматичного визначення правил з `meta.json` у структурований формат.
-parseRuleLintSpec — перетворює налаштування лінтування з `meta.json` у визначення області дії детектора.
-"per-file" — визначає, що детектор працює з окремими зміненими файлами (порівняння змін з оригіналом).
-"full" — вказує на повний, нероздільний аналіз між усіма файлами (активується лише при використанні прапорця `--full` або в CI).
-readRuleMetaRaw — зчитує та обробляє метадані одного правила з файлу `meta.json`.
+RULE_ALWAYS — позначка для безумовної активації.
+parseRuleAutoSpec — перетворює налаштування автоматичного визначення правил з `main.json` у структурований формат.
+parseRuleLintSpec — перетворює налаштування лінтера з `main.json` у визначення області дії детектора.
+"per-file" — визначає, що детектор аналізує зміни на рівні окремих файлів (порівнює відмінності з оригіналом).
+"full" — визначає, що детектор аналізує весь проєкт одночасно (активується лише при використанні прапорця `--full` або в CI).
+readRuleMetaRaw — зчитує та розбирає метадані одного правила з `main.json`.
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/skill-meta.md

@@ -3,28 +3,28 @@ type: JS Module
 title: skill-meta.mjs
 resource: npm/scripts/lib/skill-meta.mjs
 docgen:
-  crc: c0918db5
+  crc: c1757867
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Спільний парсер метаданих скіла, що зчитує дані з `npm/skills/<id>/meta.json`. Він є єдиним джерелом правди для конфігурації скілів, визначаючи умови автоактивації (через поле `auto`, де `SKILL_ALWAYS` означає "завжди"), чи виконувати скіл в окремому git-worktree (`worktree`), та чи вимагає скіл запуску з кореня репозиторію (`requireRoot`). Модуль надає механізми для парсингу цих метаданих, перевірки вимог до кореня та читання сирих даних. Він працює в режимі fail-safe, перехоплюючи помилки та повертаючи порожнє значення замість винятків.
+Спільний парсер метаданих скіла, що зчитує інформацію з `main.json`. Цей файл є єдиним джерелом правди для скіла. Модуль дозволяє визначати умови автоактивації скіла (через поле `auto`), вказувати, чи виконувати скіл в окремому git-worktree (`worktree`), та чи вимагає він запуску з кореня репозиторію (`requireRoot`). Надає константу `SKILL_ALWAYS` для безумовної активації. Хелпер використовується іншими компонентами для уникнення дублювання парсингу. Функції забезпечують перехоплення помилок (fail-safe), повертаючи порожнє значення замість винятків.
 
 ## Поведінка
 
 SKILL_ALWAYS — надає літерал для безумовної автоактивації скіла.
-parseSkillAutoSpec — перетворює значення поля `auto` з метаданих скіла у специфікацію автоактивації.
-skillRequiresRoot — визначає, чи вимагає скіл запуску з кореня репозиторію, виходячи з метаданих.
-readSkillMetaRaw — читає та парсить файл `main.json` у каталозі скіла, повертаючи його вміст або `null` у разі помилки.
+parseSkillAutoSpec — перетворює значення поля `auto` з `main.json` у специфікацію автоактивації.
+skillRequiresRoot — визначає, чи вимагає скіл запуску з кореня репозиторію, базуючись на метаданих.
+readSkillMetaRaw — читає та парсить файл `main.json` для заданого каталогу скіла.
 
 ## Публічний API
 
-SKILL_ALWAYS — маркер, що вказує на безумовну активацію
-parseSkillAutoSpec — витягує налаштування автоматичного запуску з `meta.json`
-skillRequiresRoot — визначає, чи потрібен запуск скіла з кореня репозиторію
-readSkillMetaRaw — зчитує та обробляє метадані окремого скіла з `meta.json`
+SKILL_ALWAYS — позначка для безумовної активації.
+parseSkillAutoSpec — витягує налаштування автоматичного запуску з `main.json` у структуру `SkillAutoSpec`.
+skillRequiresRoot — визначає, чи потрібен запуск скіла з кореня репозиторію (активує захист від запуску з інших місць).
+readSkillMetaRaw — зчитує та розбирає метадані одного скіла з `main.json`.
 
 ## Гарантії поведінки