@nitra/cursor 12.0.3 → 12.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [12.1.0] - 2026-06-19
+
+### Added
+
+- fix-конформність: драбина ескалації моделей (local-min → local-min+feedback → cloud-min → cloud-avg) із per-рунговим escalation-логом (.n-cursor/fix-escalation.jsonl, поле diagnosis) і кепом --max-avg; прибрано --max-iter/MODEL_HEAVY
+- analyze-escalation: аналіз escalation-логу хмарною avg-моделлю (чанкінг + map-reduce) → markdown-звіт із пропозиціями нових T0-патернів / правок .mdc / змін скриптів; CLI n-cursor analyze-escalation і авто-хук наприкінці lint --full (kill-switch N_CURSOR_FIX_ANALYZE)
+
 ## [12.0.3] - 2026-06-18
 
 ### Fixed

package/bin/n-cursor.js

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

package/package.json

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

package/rules/lint/js/docs/orchestrate.md

@@ -3,7 +3,7 @@ type: JS Module
 title: orchestrate.mjs
 resource: npm/rules/lint/js/orchestrate.mjs
 docgen:
-  crc: aed5ffe7
+  crc: 69bc0daf
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
@@ -15,6 +15,7 @@ docgen:
 Поведінка
 selectLintRules вибирає і сортує ідентифікатори правил на основі їхнього обсягу дії (`per-file` або `full`) та прапорця `--full`.
 runLint запускає оркестрацію лінтування: або виконує перевірку конформності для заданих правил, або ітерує по алфавітно відсортованих правилах, запускаючи лінтер для змінених файлів (за замовчуванням), або виконує перевірку конформності всього репозиторію при використанні прапорця `--full`.
+У режимі `--full` без `--read-only` після конформність-фази runLint викликає escalation-аналітику (`analyze-escalation.mjs`): фіксує зсув escalation-логу до фази, після — аналізує записи саме цього прогону. Аналіз не впливає на exit-код lint.
 
 ## Публічний API
 

package/rules/lint/js/orchestrate.mjs

@@ -131,7 +131,12 @@ export async function runLint(opts = {}) {
   // Конформність-фаза (поглинула `fix`): whole-repo, лише у `--full`. Кастомний rulesDir
   // (юніт-тести селектора) — реальний пакет недоступний, тож пропускаємо.
   if (full && opts.rulesDir === undefined) {
+    // Escalation-аналітика: фіксуємо зсув логу ДО конформності, після — аналізуємо
+    // записи саме цього прогону (fix-режим). Аналіз не має валити lint.
+    const { escalationLogSize, maybeAnalyzeEscalation } = await import('../../../scripts/lib/fix/analyze-escalation.mjs')
+    const escOffset = readOnly ? 0 : escalationLogSize()
     const conformanceCode = await runConformance(cwd, readOnly, log)
+    if (!readOnly) maybeAnalyzeEscalation(cwd, escOffset, log)
     if (conformanceCode !== 0) return conformanceCode
   }
   return 0

package/scripts/lib/fix/analyze-escalation.mjs

@@ -0,0 +1,315 @@
+/**
+ * Аналітика escalation-логу (спека 2026-06-19-fix-escalation-analysis-design).
+ *
+ * Читає записи рунгів драбини (`escalation-log.mjs`) — за один прогін (від байтового
+ * зсуву) або весь лог, — ділить на чанки за бюджетом символів і просить хмарну
+ * **avg**-модель проаналізувати: як зменшити LLM-залежність fix-конформності.
+ * Мета аналізу — конкретні правки пакета `@nitra/cursor`:
+ *   (A) новий ДЕТЕРМІНОВАНИЙ T0-патерн (`t0.mjs`) — прибирає LLM зовсім;
+ *   (B) уточнення `.mdc`-інструкцій правила, щоб локальна min-модель влучала з першого рунга;
+ *   (C) зміна скрипта/чека в пакеті.
+ * Результат — markdown-звіт у `.n-cursor/fix-escalation-analysis.md` (append із timestamp).
+ *
+ * Викликається CLI `n-cursor analyze-escalation` (весь лог) і наприкінці `lint --full`
+ * (записи цього прогону). Кожен виклик моделі йде через спільний `callLlm` (wire-trace).
+ */
+import { appendFileSync, mkdirSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { cwd as processCwd, env } from 'node:process'
+
+import { callLlm } from '../../../lib/llm.mjs'
+import { CLOUD_AVG } from '../../../lib/models.mjs'
+import { escalationLogPath } from './escalation-log.mjs'
+
+/** Значення `N_CURSOR_FIX_ANALYZE`, що вимикають авто-аналіз наприкінці lint. */
+const KILL_VALUES = new Set(['0', 'false', 'off', 'no'])
+/** Бюджет символів на один чанк (щоб великий лог не перевищив контекст моделі). */
+const DEFAULT_CHUNK_CHARS = 40_000
+/** Timeout одного аналітичного виклику (мс) — аналіз може бути об'ємним. */
+const ANALYZE_TIMEOUT_MS = 180_000
+
+/** No-op логер за замовчуванням. */
+const NOOP_LOG = () => {
+  /* тихо */
+}
+
+/**
+ * Спільна мета-інструкція для аналітичних викликів.
+ */
+const GOAL = [
+  `You analyze logs from @nitra/cursor's automated rule-conformance fixer ("fix").`,
+  `Each record = one attempt by a model to fix a rule-conformance violation on a rung of`,
+  `an escalation ladder. Fields: ruleId; tier (local-min|local-min-retry|cloud-min|cloud-avg);`,
+  `model; callOk (model call+apply succeeded); recheckOk (rule PASSED after this rung — "did it help");`,
+  `callError; diagnosis (model's self-stated reason a prior attempt failed); remainingViolation.`,
+  ``,
+  `Goal: reduce LLM dependence and time-to-green. For RECURRING patterns recommend CONCRETE changes`,
+  `to the @nitra/cursor package, in priority order:`,
+  `(A) a new DETERMINISTIC T0-auto pattern for npm/scripts/lib/fix/t0.mjs — give a regex that matches`,
+  `    the violation output + the mechanical fix. PREFERRED: removes the LLM entirely.`,
+  `(B) a clarification to a rule's .mdc instructions so the LOCAL min-model succeeds on the FIRST rung.`,
+  `(C) a script/check change elsewhere in the package.`,
+  `Prioritise rules that escalated to cloud (cloud-min/cloud-avg) or failed repeatedly — they cost most.`,
+  `Ignore rules resolved at local-min with no retry — they already work.`
+].join('\n')
+
+/**
+ * Чи увімкнено авто-аналіз наприкінці lint (default — так; kill-switch `N_CURSOR_FIX_ANALYZE`).
+ * @returns {boolean} true, якщо аналіз дозволено
+ */
+export function analysisEnabled() {
+  const v = env.N_CURSOR_FIX_ANALYZE
+  if (v === undefined) return true
+  return !KILL_VALUES.has(v.toLowerCase())
+}
+
+/**
+ * Розмір escalation-логу в байтах (0, якщо файлу немає/вимкнено) — для since-offset.
+ * @param {string|null} [path] шлях логу
+ * @returns {number} розмір у байтах
+ */
+export function escalationLogSize(path = escalationLogPath()) {
+  if (!path) return 0
+  try {
+    return statSync(path).size
+  } catch {
+    return 0
+  }
+}
+
+/**
+ * Читає записи escalation-логу від байтового зсуву (default 0 — весь лог). Зсув завжди
+ * на межі рядка (захоплюється після завершеного append), тож мультибайтні символи не б'ються.
+ * Биті JSON-рядки пропускаються.
+ * @param {string|null} path шлях логу
+ * @param {number} [sinceOffset] байтовий зсув початку читання
+ * @returns {object[]} розпарсені записи
+ */
+export function readEscalationRecords(path, sinceOffset = 0) {
+  if (!path) return []
+  let buf
+  try {
+    buf = readFileSync(path)
+  } catch {
+    return []
+  }
+  const text = (sinceOffset > 0 ? buf.subarray(sinceOffset) : buf).toString('utf8')
+  const out = []
+  for (const line of text.split('\n')) {
+    const t = line.trim()
+    if (!t) continue
+    try {
+      out.push(JSON.parse(t))
+    } catch {
+      /* битий рядок — пропускаємо */
+    }
+  }
+  return out
+}
+
+/**
+ * Стискає запис до полів, важливих для аналізу (без ts/ms-шуму).
+ * @param {object} r сирий запис рунга
+ * @returns {object} компактний запис
+ */
+function summarizeRecord(r) {
+  return {
+    ruleId: r.ruleId,
+    tier: r.tier,
+    model: r.model,
+    callOk: r.callOk,
+    recheckOk: r.recheckOk,
+    callError: r.callError ?? null,
+    diagnosis: r.diagnosis ?? null,
+    remainingViolation: r.remainingViolation ?? null
+  }
+}
+
+/**
+ * Ділить записи на чанки так, щоб JSON кожного чанка не перевищував `maxChars`.
+ * Працює на стиснених записах (саме вони йдуть у prompt).
+ * @param {object[]} records сирі записи
+ * @param {number} [maxChars] бюджет символів на чанк
+ * @returns {object[][]} чанки стиснених записів
+ */
+export function chunkRecords(records, maxChars = DEFAULT_CHUNK_CHARS) {
+  const items = records.map(r => summarizeRecord(r))
+  const chunks = []
+  let cur = []
+  let size = 0
+  for (const it of items) {
+    const len = JSON.stringify(it).length + 1
+    if (cur.length > 0 && size + len > maxChars) {
+      chunks.push(cur)
+      cur = []
+      size = 0
+    }
+    cur.push(it)
+    size += len
+  }
+  if (cur.length > 0) chunks.push(cur)
+  return chunks
+}
+
+/**
+ * Prompt для аналізу одного чанка.
+ * @param {object[]} items стиснені записи чанка
+ * @param {number} idx індекс чанка (0-based)
+ * @param {number} total всього чанків
+ * @returns {string} текст prompt
+ */
+function buildChunkPrompt(items, idx, total) {
+  return [
+    GOAL,
+    ``,
+    `Log chunk ${idx + 1}/${total} (${items.length} records):`,
+    JSON.stringify(items),
+    ``,
+    `Return concise markdown: per recommendation — target ruleId, type (A/B/C), and the concrete change`,
+    `(for A: the regex + mechanical fix; for B: the exact .mdc clarification; for C: the script change).`
+  ].join('\n')
+}
+
+/**
+ * Prompt для злиття часткових аналізів у фінальний звіт.
+ * @param {string[]} partials часткові аналізи чанків
+ * @returns {string} текст prompt
+ */
+function buildSynthesisPrompt(partials) {
+  return [
+    GOAL,
+    ``,
+    `Below are partial analyses of separate log chunks. Merge, dedupe and prioritise into ONE report.`,
+    ``,
+    partials.map((p, i) => `--- chunk ${i + 1} ---\n${p}`).join('\n\n'),
+    ``,
+    `Return the final markdown report: recommendations ordered highest-impact first.`
+  ].join('\n')
+}
+
+/**
+ * Безпечний виклик моделі: ковтає помилку у `null` (аналіз не має валити lint).
+ * @param {(messages: object[], model: string, opts: object) => string} call функція callLlm
+ * @param {string} prompt текст prompt
+ * @param {string} model model-id
+ * @returns {string|null} текст відповіді або null
+ */
+function safeCall(call, prompt, model) {
+  try {
+    const text = call([{ role: 'user', content: prompt }], model, { timeoutMs: ANALYZE_TIMEOUT_MS, caller: 'fix-analyze' })
+    return text || null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Аналізує записи: чанкінг → виклик avg-моделі по чанках → синтез (якщо чанків >1).
+ * Синхронний (callLlm — spawnSync-based).
+ * @param {object[]} records записи escalation-логу
+ * @param {{ model?: string, callLlm?: (messages: object[], model: string, opts: object) => string, log?: (s: string) => void, maxChars?: number }} [opts]
+ *   `model` — модель (default `CLOUD_AVG`); `callLlm` — інжекція для тестів; `log` — логер
+ * @returns {{ report: string|null, chunks: number, reason: string }} звіт і метадані
+ */
+export function analyzeEscalations(records, opts = {}) {
+  const model = opts.model ?? CLOUD_AVG
+  const call = opts.callLlm ?? callLlm
+  const log = opts.log ?? NOOP_LOG
+  const maxChars = opts.maxChars ?? DEFAULT_CHUNK_CHARS
+
+  if (records.length === 0) return { report: null, chunks: 0, reason: 'no-records' }
+  if (!model) return { report: null, chunks: 0, reason: 'no-cloud-avg-model' }
+
+  const chunks = chunkRecords(records, maxChars)
+  const partials = []
+  for (const [i, chunk] of chunks.entries()) {
+    log(`  🔎 escalation-analysis: чанк ${i + 1}/${chunks.length} (${chunk.length} записів)`)
+    const text = safeCall(call, buildChunkPrompt(chunk, i, chunks.length), model)
+    if (text) partials.push(text)
+  }
+
+  if (partials.length === 0) return { report: null, chunks: chunks.length, reason: 'empty-responses' }
+  const report = partials.length === 1 ? partials[0] : safeCall(call, buildSynthesisPrompt(partials), model)
+  return { report, chunks: chunks.length, reason: report ? 'ok' : 'empty-responses' }
+}
+
+/**
+ * Шлях markdown-звіту аналізу.
+ * @param {string} [cwd] корінь
+ * @returns {string} шлях .n-cursor/fix-escalation-analysis.md
+ */
+export function analysisReportPath(cwd = processCwd()) {
+  return join(cwd, '.n-cursor', 'fix-escalation-analysis.md')
+}
+
+/**
+ * Дописує звіт у markdown-файл із timestamp-заголовком.
+ * @param {string} report текст звіту
+ * @param {string} cwd корінь
+ * @param {string} ts ISO-час
+ * @returns {string} шлях файлу
+ */
+export function writeAnalysisReport(report, cwd, ts) {
+  const path = analysisReportPath(cwd)
+  mkdirSync(dirname(path), { recursive: true })
+  appendFileSync(path, `\n## Аналіз ${ts}\n\n${report}\n`, 'utf8')
+  return path
+}
+
+/**
+ * Спільний шлях: аналіз записів → запис звіту → лог-підсумок.
+ * @param {object[]} records записи
+ * @param {string} cwd корінь
+ * @param {(s: string) => void} log логер
+ * @returns {number} 0 — ок/пропуск, 1 — модель не дала звіт
+ */
+function analyzeAndReport(records, cwd, log) {
+  const res = analyzeEscalations(records, { log })
+  if (res.reason === 'no-records') {
+    log('ℹ️  escalation-analysis: немає записів для аналізу.')
+    return 0
+  }
+  if (res.reason === 'no-cloud-avg-model') {
+    log('⚠️  escalation-analysis: N_CLOUD_AVG_MODEL не заданий — аналіз пропущено.')
+    return 0
+  }
+  if (!res.report) {
+    log('⚠️  escalation-analysis: модель не повернула звіт.')
+    return 1
+  }
+  const reportPath = writeAnalysisReport(res.report, cwd, new Date().toISOString())
+  log(`📝 escalation-analysis: звіт → ${reportPath} (${res.chunks} чанк(и))`)
+  return 0
+}
+
+/**
+ * CLI `n-cursor analyze-escalation` — аналізує ВЕСЬ escalation-лог і пише звіт.
+ * @param {string[]} _args аргументи (зарезервовано)
+ * @param {string} [cwd] корінь
+ * @returns {number} exit code
+ */
+export function runEscalationAnalysisCli(_args, cwd = processCwd()) {
+  const records = readEscalationRecords(escalationLogPath(), 0)
+  return analyzeAndReport(records, cwd, s => console.log(s))
+}
+
+/**
+ * Хук наприкінці `lint --full` (non-read-only): аналізує записи ЦЬОГО прогону
+ * (від `sinceOffset`). Gated: kill-switch, наявність cloud-avg, наявність записів.
+ * Помилки не валять lint.
+ * @param {string} cwd корінь
+ * @param {number} sinceOffset байтовий зсув логу перед прогоном
+ * @param {(s: string) => void} log логер
+ * @returns {void}
+ */
+export function maybeAnalyzeEscalation(cwd, sinceOffset, log) {
+  if (!analysisEnabled()) return
+  const records = readEscalationRecords(escalationLogPath(), sinceOffset)
+  if (records.length === 0) return
+  if (!CLOUD_AVG) {
+    log('\nℹ️  escalation-analysis: були LLM-ескалації, але N_CLOUD_AVG_MODEL не заданий — аналіз пропущено.\n')
+    return
+  }
+  log('\n🔬 escalation-analysis: аналізую ескалації цього прогону…\n')
+  analyzeAndReport(records, cwd, log)
+}

package/scripts/lib/fix/docs/analyze-escalation.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: analyze-escalation.mjs
+resource: npm/scripts/lib/fix/analyze-escalation.mjs
+docgen:
+  crc: f802e47f
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Аналітика escalation-логу fix-конформності. Читає записи рунгів драбини (`escalation-log.mjs`) — весь лог або записи одного прогону (від байтового зсуву), — ділить на чанки за бюджетом символів і просить хмарну **avg**-модель запропонувати, як зменшити LLM-залежність: нові детерміновані T0-патерни, уточнення `.mdc`-інструкцій або зміни скриптів пакета. Результат — markdown-звіт у `.n-cursor/fix-escalation-analysis.md` (append із timestamp). Викликається CLI `n-cursor analyze-escalation` (весь лог) і наприкінці `lint --full` (записи прогону).
+
+## Поведінка
+
+`readEscalationRecords` читає JSONL від байтового зсуву (зсув на межі рядка — мультибайт не б'ється; биті рядки пропускаються); `escalationLogSize` дає зсув для scope «цей прогін». `chunkRecords` стискає записи й ділить на чанки, щоб JSON кожного не перевищив бюджет. `analyzeEscalations` (синхронний — callLlm spawnSync-based) робить виклик avg-моделі по кожному чанку, а за кількох чанків — фінальний синтез; помилки моделі ковтаються в `null` (аналіз не валить lint). `maybeAnalyzeEscalation` — хук lint: gated kill-switch `N_CURSOR_FIX_ANALYZE`, наявністю `CLOUD_AVG` і записів.
+
+## Публічний API
+
+- `analysisEnabled()` — чи дозволено авто-аналіз (kill-switch `N_CURSOR_FIX_ANALYZE`).
+- `escalationLogSize(path?)` — розмір логу в байтах (since-offset).
+- `readEscalationRecords(path, sinceOffset?)` — записи від зсуву.
+- `chunkRecords(records, maxChars?)` — чанки стиснених записів.
+- `analyzeEscalations(records, opts?)` — `{ report, chunks, reason }`; `opts.callLlm` інжектовний.
+- `analysisReportPath(cwd?)` / `writeAnalysisReport(report, cwd, ts)` — шлях/запис звіту.
+- `runEscalationAnalysisCli(args, cwd?)` — CLI: весь лог → звіт.
+- `maybeAnalyzeEscalation(cwd, sinceOffset, log)` — хук наприкінці `lint --full`.
+
+## Гарантії поведінки
+
+- Звертається до мережі лише при виклику avg-моделі (через pi/omlx за префіксом model-id).
+- Помилки виклику моделі перехоплює (fail-safe): аналіз не впливає на exit-код lint.

package/scripts/lib/fix/docs/escalation-log.md

@@ -0,0 +1,27 @@
+---
+type: JS Module
+title: escalation-log.mjs
+resource: npm/scripts/lib/fix/escalation-log.mjs
+docgen:
+  crc: 07ae959f
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+Append-only JSONL-лог драбини ескалації конформність-фіксу. Один запис на рунг драбини: модель, чи виклик удався, чи правило стало зеленим після рунга («чи допомогло»), залишковий violation і само-аналіз моделі (`diagnosis`). Доповнює always-on wire-trace — той знає вміст викликів, але не результат re-check; join — за полем `caller` (`fix:<rule>:<rung>`).
+
+## Поведінка
+
+`escalationLogPath` резолвить шлях: `N_CURSOR_FIX_ESCALATION_LOG` як kill-switch (`0|false|off|no` → лог вимкнено, повертає `null`) або як явний шлях; інакше дефолт `<cwd>/.n-cursor/fix-escalation.jsonl`.
+
+`logEscalation` дописує один JSONL-рядок (no-op, якщо лог вимкнено). Поля `remainingViolation` і `diagnosis` обрізаються до межі; `recheckOk` обнуляє `remainingViolation`. Помилки запису ковтаються — лог діагностичний і не має валити сам фікс.
+
+## Публічний API
+
+- `escalationLogPath()` — шлях активного логу або `null`, якщо вимкнено.
+- `logEscalation(rec)` — дописує запис рунга у JSONL.
+
+## Гарантії поведінки
+
+- Не звертається до мережі.
+- Перехоплює помилки запису і не пропускає винятків назовні (fail-safe).

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

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

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

@@ -3,27 +3,24 @@ type: JS Module
 title: llm-worker.mjs
 resource: npm/scripts/lib/fix/llm-worker.mjs
 docgen:
-  crc: 00730451
+  crc: de9eb68c
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль визначає моделі для стандартних та складних виправлень коду. Він надає функції для ініціалізації моделей (`MODEL`, `MODEL_HEAVY`) та для виконання роботи з мовною моделлю (`runLlmWorker`), застосовуючи згенеровані зміни до файлів проєкту.
+Модуль виправляє одне rule-порушення конформності через LLM: читає `.mdc` правила, дістає файли з violation-output, будує prompt і застосовує згенеровані зміни. Підтримує **feedback-режим** драбини ескалації — у повторний виклик передається контекст попереднього рунга, а модель спершу формулює `diagnosis` («чому попередня спроба не вдалася»), тоді виправляє.
 
 ## Поведінка
 
-MODEL визначає модель за замовчуванням для виправлення, використовуючи змінну середовища або значення за замовчуванням.
-MODEL_HEAVY визначає модель для важких виправлень, використовуючи змінну середовища або значення за замовчуванням.
-runLlmWorker виправляє одне правило-порушення, викликаючи LLM для генерації змін, а потім застосовує ці зміни до файлів проєкту.
+`runLlmWorker` читає `.mdc` правила, читає файли з violation-output, будує prompt і викликає модель через спільний `callLlm` (з міткою `caller` для wire-trace). Відповідь очікується як JSON `{diagnosis, changes}`; зміни застосовуються до файлів повним вмістом.
+
+Якщо переданий `feedback`, prompt додає блок попереднього рунга (модель, попередньо змінені файли, помилка) і просить діагностувати причину невдачі у полі `diagnosis`. Результат повертається з `changes` і `diagnosis` навіть при невдачі — щоб драбина (`orchestrator.mjs`) їх залогувала і прокинула далі.
 
 ## Публічний API
 
-MODEL — Основна модель для обробки даних.
-MODEL_HEAVY — Важка модель для складних обчислень.
-runLlmWorker — Виправляє одне порушення правила, використовуючи шаблон C1.
+- `runLlmWorker(ruleId, violationOutput, projectRoot, opts)` — виправляє одне порушення; `opts`: `model`, `feedback`, `caller`. Повертає `{ ok, error, changes, diagnosis }`.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- Не звертається до мережі.
+- Перехоплює помилки виклику моделі й не пропускає винятків назовні (fail-safe): дружнє повідомлення для відсутнього API-ключа хмарного провайдера.
+- Звертається до мережі під час виклику моделі (omlx HTTP або pi CLI, залежно від префікса model-id).

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

@@ -3,24 +3,33 @@ type: JS Module
 title: orchestrator.mjs
 resource: npm/scripts/lib/fix/orchestrator.mjs
 docgen:
-  crc: 3a66072d
+  crc: 78dfe86b
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль керує процесом валідації та виправлення правил. Він ініціює перевірку всіх правил. Якщо виявлено порушення, процес ітеративно застосовує детермінований механізм виправлення (T0) та виправлення на основі великої мовної моделі (T1) до невирішених правил. Цей цикл повторюється до досягнення стану, коли всі правила відповідають вимогам, або до перевищення встановленого ліміту ітерацій. Функція `runOrchestratorCli` запускає цей процес.
+Модуль керує процесом валідації та виправлення конформності правил. Він перевіряє правила, застосовує детермінований механізм (T0), а нерозв'язані порушення проводить по **драбині ескалації моделей**: локальна min-модель → той самий локальний тир із feedback → хмарна min → хмарна avg. Кожен крок драбини логується для подальшого аналізу. Функція `runOrchestratorCli` запускає процес.
 
 ## Поведінка
 
-1. `runOrchestratorCli` виконує початкову перевірку всіх правил. Якщо порушень немає, процес завершується успішно.
-2. Якщо порушення виявлено, ініціюється ітеративний цикл до максимальної кількості ітерацій.
-3. На кожній ітерації виконується детермінований фікс (крок T0). Це зменшує кількість правил, що потребують подальшої обробки.
-4. Якщо після кроку T0 залишилися невирішені правила, виконується LLM-фікс (крок T1). Для кожного невирішеного правила застосовується відповідна модель, яка може ескалуватися при повторних провалах.
-5. Після LLM-фіксу виконується повторна перевірка всіх правил.
-6. Якщо після перевірки всі правила чисті, процес завершується успішно.
-7. Якщо після завершення всіх ітерацій залишаються невирішені правила, процес завершується з позначкою про невирішені проблеми.
+1. `runOrchestratorCli` виконує початкову перевірку правил. Якщо порушень немає — успіх.
+2. Один прохід детермінованого фіксу (T0) зменшує набір порушень без LLM.
+3. `buildLadder` будує драбину з доступних тирів (`N_LOCAL_MIN_MODEL`, `N_CLOUD_MIN_MODEL`, `N_CLOUD_AVG_MODEL`); незадані тири відсіюються. Якщо драбина порожня — процес завершується з ознакою нерозв'язаних порушень.
+4. `escalateRule` проводить кожне правило по драбині до першого зеленого re-check:
+   - рунг `local-min` — перший прохід без feedback;
+   - рунг `local-min-retry` — той самий локальний тир, але з feedback попереднього рунга (попередні зміни + залишковий violation);
+   - рунги `cloud-min` / `cloud-avg` — хмарні моделі (через pi), теж із feedback.
+5. Достроковий вихід драбини: systemic-помилка локального тиру пропускає рунги тієї ж моделі; відсутній API-ключ на хмарному обриває драбину; вичерпаний avg-кеп пропускає avg-рунг (із записом у лог).
+6. Після обробки всіх правил — фінальна перевірка. Усі чисті → успіх; інакше — ознака нерозв'язаних.
+
+## Публічний API
+
+- `buildLadder({ localMin, cloudMin, cloudAvg })` — будує драбину рунгів із наявних тирів.
+- `escalateRule(rule, cwd, deps)` — проводить одне правило по драбині; повертає `{ resolved, avgUsed }`. Залежності (`worker`, `check`, `clock`) інжектовні для тестів.
+- `parseOrchestratorArgs(args)` — парсить `--max-avg N` (кеп на хмарні avg-виклики) і фільтр правил.
+- `runOrchestratorCli(args, cwd)` — точка входу; повертає `0` (усе чисто) або `1` (нерозв'язані).
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Не звертається до мережі.
+- Кожен рунг драбини дописується в escalation-лог (`escalation-log.mjs`): модель, чи виклик удався, чи правило стало зеленим, залишковий violation і само-аналіз моделі.
+- Звертається до мережі лише на хмарних рунгах драбини (через pi).

package/scripts/lib/fix/escalation-log.mjs

@@ -0,0 +1,92 @@
+/**
+ * Append-only JSONL-лог ескалації конформність-фіксу (спека
+ * 2026-06-19-fix-escalation-cascade-design). Один запис **на рунг драбини** —
+ * фіксує `model`, `withFeedback`, чи виклик удався (`callOk`/`callError`), чи
+ * правило стало зеленим після цього рунга (`recheckOk` = «чи допомогло»),
+ * залишковий violation і `diagnosis` (само-аналіз моделі «чому не вдалося»).
+ *
+ * Це доповнення до always-on wire-trace (`lib/omlx-trace.mjs`): trace знає
+ * `messages`/`reasoning`/`usage` кожного виклику, але **не** знає результату
+ * re-check — а саме «чи допомогло» й потрібне для пост-аналізу драбини. Join із
+ * trace — за полем `caller` (`fix:<rule>:<rung>`), яке цей модуль і формує.
+ *
+ * Шлях — дзеркало `tracePath()`: `N_CURSOR_FIX_ESCALATION_LOG` (kill-switch
+ * `0|false|off|no` → не писати; інакше явний шлях) → дефолт
+ * `<cwd>/.n-cursor/fix-escalation.jsonl`.
+ */
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { cwd, env } from 'node:process'
+
+/** Значення `N_CURSOR_FIX_ESCALATION_LOG`, що вимикають лог повністю. */
+const KILL_VALUES = new Set(['0', 'false', 'off', 'no'])
+
+/** Межа обрізки `remainingViolation`/`diagnosis` у записі (символів). */
+const MAX_FIELD_CHARS = 2000
+
+/**
+ * Шлях активного escalation-логу або `null`, якщо вимкнено kill-switch-ем.
+ * @returns {string|null} шлях до .jsonl або null
+ */
+export function escalationLogPath() {
+  const override = env.N_CURSOR_FIX_ESCALATION_LOG
+  if (override !== undefined) {
+    if (KILL_VALUES.has(override.toLowerCase())) return null
+    if (override) return override
+  }
+  return join(cwd(), '.n-cursor', 'fix-escalation.jsonl')
+}
+
+/**
+ * Обрізає рядок до `MAX_FIELD_CHARS` (null/undefined → null).
+ * @param {string|null|undefined} s вхід
+ * @returns {string|null} обрізаний рядок або null
+ */
+function cap(s) {
+  if (s === null || s === undefined) return null
+  return s.length > MAX_FIELD_CHARS ? s.slice(0, MAX_FIELD_CHARS) : s
+}
+
+/**
+ * Дописує один запис рунга у JSONL-лог (no-op, якщо вимкнено). Помилки запису
+ * ковтаються — лог діагностичний, не має валити сам фікс.
+ * @param {object} rec запис рунга
+ * @param {string} rec.ts ISO-час завершення рунга
+ * @param {string} rec.ruleId id правила
+ * @param {number} rec.rung індекс рунга драбини (0-based)
+ * @param {string} rec.tier мітка тиру (`local-min`|`local-min-retry`|`cloud-min`|`cloud-avg`)
+ * @param {string} rec.model model-id (порожній → pi-дефолт)
+ * @param {boolean} rec.withFeedback чи передавався feedback попереднього рунга
+ * @param {boolean} rec.callOk чи виклик моделі+apply удався
+ * @param {string|null} rec.callError помилка виклику (null, якщо callOk)
+ * @param {boolean} rec.recheckOk чи правило стало зеленим після рунга («чи допомогло»)
+ * @param {string|null} rec.remainingViolation залишковий violation (null, якщо recheckOk)
+ * @param {string|null} rec.diagnosis само-аналіз моделі «чому попередній рунг не вдався»
+ * @param {number} rec.ms тривалість рунга (мс)
+ * @returns {void}
+ */
+export function logEscalation(rec) {
+  const path = escalationLogPath()
+  if (!path) return
+  const line =
+    JSON.stringify({
+      ts: rec.ts,
+      ruleId: rec.ruleId,
+      rung: rec.rung,
+      tier: rec.tier,
+      model: rec.model,
+      withFeedback: rec.withFeedback,
+      callOk: rec.callOk,
+      callError: cap(rec.callError),
+      recheckOk: rec.recheckOk,
+      remainingViolation: rec.recheckOk ? null : cap(rec.remainingViolation),
+      diagnosis: cap(rec.diagnosis),
+      ms: rec.ms
+    }) + '\n'
+  try {
+    mkdirSync(dirname(path), { recursive: true })
+    appendFileSync(path, line, 'utf8')
+  } catch {
+    /* лог діагностичний — ковтаємо помилки запису */
+  }
+}

package/scripts/lib/fix/llm-worker.mjs

@@ -7,10 +7,10 @@ import { resolveModel } from '../../../lib/models.mjs'
 import { callLlm } from '../../../lib/llm.mjs'
 import { applyChanges, parseChangesResponse, readFilesForFix } from './llm-fix-apply.mjs'
 
-// Тир за замовчуванням: 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')
+// Дефолтна модель, коли викликач не задав `opts.model` (legacy/прямі виклики).
+// Драбина ескалації (`orchestrator.mjs`) завжди передає модель рунга явно, тож
+// тут лишається тільки fallback на min-тир. Перевизначення — `N_CURSOR_FIX_MODEL`.
+const MODEL = env.N_CURSOR_FIX_MODEL ?? resolveModel('min')
 
 const API_KEY_RE = /api key/i
 
@@ -49,13 +49,36 @@ function extractFilePaths(output) {
 
 /**
  * Будує prompt для pi: правило + порушення + поточний вміст файлів.
+ * Будує опційний feedback-блок драбини ескалації: попередній рунг застосував
+ * зміни, але re-check лишився червоним. Просимо модель спершу (в полі `diagnosis`)
+ * сформулювати, **чому** попередня спроба не задовольнила правило, тоді виправити.
+ * @param {{ previousModel?: string, previousChanges?: Array<{path:string}>, previousError?: string|null } | null} feedback контекст попереднього рунга
+ * @returns {string[]} рядки prompt-блоку (порожній масив, якщо feedback немає)
+ */
+function buildFeedbackBlock(feedback) {
+  if (!feedback) return []
+  const changedPaths = (feedback.previousChanges ?? []).map(c => c.path).filter(Boolean)
+  return [
+    ``,
+    `A PREVIOUS attempt (model: ${feedback.previousModel || 'pi'}) did NOT resolve this violation.`,
+    changedPaths.length > 0
+      ? `Previously changed files: ${changedPaths.join(', ')}`
+      : `The previous attempt produced no usable changes.`,
+    feedback.previousError ? `Previous attempt error: ${feedback.previousError}` : ``,
+    `The violation output below is what STILL fails after that attempt.`,
+    `In the "diagnosis" field, briefly state WHY the previous attempt failed, then provide a corrected fix.`
+  ].filter(line => line !== ``)
+}
+
+/**
  * @param {string} ruleId ID правила
  * @param {string} ruleMdc   вміст .mdc-файлу правила
  * @param {string} output    violation output
  * @param {Array<{path:string, content:string}>} files прочитані файли (path + content)
+ * @param {{ previousModel?: string, previousChanges?: Array<{path:string}>, previousError?: string|null } | null} [feedback] контекст попереднього рунга драбини (для retry-with-feedback)
  * @returns {string} текст промпта для pi
  */
-function buildPrompt(ruleId, ruleMdc, output, files) {
+function buildPrompt(ruleId, ruleMdc, output, files, feedback = null) {
   const filesBlock =
     files.length === 0
       ? '(no files identified)'
@@ -63,6 +86,7 @@ function buildPrompt(ruleId, ruleMdc, output, files) {
 
   return [
     `You fix project structure violations. Return ONLY valid JSON — no explanation, no markdown.`,
+    ...buildFeedbackBlock(feedback),
     ``,
     `Rule (n-${ruleId}.mdc):`,
     `---`,
@@ -76,13 +100,14 @@ function buildPrompt(ruleId, ruleMdc, output, files) {
     filesBlock,
     ``,
     `Return JSON with this exact shape:`,
-    `{"changes":[{"path":"relative/path/to/file","content":"full corrected file content"}]}`,
+    `{"diagnosis":"short reason the rule fails (or why prior attempt failed); empty string if first attempt","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"}`
+    `- "diagnosis" is plain text inside the JSON — do NOT emit prose outside the JSON`,
+    `- If nothing can be fixed automatically, return {"diagnosis":"...","changes":[],"error":"reason"}`
   ].join('\n')
 }
 
@@ -91,11 +116,12 @@ function buildPrompt(ruleId, ruleMdc, output, files) {
  * Зберігає дружнє повідомлення про відсутній API-ключ для хмарних провайдерів.
  * @param {string} prompt текст промпта
  * @param {string} model назва моделі (provider/id, `omlx/...` або '')
+ * @param {string} caller мітка викликача для wire-trace (`fix:<rule>:<rung>`)
  * @returns {{ text: string, error?: string }} текст відповіді або повідомлення про помилку
  */
-function callModel(prompt, model) {
+function callModel(prompt, model, caller) {
   try {
-    return { text: callLlm([{ role: 'user', content: prompt }], model, { timeoutMs: 120_000, caller: 'fix' }) }
+    return { text: callLlm([{ role: 'user', content: prompt }], model, { timeoutMs: 120_000, caller }) }
   } catch (error) {
     const msg = String(error.message)
     if (API_KEY_RE.test(msg)) {
@@ -115,14 +141,21 @@ function callModel(prompt, model) {
 
 /**
  * LLM-worker: виправляє одне rule-порушення через pi (C1 pattern).
+ * Повертає `changes`/`diagnosis` навіть при невдачі — драбина ескалації
+ * (`orchestrator.mjs`) логує їх і прокидає як feedback у наступний рунг.
  * @param {string} ruleId ID правила
  * @param {string} violationOutput  output з fix check для цього rule
  * @param {string} projectRoot      абсолютний шлях до кореня проєкту
- * @param {{ model?: string }} opts опції (model — перевизначення моделі)
- * @returns {Promise<{ ok: boolean, error?: string }>} статус виправлення і можлива помилка
+ * @param {{ model?: string, feedback?: object|null, caller?: string }} opts опції:
+ *   `model` — перевизначення моделі; `feedback` — контекст попереднього рунга
+ *   драбини (retry-with-feedback); `caller` — мітка для wire-trace
+ * @returns {{ ok: boolean, error?: string, changes: Array<{path:string}>, diagnosis: string|null }}
+ *   статус виправлення, помилка, запропоновані зміни і само-аналіз моделі
  */
 export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
   const model = opts.model ?? MODEL
+  const feedback = opts.feedback ?? null
+  const caller = opts.caller ?? 'fix'
 
   // 1. Читаємо rule .mdc
   const mdcPath = join(projectRoot, '.cursor', 'rules', `n-${ruleId}.mdc`)
@@ -132,20 +165,23 @@ export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
   const files = readFilesForFix(extractFilePaths(violationOutput), projectRoot)
 
   // 3. Будуємо prompt і викликаємо модель
-  const prompt = buildPrompt(ruleId, ruleMdc, violationOutput, files)
-  const { text, error: modelError } = callModel(prompt, model)
+  const prompt = buildPrompt(ruleId, ruleMdc, violationOutput, files, feedback)
+  const { text, error: modelError } = callModel(prompt, model, caller)
 
-  if (modelError) return { ok: false, error: modelError }
-  if (!text) return { ok: false, error: 'model returned empty response' }
+  if (modelError) return { ok: false, error: modelError, changes: [], diagnosis: null }
+  if (!text) return { ok: false, error: 'model returned empty response', changes: [], diagnosis: null }
 
   // 4. Парсимо відповідь
   const parsed = parseChangesResponse(text)
-  if (!parsed) return { ok: false, error: `cannot parse pi response: ${text.slice(0, 200)}` }
-  if (parsed.error) return { ok: false, error: parsed.error }
-
+  if (!parsed) {
+    return { ok: false, error: `cannot parse pi response: ${text.slice(0, 200)}`, changes: [], diagnosis: null }
+  }
+  const diagnosis = typeof parsed.diagnosis === 'string' && parsed.diagnosis ? parsed.diagnosis : null
   const changes = parsed.changes ?? []
-  if (changes.length === 0) return { ok: false, error: 'pi returned no changes' }
+  if (parsed.error) return { ok: false, error: parsed.error, changes, diagnosis }
+  if (changes.length === 0) return { ok: false, error: 'pi returned no changes', changes, diagnosis }
 
   // 5. Застосовуємо зміни
-  return applyChanges(changes, projectRoot)
+  const applied = applyChanges(changes, projectRoot)
+  return { ...applied, changes, diagnosis }
 }

package/scripts/lib/fix/orchestrator.mjs

@@ -2,22 +2,137 @@
 
 import { runFixCheck } from './run-fix-check.mjs'
 import { runT0AutoCli } from './t0.mjs'
+import { logEscalation } from './escalation-log.mjs'
+import { runLlmWorker } from './llm-worker.mjs'
+import { classifyOmlxError } from '../../../lib/llm.mjs'
+import { CLOUD_AVG, CLOUD_MIN, LOCAL_MIN } from '../../../lib/models.mjs'
 
-const DEFAULT_MAX_ITER = 3
-const ESCALATE_AFTER = 2
+/**
+ * Дефолтний кеп на виклики хмарної avg-моделі за один прогін (щоб драбина на N
+ * правил не спалила потужну модель). Перевизначення: `--max-avg N`.
+ */
+const DEFAULT_MAX_AVG = 3
+
+/** Маркер дружнього повідомлення про відсутній API-ключ (з `llm-worker.callModel`). */
+const NO_KEY_RE = /немає ключа|api key/i
+
+/**
+ * Будує драбину ескалації за наявними тирами (спека 2026-06-19-fix-escalation-cascade):
+ *  1. `local-min`       — `N_LOCAL_MIN_MODEL`, перший прохід;
+ *  2. `local-min-retry` — той самий локальний, але з feedback попереднього рунга;
+ *  3. `cloud-min`       — `N_CLOUD_MIN_MODEL` (через pi), з feedback;
+ *  4. `cloud-avg`       — `N_CLOUD_AVG_MODEL` (через pi), з feedback, під avg-кепом.
+ * Рунги з незаданим тиром (`''`) відсіюються — драбина стискається до доступних.
+ * @param {{ localMin: string, cloudMin: string, cloudAvg: string }} models тири з env
+ * @returns {Array<{ tier: string, model: string, feedback: boolean, local: boolean, isAvg: boolean }>} драбина
+ */
+export function buildLadder({ localMin, cloudMin, cloudAvg }) {
+  return [
+    { tier: 'local-min', model: localMin, feedback: false, local: true, isAvg: false },
+    { tier: 'local-min-retry', model: localMin, feedback: true, local: true, isAvg: false },
+    { tier: 'cloud-min', model: cloudMin, feedback: true, local: false, isAvg: false },
+    { tier: 'cloud-avg', model: cloudAvg, feedback: true, local: false, isAvg: true }
+  ].filter(r => r.model)
+}
+
+/**
+ * Рішення після провального рунга: чи обірвати драбину / пропустити модель.
+ *  - `break`     — відсутній API-ключ на хмарному (інші хмарні рунги теж без ключа);
+ *  - `skip-model` — systemic-помилка локального тиру (memory-guard/auth/down): повтор
+ *                   тієї ж моделі марний → пропустити рунги з цим model.
+ * @param {{ local: boolean }} rung поточний рунг
+ * @param {string|null|undefined} error помилка виклику worker
+ * @returns {'break'|'skip-model'|null} дія для драбини
+ */
+function decideAfterFailure(rung, error) {
+  if (!error) return null
+  if (NO_KEY_RE.test(error)) return 'break'
+  if (rung.local && classifyOmlxError(error) === 'systemic') return 'skip-model'
+  return null
+}
+
+/**
+ * Проводить ОДНЕ правило по драбині ескалації до першого зеленого re-check.
+ * Кожен рунг: виклик worker (з feedback від попереднього) → re-check цього правила →
+ * запис у escalation-лог («чи допомогло» + diagnosis). Достроковий вихід — `decideAfterFailure`
+ * (обрив на no-key, пропуск моделі на systemic) і вичерпаний avg-кеп (залогувати, не мовчки).
+ * @param {{ ruleId: string, output: string }} rule провальне правило з violation-output
+ * @param {string} cwd корінь проєкту
+ * @param {{
+ *   ladder: Array<{tier:string,model:string,feedback:boolean,local:boolean,isAvg:boolean}>,
+ *   worker: { runLlmWorker: (ruleId: string, violation: string, cwd: string, opts: object) => object },
+ *   check: (rules: string[], cwd: string) => Promise<{rules: Array<{ruleId:string,ok:boolean,output:string}>}>,
+ *   avgBudget: number,
+ *   clock?: () => number,
+ *   log?: (s: string) => void
+ * }} deps інжектовані залежності (worker/check/clock — для тестів)
+ * @returns {Promise<{ resolved: boolean, avgUsed: number }>} чи закрито правило і скільки avg-викликів витрачено
+ */
+export async function escalateRule(rule, cwd, deps) {
+  const { ladder, worker, check, avgBudget } = deps
+  const clock = deps.clock ?? (() => Date.now())
+  const log = deps.log ?? (s => console.log(s))
+  const record = base => logEscalation({ ts: new Date(clock()).toISOString(), ruleId: rule.ruleId, ...base })
+
+  let feedback = null
+  let currentViolation = rule.output
+  const skipModels = new Set()
+  let avgUsed = 0
+
+  for (const [idx, rung] of ladder.entries()) {
+    if (skipModels.has(rung.model)) continue
+
+    const common = { rung: idx, tier: rung.tier, model: rung.model, withFeedback: rung.feedback }
+    if (rung.isAvg && avgBudget - avgUsed <= 0) {
+      record({ ...common, callOk: false, callError: 'cloud-avg cap reached', recheckOk: false, remainingViolation: currentViolation, diagnosis: null, ms: 0 })
+      log(`  ⏭️  ${rule.ruleId}: ${rung.tier} пропущено (avg-кеп вичерпано)`)
+      continue
+    }
+
+    const startedAt = clock()
+    const res = worker.runLlmWorker(rule.ruleId, currentViolation, cwd, {
+      model: rung.model,
+      feedback: rung.feedback ? feedback : null,
+      caller: `fix:${rule.ruleId}:${rung.tier}`
+    })
+    if (rung.isAvg) avgUsed++
+
+    const recheck = await check([rule.ruleId], cwd)
+    const recheckOk = recheck.rules.every(r => r.ok)
+    const remaining = recheckOk ? '' : (recheck.rules.find(r => !r.ok)?.output ?? '')
+    record({ ...common, callOk: res.ok, callError: res.error ?? null, recheckOk, remainingViolation: remaining, diagnosis: res.diagnosis ?? null, ms: clock() - startedAt })
+
+    if (recheckOk) {
+      log(`  ✅ ${rung.tier} (${rung.model || 'pi'}): ${rule.ruleId}`)
+      return { resolved: true, avgUsed }
+    }
+
+    const hint = res.error ? ` ❌ ${res.error.slice(0, 120)}` : ' ❌ досі порушено'
+    log(`  ⚡ ${rung.tier} (${rung.model || 'pi'}): ${rule.ruleId}${hint}`)
+
+    // Feedback для наступного рунга + оновлений violation.
+    feedback = { previousModel: rung.model, previousChanges: res.changes ?? [], previousError: res.error ?? null }
+    currentViolation = remaining || currentViolation
+
+    const action = decideAfterFailure(rung, res.error)
+    if (action === 'break') break
+    if (action === 'skip-model') skipModels.add(rung.model)
+  }
+
+  return { resolved: false, avgUsed }
+}
 
 /**
- * Парсить `--max-iter N` і збирає rule-filter (позиційні аргументи без прапорців).
+ * Парсить `--max-avg N` і збирає rule-filter (позиційні аргументи без прапорців).
  * @param {string[]} args CLI аргументи після 'fix'
- * @returns {{ maxIter: number, ruleFilter: string[] }} ліміт ітерацій і фільтр правил
+ * @returns {{ maxAvg: number, ruleFilter: string[] }} avg-кеп і фільтр правил
  */
-function parseOrchestratorArgs(args) {
-  const maxIterIdx = args.indexOf('--max-iter')
-  const maxIter =
-    maxIterIdx === -1 ? DEFAULT_MAX_ITER : Number(args[maxIterIdx + 1] ?? 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))
-  return { maxIter, ruleFilter }
+export function parseOrchestratorArgs(args) {
+  const idx = args.indexOf('--max-avg')
+  const maxAvg = idx === -1 ? DEFAULT_MAX_AVG : Number(args[idx + 1] ?? DEFAULT_MAX_AVG) || DEFAULT_MAX_AVG
+  const skip = new Set(idx === -1 ? [] : [idx, idx + 1])
+  const ruleFilter = args.filter((a, i) => !a.startsWith('-') && !skip.has(i))
+  return { maxAvg, ruleFilter }
 }
 
 /**
@@ -40,77 +155,65 @@ async function runT0Step(cwd, ruleFilter, failed) {
   return failedAfterT0
 }
 
-/**
- * Крок T1: LLM через pi для кожного правила, з ескалацією моделі за провалами.
- * @param {Array<{ ruleId: string, output: string }>} failed правила до фіксу
- * @param {string} cwd корінь проєкту
- * @param {Map<string, number>} failCount ruleId → кількість провалів підряд (мутується)
- * @param {{ runLlmWorker: (ruleId: string, output: string, projectRoot: string, opts: {model: string}) => Promise<{ok: boolean, error?: string}>, MODEL: string, MODEL_HEAVY: string }} worker воркер і моделі
- * @returns {Promise<void>}
- */
-async function runLlmStep(failed, cwd, failCount, { runLlmWorker, MODEL, MODEL_HEAVY }) {
-  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}`)
-    }
-  }
-}
-
 /**
  * @param {string[]} args   CLI аргументи після 'fix'
  * @param {string}   cwd    корінь проєкту
  * @returns {Promise<number>}  0 = all clean, 1 = unresolved
  */
 export async function runOrchestratorCli(args, cwd) {
-  const worker = await import('./llm-worker.mjs')
-  const { maxIter, ruleFilter } = parseOrchestratorArgs(args)
-
-  /** @type {Map<string, number>} ruleId → кількість LLM-провалів підряд */
-  const failCount = new Map()
+  const worker = { runLlmWorker }
+  const { maxAvg, ruleFilter } = parseOrchestratorArgs(args)
+  const ladder = buildLadder({ localMin: LOCAL_MIN, cloudMin: CLOUD_MIN, cloudAvg: CLOUD_AVG })
 
   // ── Перша перевірка (тихо) ──
   const initial = await runFixCheck(ruleFilter, cwd)
   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++) {
-    failed = await runT0Step(cwd, ruleFilter, failed)
-    if (failed.length === 0) break
+  // ── T0-auto (детермінований, без LLM) ──
+  failed = await runT0Step(cwd, ruleFilter, failed)
+  if (failed.length === 0) {
+    console.log(`✅ fix: ${total} правил — все чисто`)
+    return 0
+  }
 
-    await runLlmStep(failed, cwd, failCount, worker)
+  // ── LLM-драбина ескалації на правило ──
+  if (ladder.length === 0) {
+    console.log(
+      `❌ fix: ${failed.length} порушень потребують LLM, але жоден тир не заданий ` +
+        `(N_LOCAL_MIN_MODEL / N_CLOUD_MIN_MODEL / N_CLOUD_AVG_MODEL)`
+    )
+    return 1
+  }
+  console.log(`   драбина: ${ladder.map(r => r.tier).join(' → ')} (avg-кеп: ${maxAvg})`)
 
-    // Перевірка після LLM
-    const afterLLM = await runFixCheck(ruleFilter, cwd)
-    failed = afterLLM.rules.filter(r => !r.ok)
-    if (failed.length === 0) break
+  let avgBudget = maxAvg
+  for (const rule of failed) {
+    const { avgUsed } = await escalateRule(rule, cwd, {
+      ladder,
+      worker,
+      check: runFixCheck,
+      avgBudget
+    })
+    avgBudget -= avgUsed
   }
 
-  if (failed.length === 0) {
+  // ── Фінальна перевірка ──
+  const finalCheck = await runFixCheck(ruleFilter, cwd)
+  const stillFailed = finalCheck.rules.filter(r => !r.ok)
+  if (stillFailed.length === 0) {
     console.log(`✅ fix: ${total} правил — все чисто`)
     return 0
   }
 
-  console.log(`❌ fix: ${failed.length} невирішених — ${failed.map(r => r.ruleId).join(', ')}`)
+  console.log(`❌ fix: ${stillFailed.length} невирішених — ${stillFailed.map(r => r.ruleId).join(', ')}`)
   return 1
 }