@nitra/cursor 3.27.0 → 3.29.0

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 { resolveModel } from '../../../lib/models.mjs'
 
-export const MODEL_HAIKU = 'claude-haiku-4-5-20251001'
-export const MODEL_SONNET = 'claude-sonnet-4-6'
+// Тир за замовчуванням: min → avg при ескалації (каскад local→cloud).
+// Перевизначення через N_CURSOR_FIX_MODEL / N_CURSOR_FIX_MODEL_HEAVY.
+export const MODEL = env.N_CURSOR_FIX_MODEL ?? resolveModel('min')
+export const MODEL_HEAVY = env.N_CURSOR_FIX_MODEL_HEAVY ?? resolveModel('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

package/skills/fix/js/t0.mjs

@@ -1,18 +1,4 @@
-/**
- * T0-auto: детермінований рівень виправлень для n-fix оркестратора.
- *
- * Парсить `output` з `n-cursor fix --json` → застосовує програмний фікс без LLM.
- * Умова застосування: violation-message містить конкретне цільове значення
- * (назву файлу, рядок для вставки, ім'я залежності), яке можна видобути regex.
- *
- * Ієрархія: T0 (rm/create, знаний тип) → T0-auto (parse violation) → T1 (LLM).
- * T0-auto запускається першим у конвергентному циклі; T1 — лише для решти.
- *
- * Публічний API:
- *   applyT0Auto(ruleId, violationOutput, cwd) → { applied: boolean, actions: string[] }
- *   listT0AutoRules()                         → string[]  (ids що мають хоч один паттерн)
- *   runT0AutoCli(args, cwd)                   → Promise<number>  (exit 0=clean, 1=violation)
- */
+/** @see ./docs/t0.md */
 import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { spawnSync } from 'node:child_process'
@@ -57,7 +43,7 @@ const PATTERNS = [
       parsed.recommendations = [...recs, ...toAdd]
       writeFileSync(extPath, JSON.stringify(parsed, null, 2) + '\n', 'utf8')
       return { ok: true, action: `додано до extensions.json: ${toAdd.join(', ')}` }
-    },
+    }
   },
 
   // ── rm-forbidden-file ────────────────────────────────────────────────────────
@@ -80,8 +66,8 @@ const PATTERNS = [
       }
       if (removed.length === 0) return { ok: false, action: 'файлів не знайдено' }
       return { ok: true, action: `видалено: ${removed.join(', ')}` }
-    },
-  },
+    }
+  }
 ]
 
 /**
@@ -116,9 +102,7 @@ export function applyT0Auto(ruleId, violationOutput, cwd) {
  * @returns {string[]}
  */
 export function filterT0AutoRules(failedRules) {
-  return failedRules
-    .filter(r => PATTERNS.some(p => p.test(r.output)))
-    .map(r => r.ruleId)
+  return failedRules.filter(r => PATTERNS.some(p => p.test(r.output))).map(r => r.ruleId)
 }
 
 // ─── CLI entry-point ──────────────────────────────────────────────────────────
@@ -141,11 +125,11 @@ export async function runT0AutoCli(args, cwd) {
   const verbose = args.includes('--verbose') || args.includes('-v')
 
   // 1. Запустити fix --json
-  const fixResult = spawnSync(
-    'bun',
-    [N_CURSOR_BIN, '_fix-check', ...ruleFilter],
-    { cwd, encoding: 'utf8', timeout: 120_000 }
-  )
+  const fixResult = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...ruleFilter], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 120_000
+  })
   const raw = fixResult.stdout?.trim()
   if (!raw) {
     console.error(`n-cursor fix-t0: fix --json повернув порожній stdout`)
@@ -191,11 +175,11 @@ export async function runT0AutoCli(args, cwd) {
   }
 
   // 4. Check-gate: перевірити лише ті правила, що ми чіпали
-  const recheck = spawnSync(
-    'bun',
-    [N_CURSOR_BIN, '_fix-check', ...applied.map(a => a.ruleId)],
-    { cwd, encoding: 'utf8', timeout: 120_000 }
-  )
+  const recheck = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...applied.map(a => a.ruleId)], {
+    cwd,
+    encoding: 'utf8',
+    timeout: 120_000
+  })
   const recheckRaw = recheck.stdout?.trim()
   if (!recheckRaw) {
     console.error(`fix-t0: check-gate: fix --json повернув порожній stdout`)
@@ -223,7 +207,7 @@ export async function runT0AutoCli(args, cwd) {
   const total = failed.length
   console.log(
     `✅ fix-t0: ${totalFixed}/${total} правил закрито T0-auto` +
-    (skipped.length > 0 ? `; ${skipped.join(', ')} → T1 (LLM)` : '')
+      (skipped.length > 0 ? `; ${skipped.join(', ')} → T1 (LLM)` : '')
   )
   return 0
 }

package/skills/start-check/js/check.mjs

@@ -1,19 +1,4 @@
-/**
- * `n-cursor start-check scan|run` — детермінована частина smoke-перевірки
- * bun-монорепо для скілу `n-start-check`.
- *
- * Мотивація: скіл раніше казав LLM-агенту вручну розгортати glob-воркспейси,
- * читати кожен `package.json`, класифікувати `start` (сервер vs CLI), запускати
- * процес із таймаутом через `perl alarm`, інтерпретувати exit-коди й парсити лог
- * на рядки готовності/помилки. Усе це детерміновано — скрипт робить це надійно й
- * крос-платформно (`spawnSync` з `timeout`), а агент лишається тільки з
- * діагностикою: **чому** саме воркспейс упав.
- *
- * `scan` — `[{workspace, name, hasStart, startCmd, type}]`.
- * `run <ws>` — `{workspace, type, exitCode, timedOut, status, ready, firstError,
- * logTail, sideEffects}` (sideEffects — read-only git-diff проти стану до запуску;
- * власне відкат лишається явним кроком скіла).
- */
+/** @see ./docs/check.md */
 import { spawnSync } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'

package/skills/start-check/js/docs/check.md

@@ -0,0 +1,34 @@
+# check.mjs
+
+## Огляд
+
+Файл `n-cursor start-check scan|run` є частиною smoke-перевірки для скілу `n-start-check`. Він автоматично аналізує та запускає воркспейси, визначаючи тип стартового скрипта (сервер чи CLI) та перевіряючи успішність його виконання з обмеженням часу. Результати аналізу та запуску записуються у форматі JSON для подальшого аналізу та діагностики проблем.
+
+## Поведінка
+
+- `classifyStartType` визначає, чи є команда `start` CLI чи довгим процесом (сервером).
+- `scanStartWorkspaces` сканує монорепо, визначаючи воркспейси з `start`, їхні команди та типи.
+- `parseStartLog` витягує готовність, першу помилку та хвіст логу з процесу.
+- `runWorkspaceStart` запускає команду `start` воркспейсу з grace-таймаутом, класифікує результат та повертає інформацію про процес.
+- `runStartCheckCli` виконує `scan` або `run` воркспейсу, приймаючи аргументи командного рядка.
+
+## Публічний API
+
+- classifyStartType — Визначає, чи є команда `start` сервером або CLI.
+- scanStartWorkspaces — Перевіряє монорепо на наявність команди `start` та її типу у кожному воркспейсі.
+- parseStartLog — Аналізує лог процесу `start` для виявлення статусу, помилок та кінця.
+- runWorkspaceStart — Запускає команду `start` у воркспейсі з обмеженим часом та визначає результат.
+- runStartCheckCli — Запускає CLI для сканування воркспейсів з `start` та індивідуального запуску воркспейсу з подальшим виводом результатів у JSON.
+
+## Гарантії поведінки
+
+- Скрипт детерміновано виконує перевірку запуску воркспейса.
+- Скрипт використовує `spawnSync` з таймаутом для запуску процесів.
+- Скрипт інтерпретує exit-коди та парсить логи.
+- Результат перевірки воркспейса представлений у форматі `[{workspace, name, hasStart, startCmd, type}]`.
+- У разі невдачі перевірки, скрипт повертає `false` або `null`.
+- Скрипт не кидає винятків.
+- Скрипт не використовує кешування.
+- Скрипт не взаємодіє з мережею.
+- Результат запуску воркспейса представлений у форматі `{workspace, type, exitCode, timedOut, status, ready, firstError, logTail, sideEffects}`.
+- `sideEffects` містить відкат стану воркспейса до його початкового стану перед запуском.