@nitra/cursor 12.6.1 → 12.8.0

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

@@ -3,158 +3,25 @@ type: JS Module
 title: list-rule-ids.mjs
 resource: npm/scripts/lib/list-rule-ids.mjs
 docgen:
-  crc: 5ef1ead5
+  crc: d8b3ea73
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Модуль `list-rule-ids.mjs` — невелика бібліотечна утиліта, призначена для перебору директорій-правил у каталозі `npm/rules/` та повернення відсортованого алфавітно списку ідентифікаторів правил, які реально містять виконуваний модуль `fix.mjs`.
+## Огляд
 
-Логіка модуля побудована навколо архітектурної інваріанти проєкту: після так званої «атомарної міграції» кожне валідне правило **зобов'язане** мати файл `fix.mjs` у власній директорії `rules/<id>/`. Будь-яка піддиректорія без `fix.mjs` вважається або «не-правилом» (службова тека), або заглушкою-чернеткою — і ігнорується. Прихованих директорій (імена, що починаються з `.`) також не існує в результаті.
+Перебирає директорії у `rules/` та фільтрує їх, вибираючи лише ті, що містять єдиний канонічний entrypoint (`rules/<id>/main.mjs`), згідно з ADR 2026-06-21. Функція повертає список ідентифікаторів правил, які відповідають цьому канону. Операція є лише для читання файлової системи.
 
-Додатково модуль підтримує опційне точкове фільтрування одним конкретним `id`, що використовується CLI-флагом `--rule abie` для прогону команд у режимі «тільки одне правило».
+## Поведінка
 
-Модуль повністю асинхронний (використовує `node:fs/promises`), не має зовнішніх npm-залежностей і не виконує жодних побічних ефектів окрім читання директорії та перевірки наявності файлу через `existsSync`.
+1. Зчитує список усіх каталогів у директорії, що містить правила.
+2. Фільтрує цей список, залишаючи лише каталоги, які не починаються з крапки.
+3. Для кожного каталогу перевіряє, чи існує у ньому файл `main.mjs`.
+4. Фільтрує список, залишаючи лише ті каталоги, які містять файл `main.mjs`.
+5. Якщо надано фільтр, додатково фільтрує список, залишаючи лише той ID, що збігається з фільтром.
+6. Сортує отримані ID в алфавітному порядку.
+7. Повертає відсортований список ID правил.
 
-## Експорти / 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`) семантично не є помилками — вони лише звужують повернений масив.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/read-n-cursor-config-lite.md

@@ -3,30 +3,26 @@ type: JS Module
 title: read-n-cursor-config-lite.mjs
 resource: npm/scripts/lib/read-n-cursor-config-lite.mjs
 docgen:
-  crc: a5fb0592
+  crc: a38ac2f4
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Цей файл читає файл `.n-cursor.json`, що містить список правил для конфігурації. Він повертає цей список, щоб `fix.mjs` міг використовувати правила для визначення конфігурації. Це забезпечує базове читання конфігурації правил для запуску `fix.mjs` з командного рядка.
+## Огляд
 
-## Поведінка
+Модуль надає легкий, лише для читання, інтерфейс для парсингу конфігурації `.n-cursor.json`. Він призначений для ізольованих, окремих викликів `check.mjs`. Модуль визначає стан кожного правила, ґрунтуючись на вмісті `.n-cursor.json`. Якщо файл відсутній, правило вважається активним (поведінка "open by default"). Якщо файл присутній, стан правила залежить від списків `rules` та `disableRules` у конфігурації. Модуль повертає об'єкт, що містить списки активних та вимкнених правил.
 
-**readNCursorConfigLite**
-Зчитує конфігурацію з файлу `.n-cursor.json`. Повертає об'єкт з інформацією про правила та вимкнені правила. Якщо файл відсутній, повертає конфігурацію з порожнім масивом правил.
+## Поведінка
 
-**isRuleEnabled**
-Перевіряє, чи правило з активним статусом згідно з конфігурацією. Повертає `true`, якщо файл відсутній, правило вимкнено в `disable-rules` або присутнє в `rules`. Повертає `false` в іншому випадку.
+Поведінка
+readNCursorConfigLite читає конфігураційний файл .n-cursor.json у вказаному каталозі, повертаючи стан його існування та списки дозволених і вимкнених правил.
+isRuleEnabled визначає, чи має бути виконане правило, виходячи зі стану конфігураційного файлу та ID правила.
 
 ## Публічний API
 
-- readNCursorConfigLite — Завантажує конфігурацію курсора.
-- isRuleEnabled — Перевіряє статус активності правила.
+readNCursorConfigLite — зчитує базові налаштування курсора з конфігурації.
+isRuleEnabled — визначає, чи діє певне правило на основі конфігурації. Якщо конфігурація відсутня, правило вважається активним за замовчуванням. Якщо правило явно вимкнено, воно не діє. Якщо правило визначено у списку правил, воно діє. В іншому випадку, правило не діє.
 
 ## Гарантії поведінки
 
-- Якщо файл `.n-cursor.json` відсутній, вважається, що всі правила включені.
-- Якщо файл `.n-cursor.json` існує, але поле `rules` порожнє, вважається, що всі правила включені.
-- Якщо файл `.n-cursor.json` існує і має поле `rules`, але поле `rules` порожнє, вважається, що всі правила включені.
-- Якщо правило вказане в полі `disable-rules`, воно вимкнено.
-- Повертає `false` якщо файл `.n-cursor.json` відсутній або недійсний.
-- Повертає `null` якщо не вдалося прочитати файл `.n-cursor.json`.
-- Не використовує кешування.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/run-lint-step.md

@@ -3,27 +3,27 @@ type: JS Module
 title: run-lint-step.mjs
 resource: npm/scripts/lib/run-lint-step.mjs
 docgen:
-  crc: 5932fa98
+  crc: f37a61b9
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Цей файл забезпечує спільний хелпер для запуску окремих кроків у ланцюжку linting, що використовується CLI-обгортками. Він імітує прямий виклик команд у shell, логуючи команди та перенаправляючи stdout/stderr на користувацькі stream-и. Це дозволяє уникнути дублювання обгорток у різних `rules/<id>/js/lint.mjs` файлах.
+Спільний хелпер для CLI-обгорток `lint-<rule>`. Він запускає один крок ланцюжка з логуванням команди та прокидає stdout/stderr на користувацькі stream-и (`stdio: 'inherit'`). Це дозволяє rule-адаптерам `n-cursor lint <rule>` уникнути дублювання логіки обгортки у файлах `rules/<id>/js/lint.mjs`. Функція не виконує операцій з файловою системою чи базою даних.
 
 ## Поведінка
 
-1.  Записує в лог повідомлення про початок виконання кроку ланцюжка з описом команди та її аргументів.
-2.  Визначає шлях до виконуваного файлу команди на основі її імені.
-3.  Якщо шлях не знайдено в системному PATH, записує повідомлення про помилку та повертає код 127.
-4.  Запускає визначену команду з заданими аргументами, передаючи стандартний потік введення/виведення (stdio) потокам користувача.
-5.  Якщо команда завершилася з помилкою, записує повідомлення про помилку та повертає код 1.
-6.  Якщо команда завершилася успішно, повертає код виходу дочірнього процесу, який дорівнює 0, якщо все добре, або 1, якщо виникла помилка.
+1. Викликається `runLintStep` для запуску одного кроку ланцюжка лінтування.
+2. Виводиться у консоль повідомлення про запуск команди з вказаним заголовком.
+3. Визначається повний шлях до команди.
+4. Якщо повний шлях до команди не знайдено в PATH, виводиться повідомлення про помилку, і функція повертає код 127.
+5. Запускається дочірній процес з успадкованими потоками виводу та помилки.
+6. Якщо виникає помилка при запуску процесу, виводиться повідомлення про помилку, і функція повертає код 1.
+7. Якщо процес успішно запущено, функція повертає код виходу дочірнього процесу.
 
 ## Публічний API
 
-runLintStep — запускає процес linting та перевіряє його успішність.
+runLintStep — запускає один етап перевірки коду, знаходячи відповідну команду в системному шляху та виконуючи її з передаченим вхідно-вихідним потоком.
 
 ## Гарантії поведінки
 
-- Запускає один крок ланцюжка linting.
-- Перенаправляє stdout та stderr на користувацькі stream-и (stdio: 'inherit').
-- Не використовує кешування.
-- Не має внутрішніх приватних імен.
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: run-lint.mjs
+resource: npm/scripts/lib/run-lint.mjs
+docgen:
+  crc: dd80d058
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Модуль керує вибором та виконанням правил лінтування. Він визначає набір правил для лінтування, спираючись на конфігурації `meta.json` та `.n-cursor.json`. Публічна функція `selectLintRules` вибирає та сортує ці правила на основі їхньої лінт-поверхні. Публічна функція `runLint` ініціює виконання визначеного набору правил, перевіряючи змінені файли або весь репозиторій.
+
+## Поведінка
+
+selectLintRules вибирає і алфавітно сортує ідентифікатори правил для лінтування на основі їхньої лінт-поверхні та наявності в активних конфігураціях.
+runLint запускає лінт-оркестрацію, виконуючи перевірку змінених файлів або повний прогін репозиторію, залежно від наданих опцій.
+
+## Публічний API
+
+selectLintRules — обирає ідентифікатори правил для контексту, розташовуючи їх в алфавітному порядку.
+runLint — ініціює процес лінтування.
+full — сканує весь репозиторій, порівнюючи його з початковим станом.
+readOnly — лише виявляє проблеми без внесення змін.
+rules — виконує повне сканування репозиторію, застосовуючи лише вказаний набір правил.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -3,22 +3,26 @@ type: JS Module
 title: run-rule-cli.mjs
 resource: npm/scripts/lib/run-rule-cli.mjs
 docgen:
-  crc: 264e7ab0
-  score: 100
+  crc: 1251c4d0
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 95
 ---
 
-Файл є автономним CLI-запускачем для одного правила. Він друкує звіт про перевірку та повертає агрегований код виходу. Whitelist-гейту тут немає: гейтинг активних правил живе виключно у `resolveCheckRuleIds` (селекція за `.n-cursor.json`), а прямий запуск файлу правила — свідома debug/override-дія, тож виконується беззастережно.
+## Огляд
+
+Standalone CLI runner для одного правила. Викликається з `rules/<id>/check.mjs` у блоці `if (import.meta.main)`, що робить його повним еквівалентом `bun rules/<id>/check.mjs` або `npx @nitra/cursor fix <id>`. Цей запуск є свідомим (debug / override) і виконується без whitelist-гейту. Ініціалізує кеш для проходження файлової системи та виконує стандартну перевірку, друкуючи summary результату та повертаючи aggregated exit-code.
 
 ## Поведінка
 
-1.  Викликається для запуску правила.
-2.  Друкує повідомлення про перевірку правила.
-3.  Використовує кеш для перевірки.
-4.  Викликає функцію для виконання стандартного правила з кешем.
-5.  Повертає агрегований код виходу.
+1. Викликається для виконання одного правила у режимі командного рядка.
+2. Визначається ідентифікатор правила на основі шляху до директорії правила.
+3. Виводиться повідомлення про початок перевірки для цього правила.
+4. Ініціалізується кеш для проходження файлової системи.
+5. Виконується стандартна перевірка для правила, використовуючи ініціалізований кеш.
+6. Виводиться підсумок результату перевірки.
+7. Повертається код виходу, що відображає успішність або наявність порушень.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Кешує результати в межах одного прогону.
-- Не звертається до мережі.

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

@@ -3,24 +3,43 @@ type: JS Module
 title: run-standard-lint.mjs
 resource: npm/scripts/lib/run-standard-lint.mjs
 docgen:
-  crc: e7e3f0ae
+  crc: 2b275963
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
 ---
 
-Файл забезпечує централізовану точку запуску для підкоманд `lint-<rule>` у `@nitra/cursor`. Він серіалізує та дедублює запуски, використовуючи `withLock`, щоб гарантувати узгодженість та ефективність. Це дозволяє легко інтегрувати нові правила та обробляти крос-cutting концерни, не вносячи змін у окремі файли правил.
+## Огляд
+
+Спільна точка входу для канонічних `lint-<rule>` підкоманд `@nitra/cursor`. Файл серіалізує та дедуплікує запуски лінту через `withLock`. `ruleId` визначається зі шляху незалежно від глибини виклику (наприклад, `rules/<id>`). Це дозволяє уніфікувати крос-cutting концерни. Інтеграція з боку правила виглядає так:
+
+- import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'
+-
+- async function runLintFooSteps { ... }
+-
+- export function lint { return runStandardLint }
 
 ## Поведінка
 
-runLintFooCli: Запускає лінт для правила, використовуючи `runStandardLint`.
-runStandardLint: Серіалізує та дедуплікує запуск лінту, використовуючи блокування. Визначає ідентифікатор правила з шляху.
+lint: Викликає стандартизований лінт, використовуючи шлях каталогу правила для визначення його ідентифікатора.
+runStandardLint: Серіалізує та дедуплікує запуск лінту для заданого правила, використовуючи ідентифікатор, виведений зі шляху каталогу правила.
 
 ## Публічний API
 
-- runLintFooCli — Перевіряє код на відповідність стандартам Foo CLI.
-- runStandardLint — Перевіряє код на відповідність загальним стандартам кодування.
+lint — є спільною точкою входу для канонічних `lint-<rule>` підкоманд `@nitra/cursor`. Він ініціює серіалізацію та дедуплікацію запусків лінтингу для вказаних файлів, забезпечуючи централізоване управління крос-cutting концернами.
+
+runStandardLint — виконує стандартний лінтинг у директорії, приймаючи контекст директорії та функцію, що описує кроки лінтингу.
+
+Приклад інтеграції:
+
+```js
+import { runStandardLint } from '../../scripts/lib/run-standard-lint.mjs'
+
+async function runLintFooSteps { ... }
+
+export function lint { return runStandardLint }
+```
 
 ## Гарантії поведінки
 
-- Приймає `ruleId` з шляху файлу.
-- Створює блокування з іменем `lint-<ruleId>`.
-- Використовує попередньо збережені результати для уникнення повторного виконання.
-- Повертає результат виконання.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

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

@@ -3,23 +3,24 @@ type: JS Module
 title: run-standard-rule.mjs
 resource: npm/scripts/lib/run-standard-rule.mjs
 docgen:
-  crc: c1ae8f0e
-  score: 90
+  crc: 0c3b2e60
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 70
 ---
 
-Файл інкапсулює оркестрацію виконання правил. Він забезпечує запуск правила через визначений шлях, ізолюючи його виконання у блоці `withLock` для уникнення паралельних запусків.
+## Огляд
+
+Файл надає публічний API для оркестрації правил, який викликається з `rules/<id>/check.mjs`. Він інкапсулює логіку пошуку єдиного правила (`discoverOneRule`) та його виконання (`runRule`). Виконання обертається у `withLock` для дедуплікації паралельних запусків того самого правила на основі стану git-дерева. Локальна логіка в правилах заборонена; розширення поведінки відбувається через `ctx`-опції. Це централізована точка для запуску стандартних правил з кешуванням у межах одного прогону.
 
 ## Поведінка
 
-1.  Отримання шляху до правила
-2.  Визначення ідентифікатора правила
-3.  Охоплення виконання у блоці блокування
-4.  Пошук правила
-5.  Отримання кешу проходу
-6.  Запуск виконання правила
+1. Викликати `runStandardRule` для певного правила.
+2. Забезпечити унікальну блокування для виконання цього правила, використовуючи його ID.
+3. Виявити єдине правило, пов'язане з наданим шляхом.
+4. Отримати або створити кеш для прогону.
+5. Виконати правило, використовуючи виявлене правило, шлях до пакету та кеш прогону.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Кешує результати в межах одного прогону.
-- Не звертається до мережі.

package/scripts/lib/docs/timing-summary.md

@@ -3,26 +3,25 @@ type: JS Module
 title: timing-summary.mjs
 resource: npm/scripts/lib/timing-summary.mjs
 docgen:
-  crc: f21a9b91
+  crc: ee74c1cd
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Цей файл генерує табличне резюме часу виконання для команд `fix` та `lint`, які використовуються в orchestrator. Він підсумовує час виконання окремих правил та скриптів linting, надаючи інформацію для аналізу продуктивності. Результат представлений у вигляді рядка, який можна вивести для відображення користувачеві.
+## Огляд
+
+Формує таблицю-резюме часу виконання для оркестратора `fix` або `lint`. Таблиця використовується після прогону всіх правил перевірки (`runFixCommand` у `bin/n-cursor.js`) або після прогону скриптів лінтингу (`runLintCli` у `scripts/lib/run-lint-cli.mjs`), які визначаються у `package.json`. Звіт містить деталі часу виконання для кожного елемента у форматі `<ціла>.<десята>s`, а маркер `❌` на рядку вказує на невдачу (`ok === false`).
 
 ## Поведінка
 
-formatDurationMs: Перетворює мілісекунди на рядок у форматі `<ціла>.<десята>s`.
-formatTimingSummary: Формує таблицю-резюме часу виконання з масиву записів, виводячи їх у текстовому форматі.
+formatDurationMs перетворює тривалість у мілісекундах у рядок формату `<ціла>.<десята>s`.
+formatTimingSummary генерує багаторядковий текст таблиці-резюме часу виконання на основі наданого заголовка та списку записів про час.
 
 ## Публічний API
 
-- formatDurationMs — Форматує значення тривалості в форматі `<сек>.<десята>с`. Округлення виконується вниз (floor), щоб забезпечити консистентність результатів незалежно від платформи.
-- formatTimingSummary — Створює багаторядковий текст у форматі таблиці-резюме для виведення в консоль (stdout).
+⏱ formatDurationMs: Перетворює мілісекунди на формат `<sec>.<десята>s`, використовуючи округлення вниз.
+⏱ formatTimingSummary: Генерує багаторядковий вивід у форматі таблиці-резюме для стандартного виводу.
 
 ## Гарантії поведінки
 
-❌ Якщо `ok` дорівнює `false`, повертає `null`.
-❌ Якщо час виконання перевищує 5 секунд, повертає `null`.
-Повертає рядок, що містить таблицю з часом виконання.
-Час виконання виражається у форматі `<ціла>.<десята>s`.
-Повертає рядок з символом `\n` в кінці.
-Не використовує кешування.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/docs/worktree-notice.md

@@ -6,11 +6,8 @@ docgen:
   crc: 1f7d5e0d
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
-  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-## Огляд
-
 Цей файл вшиває worktree-інструкцію у синкнутий `SKILL.md` (рішення D2 зі spec). Коли `meta.json.worktree === true`, скіл вставляє/замінює ідемпотентний ре-синкнутий блок, що містить маркери WORKTREE_START та WORKTREE_END, забезпечуючи виконання скілу в окремому git-worktree та запобігаючи паралелізації. Функція `injectWorktreeNotice` керує наявністю або відсутністю цього блоку в `SKILL.md` на основі конфігурації.
 
 ## Поведінка

package/scripts/lib/fix/analyze-escalation.mjs

@@ -231,7 +231,10 @@ function buildSynthesisPrompt(partials) {
  */
 function safeCall(call, prompt, model) {
   try {
-    const text = call([{ role: 'user', content: prompt }], model, { timeoutMs: ANALYZE_TIMEOUT_MS, caller: 'fix-analyze' })
+    const text = call([{ role: 'user', content: prompt }], model, {
+      timeoutMs: ANALYZE_TIMEOUT_MS,
+      caller: 'fix-analyze'
+    })
     return text || null
   } catch {
     return null

package/scripts/lib/fix/docs/index.md

@@ -6,13 +6,14 @@ resource: npm/scripts/lib/fix/
 
 # npm/scripts/lib/fix
 
-| Файл | Тип |
-|---|---|
-| [analyze-escalation.mjs](analyze-escalation.md) | JS Module |
-| [escalation-log.mjs](escalation-log.md) | JS Module |
-| [llm-fix-apply.mjs](llm-fix-apply.md) | JS Module |
-| [llm-lint-fix.mjs](llm-lint-fix.md) | JS Module |
-| [llm-worker.mjs](llm-worker.md) | JS Module |
-| [orchestrator.mjs](orchestrator.md) | JS Module |
-| [run-fix-check.mjs](run-fix-check.md) | JS Module |
-| [t0.mjs](t0.md) | JS Module |
+| Файл                                                  | Тип       |
+| ----------------------------------------------------- | --------- |
+| [analyze-escalation.mjs](analyze-escalation.md)       | JS Module |
+| [escalation-log.mjs](escalation-log.md)               | JS Module |
+| [llm-fix-apply.mjs](llm-fix-apply.md)                 | JS Module |
+| [llm-lint-fix.mjs](llm-lint-fix.md)                   | JS Module |
+| [llm-worker.mjs](llm-worker.md)                       | JS Module |
+| [orchestrator.mjs](orchestrator.md)                   | JS Module |
+| [run-conformance-check.mjs](run-conformance-check.md) | JS Module |
+| [run-fix-check.mjs](run-fix-check.md)                 | JS Module |
+| [t0.mjs](t0.md)                                       | JS Module |

package/scripts/lib/fix/docs/orchestrator.md

@@ -3,34 +3,39 @@ type: JS Module
 title: orchestrator.mjs
 resource: npm/scripts/lib/fix/orchestrator.mjs
 docgen:
-  crc: d327ab6d
+  crc: fbc91330
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль керує процесом валідації та виправлення конформності правил. Він перевіряє правила, застосовує детермінований механізм (T0), а нерозв'язані порушення проводить по **драбині ескалації моделей**: локальна min-модель → той самий локальний тир із feedback → хмарна min → хмарна avg. Кожен крок драбини логується для подальшого аналізу. Функція `runOrchestratorCli` запускає процес.
+## Огляд
+
+Модуль керує процесом вирішення порушень за допомогою багаторівневої системи ескалації. Він збирає послідовність рівнів моделей, починаючи з локальних і закінчуючи хмарними. Модуль парсить параметри запуску за допомогою `parseOrchestratorArgs` та виконує повний цикл фіксації, застосовуючи детермінований фікс. Для невирішених проблем застосовується ескалація правил через `escalateRule`, а фінальний запуск оркестратора здійснюється через `runOrchestratorCli`, який використовує структуру, побудовану за допомогою `buildLadder`.
 
 ## Поведінка
 
-1. `runOrchestratorCli` виконує початкову перевірку правил. Якщо порушень немає — успіх.
-2. Один прохід детермінованого фіксу (T0) зменшує набір порушень без LLM.
-3. `buildLadder` будує драбину з доступних тирів (`N_LOCAL_MIN_MODEL`, `N_CLOUD_MIN_MODEL`, `N_CLOUD_AVG_MODEL`); незадані тири відсіюються. Якщо драбина порожня — процес завершується з ознакою нерозв'язаних порушень.
-4. `escalateRule` проводить кожне правило по драбині до першого зеленого re-check:
-   - рунг `local-min` — перший прохід без feedback;
-   - рунг `local-min-retry` — той самий локальний тир, але з feedback попереднього рунга (попередні зміни + залишковий violation);
-   - рунги `cloud-min` / `cloud-avg` — хмарні моделі (через pi), теж із feedback.
-   Кожен рунг має per-tier `timeoutMs`: локальні **fail-fast** (`N_LOCAL_FIX_TIMEOUT_MS`, дефолт 45s — не палити стіну 120s на повільному локальному inference), хмарні — повний (`N_CLOUD_FIX_TIMEOUT_MS`, дефолт 120s).
-5. Достроковий вихід драбини: systemic-помилка локального тиру пропускає рунги тієї ж моделі; відсутній API-ключ на хмарному обриває драбину; хмарний транспортний збій (pi таймаут/spawn) обриває драбину, щоб не палити avg-бюджет на ту саму стіну; вичерпаний avg-кеп пропускає avg-рунг (із записом у лог).
-6. Після обробки всіх правил — фінальна перевірка. Усі чисті → успіх; інакше — ознака нерозв'язаних.
+buildLadder будує послідовність тирів ескалації для вирішення порушень, від локальних мінімальних моделей до хмарних середніх моделей.
+escalateRule проводить один прохід по послідовності тирів, намагаючись вирішити порушення, і повертає статус вирішення та використаний бюджет хмарних викликів.
+parseOrchestratorArgs парсить аргументи командного рядка для визначення максимального бюджету хмарних викликів та фільтра правил.
+runOrchestratorCli виконує повний цикл фіксації: перевіряє правила, застосовує детермінований фікс (T0-auto), а потім використовує LLM-драбину ескалації для невирішених порушень.
 
 ## Публічний API
 
-- `buildLadder({ localMin, cloudMin, cloudAvg })` — будує драбину рунгів із наявних тирів.
-- `escalateRule(rule, cwd, deps)` — проводить одне правило по драбині; повертає `{ resolved, avgUsed }`. Залежності (`worker`, `check`, `clock`) інжектовні для тестів.
-- `parseOrchestratorArgs(args)` — парсить `--max-avg N` (кеп на хмарні avg-виклики) і фільтр правил.
-- `runOrchestratorCli(args, cwd)` — точка входу; повертає `0` (усе чисто) або `1` (нерозв'язані).
+buildLadder — Створює послідовність моделей для ескалації, виходячи з доступних рівнів.
+
+local-min — Запускає первинний прохід з найменшою локальною моделлю.
+local-min-retry — Повторює локальний прохід, використовуючи відгук від попереднього кроку.
+cloud-min — Запускає прохід з найменшою хмарною моделлю, використовуючи відгук.
+cloud-avg — Запускає прохід з середньою хмарною моделлю, використовуючи відгук та обмеження середнього.
+
+escalateRule — Виконує одне правило по драбині ескалації до першого успішного перевірки.
+Кожен рунг — Запускає роботу моделі з урахуванням попереднього відгуку, перевіряє правило, фіксує результат у лозі.
+Достроковий вихід — Зупиняє процес при певних умовах (відсутність ключа, пропуск моделі на системному рівні) або при досягненні ліміту середнього.
+
+parseOrchestratorArgs — Витягує максимальне значення середнього та збирає список правил для фільтрації з командного рядка.
+
+runOrchestratorCli — Запускає основний процес оркестрації, обробляючи аргументи та виконуючи ескалацію правил.
 
 ## Гарантії поведінки
 
-- Кожен рунг драбини дописується в escalation-лог (`escalation-log.mjs`): модель, чи виклик удався, чи правило стало зеленим, залишковий violation і само-аналіз моделі.
-- Звертається до мережі лише на хмарних рунгах драбини (через pi).
+- Read-only: не виконує операцій запису (ФС/БД).