@nitra/cursor 3.26.0 → 3.28.0

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/SKILL.md

@@ -8,42 +8,16 @@ description: >-
 
 ## Scope
 
-Цей скіл відповідає **лише за структуру** проєкту: щоб `.cursor/rules/` + `npx @nitra/cursor fix` були задоволені (наявність конфігів, залежностей, скриптів, GitHub workflows, відсутність заборонених файлів). **Лінт-порушення у самому коді** (ESLint, oxlint, jscpd, cspell, knip, sonarjs, stylelint тощо) — **поза скоупом**; їх діагностує й виправляє **`/n-lint`** (`bun run lint`). Не запускай `bun run lint` із цього скілу і не намагайся виправляти його порушення тут — це задача `/n-lint`. Якщо `npx @nitra/cursor fix` чистий, а `bun run lint` лишився червоним — запусти `/n-lint` окремо.
+Цей скіл відповідає **лише за структуру** проєкту: щоб `.cursor/rules/` + `npx @nitra/cursor fix` були задоволені (наявність конфігів, залежностей, скриптів, GitHub workflows, відсутність заборонених файлів). **Лінт-порушення у самому коді** (ESLint, oxlint, jscpd, cspell, knip, sonarjs, stylelint тощо) — **поза скоупом**; їх діагностує й виправляє **`/n-lint`** (`bun run lint`).
 
 ## Workflow
 
-1. **Діагностика** — запусти перевірку через retry-обгортку `n_cursor_npx` (визначена у worktree-preflight, крок 0.1: переживає транзитну CDN-гонку щойно опублікованої версії, а реальний `❌` від `fix` віддає одразу). Прапорець `--json` дає **структурований** результат у stdout, щоб не парсити термінальний текст. За замовчуванням — лише правила з `.cursor/rules/*.mdc`, для яких у пакеті є programmatic check; повний набір — явні аргументи: `n_cursor_npx fix bun ga --json`:
-
-```bash
-n_cursor_npx fix --json
-```
-
-2. **Аналіз** — розбери JSON `{ total, failed, rules: [{ ruleId, ok, output }] }`. Працюй **лише** з елементами `ok:false`; їх `output` містить готові `❌`-повідомлення правила (не парси stdout вручну, не визначай правила з тексту). Якщо `failed === 0` — нічого виправляти.
-
-3. **Виправлення** — для кожного `❌` відкрий відповідне правило з `.cursor/rules/` і виправ:
-   - Створи відсутні конфігураційні файли (`.cspell.json`, `.oxfmtrc.json`, `eslint.config.js`, тощо)
-   - Додай відсутні залежності до `package.json`
-   - Створи або оновити `.vscode/settings.json` та `extensions.json`
-   - Створи відсутні GitHub Actions workflows у `.github/workflows/`
-   - Видали заборонені файли та залежності (`package-lock.json`, `yarn.lock`, prettier, тощо)
-   - Оновити скрипти в `package.json`
-
-4. **Встановлення** — якщо були змінені залежності:
-
 ```bash
-bun i
+n_cursor_npx fix
 ```
 
-5. **Форматування** — відформатуй змінені файли:
+Exit 0 = чисто, 1 = є unresolved (перевір вивід — буде список правил що не закрились після 3 ітерацій).
 
-```bash
-oxfmt .
-```
-
-6. **Верифікація** — перевір що все виправлено (та сама retry-обгортка `n_cursor_npx`); чекаєш `failed === 0`:
-
-```bash
-n_cursor_npx fix --json
-```
+Якщо змінились залежності — `bun i`. Якщо змінились JS/TS файли — `oxfmt .`.
 
-7. **Результат** — `failed` має стати `0` (усі правила `ok:true`). Якщо лишились `ok:false` — повтори кроки 3-6. Лінт-помилки від `bun run lint` тут **не виправляй** — вони на скіл `/n-lint`.
+Для конкретних правил: `n_cursor_npx fix bun ga`.

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

@@ -0,0 +1,216 @@
+/** @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'
+
+// Тир за замовчуванням: 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.
+ * Розуміє workspace-prefix: `[npm] skills/foo.mjs` → `npm/skills/foo.mjs`.
+ *
+ * @param {string} output violation output з fix check
+ * @returns {string[]} унікальні відносні шляхи (від кореня проєкту)
+ */
+function extractFilePaths(output) {
+  const seen = new Set()
+  const results = []
+
+  // Патерн з 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)
+    }
+  }
+
+  return results
+}
+
+/**
+ * Будує prompt для pi: правило + порушення + поточний вміст файлів.
+ *
+ * @param {string} ruleId
+ * @param {string} ruleMdc   вміст .mdc-файлу правила
+ * @param {string} output    violation output
+ * @param {Array<{path:string, content:string}>} files
+ * @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')
+
+  return [
+    `You fix project structure violations. Return ONLY valid JSON — no explanation, no markdown.`,
+    ``,
+    `Rule (n-${ruleId}.mdc):`,
+    `---`,
+    ruleMdc,
+    `---`,
+    ``,
+    `Violation output:`,
+    output,
+    ``,
+    `Current file contents:`,
+    filesBlock,
+    ``,
+    `Return JSON with this exact shape:`,
+    `{"changes":[{"path":"relative/path/to/file","content":"full corrected file content"}]}`,
+    ``,
+    `Rules:`,
+    `- "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"}`
+  ].join('\n')
+}
+
+/**
+ * Запускає pi і повертає stdout як рядок.
+ *
+ * @param {string} prompt
+ * @param {string} model
+ * @returns {{ text: string, error?: string }}
+ */
+function callPi(prompt, model) {
+  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() ?? '' }
+}
+
+/**
+ * Парсить JSON-відповідь від pi.
+ * pi може обгорнути JSON у ```json ... ```, тому пробуємо витягти.
+ *
+ * @param {string} text
+ * @returns {{ changes: Array<{path:string,content:string}>, error?: string } | null}
+ */
+function parseResponse(text) {
+  // Спроба 1: прямий JSON
+  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 */
+    }
+  }
+
+  // Спроба 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 */
+    }
+  }
+
+  return null
+}
+
+/**
+ * LLM-worker: виправляє одне rule-порушення через pi (C1 pattern).
+ *
+ * @param {string} ruleId
+ * @param {string} violationOutput  output з fix check для цього rule
+ * @param {string} projectRoot      абсолютний шлях до кореня проєкту
+ * @param {{ model?: string }} opts
+ * @returns {Promise<{ ok: boolean, error?: string }>}
+ */
+export async function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
+  const model = opts.model ?? MODEL
+
+  // 1. Читаємо rule .mdc
+  const mdcPath = join(projectRoot, '.cursor', 'rules', `n-${ruleId}.mdc`)
+  const ruleMdc = existsSync(mdcPath) ? readFileSync(mdcPath, 'utf8') : '(rule file not found)'
+
+  // 2. Витягуємо файли з violation output і читаємо їх
+  const filePaths = extractFilePaths(violationOutput)
+  const files = filePaths
+    .map(p => {
+      const abs = join(projectRoot, p)
+      if (!existsSync(abs)) return null
+      try {
+        return { path: p, content: readFileSync(abs, 'utf8') }
+      } catch {
+        return null
+      }
+    })
+    .filter(Boolean)
+
+  // 3. Будуємо prompt і викликаємо pi
+  const prompt = buildPrompt(ruleId, ruleMdc, violationOutput, files)
+  const { text, error: piError } = callPi(prompt, model)
+
+  if (piError) return { ok: false, error: piError }
+  if (!text) return { ok: false, error: 'pi returned empty response' }
+
+  // 4. Парсимо відповідь
+  const parsed = parseResponse(text)
+  if (!parsed) return { ok: false, error: `cannot parse pi response: ${text.slice(0, 200)}` }
+  if (parsed.error) return { ok: false, error: parsed.error }
+
+  const changes = parsed.changes ?? []
+  if (changes.length === 0) return { ok: false, error: 'pi returned no changes' }
+
+  // 5. Застосовуємо зміни
+  for (const change of changes) {
+    if (!change.path || typeof change.content !== 'string') continue
+    const abs = join(projectRoot, change.path)
+    try {
+      writeFileSync(abs, change.content, 'utf8')
+    } catch (e) {
+      return { ok: false, error: `write ${change.path}: ${e.message}` }
+    }
+  }
+
+  return { ok: true }
+}

package/skills/fix/js/orchestrator.mjs

@@ -0,0 +1,119 @@
+/** @see ./docs/orchestrator.md */
+
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+
+const HERE = fileURLToPath(new URL('.', import.meta.url))
+const N_CURSOR_BIN = join(HERE, '../../../bin/n-cursor.js')
+
+const DEFAULT_MAX_ITER = 3
+const ESCALATE_AFTER = 2
+
+/**
+ * @param {string[]} args   CLI аргументи після 'fix'
+ * @param {string}   cwd    корінь проєкту
+ * @returns {Promise<number>}  0 = all clean, 1 = unresolved
+ */
+export async function runOrchestratorCli(args, cwd) {
+  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
+  const skipIdxs = new Set(maxIterIdx !== -1 ? [maxIterIdx, maxIterIdx + 1] : [])
+  const ruleFilter = args.filter((a, i) => !a.startsWith('-') && !skipIdxs.has(i))
+
+  /** @type {Map<string, number>} ruleId → кількість LLM-провалів підряд */
+  const failCount = new Map()
+
+  // ── Перша перевірка (тихо) ──
+  const initial = runFixCheck(cwd, ruleFilter)
+  if (!initial) {
+    console.error(`❌ fix: помилка перевірки`)
+    return 1
+  }
+
+  let failed = initial.rules.filter(r => !r.ok)
+  const total = initial.total
+
+  // Нічого не зламано — коротка відповідь
+  if (failed.length === 0) {
+    console.log(`✅ fix: ${total} правил — все чисто`)
+    return 0
+  }
+
+  // Є порушення — показуємо прогрес
+  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: '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))
+
+    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 failed) {
+      const prevFails = failCount.get(rule.ruleId) ?? 0
+      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(`  ⚡ LLM (${label}): ${rule.ruleId}`)
+        failCount.delete(rule.ruleId)
+      } else {
+        failCount.set(rule.ruleId, prevFails + 1)
+        const hint = (result.error ?? '').slice(0, 200)
+        console.log(`  ⚡ LLM (${label}): ${rule.ruleId} ❌  ${hint}`)
+      }
+    }
+
+    // Перевірка після LLM
+    const afterLLM = runFixCheck(cwd, ruleFilter)
+    failed = afterLLM?.rules.filter(r => !r.ok) ?? failed
+    if (failed.length === 0) break
+  }
+
+  if (failed.length === 0) {
+    console.log(`✅ fix: ${total} правил — все чисто`)
+    return 0
+  }
+
+  console.log(`❌ fix: ${failed.length} невирішених — ${failed.map(r => r.ruleId).join(', ')}`)
+  return 1
+}
+
+/**
+ * Внутрішня check-gate: запускає fix-перевірки і повертає структурований результат.
+ * Не є публічним CLI — викликається лише оркестратором.
+ *
+ * @param {string}   cwd
+ * @param {string[]} ruleFilter
+ * @returns {{ total: number, failed: number, rules: Array<{ ruleId: string, ok: boolean, output: string }> } | null}
+ */
+function runFixCheck(cwd, ruleFilter = []) {
+  const r = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...ruleFilter], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 120_000
+  })
+  const stdout = r.stdout?.trim()
+  if (!stdout) return null
+  try {
+    return JSON.parse(stdout)
+  } catch {
+    return null
+  }
+}