@nitra/cursor 12.15.0 → 12.15.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [12.15.1] - 2026-06-26
+
+### Changed
+
+- spec
+
 ## [12.15.0] - 2026-06-26
 
 ### Changed

package/bin/n-cursor.js

@@ -1528,15 +1528,6 @@ try {
 
       break
     }
-    case 'analyze-escalation': {
-      // n-cursor analyze-escalation — читає весь escalation-лог (.n-cursor/fix-escalation.jsonl),
-      // чанкує й просить хмарну avg-модель запропонувати, як зменшити LLM-залежність fix-
-      // конформності (нові T0-патерни / правки .mdc / зміни скриптів). Звіт → markdown.
-      const { runEscalationAnalysisCli } = await import('../scripts/lib/fix/analyze-escalation.mjs')
-      process.exitCode = await runEscalationAnalysisCli(args)
-
-      break
-    }
     case 'taze': {
       // n-cursor taze diff — read-only semver-diff package.json ↔ package.json.taze-bak
       // (root + воркспейси) для скілу n-taze: скрипт класифікує major-оновлення,
@@ -1575,7 +1566,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, hook, adr-normalize-local, lint (включно зі scope: lint ga|rego|k8s|docker|text), analyze-escalation, taze, release, skill, doc-aggregate`
+        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, hook, adr-normalize-local, lint (включно зі scope: lint ga|rego|k8s|docker|text), taze, release, skill, doc-aggregate`
       )
       process.exitCode = 1
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "12.15.0",
+  "version": "12.15.1",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/bun/docs/main.md

@@ -3,24 +3,25 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/bun/main.mjs
 docgen:
-  crc: 18950415
+  crc: 7cca0901
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль застосовує політики до коду та перевіряє ліцензії залежностей (bun.mdc). Функція `run` застосовує політику до коду, використовуючи кешування у межах прогону для прискорення. Функція `lint` перевіряє ліцензії npm-залежностей, спираючись на конфігурацію в .licensee.json. У режимі `fix` вона створює .licensee.json, а в режимі `readOnly` блокує виконання.
+Модуль виконує виконання політики доступу до коду проєкту та перевірку ліцензій залежностей. Функція `run` застосовує політику, що включає посилання на (bun.mdc), тоді як функція `lint` перевіряє ліцензії npm-залежностей відповідно до конфігурації, визначеної у .licensee.json. Кешування результатів відбувається у межах одного прогону.
 
 ## Поведінка
 
-run виконує перевірку, застосовуючи політику до коду, використовуючи кешування.
-lint виконує перевірку ліцензій npm-залежностей, генеруючи `.licensee.json` у fix-режимі або відмовляючись у readOnly режимі.
+run виконує перевірку, застосовуючи політику до коду проєкту, включаючи посилання на mdc.
+
+lint виконує перевірку ліцензій npm-залежностей через `.licensee.json`. У fix-режимі створює `.licensee.json` з дефолтним allowlist (blueOak: bronze), а у readOnly (CI) відсутність файлу призводить до невдачі.
 
 ## Публічний API
 
-run — Точка входу правила, що виконує перевірку: застосовує логіку, перевіряє відповідність політиці та посилання на маркери повідомлень (bun.mdc).
-lint — Інструмент для перевірки ліцензій npm-залежностей у всьому репозиторії. У режимі `--full` він працює повноцінно; у режимі виправлення автоматично створює файл .licensee.json, якщо його немає.
+run — виконує основний потік правила: застосовує логіку, перевіряє відповідність політикам та посиланням (bun.mdc).
+lint — проводить перевірку ліцензій npm-залежностей у всьому репозиторії. У режимі `--full` і `--fix` автоматично створює файл .licensee.json, якщо він відсутній.
 
 ## Гарантії поведінки
 

package/rules/python/docs/main.md

@@ -3,28 +3,28 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/python/main.mjs
 docgen:
-  crc: b072766d
+  crc: 2bdec93d
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 90
+  score: 95
 ---
 
 ## Огляд
 
-Виконує послідовність кроків для валідації коду Python відповідно до правил, визначених у (python.mdc). Перед запуском інструментів перевіряє наявність `pyproject.toml` у корені; якщо він відсутній, завершує роботу з кодом 0. Якщо файл присутній, перевіряє наявність `uv` у PATH, оскільки він є єдиним пакет-менеджером. Обов'язково виконує `uv lock --check` для підтвердження актуальності lock-файлу та `uv sync --frozen` для синхронізації середовища з `uv.lock` (див. https://docs.astral.sh/uv/). Опційні лінтери запускаються лише за умови їх доступності через `uv run`. При використанні `ruff` застосовується автоматичне виправлення (`auto-fix`), що модифікує робоче дерево. Усі операції виконуються з механізмом перехоплення помилок (fail-safe), запобігаючи викиданню винятків назовні.
+Цей модуль виконує послідовність кроків для забезпечення якості коду Python, використовуючи інструменти з екосистеми [uv](https://docs.astral.sh/uv/). Якщо файл `pyproject.toml` відсутній у корені, процес завершується з кодом 0 без запуску інструментів. Якщо файл присутній, але `uv` не знайдено в PATH, це розглядається як помилка. Модуль гарантує актуальність lock-файлу (`uv lock --check`) та збірку середовища (`uv sync --frozen`) перед запуском лінтерів. Опціональні лінтери запускаються лише за умови їх доступності через `uv run`.
 
 ## Поведінка
 
-run виконує стандартну перевірку на основі контексту.
-runLintPythonSteps виконує повний цикл лінтування Python, включаючи перевірку `uv lock --check`, `uv sync --frozen` та запуск лінтерів, якщо `pyproject.toml` присутній.
-runLintPython запускає кроки лінтування Python, використовуючи механізм серіалізації через `runStandardLint`.
-lint оркеструє запуск `runLintPython` з опцією `readOnly` для детектних перевірок.
+run виконує стандартну перевірку проєкту, використовуючи контекст прогону.
+runLintPythonSteps виконує повний набір кроків лінтування Python, включаючи перевірку `pyproject.toml`, виконання `uv lock --check` та `uv sync --frozen`, а також запуск опціональних лінтерів (`ruff`, `mypy`) та перевірку ліцензій.
+runLintPython запускає повний процес лінтування Python, серіалізуючи його через стандартний механізм перевірки.
+lint оркеструє запуск `runLintPython`, надаючи можливість вказати режим без мутацій (`readOnly`).
 
 ## Публічний API
 
-run — Точка входу для виконання правил, яка перевіряє аспекти застосування (JS-занепокложення $\rightarrow$ політика $\rightarrow$ mdc-посилання).
-runLintPythonSteps — Виконує внутрішні етапи перевірки коду Python без збереження результатів.
-runLintPython — Публічний інтерфейс командного рядка для запуску перевірки коду Python, що забезпечує унікальність завдяки блоку блокування та аналізу стану Git-дерева.
-lint — Адаптер, що керує запуском перевірки коду Python, делегуючи це `runLintPython`.
+run — Основна точка входу правила, яка виконує перевірку (JS-занепокложення $\rightarrow$ політика $\rightarrow$ mdc-посилання) та викликає перевірку якості коду.
+runLintPythonSteps — Виконує внутрішні етапи перевірки якості Python-коду без збереження логів.
+runLintPython — Публічний інтерфейс для запуску перевірки якості Python-коду, який синхронізується з станом Git-дерева.
+lint — Координатор, що ініціює запуск перевірки якості Python-коду, делегуючи цю роботу `runLintPython`.
 
 ## Гарантії поведінки
 

package/rules/rust/docs/main.md

@@ -3,25 +3,25 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/rust/main.mjs
 docgen:
-  crc: bbddef51
+  crc: 93dfaee0
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль надає інструменти для забезпечення якості коду на Rust. Він дозволяє виконати перевірку стилю за допомогою функції `lint` або запустити повну оркестрацію, що включає форматування та аналіз, за допомогою функції `run`. (rust.mdc)
+Модуль надає функції `run` та `lint` для аналізу коду на Rust. Функція `lint` виконує стандартну перевірку коду. Функція `run` запускає повну оркестрацію, яка включає форматування за допомогою `rustfmt` та статичний аналіз за допомогою `clippy` через `cargo` (rust.mdc).
 
 ## Поведінка
 
 run виконує стандартну перевірку для Rust-коду.
 
-lint запускає оркестрацію перевірки Rust-коду, включаючи форматування та аналіз.
+lint запускає оркестрацію перевірки Rust-коду, виконуючи `rustfmt` та `clippy` через `cargo`.
 
 ## Публічний API
 
-run — виконує основну перевірку, що включає перевірку логіки, пов'язаної з JS, політики та посиланнями MDC (rust.mdc).
-lint — забезпечує фіксацію та виконання перевірок стилю коду (аналогічно cargo fmt/clippy) для `n-cursor lint rust`.
+run — виконує основну логіку: перевіряє відповідність вимогам (JS-занепокложення $\rightarrow$ політика $\rightarrow$ mdc-посилання) (rust.mdc).
+lint — забезпечує оркестрацію для статичного аналізу коду Rust.
 
 ## Гарантії поведінки
 

package/scripts/docs/update-blue-oak.md

@@ -3,25 +3,25 @@ type: JS Module
 title: update-blue-oak.mjs
 resource: npm/scripts/update-blue-oak.mjs
 docgen:
-  crc: f818f73b
+  crc: dac30fed
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 95
 ---
 
 ## Огляд
 
-Оновлює вбудований список ліцензій Blue Oak Council, отримуючи дані з https://blueoakcouncil.org/list.json. Витягує SPDX-ідентифікатори ліцензій рівнів Model, Gold, Silver та Bronze і зберігає їх у npm/data/blue-oak.json. Цей процес запускається вручну у середовищі @nitra/cursor командою bun npm/scripts/update-blue-oak.mjs. Оновлення відбувається рідко, але нові permissive ліцензії з'являються раз на кілька місяців. Lead-рівень (найгірший, GPL-compatible) навмисно виключений.
+Оновлює вбудований список ліцензій Blue Oak Council, звертаючись до мережі за даними з https://blueoakcouncil.org/list.json. Цей процес створює або оновлює файл npm/data/blue-oak.json, який містить SPDX-ідентифікатори ліцензій рівнів Model, Gold, Silver та Bronze. Запуск здійснюється вручну у `@nitra/cursor` за допомогою команди `bun npm/scripts/update-blue-oak.mjs`. Оновлення необхідне при апгрейді @nitra/cursor, оскільки нові permissive ліцензії з'являються рідко. Lead-рівень (найгірший, GPL-compatible) навмисно виключений.
 
 ## Поведінка
 
 1. Завантажує дані з https://blueoakcouncil.org/list.json.
-2. Перевіряє успішність отримання даних. У разі невдачі зупиняє виконання.
-3. Парсить отриманий JSON-відповідь.
+2. Перевіряє успішність отримання даних. У разі невдачі припиняє виконання.
+3. Парсить отримані дані.
 4. Ітерує по рейтингах у даних.
-5. Для кожного рейтингу перевіряє, чи належить він до рівнів Model, Gold, Silver або Bronze.
-6. Якщо рейтинг відповідає критеріям, витягує всі SPDX-ідентифікатори ліцензій, пов'язані з цим рейтингом, та додає їх до списку.
-7. Формує об'єкт, що містить версію даних та зібраний список SPDX-ідентифікаторів.
-8. Зберігає цей об'єкт у файл blue-oak.json у каталозі data.
+5. Вибирає лише рейтинги Model, Gold, Silver та Bronze.
+6. Збирає всі SPDX-ідентифікатори ліцензій, що належать до обраних рейтингів.
+7. Формує об'єкт, що містить версію та список зібраних SPDX-ідентифікаторів.
+8. Зберігає цей об'єкт у файл npm/data/blue-oak.json.
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/discover-checkable-rules.md

@@ -3,24 +3,24 @@ type: JS Module
 title: discover-checkable-rules.mjs
 resource: npm/scripts/lib/discover-checkable-rules.mjs
 docgen:
-  crc: 403ab2ee
+  crc: d06cd969
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Шукає правила, для яких є щось «прогонне» у визначених структурах. Виявляє JS-концерни за шляхами `rules/<id>/js/<concern>.mjs` та Policy-концерни, які мають пару з `<concern>.rego` (зв'язану з конфігурацією `target.json`). Ігнорує файли з префіксом `_` та `*.test.mjs`, а також каталоги `_lib/`. Виконання є швидким скануванням структури (шляхи та назви) без парсингу вмісту.
+Визначає наявність JS-концернів та policy-концернів у заданому каталозі правила. Сканує всі каталоги правил, шукаючи JS-концерни у файлах `rules/<id>/js/<concern>.mjs` та policy-концерни, що асоціюються з парою `<concern>.rego` та `target.json`. Повертає список правил, які містять такі прогонні частини. Файли з префіксом `_` або `*.test.mjs` ігноруються.
 
 ## Поведінка
 
-discoverOneRule описує набір JS-концернів та policy-концернів для одного каталогу правила, використовуючи шлях до цього каталогу та його ідентифікатор.
-discoverCheckableRules сканує каталог з усіма правилами та повертає список правил, які мають JS-концерни або policy-концерни, фільтруючи ті, що не містять прогонного контенту.
+discoverOneRule описує правило, виявляючи JS-концерни та policy-концерни в заданому каталозі правила.
+discoverCheckableRules сканує каталог правил і повертає список правил, які мають JS-концерни або policy-концерни, фільтруючи ті, що не мають прогонних частин.
 
 ## Публічний API
 
-discoverOneRule — створює об'єкт перевірки для одного каталогу правила.
-discoverCheckableRules — знаходити правила у каталозі `rules/`, які мають відповідні скрипти у `js/` або політики у `policy/`.
+- discoverOneRule — Створює об'єкт для одного правила, що перевіряє конкретний каталог.
+- discoverCheckableRules — Знаходить правила у каталозі `rules/`, які мають відповідні скрипти (у `js/`) або політики (у `policy/`). Ігнорує правила, що містять лише документацію.
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/inline-template-links.md

@@ -3,22 +3,24 @@ type: JS Module
 title: inline-template-links.mjs
 resource: npm/scripts/lib/inline-template-links.mjs
 docgen:
-  crc: e1bed533
+  crc: 252fb1e1
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль інтегрує зовнішній контент у текстовий вивід, використовуючи конфігурації з `package.json.snippet.json` та `package.json`. Він замінює посилання на шаблони в тексті на їхній вміст за допомогою `inlineTemplateLinks` та доповнює текст вмістом усіх знайдених файлів `.mdc` з директорій `js/` та `policy/<concern>/` за допомогою `appendDiscoveredMdcFiles`.
+## Огляд
+
+Модуль збагачує текстовий контент, використовуючи конфігурації з package.json.snippet.json та package.json. Функція inlineTemplateLinks замінює текстові посилання на шаблони вбудованими блоками, якщо відповідні файли знаходяться у директорії правил. Функція appendDiscoveredMdcFiles доповнює текст вмістом усіх знайдених файлів `.mdc` з піддиректорій `js/` та `policy/` у директорії правил.
 
 ## Поведінка
 
-inlineTemplateLinks замінює посилання на шаблони в тексті на вбудовані блоки з вмістом відповідних файлів.
-appendDiscoveredMdcFiles додає вміст усіх знайдених файлів \*.mdc з директорій js/ та policy/<concern>/ до наданого тексту.
+inlineTemplateLinks замінює посилання на шаблони в тексті на вбудовані блоки з вмістом файлу, якщо ці файли існують у вказаній директорії правил.
+appendDiscoveredMdcFiles додає до кінця тексту вміст усіх знайдених файлів `.mdc` з піддиректорій `js/` та `policy/` у директорії правил.
 
 ## Публічний API
 
-inlineTemplateLinks — Замінює посилання у Markdown, що містять `/template/`, на вбудовані блоки, зчитуючи вміст з вказаного файлу. Викидає помилку, якщо цільове посилання не знайдено.
-appendDiscoveredMdcFiles — Додає всі знайдені файли з розширенням `.mdc` з підкаталогів `js/` та `policy/<concern>/`. Спочатку додаються файли з `js/` (у алфавітному порядку), а потім файли з підкаталогів `policy/` (у алфавітному порядку за назвою `concern`, а потім за назвою файлу).
+inlineTemplateLinks — Замінює посилання на шаблони в Markdown на вбудовані блоки, якщо шлях містить `/template/`. Помилка виникає, якщо цільовий файл посилання відсутній.
+appendDiscoveredMdcFiles — Додає всі знайдені файли `.mdc` з папок `js/` та `policy/<concern>/`. Файли з `js/` йдуть першими, а потім файли з підпапок `policy/<concern>/` (у алфавітному порядку за `concern`, а потім за назвою файлу).
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/list-project-rules-mdc.md

@@ -3,17 +3,19 @@ type: JS Module
 title: list-project-rules-mdc.mjs
 resource: npm/scripts/lib/list-project-rules-mdc.mjs
 docgen:
-  crc: 60cd4e83
+  crc: 59fe0e6e
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Цей модуль визначає шлях до `.mdc`-файлів правил у проєкті-споживачі, що зберігаються у директорії, вказаній константою CURSOR_RULES_DIR. Він надає відсортований список імен цих файлів. Це винесення логіки з `bin/n-cursor.js` забезпечує розділення відповідальності між інструментом командного рядка та функцією перевірки конформності.
+## Огляд
+
+Цей модуль визначає шлях до правил у проєкті-споживачі, що константою експортується як CURSOR_RULES_DIR=".cursor/rules". Він надає відсортований список імен файлів `.mdc` з каталогу правил. Це дозволяє розділити логіку диспетчеризації командного інтерфейсу та логіку перевірки конформності. Функція зчитує та повертає список файлів, якщо каталог правил існує.
 
 ## Поведінка
 
 CURSOR_RULES_DIR — Вказує на каталог правил у проєкті-споживачі.
-listProjectRulesMdcFiles — Повертає відсортований список імен файлів з розширенням `.mdc` у каталозі правил проєкту, або порожній масив, якщо каталог не існує.
+listProjectRulesMdcFiles — Повертає відсортований список імен файлів `.mdc` з каталогу правил проєкту-споживача, якщо цей каталог існує.
 
 ## Публічний API
 

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

@@ -3,30 +3,27 @@ type: JS Module
 title: root-notice.mjs
 resource: npm/scripts/lib/root-notice.mjs
 docgen:
-  crc: 5f3ca2bb
+  crc: 65db7d81
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Цей файл вставляє root-guard preflight для скілів, які змінюють проєкт у поточному каталозі. Він забезпечує, що скіл виконується in-place, без ізоляції worktree, і використовується для випадків, коли не потрібна ізоляція worktree. Це гарантує коректне виконання скілу від імені проєкту.
+## Огляд
+
+Цей модуль вшиває інструкцію для агента у файл `SKILL.md`. Інструкція вказує, що скіл мутує проєкт у поточному каталозі, але виконується in-place (без worktree-ізоляції), що відповідає конфігурації `meta.json` $\to$ `requireRoot: true` і `worktree: false`. Це застосовується до скілів, які змінюють `meta.json` або `package.json` безпосередньо, на відміну від worktree-скілів, які мають свій `root-assert` у `worktree-notice.mjs`. Блок є інструкцією агенту, що читає `SKILL.md`, і є ре-синк ідемпотентним: наявний блок замінюється, при `false` — видаляється. Програмний аналог для CLI-команд — `assertCwdIsProjectRoot`. Інструкція позначається маркерами `ROOT_START` ("<!-- n-cursor:root:start -->") та `ROOT_END` ("<!-- n-cursor:root:end -->").
 
 ## Поведінка
 
-ROOT_START: вставляє маркер початку root-блоку.
-ROOT_END: вставляє маркер кінця root-блоку.
-injectRootNotice: вставляє, оновлює або видаляє root-guard блок у вмісті `SKILL.md` на основі параметра `enabled`.
+ROOT_START: Позначає початок блоку інструкції щодо перевірки кореня репозиторію.
+ROOT_END: Позначає кінець блоку інструкції щодо перевірки кореня репозиторію.
+injectRootNotice: Вставляє, оновлює або видаляє блок інструкції щодо перевірки кореня репозиторію у вмісті файлу `SKILL.md` на основі булевого прапорця.
 
 ## Публічний API
 
-- ROOT_START — Позначає початок блоку root.
-- ROOT_END — Позначає кінець блоку root.
-- injectRootNotice — Змінює вміст `SKILL.md` щодо root-guard блоку.
+ROOT_START — маркер початку основного блоку документації.
+ROOT_END — маркер завершення основного блоку документації.
+injectRootNotice — додає, змінює або видаляє захисний блок у файлі `SKILL.md`.
 
 ## Гарантії поведінки
 
-- Якщо `requireRoot: true` у `meta.json`, то поточний робочий каталог є коренем проєкту.
-- Якщо `requireRoot: false`, то блок не вставляється.
-- Вставка відбувається лише між маркерами.
-- Вставка ре-синк ідемпотентно: наявний блок замінюється.
-- `ROOT_START` викликається перед вставкою блоку.
-- `ROOT_END` викликається після вставки блоку.
-- `injectRootNotice` викликається під час вставки блоку.
-- Немає кешування.
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -3,26 +3,28 @@ type: JS Module
 title: run-lint.mjs
 resource: npm/scripts/lib/run-lint.mjs
 docgen:
-  crc: f574f097
+  crc: 3c7deca0
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль керує процесом лінтування коду. Він визначає набір активних правил лінтування, використовуючи конфігурації з `meta.json` та `.n-cursor.json`. Модуль надає можливість вибрати ці правила за допомогою `selectLintRules` та ініціювати запуск перевірки коду за допомогою `runLint`.
+## Огляд
+
+Модуль визначає набір правил лінтування, спираючись на конфігурації `meta.json` та `.n-cursor.json`. Він використовує `selectLintRules` для вибору та сортування цих правил, а потім ініціалізує процес перевірки конформності та форматування за допомогою `runLint` у різних режимах (scoped, hook, delta, full).
 
 ## Поведінка
 
-selectLintRules визначає, які правила лінтуються на основі їхньої конфігурації та активності в `.n-cursor.json`, повертаючи відсортований список ID.
-runLint запускає лінтер-оркестрацію залежно від наданих опцій: виконує прогін для конкретних правил, перевіряє лише змінені файли, виконує повний прогін репозиторію або форматування.
+selectLintRules вибирає і алфавітно сортує ідентифікатори правил для лінтування на основі їхньої метаінформації та стану активації в `.n-cursor.json`.
+runLint запускає лінт-оркестрацію, виконуючи різні режими залежно від наданих опцій: scoped (за назвами правил), hook (за явним списком файлів), delta (зміна відносно origin) або full (весь репозиторій), включаючи конформність та форматування у fix-режимі.
 
 ## Публічний API
 
-selectLintRules — вибирає ідентифікатори правил для контексту в алфавітному порядку.
+selectLintRules — обирає ідентифікатори правил для контексту, у алфавітному порядку.
 runLint — ініціює процес лінтування.
 full — аналізує весь репозиторій, порівнюючи поточний стан із початковим.
-readOnly — лише виявляє проблеми, не вносячи змін.
-rules — виконує повний прогін лише для заданого набору правил у вказаному контексті.
-files — виконує перевірку лише для перелічених файлів у режимі хука.
+readOnly — лише виявляє проблеми без внесення змін.
+rules — виконує повний прогін лише для заданого набору правил.
+files — застосовує правила до конкретного переліку файлів у режимі хука.
 
 ## Гарантії поведінки
 

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

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

package/scripts/lib/fix/docs/discover-t0-patterns.md

@@ -3,28 +3,25 @@ type: JS Module
 title: discover-t0-patterns.mjs
 resource: npm/scripts/lib/fix/discover-t0-patterns.mjs
 docgen:
-  crc: f2a262bb
+  crc: 3f3b47e0
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль сканує директорію правил для пошуку файлів `fix-*.mjs`, що містять визначення T0-паттернів. Він динамічно імпортує ці файли з папок `js` та `policy/{concern}` для кожного правила. Ініціалізація результату відбувається за допомогою _top-level await_ у `t0.mjs`. Функція збирає масив об'єктів, що описують усі знайдені паттерни.
+Сканує директорії `npm/rules/{rule}/js/fix-*.mjs` та `npm/rules/{rule}/policy/{concern}/fix-*.mjs` для всіх правил. Динамічно імпортує кожен знайдений файл `fix-*.mjs` та збирає масиви `patterns`. Результат ініціалізується через top-level await у `t0.mjs` і представляє унікальний список усіх виявлених T0-паттернів. Функція не виконує операцій запису та перехоплює помилки, повертаючи `null` у випадку збоїв замість викидання винятків.
 
 ## Поведінка
 
-1. Перевіряє існування директорії, вказаної як `rulesDir`. Якщо директорія не існує, повертає порожній масив.
-2. Зчитує список усіх елементів у директорії `rulesDir`.
-3. Для кожного елемента, який є директорією та не починається з крапки, виконується наступне:
-   а. Визначається повний шлях до директорії правила.
-   б. Знаходяться всі файли `fix-*.mjs` у піддиректорії `js` цього правила.
-   в. Знаходяться всі файли `fix-*.mjs` у піддиректоріях `policy/{concern}` цього правила.
-   г. Для кожного знайденого файлу `fix-*.mjs` виконується динамічний імпорт.
-   д. Якщо імпорт успішний, збирається масив `patterns` з імпортованого модуля та додається до загального списку паттернів.
-   е. У разі помилки імпорту, помилка виводиться в консоль, але процес продовжується.
-4. Після обробки всіх правил, виконується дедуплікація загального списку паттернів за їхніми ідентифікаторами.
-5. Повертається фінальний, унікальний масив T0-паттернів.
+1. Перевіряє існування шляху `rulesDir`. Якщо шлях не існує, повертає порожній масив.
+2. Знаходить усі файли з шаблонами у шляхах `*/js/fix-*.mjs` та `*/policy/*/fix-*.mjs` у межах `rulesDir`.
+3. Для кожного знайденого файлу:
+   а. Намагається динамічно імпортувати вміст файлу.
+   б. Якщо імпорт успішний і вміст містить масив `patterns`, додає ці паттерни до загального списку.
+   в. Якщо імпорт не вдається, реєструє помилку, але продовжує роботу.
+4. Фільтрує загальний список паттернів, щоб уникнути дублікатів, зберігаючи лише перше входження кожного паттерна за його ідентифікатором.
+5. Повертає відфільтрований масив унікальних T0-паттернів.
 
 ## Публічний API
 

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

@@ -8,7 +8,6 @@ resource: npm/scripts/lib/fix/
 
 | Файл                                                  | Тип       |
 | ----------------------------------------------------- | --------- |
-| [analyze-escalation.mjs](analyze-escalation.md)       | JS Module |
 | [discover-t0-patterns.mjs](discover-t0-patterns.md)   | JS Module |
 | [escalation-log.mjs](escalation-log.md)               | JS Module |
 | [llm-fix-apply.mjs](llm-fix-apply.md)                 | JS Module |

package/scripts/lib/fix/docs/llm-worker.md

@@ -3,31 +3,26 @@ type: JS Module
 title: llm-worker.mjs
 resource: npm/scripts/lib/fix/llm-worker.mjs
 docgen:
-  crc: 5d019a98
+  crc: b5e54981
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль виділяє унікальні відносні шляхи файлів, пов'язаних із порушеннями, та виконує LLM-виклик для виправлення одного rule-порушення. Підтримує вибір sub-check `.mdc` за конкретним target-файлом — замість повного `n-{id}.mdc` передає моделі лише релевантну секцію правила (1–2 KB замість 20+ KB).
+Модуль витягує унікальні відносні шляхи файлів з даних про порушення, використовуючи конфігурацію з target.json. Потім він викликає LLM для генерації змін, які виправляють кожне порушення.
 
 ## Поведінка
 
-`extractFilePaths` витягує унікальні відносні шляхи файлів із violation output, пріоритетно розбираючи рядки ❌ (файли що потребують фіксу), потім generic-regex для контексту. Розуміє workspace-prefix `[npm] path/file.ext → npm/path/file.ext`.
-
-`selectSubCheckMdc` читає `policy/<concern>/target.json` з каталогу `npm/rules/{ruleId}/` пакету, знаходить concerns із `files.single`, що відповідають failing-файлам із violation output, і повертає конкатенацію відповідних `.mdc`. Повертає `null` якщо правило не має policy-підкаталогу або жоден concern не збігається з ❌-файлами.
-
-`runLlmWorker` спочатку викликає `selectSubCheckMdc` — і якщо отримує match, передає моделі лише той sub-check `.mdc`. Якщо match немає — fallback на повний `n-{id}.mdc`. Далі читає файли з violation output, будує prompt, викликає LLM через `callLlmRich` і застосовує зміни.
+extractFilePaths витягує унікальні відносні шляхи файлів з вихідних даних про порушення, розпізнаючи як явні помилки, так і контекст файлів.
+runLlmWorker виправляє одне порушення правила, викликаючи LLM для генерації змін, парсить відповідь та застосовує зміни до файлової системи.
 
 ## Публічний API
 
-`extractFilePaths(output)` — повертає унікальні відносні шляхи файлів з violation output (❌-рядки першими).
-
-`runLlmWorker(ruleId, violationOutput, projectRoot, opts)` — виправляє одне порушення правила через LLM. Повертає `{ ok, error?, changes, diagnosis, reasoning, reasoningSource, promptSummary }`. `promptSummary.subCheckMdc: boolean` вказує чи використано точковий sub-check замість повного mdc.
+extractFilePaths — Визначає шляхи файлів, які потребують виправлення, використовуючи `target.json` як пріоритет, а у разі його відсутності — всі знайдені шляхи.
+runLlmWorker — Виправляє одне порушення правила, використовуючи модель LLM. Повертає результати виправлення або діагностики, які використовуються для подальшої обробки.
 
 ## Гарантії поведінки
 
-- Читає `policy/` безпосередньо з пакету (`import.meta.dirname/../../../rules/`), без pre-generation файлів.
-- Fallback на повний `n-{id}.mdc` при: відсутності policy-підкаталогу, `walkGlob`-таргетах, відсутності ❌-файлів у violation, нульовому match.
-- Перехоплює всі помилки LLM і повертає структурований `{ ok: false, error }`.
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

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

@@ -3,29 +3,38 @@ type: JS Module
 title: orchestrator.mjs
 resource: npm/scripts/lib/fix/orchestrator.mjs
 docgen:
-  crc: c34d0630
+  crc: c6f15470
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль відповідає за управління процесом вирішення порушень. Він будує послідовність тирів ескалації за допомогою `buildLadder`. Функція `parseOrchestratorArgs` визначає бюджет LLM та фільтр правил. Далі, `runOrchestratorCli` виконує процес виправлення правил, послідовно застосовуючи `escalateRule` по тирах до досягнення першого успішного вирішення.
+## Огляд
+
+Модуль відповідає за оркестрацію вирішення порушень. Він парсить аргументи для визначення бюджету та фільтрів за допомогою `parseOrchestratorArgs`. Потім він будує послідовність тирів ескалації, використовуючи `buildLadder`, і може ескалувати правила за допомогою `escalateRule`. Нарешті, він виконує повний цикл фіксації порушень через `runOrchestratorCli`.
 
 ## Поведінка
 
-buildLadder будує послідовність тирів ескалації для вирішення порушень.
-escalateRule проходить по послідовності тирів, намагаючись вирішити одне правило до першого успішного перевірки.
-parseOrchestratorArgs парсить аргументи командного рядка для визначення максимального бюджету LLM та фільтра правил.
-runOrchestratorCli виконує повний процес виправлення правил, використовуючи послідовність тирів та бюджет LLM.
+buildLadder будує послідовність тирів ескалації для вирішення порушень, від локальних до хмарних моделей.
+escalateRule проводить один прогін по послідовності тирів, намагаючись вирішити порушення, і повертає статус вирішення та використаний бюджет хмарних викликів.
+parseOrchestratorArgs парсить аргументи командного рядка, щоб визначити максимальний бюджет хмарних викликів та фільтр правил.
+runOrchestratorCli виконує повний цикл фіксації порушень: початкова перевірка, детермінований фікс T0-auto, ітеративний LLM-фікс за драбиною ескалації, а потім фінальна перевірка.
 
 ## Публічний API
 
-buildLadder — Створює послідовність моделей для ескалації, виходячи з доступних рівнів. Недоступні рівні ігноруються.
+buildLadder — Створює послідовність моделей для ескалації, виходячи з доступних рівнів.
+
+local-min — Перший прохід з локальною мінімальною моделлю.
+local-min-retry — Повторний прохід локальною моделлю з урахуванням результатів попереднього кроку.
+cloud-min — Використання мінімальної хмарної моделі з зворотним зв'язком.
+cloud-avg — Використання середньої хмарної моделі з зворотним зв'язком, обмежене середнім бюджетом.
 
-escalateRule — Виконує один етап перевірки за драбиною ескалації. Для кожного кроку викликається модель, відбувається повторна перевірка правила, і результат фіксується в лозі. Процес може зупинитися достроково при певних умовах або після вичерпання ліміту.
+escalateRule — Застосовує одне правило по послідовності ескалації до першого успішного перевірки.
+Кожен рунг — Викликає обробника з попереднім результатом, перевіряє правило, фіксує результат у лозі.
+Достроковий вихід — Зупиняє процес при певних умовах (відсутність ключа, пропуск моделі на системному рівні) або перевищенні середнього бюджету.
 
-parseOrchestratorArgs — Витягує максимальне значення для середнього бюджету з аргументів командного рядка та збирає список фільтрів правил.
+parseOrchestratorArgs — Витягує максимальне значення середнього бюджету з аргументів командного рядка та збирає фільтри правил.
 
-runOrchestratorCli — Запускає основний процес оркестрації, обробляючи аргументи та керуючи виконанням правил.
+runOrchestratorCli — Запускає основний процес оркестрації з командного рядка.
 
 ## Гарантії поведінки