@nitra/cursor 12.11.1 → 12.11.2

package/rules/text/policy/vscode_extensions/docs/fix-vscode_extensions.md

@@ -0,0 +1,21 @@
+---
+type: JS Module
+title: fix-vscode_extensions.mjs
+resource: npm/rules/text/policy/vscode_extensions/fix-vscode_extensions.mjs
+docgen:
+  crc: 319883fc
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Файл імпортує шаблони для виправлення розширень VS Code. Ці шаблони використовуються для корекції розширень.
+
+## Поведінка
+
+1. Імпортує шаблони для виправлення розширень VS Code з файлу `../../../../scripts/lib/fix/vscode-ext-add.mjs`.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/text/policy/vscode_extensions/fix-vscode_extensions.mjs

@@ -0,0 +1 @@
+export { patterns } from '../../../../scripts/lib/fix/vscode-ext-add.mjs'

package/rules/vue/js/docs/packages.md

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Модуль визначає, чи є пакет бібліотекою компонентів Vue, виходячи з даних у `package.json`, `jsconfig.json`, `package-lock.json`, `extensions.json`. Він також перевіряє відповідність усіх пакетів, що залежать від `vue`, критеріям, описаним у `vue.mdc`, і повертає код виходу.
 
 ## Поведінка

package/scripts/docs/index.md

@@ -12,8 +12,6 @@ resource: npm/scripts/
 | [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 |
 | [hook.mjs](hook.md)                                                                 | JS Module |
 | [post-tool-use-check.mjs](post-tool-use-check.md)                                   | JS Module |

package/scripts/lib/discover-checkable-rules.mjs

@@ -51,6 +51,7 @@ async function listJsConcerns(jsDir) {
     if (!entry.isFile()) continue
     if (!entry.name.endsWith('.mjs')) continue
     if (entry.name.endsWith('.test.mjs')) continue
+    if (entry.name.startsWith('fix-')) continue
     if (entry.name.startsWith('_')) continue
     if (entry.name.startsWith('.')) continue
     const name = entry.name.slice(0, -'.mjs'.length)

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

@@ -3,167 +3,25 @@ type: JS Module
 title: discover-checkable-rules.mjs
 resource: npm/scripts/lib/discover-checkable-rules.mjs
 docgen:
-  crc: 39016d17
+  crc: 403ab2ee
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
 ---
 
-Модуль `discover-checkable-rules.mjs` — це discovery-шар для CLI-команди `fix`. Його завдання — швидко просканувати файлову структуру каталогу `npm/rules/` та виявити «прогонні» правила, тобто правила, у яких є щонайменше один JS-концерн або policy-концерн. Правила, які складаються тільки з декларативних артефактів (`.mdc` + `auto.md`) без жодного прогонного концерну, відсіюються.
+## Огляд
 
-Виокремлюються два типи концернів:
+Шукає правила, для яких є щось «прогонне» у визначених структурах. Виявляє JS-концерни за шляхами `rules/<id>/js/<concern>.mjs` та Policy-концерни, які мають пару з `<concern>.rego` (зв'язану з конфігурацією `target.json`). Ігнорує файли з префіксом `_` та `*.test.mjs`, а також каталоги `_lib/`. Виконання є швидким скануванням структури (шляхи та назви) без парсингу вмісту.
 
-- **JS concerns** — окремі файли `rules/<id>/js/<concern>.mjs`. Кожен файл — один концерн (flat-конвенція).
-- **Policy concerns** — підкаталоги `rules/<id>/policy/<concern>/`, у яких присутній файл `target.json` (поруч із якого зазвичай лежить `<concern>.rego`).
+## Поведінка
 
-Модуль свідомо не парсить вміст `target.json` і не читає JS-файли — це лише швидкий «структурний» скан (шляхи + назви) без I/O-вмісту. Парсинг покладено на runner.
+discoverOneRule описує набір JS-концернів та policy-концернів для одного каталогу правила, використовуючи шлях до цього каталогу та його ідентифікатор.
+discoverCheckableRules сканує каталог з усіма правилами та повертає список правил, які мають JS-концерни або policy-концерни, фільтруючи ті, що не містять прогонного контенту.
 
-Файли-помічники з префіксом `_` (зокрема каталог `_lib/`), тестові файли `*.test.mjs`, а також приховані файли/каталоги (`.`-префікс) ігноруються.
+## Публічний API
 
-Історичний контекст конвенції розкладки JS-концернів:
+discoverOneRule — створює об'єкт перевірки для одного каталогу правила.
+discoverCheckableRules — знаходити правила у каталозі `rules/`, які мають відповідні скрипти у `js/` або політики у `policy/`.
 
-- `js/<concern>/check.mjs` — версії 1.13.80–1.13.89 (вкладений каталог на концерн);
-- `js/<concern>.mjs` — версії 1.13.90+ (flat: концерн = файл, а не каталог).
+## Гарантії поведінки
 
-Допоміжні файли, тести, шаблони й дані винесені в окремі топ-level папки правила: `js/_lib/`, `tests/`, `templates/`, `data/`.
-
-## Експорти / API
-
-Модуль експортує дві асинхронні функції:
-
-| Експорт                                   | Тип                                                | Призначення                                                                                    |
-| ----------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| `discoverOneRule(ruleDir, ruleId)`        | `async (string, string) => Promise<CheckableRule>` | Будує опис одного правила за заданим шляхом каталогу та id, без обходу `rules/`.               |
-| `discoverCheckableRules(bundledRulesDir)` | `async (string) => Promise<CheckableRule[]>`       | Сканує цілий каталог `npm/rules/` і повертає масив правил, для яких є JS- або policy-концерни. |
-
-Внутрішніми (не експортованими) залишаються функції `listJsConcerns` і `listPolicyConcerns`.
-
-### Типи (JSDoc `@typedef`)
-
-```text
-JsConcern        { name: string }                                  // basename файла js/<name>.mjs без розширення
-PolicyConcern    { name: string }                                  // imʼя підкаталогу policy/<name>/
-CheckableRule    {
-                   id: string,                                     // = basename каталогу rules/<id>/
-                   jsConcerns: JsConcern[],                        // алфавітно
-                   policyConcerns: PolicyConcern[],                // алфавітно
-                 }
-```
-
-## Функції
-
-### `listJsConcerns(jsDir)` (internal)
-
-- **Сигнатура:** `async function listJsConcerns(jsDir: string): Promise<JsConcern[]>`
-- **Параметри:**
-  - `jsDir` — абсолютний шлях до каталогу `rules/<id>/js/`.
-- **Повертає:** масив `JsConcern[]`, відсортований алфавітно за `name` через `Array.prototype.toSorted` із компаратором `localeCompare`.
-- **Логіка:**
-  1. Якщо каталог `jsDir` не існує (`existsSync` повертає `false`) — повертається `[]`.
-  2. Читається вміст через `readdir(jsDir, { withFileTypes: true })` — тобто отримуються `Dirent`-обʼєкти з метаінформацією.
-  3. Пропускаються:
-     - сутності, що не є файлом (`!entry.isFile()`);
-     - файли без розширення `.mjs`;
-     - тестові файли `*.test.mjs`;
-     - службові файли з префіксом `_` (наприклад вміст `_lib/`, хоча сам `_lib` як каталог не буде файлом і відсіється раніше);
-     - приховані файли з префіксом `.`.
-  4. Для решти файлів обчислюється `name = entry.name.slice(0, -'.mjs'.length)` — basename без розширення.
-- **Side effects:** лише файлові читання (`existsSync`, `readdir`), без запису.
-
-### `listPolicyConcerns(policyDir)` (internal)
-
-- **Сигнатура:** `async function listPolicyConcerns(policyDir: string): Promise<PolicyConcern[]>`
-- **Параметри:**
-  - `policyDir` — абсолютний шлях до каталогу `rules/<id>/policy/`.
-- **Повертає:** масив `PolicyConcern[]`, відсортований алфавітно за `name`.
-- **Логіка:**
-  1. Якщо `policyDir` не існує — повертається `[]`.
-  2. Читається вміст з `withFileTypes: true`.
-  3. Пропускаються будь-які записи, що не є каталогом, а також приховані каталоги (префікс `.`).
-  4. Для кожного підкаталогу перевіряється наявність файла `target.json` через `existsSync(join(policyDir, entry.name, 'target.json'))`. Якщо `target.json` є — підкаталог зараховується як policy-концерн.
-- **Side effects:** лише файлові читання, без запису.
-
-### `discoverOneRule(ruleDir, ruleId)` (exported)
-
-- **Сигнатура:** `export async function discoverOneRule(ruleDir: string, ruleId: string): Promise<CheckableRule>`
-- **Параметри:**
-  - `ruleDir` — абсолютний шлях до каталогу правила `rules/<id>/`;
-  - `ruleId` — ідентифікатор правила, зазвичай `basename(ruleDir)`. Передається явно, бо функція не виводить його з шляху самостійно.
-- **Повертає:** обʼєкт `CheckableRule` з полями `id`, `jsConcerns`, `policyConcerns`. На відміну від `discoverCheckableRules`, тут не виконується фільтрація «має бути хоч щось» — повертається опис як є (можуть бути порожні масиви концернів).
-- **Логіка:** паралельно (точніше — послідовно `await`-ить) запускає `listJsConcerns(join(ruleDir, 'js'))` і `listPolicyConcerns(join(ruleDir, 'policy'))` та збирає результати в обʼєкт.
-- **Використання:** викликається `runStandardRule`-flow для per-rule entry-point, коли потрібно отримати опис конкретного правила, а не сканувати весь каталог.
-- **Side effects:** лише читання файлової системи.
-
-### `discoverCheckableRules(bundledRulesDir)` (exported)
-
-- **Сигнатура:** `export async function discoverCheckableRules(bundledRulesDir: string): Promise<CheckableRule[]>`
-- **Параметри:**
-  - `bundledRulesDir` — абсолютний шлях до кореневого каталогу всіх правил (зазвичай `npm/rules/`).
-- **Повертає:** масив `CheckableRule[]`, відсортований алфавітно за `id`. Включаються тільки правила, у яких `jsConcerns.length > 0 || policyConcerns.length > 0`.
-- **Логіка:**
-  1. Якщо `bundledRulesDir` не існує — повертається `[]`.
-  2. Читається вміст каталогу з `withFileTypes: true`.
-  3. Пропускаються сутності, які не є каталогом, та приховані каталоги (префікс `.`).
-  4. Для кожного підкаталогу формується `ruleDir = join(bundledRulesDir, entry.name)` і викликається `discoverOneRule(ruleDir, entry.name)`.
-  5. Правила, у яких немає жодного JS- або policy-концерну (декларативні-only), відсіюються.
-- **Side effects:** лише читання файлової системи (без запису, без мережевих викликів).
-
-## Залежності
-
-Виключно зовнішні стандартні модулі Node.js:
-
-- `node:fs` → `existsSync` — синхронна перевірка існування шляху;
-- `node:fs/promises` → `readdir` — асинхронне читання вмісту каталогу (з `withFileTypes: true` повертає `Dirent[]`);
-- `node:path` → `join` — кросплатформова конкатенація шляхів.
-
-Внутрішніх імпортів з інших модулів проєкту немає. Це робить модуль чистим discovery-шаром без бізнес-логіки, що дозволяє безпечно його тестувати ізольовано (потрібна лише підготовлена файлова структура у тимчасовому каталозі).
-
-Зворотні залежності (хто використовує цей модуль): runner-флоу CLI `fix` (зокрема `runStandardRule`), який після discovery читає `target.json` для policy-концернів і виконує JS-концерни.
-
-## Потік виконання / Використання
-
-### Типовий сценарій 1. Повний скан правил для CLI `fix`
-
-```javascript
-import { discoverCheckableRules } from './discover-checkable-rules.mjs'
-
-const rules = await discoverCheckableRules('/abs/path/to/npm/rules')
-for (const rule of rules) {
-  // rule.id, rule.jsConcerns, rule.policyConcerns
-}
-```
-
-Послідовність дій усередині:
-
-1. `discoverCheckableRules` перевіряє існування кореневого каталогу.
-2. Перебирає підкаталоги верхнього рівня (= потенційні правила).
-3. Для кожного підкаталогу викликає `discoverOneRule`, який своєю чергою:
-   - сканує `rules/<id>/js/` через `listJsConcerns`;
-   - сканує `rules/<id>/policy/` через `listPolicyConcerns`;
-4. Якщо знайдено хоч один концерн — правило додається у вихідний масив.
-5. Масив сортується за `id`.
-
-### Типовий сценарій 2. Per-rule entry-point
-
-```javascript
-import { discoverOneRule } from './discover-checkable-rules.mjs'
-
-const rule = await discoverOneRule('/abs/path/to/npm/rules/n-js', 'n-js')
-// rule.id === 'n-js'
-// rule.jsConcerns — список JS-концернів у js/
-// rule.policyConcerns — список policy-концернів у policy/
-```
-
-Цей шлях оминає енумерацію всього `rules/`, що корисно коли id правила вже відомий (наприклад, передано аргументом CLI).
-
-### Гарантії та обмеження
-
-- **Чистота:** функції — read-only (не пишуть у ФС, не виконують код концернів). Це дозволяє безпечно викликати їх повторно.
-- **Сортування:** усі результати алфавітно відсортовані через `toSorted` із `localeCompare`. Це робить вивід детермінованим між запусками й між платформами (хоч порядок `readdir` залежить від ФС).
-- **Толерантність до відсутніх каталогів:** будь-яка з директорій (`rules/`, `js/`, `policy/`) може бути відсутня — повертається порожній масив без помилки.
-- **Тести/хелпери:** файли з префіксом `_` і `*.test.mjs` гарантовано виключаються із JS-концернів.
-- **Що _не_ робиться:** не валідуються імена концернів, не парситься `target.json`, не перевіряється наявність `<name>.rego` поруч із `target.json`. Це робота runner-а.
-
-### Eage cases
-
-- Файл з префіксом `.` у `js/` — пропускається.
-- Підкаталог у `js/` (наприклад `_lib/`) — не є файлом, відсіюється першою перевіркою `entry.isFile()`.
-- Підкаталог у `policy/` без `target.json` — пропускається; наявність `<name>.rego` без `target.json` не зараховується.
-- Порожнє правило (тільки `.mdc`/`auto.md` без `js/` і `policy/`) — не потрапляє у вихід `discoverCheckableRules`, але буде повернене з порожніми масивами в `discoverOneRule`.
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/fix/discover-t0-patterns.mjs

@@ -0,0 +1,83 @@
+/**
+ * Discovery T0-autofix паттернів з rule-level `fix-*.mjs` файлів.
+ *
+ * Сканує `npm/rules/{rule}/js/fix-*.mjs` і `npm/rules/{rule}/policy/{concern}/fix-*.mjs`
+ * по всіх правилах, динамічно імпортує кожен і збирає масиви `patterns`.
+ * `t0.mjs` ініціалізує результат через top-level await (один раз при завантаженні модуля).
+ */
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * @typedef {{ id: string, test: (output: string) => boolean, apply: (output: string, cwd: string) => Promise<{ok: boolean, action: string}> | {ok: boolean, action: string} }} T0Pattern
+ */
+
+/**
+ * Повертає абсолютні шляхи до `fix-*.mjs` файлів у директорії (плоско, без рекурсії).
+ * @param {string} dir абсолютний шлях до директорії
+ * @returns {Promise<string[]>}
+ */
+async function findFixFiles(dir) {
+  if (!existsSync(dir)) return []
+  const entries = await readdir(dir, { withFileTypes: true })
+  return entries
+    .filter(e => e.isFile() && e.name.startsWith('fix-') && e.name.endsWith('.mjs'))
+    .map(e => join(dir, e.name))
+}
+
+/**
+ * Повертає абсолютні шляхи до `policy/{concern}/fix-*.mjs` у правилі.
+ * @param {string} policyDir абсолютний шлях `rules/{rule}/policy/`
+ * @returns {Promise<string[]>}
+ */
+async function findPolicyFixFiles(policyDir) {
+  if (!existsSync(policyDir)) return []
+  const entries = await readdir(policyDir, { withFileTypes: true })
+  const paths = []
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    paths.push(...(await findFixFiles(join(policyDir, entry.name))))
+  }
+  return paths
+}
+
+/**
+ * Збирає всі T0-паттерни з `fix-*.mjs` файлів усіх правил у `rulesDir`.
+ * @param {string} rulesDir абсолютний шлях до `npm/rules/`
+ * @returns {Promise<T0Pattern[]>} об'єднаний масив паттернів
+ */
+export async function discoverT0Patterns(rulesDir) {
+  if (!existsSync(rulesDir)) return []
+  const ruleEntries = await readdir(rulesDir, { withFileTypes: true })
+  /** @type {T0Pattern[]} */
+  const allPatterns = []
+
+  for (const ruleEntry of ruleEntries) {
+    if (!ruleEntry.isDirectory() || ruleEntry.name.startsWith('.')) continue
+    const ruleDir = join(rulesDir, ruleEntry.name)
+
+    const fixPaths = [
+      ...(await findFixFiles(join(ruleDir, 'js'))),
+      ...(await findPolicyFixFiles(join(ruleDir, 'policy')))
+    ]
+
+    for (const fixPath of fixPaths) {
+      try {
+        const mod = await import(fixPath)
+        if (Array.isArray(mod.patterns)) allPatterns.push(...mod.patterns)
+      } catch (err) {
+        console.error(`[discover-t0-patterns] не вдалося імпортувати ${fixPath}: ${err.message}`)
+      }
+    }
+  }
+
+  // Дедуплікація за id: shared утиліти (напр. vscode-ext-add) re-export'яться з ≥2 правил
+  // і потрапляють у список кілька разів — залишаємо перше входження.
+  const seen = new Set()
+  return allPatterns.filter(p => {
+    if (seen.has(p.id)) return false
+    seen.add(p.id)
+    return true
+  })
+}

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

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

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

@@ -3,27 +3,29 @@ type: JS Module
 title: llm-fix-apply.mjs
 resource: npm/scripts/lib/fix/llm-fix-apply.mjs
 docgen:
-  crc: 62e475fa
+  crc: 49f989ca
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль є спільним ядром для застосування виправлень, згенерованих LLM, використовуючи конформні (`llm-worker.mjs`) та інструментальні (`llm-lint-fix.mjs`) механізми для уникнення дублювання логіки парсингу та застосування змін. Він парсить структуровану відповідь моделі, що містить список змін у форматі `{changes:[{path,content}]}`. Далі, він зчитує вміст файлів, зазначених у цих змінах, та застосовує оновлений вміст до відповідних файлів. Усі операції реалізовані з механізмом fail-safe: при невдачах функції повертають значення помилки (false/null/Err) замість викидання винятків.
+## Огляд
+
+Це спільне ядро LLM-фіксу, призначене для оркестрації процесу застосування змін, згенерованих моделлю. Модуль використовує `llm-worker.mjs` та `llm-lint-fix.mjs` для забезпечення конформності та виконання лінтер-фіксів. Основний функціонал включає: парсинг відповіді LLM за схемою `{changes:[{path,content}]}` (через `parseChangesResponse`), зчитування необхідних файлів (`readFilesForFix`), та безпечне застосування змін (`applyChanges`). Система реалізує механізм fail-safe, перехоплюючи помилки та повертаючи `null` замість винятків для певних сценаріїв. При цьому шляхи `.git` та `node_modules` свідомо ігноруються.
 
 ## Поведінка
 
-parseChangesResponse парсить сирий текст відповіді моделі, щоб витягнути структуру змін у форматі патчу або повернути null у разі невдачі парсингу.
-readFilesForFix зчитує вміст файлів, зазначених у списку відносних шляхів, відносно кореня проєкту, повертаючи список об'єктів з шляхом та вмістом або null для неіснуючих файлів.
-applyChanges записує нові вмісти в файли, використовуючи наданий список змін, відносно кореня проєкту; перед записом створює батьківську теку (`mkdirSync recursive`) — модель може запропонувати новий файл у ще неіснуючому каталозі. Повертає статус успіху або помилки.
+parseChangesResponse парсить сирий текст відповіді моделі, витягуючи структуру змін у форматі патчу, або повертає null, якщо парсинг неможливий.
+readFilesForFix читає вміст файлів, вказаних у списку, відносно кореня проєкту. Якщо прямий шлях не знайдено, шукає файл за його базовим ім'ям у проєкті, ігноруючи каталоги `.git` та `node_modules`.
+applyChanges записує вміст, наданий у змінних, у відповідні файли проєкту, створюючи необхідні каталоги, якщо вони відсутні.
 
 ## Публічний API
 
-parseChangesResponse — витягує структуру змін із JSON-відповіді моделі.
-readFilesForFix — зчитує вміст файлів за заданими шляхами для використання у запиті.
-applyChanges — замінює вміст файлів на нові дані, отримані у змінних змін.
+parseChangesResponse — розбирає JSON-відповідь моделі, витягуючи вміст першого об'єкта.
+readFilesForFix — зчитує вміст файлів за заданими шляхами, шукаючи їх у системі, якщо прямий шлях не знайдено.
+applyChanges — замінює вміст файлів на новий, наданий у змінній `changes`.
 
 ## Гарантії поведінки
 
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

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

@@ -3,32 +3,24 @@ type: JS Module
 title: llm-worker.mjs
 resource: npm/scripts/lib/fix/llm-worker.mjs
 docgen:
-  crc: d6c0b516
+  crc: 55419474
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
 ## Огляд
 
-Модуль взаємодіє з мовною моделлю для обробки правил та файлів. Він формує запит до моделі, отримує пропозиції щодо змін, які не застосовуються до файлової системи. Функція обробки гарантує перехоплення помилок (fail-safe) та не генерує винятків назовні.
+Модуль виділяє унікальні відносні шляхи файлів, пов'язаних із порушеннями. Він також виконує роботу з великою мовною моделлю для аналізу даних про порушення, зчитуючи правила та обробляючи відповідні файли.
 
 ## Поведінка
 
-1. Викликає runLlmWorker для виправлення однієї проблеми.
-2. Зчитує вміст відповідного файлу правила.
-3. Витягує шляхи до файлів, які порушені, з вихідних даних про порушення.
-4. Зчитує вміст цих файлів.
-5. Формує повний текстовий запит для моделі, включаючи правило, вихідні дані про порушення, вміст файлів та, за наявності, контекст попередньої спроби.
-6. Відправляє цей запит моделі.
-7. У разі помилки при виклику моделі, повертає статус невдачі з деталями помилки.
-8. Якщо модель відповідає, парсить її відповідь, щоб отримати діагноз та список змін.
-9. У разі неможливості розібрати відповідь або відсутності змін, повертає статус невдачі.
-10. Якщо зміни успішно отримані, застосовує ці зміни до файлової системи проєкту.
-11. Повертає результат, що містить статус успіху, список застосованих змін, діагноз та метадані про запит.
+extractFilePaths витягує унікальні відносні шляхи файлів із вихідних даних про порушення, розпізнаючи як явні файли, що потребують виправлення, так і файли, що надають контекст.
+runLlmWorker викликає LLM для виправлення одного порушення, зчитує відповідне правило, аналізує файли, формує промпт, отримує відповідь від моделі та застосовує виправлення.
 
 ## Публічний API
 
-runLlmWorker — виправляє одне порушення правила, використовуючи шаблон C1. Повертає результати виправлення чи діагнозу незалежно від успіху, що дозволяє наступним етапам системи отримувати інформацію про спробу. Поля про міркування та підсумок запиту використовуються для детального виводу в режимі `--full`. Дозволяє перевизначити модель, передати контекст попередніх спроб, позначити джерело виклику та встановити ліміти часу для кожного рівня виконання. Керує обсягом токенів, доступних для процесу мислення.
+extractFilePaths — виділяє відносні шляхи файлів з виводу помилок, обробляючи префікс робочого простору та пріоритетно парсячи рядки, що вказують на необхідність виправлення.
+runLlmWorker — виправляє одне порушення правила за допомогою LLM, повертаючи результати змін чи діагнозу, що слугує інформацією для наступних етапів процесу.
 
 ## Гарантії поведінки
 

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

@@ -8,8 +8,6 @@ docgen:
   score: 100
 ---
 
-## Огляд
-
 Модуль відповідає за управління процесом вирішення порушень. Він будує послідовність тирів ескалації за допомогою `buildLadder`. Функція `parseOrchestratorArgs` визначає бюджет LLM та фільтр правил. Далі, `runOrchestratorCli` виконує процес виправлення правил, послідовно застосовуючи `escalateRule` по тирах до досягнення першого успішного вирішення.
 
 ## Поведінка

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

@@ -3,26 +3,27 @@ type: JS Module
 title: t0.mjs
 resource: npm/scripts/lib/fix/t0.mjs
 docgen:
-  crc: cfb0d5c9
+  crc: 92c9348d
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль керує автоматичним застосуванням паттернів T0-auto до виводів порушень. Він використовує конфігурації з `extensions.json` та `package-lock.json` для визначення правил. Модуль фільтрує правила, які можуть бути автоматично оброблені, застосовує паттерни за допомогою `applyT0Auto`, а потім запускає повний цикл перевірки для всіх провальних правил через `runT0AutoCli`. Усі операції виконуються з механізмом fail-safe, що запобігає виникненню винятків назовні.
+## Огляд
+
+Модуль забезпечує механізм автоматичного застосування паттернів T0-auto. Він дозволяє відфільтровувати правила, до яких застосовуються ці паттерни, та запускає повний цикл перевірки конформності з автоматичним виправленням через `runT0AutoCli`.
 
 ## Поведінка
 
-Поведінка
-applyT0Auto застосовує всі визначені T0-auto паттерни до одного виводу порушення, повертаючи результат застосування та список виконаних дій.
-filterT0AutoRules повертає список ID правил, для яких існує хоча б один T0-auto паттерн, виходячи з виводу порушення.
-runT0AutoCli запускає T0-auto для всіх провальних правил, повторно перевіряє конформність та виводить підсумок щодо закритого чи незакритого порушень.
+applyT0Auto застосовує всі T0-auto паттерни до одного виявленого порушення, повертаючи результат застосування та список виконаних дій.
+filterT0AutoRules повертає список ID правил, для яких існують відповідні T0-auto паттерни, виходячи з виявлених порушень.
+runT0AutoCli запускає процес T0-auto: виконує перевірку конформності, застосовує T0-auto до порушень, повторно перевіряє змінені правила та виводить підсумок.
 
 ## Публічний API
 
-applyT0Auto — вносить зміни до виводу порушень, використовуючи всі визначені T0-auto шаблони.
-filterT0AutoRules — визначає, які правила мають відповідні T0-auto шаблони, аналізуючи вивід порушень, отриманий з `fix --json`.
-runT0AutoCli — виконує команду `n-cursor fix-t0 [rule...]`, що включає застосування T0-auto до кожного порушення, повторну перевірку check-gate та виведення результату.
+applyT0Auto — застосовує всі T0-auto шаблони до вихідних даних про порушення.
+filterT0AutoRules — визначає і повертає ідентифікатори правил, які мають принаймні один T0-auto шаблон, виходячи з результату `fix --json`.
+runT0AutoCli — виконує команду `n-cursor fix-t0 [rule...]`, яка запускає `fix --json`, застосовує T0-auto до кожного порушення, повторно перевіряє check-gate та виводить звіт.
 
 ## Гарантії поведінки
 
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/fix/docs/vscode-ext-add.md

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: vscode-ext-add.mjs
+resource: npm/scripts/lib/fix/vscode-ext-add.mjs
+docgen:
+  crc: 950e9098
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Реалізує Shared T0-autofix паттерн для правил із `vscode_extensions.rego`. Механізм витягує назви розширень із повідомлень про порушення та додає їх до секції `recommendations` у конфігурації `.vscode/extensions.json`, якщо вони відсутні. Паттерн універсальний для правил, що емітують вимогу «recommendations має містити "…"». Функціональність надається через публічні функції `patterns` та забезпечує перехоплення помилок для запобігання виняткам.
+
+## Поведінка
+
+1. Перевіряє, чи повідомлення про порушення містить шаблон, що вказує на необхідність додати рекомендації.
+2. Витягує назви розширень з повідомлення про порушення.
+3. Перевіряє наявність файлу `.vscode/extensions.json` у поточній робочій директорії.
+4. Зчитує вміст `.vscode/extensions.json` та парсить його як JSON.
+5. Ініціалізує список існуючих рекомендацій.
+6. Визначає назви розширень, які потрібно додати, відфільтровувавши ті, що вже присутні.
+7. Якщо є розширення для додавання, оновлює список рекомендацій у парсереному об'єкті.
+8. Записує оновлений JSON-об'єкт назад у `.vscode/extensions.json`.
+9. Повертає результат виконання операції.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).