@nitra/cursor 3.27.0 → 3.28.0

package/skills/docgen/js/docs/docgen-extract.md

@@ -0,0 +1,28 @@
+# docgen-extract.mjs
+
+## Огляд
+
+Файл `extractFacts` витягує інформацію про поведінку коду, формуючи об'єкт "факт-лист". Цей факт-лист використовується Stage 1 docgen-конвеєра для створення точкових промптів. Функція є ключовою частиною детермінованого процесу генерації документації, виключаючи використання великих мовних моделей.
+
+## Поведінка
+
+1.  **Обробка даних:** Система аналізує код, витягуючи інформацію про експортовані функції, імпорти та їхні описи.
+2.  **Ідентифікація відхилень:** Система визначає, чи використовується код для виконання операцій, які можуть призвести до помилок, наприклад, запис у файли, створення директорій, видалення файлів, обробка мережевих запитів або використання try/catch блоків.
+3.  **Виявлення пропущених шляхів:** Система виявляє, чи використовується код для обробки певних шляхів файлів, таких як `.github`, `.git`, `node_modules` або `base/`, `ua/`, `.firebase`.
+4.  **Визначення кешування:** Система визначає, чи використовується код для кешування даних, наприклад, за допомогою Map або Cache.
+5.  **Визначення відсутності обробки помилок:** Система визначає, чи використовується код для обробки помилок, наприклад, за допомогою try/catch блоків.
+6.  **Визначення мережевих операцій:** Система визначає, чи використовується код для виконання мережевих операцій, наприклад, за допомогою fetch або axios.
+7.  **Вихідні дані:** Система надає вихідні дані у вигляді об'єкта, що містить витягнуту інформацію про код, а також виявлені відхилення та пропущені шляхи.
+
+## Публічний API
+
+extractFacts — Витягує факти з коду файлу, представляючи їх у вигляді списку.
+
+## Гарантії поведінки
+
+- Екстрагує з коду список фактів.
+- Повертає об'єкт з витягнутими фактами.
+- Не викликає винятків при невдачі.
+- Кешує результати для одного прогону.
+- Не використовує мережу.
+- Не обробляє файли/каталоги .github, .git, node_modules, base/, ua/, .firebase.

package/skills/docgen/js/docs/docgen-gen.md

@@ -0,0 +1,41 @@
+# docgen-gen.mjs
+
+## Огляд
+
+Цей файл генерує документацію на основі коду, використовуючи конвеєр обробки. Він автоматично створює Markdown-файли, що містять опис коду, використовуючи декілька етапів, включаючи вилучення фактів та створення текстових описів. Ця функція є ключовою частиною системи документування, забезпечуючи автоматизований та послідовний процес створення документації.
+
+## Поведінка
+
+1.  Модуль визначає основну функцію `generateDoc`, яка приймає код джерела та налаштовує параметри для генерації документації.
+2.  Вхідний код обробляється для вилучення ключових фактів про функціональність модуля, включаючи назви функцій та їх призначення.
+3.  Вилучені факти використовуються для оцінки якості документації, зокрема, перевіряється, чи опис відповідає реальній поведінці модуля.
+4.  Оцінка якості здійснюється за допомогою декількох критеріїв: опис має бути чітким та описовим, а поведінка – узгодженою з кодом.
+5.  Якщо оцінка якості низька, використовується хмарний сервіс Claude для перевірки документації та надання рекомендацій щодо покращення.
+6.  У випадку, коли оцінка якості висока, генерується документ, який містить огляд модуля, його поведінку, API та гарантії поведінки.
+7.  Документація форматується у Markdown, з використанням фіксованого набору заголовків та розділів.
+8.  Під час генерації документації враховуються можливі пропуски в інформації про шляхи, що може вплинути на оцінку якості.
+9.  Використовується хмарний сервіс Claude для оцінки якості документації та надання рекомендацій щодо покращення.
+10. Генерується документ, який містить огляд модуля, його поведінку, API та гарантії поведінки.
+
+## Публічний API
+
+- generateDoc — Генерує документацію з файлу, включаючи метадані, токени, оцінки, проблеми та рівень.
+- Routing (sym-threshold) — Розподіляє обробку на основі значення символу, визначаючи рівень (Tier) та тип рефері (Haiku або без хмарного рефері).
+  - sym < BORDERLINE_SYM_LOW — Tier 1 без хмарного рефері.
+  - sym ∈ [BORDERLINE_SYM_LOW, symThreshold) — Tier 1 з хмарним рефері (Haiku).
+  - sym >= symThreshold — Відразу Tier 2.
+  - scoreCloud=true — Автоматично запускає хмарний рефері для всіх Tier 1.
+
+## Гарантії поведінки
+
+- Конвеєр завжди генерує .md-документацію на основі вхідного коду.
+- Конвеєр використовує інверсію керування, де JS-код визначає весь процес.
+- Stage 0 (extractFacts) не впливає на вихідну документацію.
+- Stage 1 (sectionInstructions) генерує точкові промпти для кожної секції коду.
+- Stage 2 (stripSignatures) завжди видаляє інформацію про сигнатури.
+- Stage 2.5 (scoreDoc) оцінює документацію за фактами.
+- Stage 3 (assemble) збирає документацію з фіксованими заголовками та порядком.
+- При низькому балі скорингу (claudeOneShot) використовується хмарний сервіс для перефразування.
+- При сим-значенні нижче BORDERLINE_SYM_LOW, документація генерується локально без використання хмарного рефері.
+- При сим-значенні між BORDERLINE_SYM_LOW та DEFAULT_SYM_THRESHOLD, документація генерується локально та оцінюється за допомогою cloudScoreDoc (Haiku).
+- При сим-значенні, що перевищує DEFAULT_SYM_THRESHOLD, документація генерується безпосередньо, без локальної оцінки

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

@@ -0,0 +1,24 @@
+# docgen-ignore.mjs
+
+## Огляд
+
+Цей файл містить список глобальних файлів, які `docgen` ігнорує під час генерації документації. Він використовується для визначення, які файли не потрібно аналізувати, забезпечуючи ефективність процесу генерації та запобігаючи включенню нерелевантної інформації. Цей список є основою для predicate, який scanner використовує для визначення, чи потрібно читати певний файл.
+
+## Поведінка
+
+DOCGEN_IGNORE_GLOBS: визначає список глобів, які `docgen` ігнорує.
+isDocgenIgnored: перевіряє, чи шлях має бути пропущений `docgen`, використовуючи глоби.
+
+## Публічний API
+
+- DOCGEN_IGNORE_GLOBS — Список glob-ів, які ігнорує `docgen`.
+- isDocgenIgnored — Перевіряє, чи потрібно пропустити шлях під час генерації документації.
+
+## Гарантії поведінки
+
+- `DOCGEN_IGNORE_GLOBS` завжди ігнорує певний набір шляхів.
+- `isDocgenIgnored` повертає `true` якщо шлях ігнорується.
+- Шляхи `.git` та `node_modules` завжди ігноруються.
+- Файл є read-only.
+- У разі невдачі повертає `false` або `null`.
+- Результат прогону кешується для подальшого використання.

package/skills/docgen/js/docs/docgen-prompts.md

@@ -0,0 +1,24 @@
+# docgen-prompts.mjs
+
+## Огляд
+
+Цей файл містить опис коду для конвеєра docgen. Він визначає точкові промпти для кожної секції коду, що генерується. Це дозволяє ефективно генерувати документацію на основі коду.
+
+## Поведінка
+
+Напиши вміст секції «Поведінка»: для кожної публічної функції — один короткий пункт «що вона робить». Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex. Без заголовка.
+
+## Публічний API
+
+- STYLE — Підготовка документації на першому етапі генерації: створення факт-листа та коду, а потім генерація точкових промптів для кожної секції.
+- v2 — Мінімальний контекст секції: код розміщується лише в `Поведінку`. `Огляд` містить лише заголовок, `API` – список експортів, `Гарантії` – маркери. Це дозволяє один раз обробити інсульт коду, а не секцію за секцією.
+- sectionMessages — Набори повідомлень для кожної секції з мінімальним контекстом. Код розміщується лише в `Поведінку`, решта – на факт-листи.
+- oneShotMessages — База повідомлень для порівняння.
+- oneShotPromptText — Текст user-промпту для one-shot (для резервного копіювання в хмарі через Anthropic SDK).
+
+## Гарантії поведінки
+
+- `docgen-конвеєр` кешує результати генерації промптів для кожної секції.
+- `Огляд` містить лише заголовок секції.
+- `API` містить лише список експортів секції.
+- `Гарантії` містять лише маркери.

package/skills/docgen/js/docs/docgen-scan.md

@@ -0,0 +1,48 @@
+# docgen-scan.mjs
+
+## Огляд
+
+`docgen scanner` обходить проєкт, щоб створити JSON-список кодових файлів, розташованих у теці `docs/` поряд із джерелом. Цей список використовується іншими скілами для генерації документації. Інструмент забезпечує детермінований обхід проєкту та відстежує наявність файлів, не використовуючи мережеві ресурси чи LLM.
+
+## Поведінка
+
+- `isSourceFile`: Перевіряє, чи файл є джерелом коду, враховуючи розширення та тестові файли.
+- `docPathForSource`: Генерує шлях до файлу документації для заданого джерела, враховуючи відносні шляхи.
+- `scanForDocgen`: Рекурсивно обходить дерево проєкту, визначаючи кодові файли, які потрібно документувати, та їх відповідні шляхи до документації.
+- `slugForModule`: Генерує унікальний slug для модуля на основі його відносного шляху.
+- `findModuleRoots`: Знаходить абсолютні шляхи коренів модулів проєкту.
+- `nearestModuleRoot`: Знаходить найближчий модуль-предок для заданого файлу.
+- `scanForModules`: Лістить модулі проєкту, визначаючи їхні члени (sourcePath-и) та шляхи до документації.
+- `resolveRoot`: Визначає абсолютний корінь проєкту на основі аргументів командного рядка.
+- `runDocgenScanCli`: Запускає сканування docgen як CLI, виводить JSON-масив у stdout та повертає код виходу.
+- `runDocgenModulesCli`: Запускає сканування модулів docgen як CLI, виводить JSON-масив у stdout та повертає код виходу.
+
+## Публічний API
+
+- isSourceFile — Визначає, чи є файл кодовим джерелом для створення документації.
+- docPathForSource — Генерує шлях до md-файлу, пов'язаний з кодовим файлом.
+- scanForDocgen — Рекурсивно обстежує структуру проєкту, виявляючи файли для документування.
+- slugForModule — Створює унікальний ідентифікатор (slug) для модуля на основі його шляху.
+- findModuleRoots — Знаходить корені модулів, визначаючи директорії з файлом `package.json`.
+- nearestModuleRoot — Визначає найближчий модуль-предок для заданого файлу.
+- scanForModules — Створює список логічних модулів проєкту, включаючи файли та інформацію про них.
+- resolveRoot — Встановлює базову директорію для сканування, використовуючи аргумент командного рядка або поточну директорію.
+- runDocgenScanCli — Запускає сканування для виявлення файлів документації та виводить результат у форматі JSON.
+- runDocgenModulesCli — Запускає сканування модулів та виводить результат у форматі JSON.
+
+## Гарантії поведінки
+
+- `isSourceFile` повертає `true`, якщо вказаний шлях до файлу є джерелом коду.
+- `isSourceFile` повертає `false` в іншому випадку.
+- `docPathForSource` повертає шлях до відповідної папки `docs/` для вказаного джерела.
+- `scanForDocgen` повертає JSON-список шляхів до кодових файлів, які потрібно обробити.
+- `scanForDocgen` встановлює прапор `exists` у випадку, якщо файл або папка вже існують.
+- `slugForModule` повертає унікальний URL-шлях для модуля.
+- `findModuleRoots` повертає список кореневих модулів проєкту.
+- `nearestModuleRoot` повертає найближчий кореневий модуль до вказаного шляху.
+- `scanForModules` повертає список модулів проєкту.
+- `resolveRoot` повертає кореневу папку проєкту.
+- `runDocgenScanCli` запускає процес сканування для `docgen`.
+- `runDocgenModulesCli` запускає процес сканування для модулів.
+- У разі невдачі повертається `false` та `null`.
+-

package/skills/fix/js/docs/llm-worker.md

@@ -0,0 +1,27 @@
+# llm-worker.mjs
+
+## Огляд
+
+Цей файл є LLM-робітником, який збирає контекст для n-fix оркестратора, зокрема правила з файлів .mdc та звіти про порушення. Він передає цей контекст великій мовній моделі (LLM) для генерації JSON з пропозиціями змін. Після отримання змін, скрипт застосовує їх до відповідних ресурсів.
+
+## Поведінка
+
+runLlmWorker: Виправляє одне rule-порушення через pi (C1 pattern). Збирає контекст з rule .mdc, файлів з violation output, та передає його в pi для отримання JSON зі змінами. Застосовує зміни, якщо вони були отримані від pi. Якщо pi не повернув JSON, або не зміг застосувати зміни, повертає помилку. Використовує модель Claude HAIKU за замовчуванням, або модель, вказану в опціях.
+
+## Публічний API
+
+MODEL_HAIKU — Генерує короткі вірші.
+MODEL_SONNET — Генерує вірші у форматі сонету.
+runLlmWorker — Виправляє порушення правил, використовуючи pi (C1 pattern).
+
+## Гарантії поведінки
+
+- Приймає контекст з файлів `.mdc` та файлів з violation.
+- Повертає JSON з пропозиціями змін.
+- Застосовує зміни, отримані від `pi`.
+- Використовує LLM для генерації змін.
+- Викликає LLM через `pi`.
+- Не використовує tool-use.
+- Не кидає винятків.
+- У разі невдачі повертає `false` та `null`.
+- Не використовує кешування.

package/skills/fix/js/docs/orchestrator.md

@@ -0,0 +1,32 @@
+# orchestrator.mjs
+
+## Огляд
+
+Файл `convergence-loop` є автономним оркестратором для n-fix, який забезпечує перевірку та виправлення коду без участі LLM. Він ініціює детерміністичні перевірки, regex-парсинг та ітеративні процеси з використанням LLM для вирішення складних проблем. Цей компонент є ключовим елементом системи, що автоматизує процес забезпечення коректності коду n-fix.
+
+## Поведінка
+
+1.  **Ініціалізація:** Запускається оркестратор, визначаються максимальна кількість ітерацій (за замовчуванням 3) та порогове значення для ескалації LLM (за замовчуванням 2 невдачі).
+2.  **Первинна перевірка:** Виконується детермінована перевірка (T0) на основі заданих правил, без залучення LLM. Результат перевірки записується.
+3.  **Автоматичний фікс (T0-auto):** Якщо перевірка виявила порушення, запускається автоматичний фікс, який використовує regex для виявлення та виправлення проблем.
+4.  **Ітерація:** Програма повторює наступні кроки до досягнення максимальної кількості ітерацій:
+    - **Перевірка (T0):** Виконується детермінована перевірка (T0) на основі поточного стану.
+    - **Автоматичний фікс (T0-auto):** Якщо перевірка виявила порушення, запускається автоматичний фікс.
+    - **Виклик LLM (T1):** Для кожного порушення, яке не було виправлено автоматичним фіксом, викликається LLM (haiku або sonnet, залежно від кількості попередніх невдач) для генерації рішення.
+    - **Оцінка рішення LLM:** LLM генерує рішення, яке оцінюється на предмет успіху.
+    - **Оновлення стану:** Якщо рішення LLM успішне, порушення виправляється, і кількість невдалих спроб LLM для цього правила встановлюється на нуль.
+5.  **Фінальна перевірка:** Після завершення всіх ітерацій виконується остаточна перевірка, щоб визначити, чи були виправлені всі порушення.
+6.  **Повернення результату:** Оркестратор повертає код 0, якщо всі правила були виправлені, і код 1, якщо хоча б одне правило залишилося не виправленим. У випадку помилки парсингу JSON, повертається null.
+
+## Гарантії поведінки
+
+- Оркестратор запускається при виклику `runOrchestratorCli`.
+- Програма виконує цикл з перевірок, поки не буде досягнуто максимальну кількість ітерацій (`maxIter`).
+- Після кожної ітерації (`T0`, `T0-auto`, `T1`) виконується перевірка.
+- `T0` виконується детерміновано без використання LLM.
+- `T0-auto` виконує regex-парсинг та застосовує програмний фікс у разі виявлення порушення.
+- `T1` використовує LLM через `pi` (ескалація до `haiku` та `sonnet`).
+- `check-gate` повторно запускає `T0` після кожної ітерації.
+- У разі помилки програма повертає `false` або `null`.
+- Програма кешує результати для оптимізації роботи в межах одного запуску.
+- Програма не взаємодіє з мережею.

package/skills/fix/js/docs/t0.md

@@ -0,0 +1,29 @@
+# t0.mjs
+
+## Огляд
+
+Файл `t0-auto` забезпечує детермінований рівень виправлень для n-fix оркестратора, автоматично застосовуючи програмні фікси на основі аналізу вихідних даних `n-cursor fix --json`. Він парсить повідомлення про порушення, видобуваючи з них інформацію про цільові файли або рядки для вставки, і застосовує відповідні фікси. Це дозволяє швидко та передбачувано виправляти помилки, не використовуючи LLM, і є першим етапом у конвергентному циклі виправлення.
+
+## Поведінка
+
+applyT0Auto: Застосовує всі T0-auto паттерни до вхідного `violationOutput` та повертає об'єкт, що вказує, чи застосовано фікс, та список виконаних дій.
+filterT0AutoRules: Повертає список id правил, для яких є хоч один T0-auto паттерн, на основі `failedRules`.
+runT0AutoCli: Запускає `n-cursor fix --json`, застосовує T0-auto, повторно перевіряє check-gate та виводить підсумок. Повертає 0 у разі успіху, 1 у разі помилки.
+
+## Публічний API
+
+- applyT0Auto — Застосовує автоматичні правила виправлення до виявлених проблем.
+- filterT0AutoRules — Визначає ідентифікатори правил, які мають T0-auto паттерни.
+- runT0AutoCli — Запускає CLI-інструмент для автоматичного виправлення, включаючи перевірку та звітність.
+
+## Гарантії поведінки
+
+- `applyT0Auto` застосовує програмний фікс, якщо `violationOutput` містить інформацію, яку можна видобути за допомогою регулярних виразів, і `violation-message` містить цільове значення, що відповідає одному з ідентифікаторів правил T0-auto. Результат: `applied` - boolean, `actions` - string[] (список виконаних дій).
+- `listT0AutoRules` повертає список ідентифікаторів правил T0-auto, які мають хоча б один паттерн.
+- `runT0AutoCli` повертає код виходу 0, якщо процес виконано успішно, і 1, якщо виявлено порушення.
+- T0-auto запускається першим у конвергентному циклі.
+- T1 запускається лише для решти.
+- Система перехоплює помилки та не кидає винятки.
+- В системі немає кешування.
+- Вхідні дані `applyT0Auto` повинні відповідати формату JSON, вихідному від `n-cursor fix --json`.
+- Якщо `violation-message` не містить інформації, яку можна видобути за допомогою регулярних виразів, `applyT0Auto` не виконує жод

package/skills/fix/js/llm-worker.mjs

@@ -1,36 +1,47 @@
-/**
- * LLM-worker для n-fix оркестратора — C1 pattern:
- *   script збирає контекст (rule .mdc + файли з violation) →
- *   pi повертає JSON зі змінами →
- *   script застосовує.
- *
- * Всі LLM-виклики через `pi` (користувач налаштовує ключі самостійно).
- * Tool-use не використовується — LLM отримує повний контекст у промпті.
- */
+/** @see ./docs/llm-worker.md */
 
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { spawnSync } from 'node:child_process'
+import { env } from 'node:process'
+import { CLOUD_MIN, CLOUD_AVG } from '../../../lib/models.mjs'
 
-export const MODEL_HAIKU = 'claude-haiku-4-5-20251001'
-export const MODEL_SONNET = 'claude-sonnet-4-6'
+// Тир за замовчуванням: CLOUD_MIN → CLOUD_AVG при ескалації.
+// Перевизначення через N_CURSOR_FIX_MODEL / N_CURSOR_FIX_MODEL_HEAVY.
+export const MODEL = env.N_CURSOR_FIX_MODEL ?? CLOUD_MIN
+export const MODEL_HEAVY = env.N_CURSOR_FIX_MODEL_HEAVY ?? CLOUD_AVG
 
 /**
  * Витягує відносні шляхи файлів із violation output.
- * Шукає патерни типу `path/to/file.ext` або `[ws] path/to/file.ext:123`.
+ * Розуміє workspace-prefix: `[npm] skills/foo.mjs` → `npm/skills/foo.mjs`.
  *
  * @param {string} output violation output з fix check
- * @returns {string[]} унікальні відносні шляхи
+ * @returns {string[]} унікальні відносні шляхи (від кореня проєкту)
  */
 function extractFilePaths(output) {
   const seen = new Set()
   const results = []
-  // Матчить шляхи: слово/крапка/тире, з розширенням, необов'язковий :рядок на кінці
-  const re = /(?:^|\s|\[[\w/]+\]\s)([\w./][\w./\-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
+
+  // Патерн з workspace: [npm] skills/foo.mjs або [demo] src/bar.ts
+  const wsRe = /\[([\w-]+)\]\s+([\w./][\w./\-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
+  for (const m of output.matchAll(wsRe)) {
+    const p = `${m[1]}/${m[2]}`
+    if (!seen.has(p)) {
+      seen.add(p)
+      results.push(p)
+    }
+  }
+
+  // Патерн без workspace: просто path/to/file.ext або ./file.ext
+  const re = /(?:^|\s)(\.?[\w][\w./\-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
   for (const m of output.matchAll(re)) {
     const p = m[1]
-    if (!seen.has(p)) { seen.add(p); results.push(p) }
+    if (!seen.has(p)) {
+      seen.add(p)
+      results.push(p)
+    }
   }
+
   return results
 }
 
@@ -44,9 +55,10 @@ function extractFilePaths(output) {
  * @returns {string}
  */
 function buildPrompt(ruleId, ruleMdc, output, files) {
-  const filesBlock = files.length === 0
-    ? '(no files identified)'
-    : files.map(f => `<file path="${f.path}">\n${f.content}\n</file>`).join('\n\n')
+  const filesBlock =
+    files.length === 0
+      ? '(no files identified)'
+      : files.map(f => `<file path="${f.path}">\n${f.content}\n</file>`).join('\n\n')
 
   return [
     `You fix project structure violations. Return ONLY valid JSON — no explanation, no markdown.`,
@@ -69,7 +81,7 @@ function buildPrompt(ruleId, ruleMdc, output, files) {
     `- "path" is relative to the project root`,
     `- "content" is the complete new file content (not a diff)`,
     `- Only include files that actually need to change`,
-    `- If nothing can be fixed automatically, return {"changes":[],"error":"reason"}`,
+    `- If nothing can be fixed automatically, return {"changes":[],"error":"reason"}`
   ].join('\n')
 }
 
@@ -81,14 +93,25 @@ function buildPrompt(ruleId, ruleMdc, output, files) {
  * @returns {{ text: string, error?: string }}
  */
 function callPi(prompt, model) {
-  const r = spawnSync(
-    'pi',
-    ['-p', prompt, '--model', model, '--no-session', '--mode', 'text', '--no-tools'],
-    { encoding: 'utf8', timeout: 120_000 }
-  )
+  const modelArgs = model ? ['--model', model] : []
+  const r = spawnSync('pi', ['-p', prompt, ...modelArgs, '--no-session', '--mode', 'text', '--no-tools'], {
+    encoding: 'utf8',
+    timeout: 120_000
+  })
   if (r.error) return { text: '', error: r.error.message }
   if (r.status !== 0) {
     const stderr = r.stderr?.slice(0, 300) ?? ''
+    if (stderr.toLowerCase().includes('no api key') || stderr.toLowerCase().includes('api key')) {
+      const provider = model ? model.split('/')[0] : 'дефолтного провайдера'
+      return {
+        text: '',
+        error: [
+          `pi: немає ключа для ${provider}.`,
+          `Встановіть N_CLOUD_MIN_MODEL=provider/model-id`,
+          `(напр.: openai/gpt-5.4-mini, google/gemini-2.5-flash, ollama/gemma3:4b)`,
+        ].join(' ')
+      }
+    }
     return { text: '', error: `pi exit ${r.status}: ${stderr}` }
   }
   return { text: r.stdout?.trim() ?? '' }
@@ -103,19 +126,31 @@ function callPi(prompt, model) {
  */
 function parseResponse(text) {
   // Спроба 1: прямий JSON
-  try { return JSON.parse(text) } catch { /* fallthrough */ }
+  try {
+    return JSON.parse(text)
+  } catch {
+    /* fallthrough */
+  }
 
   // Спроба 2: витягти з ```json ... ```
   const m = text.match(/```(?:json)?\s*([\s\S]*?)```/)
   if (m) {
-    try { return JSON.parse(m[1].trim()) } catch { /* fallthrough */ }
+    try {
+      return JSON.parse(m[1].trim())
+    } catch {
+      /* fallthrough */
+    }
   }
 
   // Спроба 3: перший { ... } блок
   const start = text.indexOf('{')
   const end = text.lastIndexOf('}')
   if (start !== -1 && end > start) {
-    try { return JSON.parse(text.slice(start, end + 1)) } catch { /* fallthrough */ }
+    try {
+      return JSON.parse(text.slice(start, end + 1))
+    } catch {
+      /* fallthrough */
+    }
   }
 
   return null
@@ -131,7 +166,7 @@ function parseResponse(text) {
  * @returns {Promise<{ ok: boolean, error?: string }>}
  */
 export async function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
-  const model = opts.model ?? MODEL_HAIKU
+  const model = opts.model ?? MODEL
 
   // 1. Читаємо rule .mdc
   const mdcPath = join(projectRoot, '.cursor', 'rules', `n-${ruleId}.mdc`)

package/skills/fix/js/orchestrator.mjs

@@ -1,14 +1,4 @@
-/**
- * Автономний оркестратор n-fix: convergence-loop без участі агента-LLM.
- *
- * Тири:
- *   T0      — детерміністична перевірка (runFixCheck, 0 LLM)
- *   T0-auto — regex-парсинг violation → програмний фікс (0 LLM)
- *   T1      — LLM через pi (haiku → sonnet ескалація)
- *   check-gate — re-run T0 після кожного тіру; loop до maxIter
- *
- * meta.json: { "orchestrator": true } — CLI маршрутизує `fix` сюди.
- */
+/** @see ./docs/orchestrator.md */
 
 import { spawnSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
@@ -26,81 +16,82 @@ const ESCALATE_AFTER = 2
  * @returns {Promise<number>}  0 = all clean, 1 = unresolved
  */
 export async function runOrchestratorCli(args, cwd) {
-  const { runLlmWorker, MODEL_HAIKU, MODEL_SONNET } = await import('./llm-worker.mjs')
+  const { runLlmWorker, MODEL, MODEL_HEAVY } = await import('./llm-worker.mjs')
 
   const maxIterIdx = args.indexOf('--max-iter')
   const maxIter =
-    maxIterIdx !== -1
-      ? Number(args[maxIterIdx + 1] ?? DEFAULT_MAX_ITER) || DEFAULT_MAX_ITER
-      : DEFAULT_MAX_ITER
+    maxIterIdx !== -1 ? Number(args[maxIterIdx + 1] ?? DEFAULT_MAX_ITER) || DEFAULT_MAX_ITER : DEFAULT_MAX_ITER
   const skipIdxs = new Set(maxIterIdx !== -1 ? [maxIterIdx, maxIterIdx + 1] : [])
   const ruleFilter = args.filter((a, i) => !a.startsWith('-') && !skipIdxs.has(i))
 
-  console.log(`🔄 n-cursor fix`)
-  if (ruleFilter.length) console.log(`   rules: ${ruleFilter.join(', ')}`)
-
   /** @type {Map<string, number>} ruleId → кількість LLM-провалів підряд */
   const failCount = new Map()
 
-  for (let iter = 1; iter <= maxIter; iter++) {
-    console.log(`\n── Ітерація ${iter}/${maxIter} ──`)
+  // ── Перша перевірка (тихо) ──
+  const initial = runFixCheck(cwd, ruleFilter)
+  if (!initial) {
+    console.error(`❌ fix: помилка перевірки`)
+    return 1
+  }
 
-    // ── T0: check ──
-    const state = runFixCheck(cwd, ruleFilter)
-    if (!state) {
-      console.error(`❌ fix: перевірка повернула помилку`)
-      return 1
-    }
+  let failed = initial.rules.filter(r => !r.ok)
+  const total = initial.total
 
-    const failed = state.rules.filter(r => !r.ok)
-    if (failed.length === 0) {
-      console.log(`✅ fix: 0/${state.total} порушень`)
-      return 0
-    }
+  // Нічого не зламано — коротка відповідь
+  if (failed.length === 0) {
+    console.log(`✅ fix: ${total} правил — все чисто`)
+    return 0
+  }
 
-    console.log(`   ❌ ${failed.length}: ${failed.map(r => r.ruleId).join(', ')}`)
+  // Є порушення — показуємо прогрес
+  console.log(`🔄 fix: ${failed.length}/${total} порушень (${failed.map(r => r.ruleId).join(', ')})`)
+  if (ruleFilter.length) console.log(`   filter: ${ruleFilter.join(', ')}`)
 
+  for (let iter = 1; iter <= maxIter; iter++) {
     // ── T0-auto: детермінований фікс без LLM ──
-    spawnSync('bun', [N_CURSOR_BIN, 'fix-t0', ...ruleFilter], { cwd, stdio: 'inherit' })
+    spawnSync('bun', [N_CURSOR_BIN, 'fix-t0', ...ruleFilter], { cwd, stdio: 'pipe' })
+
+    const afterT0 = runFixCheck(cwd, ruleFilter)
+    const failedAfterT0 = afterT0?.rules.filter(r => !r.ok) ?? failed
+    const t0Fixed = failed.filter(r => !failedAfterT0.find(f => f.ruleId === r.ruleId))
 
-    const stateAfterT0 = runFixCheck(cwd, ruleFilter)
-    const failedAfterT0 = stateAfterT0?.rules.filter(r => !r.ok) ?? failed
-    if (failedAfterT0.length === 0) {
-      console.log(`✅ fix: всі правила закриті T0-auto`)
-      return 0
+    if (t0Fixed.length > 0) {
+      console.log(`  ⚙️  T0-auto: ${t0Fixed.map(r => r.ruleId).join(', ')}`)
     }
 
+    failed = failedAfterT0
+    if (failed.length === 0) break
+
     // ── T1: LLM через pi ──
-    for (const rule of failedAfterT0) {
+    for (const rule of failed) {
       const prevFails = failCount.get(rule.ruleId) ?? 0
-      const model = prevFails >= ESCALATE_AFTER ? MODEL_SONNET : MODEL_HAIKU
-      const tier = prevFails >= ESCALATE_AFTER ? 'sonnet' : 'haiku'
-
-      console.log(`\n⚡ [${tier}] → ${rule.ruleId}`)
+      const model = prevFails >= ESCALATE_AFTER ? MODEL_HEAVY : MODEL
+      const label = model || 'pi'
 
       const result = await runLlmWorker(rule.ruleId, rule.output, cwd, { model })
 
       if (result.ok) {
-        console.log(`   ✅ закрито`)
+        console.log(`  ⚡ LLM (${label}): ${rule.ruleId}`)
         failCount.delete(rule.ruleId)
       } else {
         failCount.set(rule.ruleId, prevFails + 1)
-        console.log(`   ❌ (${prevFails + 1}× fail): ${result.error ?? ''}`)
+        const hint = (result.error ?? '').slice(0, 200)
+        console.log(`  ⚡ LLM (${label}): ${rule.ruleId} ❌  ${hint}`)
       }
     }
-  }
 
-  // ── Фінальна перевірка ──
-  const final = runFixCheck(cwd, ruleFilter)
-  const finalFailed = final?.rules.filter(r => !r.ok) ?? []
+    // Перевірка після LLM
+    const afterLLM = runFixCheck(cwd, ruleFilter)
+    failed = afterLLM?.rules.filter(r => !r.ok) ?? failed
+    if (failed.length === 0) break
+  }
 
-  if (finalFailed.length === 0) {
-    console.log(`\n✅ fix: чисто`)
+  if (failed.length === 0) {
+    console.log(`✅ fix: ${total} правил — все чисто`)
     return 0
   }
 
-  console.log(`\n❌ fix: ${finalFailed.length} unresolved після ${maxIter} ітерацій`)
-  console.log(`   ${finalFailed.map(r => r.ruleId).join(', ')}`)
+  console.log(`❌ fix: ${failed.length} невирішених — ${failed.map(r => r.ruleId).join(', ')}`)
   return 1
 }
 
@@ -116,7 +107,7 @@ function runFixCheck(cwd, ruleFilter = []) {
   const r = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...ruleFilter], {
     cwd,
     encoding: 'utf8',
-    timeout: 120_000,
+    timeout: 120_000
   })
   const stdout = r.stdout?.trim()
   if (!stdout) return null