@nitra/cursor 12.0.3 → 12.2.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-fix-apply.md

@@ -3,7 +3,7 @@ type: JS Module
 title: llm-fix-apply.mjs
 resource: npm/scripts/lib/fix/llm-fix-apply.mjs
 docgen:
-  crc: 80befb00
+  crc: 62e475fa
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
@@ -14,7 +14,7 @@ docgen:
 
 parseChangesResponse парсить сирий текст відповіді моделі, щоб витягнути структуру змін у форматі патчу або повернути null у разі невдачі парсингу.
 readFilesForFix зчитує вміст файлів, зазначених у списку відносних шляхів, відносно кореня проєкту, повертаючи список об'єктів з шляхом та вмістом або null для неіснуючих файлів.
-applyChanges записує нові вмісти в файли, використовуючи наданий список змін, відносно кореня проєкту, повертаючи статус успіху або помилки.
+applyChanges записує нові вмісти в файли, використовуючи наданий список змін, відносно кореня проєкту; перед записом створює батьківську теку (`mkdirSync recursive`) — модель може запропонувати новий файл у ще неіснуючому каталозі. Повертає статус успіху або помилки.
 
 ## Публічний API
 

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/docs/t0.md

@@ -3,19 +3,18 @@ type: JS Module
 title: t0.mjs
 resource: npm/scripts/lib/fix/t0.mjs
 docgen:
-  crc: 0321ecc1
+  crc: 524d91e2
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
-Модуль керує автоматичним застосуванням паттернів до правил для виправлення виводів порушень. Він визначає, які автоматичні паттерни можуть бути застосовані до правил, використовуючи `filterT0AutoRules`, і запускає повний процес виправлення для всіх відповідних правил через `applyT0Auto` та `runT0AutoCli`. Код працює у режимі fail-safe, перехоплюючи помилки та не викидаючи винятків назовні. Робота модуля залежить від конфігурацій `extensions.json` та `package-lock.json`.
+Модуль керує детермінованим (без LLM) застосуванням паттернів до виводів порушень конформності. Паттерни: `vscode-ext-add` (дописати розширення), `rm-forbidden-file` (видалити заборонений файл), `changelog-create-change-file` (створити change-файл через канонічну `writeChange` для воркспейсів із «немає change-файлу» — прибирає ескалацію в LLM на цьому кейсі). `filterT0AutoRules` визначає, які правила мають придатний паттерн; `applyT0Auto`/`runT0AutoCli` застосовують. Паттерн може бути sync або async (await нормалізує). Fail-safe: помилки перехоплюються.
 
 ## Поведінка
 
-Поведінка
-applyT0Auto застосовує визначені автоматичні паттерни до одного виводу порушення, щоб виправити його.
-filterT0AutoRules повертає список ідентифікаторів правил, для яких існують відповідні автоматичні паттерни.
-runT0AutoCli запускає процес виправлення T0-автоматично для всіх провальних правил, застосовуючи паттерни, повторно перевіряючи стан і виводячи підсумок.
+applyT0Auto застосовує придатні паттерни до одного виводу порушення (await на apply — паттерн може бути async, як `changelog-create-change-file`).
+filterT0AutoRules повертає id правил, для яких існує придатний паттерн.
+runT0AutoCli запускає T0-auto для всіх провальних правил, повторно перевіряє check-gate і виводить підсумок.
 
 ## Публічний API
 

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-fix-apply.mjs

@@ -3,8 +3,8 @@
  * під фікс і застосування змін. Використовують і `llm-worker.mjs` (конформність), і
  * `llm-lint-fix.mjs` (per-tool лінтер-фіксери) — щоб не дублювати парс/apply (knip/jscpd).
  */
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
 
 const JSON_CODE_BLOCK_RE = /```(?:json)?[ \t]{0,8}\n?([\s\S]*?)```/
 
@@ -69,7 +69,11 @@ export function applyChanges(changes, projectRoot) {
   for (const change of changes) {
     if (!change.path || typeof change.content !== 'string') continue
     try {
-      writeFileSync(join(projectRoot, change.path), change.content, 'utf8')
+      const abs = join(projectRoot, change.path)
+      // Створюємо батьківську теку перед записом: модель може запропонувати новий файл
+      // у ще неіснуючому каталозі (напр. `<ws>/.changes/…`) — інакше writeFileSync ENOENT.
+      mkdirSync(dirname(abs), { recursive: true })
+      writeFileSync(abs, change.content, 'utf8')
     } catch (error) {
       return { ok: false, error: `write ${change.path}: ${error.message}` }
     }