@nitra/cursor 11.0.0 → 11.2.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [11.2.0] - 2026-06-15
+
+### Changed
+
+- cspell-fix: заміна зламаного whole-file rewrite на classify→.cspell.json. Стара схема (llmLintFix whole-file) давала timeout 120с та parse-fail на реальних файлах; нова класифікує знахідки через bounded omlx-запит (≤80 слів → компактний JSON) і авто-дописує валідні слова у .cspell.json словник (sorted+dedup), а ймовірні одруки емітує на рев'ю без авто-застосування. Підтверджено на репо: 73 слова у словник за ≈5с (vs 120с timeout раніше).
+- cspell-fix: whole-file omlx-апплай → класифікація+словник (нова схема, спека docs/specs/2026-06-15-opportunistic-llm-fix-tier.md). Старий підхід (модель повертає весь файл як JSON) на укр+тех-репо операційно ламався — 120с-таймаути, memory-guard reject, parse-fail (вимір: 1406 знахідок / 292 файли, ~90% — валідні терміни, не одруки). Новий fix-режим робить **один bounded omlx-виклик**: класифікує distinct «Unknown word» → валідні слова авто-дописує у `.cspell.json#words` (sorted/dedup, видно в diff) → ймовірні одруки лишає списком на рев'ю (НЕ авто-виправляє — апплай небезпечний) → re-detect. read-only незмінний (нуль мутацій). Єдиний knob моделі — `N_LOCAL_MIN_MODEL` (прибрано `N_CURSOR_FIX_MODEL` із цього шляху). Preflight omlx (fast-skip замість приречених викликів), cap класифікації з логом надлишку. `groupFindingsByFile` → `unknownWords`/`appendWordsToDict`.
+- llm: спільний `preflightLocalModel(model)` у `npm/lib/llm.mjs` — omlx health-check (memory-guard / down / auth) як одна цеглина opportunistic LLM-fix tier (спека docs/specs/2026-06-15-opportunistic-llm-fix-tier.md). Прибрано дубльовані локальні `preflightProblem` із `doc-files/js/docgen-files-batch.mjs` (генерація) і `text/lint/cspell-fix.mjs` (класифікація) — обидва тепер кличуть спільний хелпер із `N_LOCAL_MIN_MODEL`. Per-target loop/circuit-breaker лишається у doc-files (cspell — single-call). Поведінка незмінна.
+
+## [11.1.0] - 2026-06-15
+
+### Changed
+
+- doc-files lint-крок: opportunistic LLM-fix tier (спека docs/specs/2026-06-15-opportunistic-llm-fix-tier.md). У fix-by-default (не `--read-only`) крок тепер не лише детектить застарілі доки, а й намагається їх **згенерувати** локальною моделлю, якщо omlx піднято; недоступний omlx → fix пропускається з повідомленням і лишається exit 1 (гейт тримається, без false-green). `--read-only` (CI/hook) лишається суто детектом — нуль мутацій/LLM. Прапор `meta.json: llmFix:true` (схема `rule-meta.json`) — opt-in лише для контент-правил; логічні лінтери НЕ вмикати (LLM-правка коду може змінити поведінку). Спільне ядро генерації винесено в `runGenerationBatch`/`preflightProblem` (експорт з `docgen-files-batch.mjs`) — перевикористовують і батч-CLI `fix-doc-files`, і lint-крок.
+
 ## [11.0.0] - 2026-06-15
 
 ### Removed

package/lib/llm.mjs

@@ -168,3 +168,30 @@ export function omlxHealthCheck(opts = {}) {
     return { ok: false, reason: 'error', detail }
   }
 }
+
+/**
+ * Спільний preflight локальної fix/gen-моделі (opportunistic LLM-fix tier, спека
+ * docs/specs/2026-06-15-opportunistic-llm-fix-tier.md): чи можна звати модель зараз.
+ * Health-check лише для omlx-бекенду (pi/cloud — завжди дозволено). Використовують
+ * doc-files (генерація) і text/cspell (класифікація) — fast-skip замість приречених викликів.
+ * @param {string} model model-id (зазвичай `N_LOCAL_MIN_MODEL`)
+ * @returns {string|null} людинозрозумілий текст проблеми, або null якщо можна викликати
+ */
+export function preflightLocalModel(model) {
+  if (!model) {
+    return 'модель не задано. Вистав N_LOCAL_MIN_MODEL (напр. omlx/mlx-community--gemma-4-e4b-it-OptiQ-4bit) і повтори.'
+  }
+  if (pickBackend(model) !== 'omlx') return null
+  const hc = omlxHealthCheck({ model })
+  if (hc.ok) return null
+  if (hc.reason === 'memory-guard') {
+    return `omlx memory-guard: модель не влазить у динамічну стелю пам'яті (машина зайнята).\n  Звільни пам'ять або повтори прогін пізніше.\n  ${hc.detail}`
+  }
+  if (hc.reason === 'down') {
+    return `omlx-сервер не відповідає. Запусти \`omlx serve\` і повтори.\n  ${hc.detail}`
+  }
+  if (hc.reason === 'auth') {
+    return `omlx вимагає API-ключ. Вистав N_CURSOR_OMLX_KEY (auth.api_key з ~/.omlx/settings.json).\n  ${hc.detail}`
+  }
+  return `omlx помилка: ${hc.detail}`
+}

package/package.json

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

package/rules/doc-files/js/docgen-crc.mjs

@@ -10,8 +10,8 @@
  * Degraded-маркер (ADR 260610-2228): якщо локальний конвеєр не дотягнув до порогу
  * якості, дока все одно пишеться, а frontmatter додатково несе `score` (det-оцінка)
  * та `issues` (коди проблем). CRC при цьому свіжий — Stop-гейт не блокує задачі через
- * слабкість моделі; борг видимий через `check --degraded` і адресно перегенеровується
- * через `gen --retry-degraded`.
+ * слабкість моделі; борг видимий через `check --degraded` і автоматично доретраюється
+ * наступним `gen` (рівно один раз на версію джерела — далі `retried: true` у frontmatter).
  *
  * Frontmatter — єдиний дозволений виняток із правила «чистий Markdown без HTML»:
  * це машинні метадані, не контент. Формат:
@@ -54,6 +54,8 @@ const CRC_RE = /^[ \t]{0,8}crc:[ \t]{0,8}(.+)$/mu
 const MODEL_RE = /^[ \t]{0,8}model:[ \t]{0,8}(.+)$/mu
 const SCORE_RE = /^[ \t]{0,8}score:[ \t]{0,8}(\d+)$/mu
 const ISSUES_RE = /^[ \t]{0,8}issues:[ \t]{0,8}(.+)$/mu
+const RETRIED_RE = /^[ \t]{0,8}retried:[ \t]{0,8}true[ \t]*$/mu
+const JUDGE_MODEL_RE = /^[ \t]{0,8}judgeModel:[ \t]{0,8}(.+)$/mu
 const LEADING_NEWLINES_RE = /^\n+/u
 const ISSUE_CODE_TAIL_RE = /[,:]$/u
 
@@ -62,7 +64,7 @@ const ISSUE_CODE_TAIL_RE = /[,:]$/u
  * Поля `model`/`score`/`issues` опційні (back-compat зі старими доками): без них —
  * `model:null`, `score:null`, `issues:[]`.
  * @param {string} md вміст md-файлу
- * @returns {{ data: { source: string|null, crc: string|null, model: string|null, score: number|null, issues: string[] }|null, body: string }} метадані + тіло без frontmatter
+ * @returns {{ data: { source: string|null, crc: string|null, model: string|null, score: number|null, issues: string[], retried: boolean, judgeModel: string|null }|null, body: string }} метадані + тіло без frontmatter
  */
 export function parseDocFrontmatter(md) {
   const match = md.match(FRONTMATTER_RE)
@@ -81,7 +83,9 @@ export function parseDocFrontmatter(md) {
             .split(',')
             .map(s => s.trim())
             .filter(Boolean)
-        : []
+        : [],
+      retried: RETRIED_RE.test(block),
+      judgeModel: block.match(JUDGE_MODEL_RE)?.[1].trim() ?? null
     },
     body: md.slice(match[0].length)
   }
@@ -107,7 +111,7 @@ function issueCodes(issues) {
  * Будує frontmatter-блок із шляхом джерела, CRC, (опційно) моделлю-генератором і якістю.
  * @param {string} source відносний шлях джерела
  * @param {string} crc CRC32 джерела у hex
- * @param {{ score: number, issues?: string[] }|null} [quality] det-оцінка доки; null — без полів якості
+ * @param {{ score: number, issues?: string[], retried?: boolean, judge?: {model?: string} }|null} [quality] det-оцінка доки (+ опц. `retried`-маркер і `judge.model` хмарного судді); null — без полів якості
  * @param {string|null} [model] повний id моделі-генератора; null — без поля `model`
  * @returns {string} рядок `---\ndocgen:\n  source: …\n  crc: …[\n  model: …][\n  score: …][\n  issues: …]\n---\n`
  */
@@ -118,6 +122,8 @@ export function buildDocFrontmatter(source, crc, quality = null, model = null) {
     lines.push(`score: ${quality.score}`)
     const codes = issueCodes(quality.issues ?? [])
     if (codes.length > 0) lines.push(`issues: ${codes.join(',')}`)
+    if (quality.retried) lines.push('retried: true')
+    if (quality.judge && quality.judge.model) lines.push(`judgeModel: ${quality.judge.model}`)
   }
   const indented = lines.map(l => '  ' + l).join('\n')
   return `---\ndocgen:\n${indented}\n---\n`
@@ -128,7 +134,7 @@ export function buildDocFrontmatter(source, crc, quality = null, model = null) {
  * @param {string} md тіло доки (з frontmatter або без)
  * @param {string} source відносний шлях джерела
  * @param {string} crc CRC32 джерела у hex
- * @param {{ score: number, issues?: string[] }|null} [quality] det-оцінка доки
+ * @param {{ score: number, issues?: string[], retried?: boolean, judge?: {model?: string} }|null} [quality] det-оцінка доки (+ опц. `retried`-маркер і `judge.model` хмарного судді)
  * @param {string|null} [model] повний id моделі-генератора; null — без поля `model`
  * @returns {string} md зі свіжим frontmatter
  */
@@ -150,12 +156,17 @@ export function readDocCrc(docAbsPath) {
 /**
  * Якість, збережена у frontmatter доки.
  * @param {string} docAbsPath абсолютний шлях md-доки
- * @returns {{ score: number|null, issues: string[] }} `score:null` — доки немає або поле відсутнє
+ * @returns {{ score: number|null, issues: string[], retried: boolean, judgeModel: string|null }} `score:null` — доки немає або поле відсутнє; `retried` — чи док уже доретраювали при цьому CRC; `judgeModel` — хмарна модель-суддя, що позначила док (або null)
  */
 export function readDocQuality(docAbsPath) {
-  if (!existsSync(docAbsPath)) return { score: null, issues: [] }
+  if (!existsSync(docAbsPath)) return { score: null, issues: [], retried: false, judgeModel: null }
   const data = parseDocFrontmatter(readFileSync(docAbsPath, 'utf8')).data
-  return { score: data?.score ?? null, issues: data?.issues ?? [] }
+  return {
+    score: data?.score ?? null,
+    issues: data?.issues ?? [],
+    retried: data?.retried ?? false,
+    judgeModel: data?.judgeModel ?? null
+  }
 }
 
 /**

package/rules/doc-files/js/docgen-files-batch.mjs

@@ -4,8 +4,8 @@
  * Уся черга/батчинг/CRC-штамп живуть тут, а не в контексті моделі — тому
  * масовий перший прогін на сотні файлів не «заморює» агента. Конвеєр суто
  * локальний: жодних cloud-ескалацій; якщо det-score нижче порогу — дока все
- * одно пишеться з degraded-маркером (`score`/`issues` у frontmatter), а
- * `gen --retry-degraded` адресно переганяє лише такі доки пізніше.
+ * одно пишеться з degraded-маркером (`score`/`issues` у frontmatter), а наступний
+ * `gen` автоматично доретраює такі доки (один раз на версію джерела — далі `retried:true`).
  *
  * Перед масовим прогоном — health-check omlx: memory-guard зайнятої 8GB машини
  * означає «відклади прогін», а не сотні хибних «✗» у звіті.
@@ -14,7 +14,7 @@ import { readFileSync, mkdirSync, writeFileSync, existsSync, statSync } from 'no
 import { dirname, join } from 'node:path'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
-import { omlxHealthCheck, pickBackend, classifyOmlxError } from '../../../lib/llm.mjs'
+import { classifyOmlxError, preflightLocalModel } from '../../../lib/llm.mjs'
 import { generateDoc, DEFAULT_LOCAL_MODEL } from './docgen-gen.mjs'
 import { crc32, stampDoc, readDocQuality, readDocModel, QUALITY_THRESHOLD } from './docgen-crc.mjs'
 import { resolveRoot, scanForDocFiles } from './docgen-scan.mjs'
@@ -22,7 +22,7 @@ import { resolveRoot, scanForDocFiles } from './docgen-scan.mjs'
 /**
  * Парсить `--limit N` / `--from N` / прапори режимів для дозапуску великого прогону.
  * @param {string[]} argv аргументи
- * @returns {{ from: number, limit: number, overwrite: boolean, retryDegraded: boolean }} зріз і режими
+ * @returns {{ from: number, limit: number, overwrite: boolean }} зріз і режими
  */
 function parseGenArgs(argv) {
   const num = (flag, dflt) => {
@@ -32,65 +32,38 @@ function parseGenArgs(argv) {
   return {
     from: num('--from', 0),
     limit: num('--limit', Infinity),
-    overwrite: argv.includes('--overwrite'),
-    retryDegraded: argv.includes('--retry-degraded')
+    overwrite: argv.includes('--overwrite')
   }
 }
 
 /**
- * Цілі генерації за режимом:
- *   - default          → застарілі (stale);
- *   - `--overwrite`     → усі;
- *   - `--retry-degraded` → свіжі за CRC, але зі `score < QUALITY_THRESHOLD`.
+ * Цілі генерації:
+ *   - default      → застарілі (stale) АБО degraded-доки, які ще не доретраювали при цьому CRC;
+ *   - `--overwrite` → усі.
+ * Degraded-док отримує рівно ОДИН доретрай на версію джерела: після невдалого доретраю
+ * (лишився degraded) штампується `retried: true` і його більше не чіпають до зміни джерела
+ * (нова версія → CRC-mismatch → stale → лічильник скидається). Конвеєр сходиться без прапора.
  * @param {string} root абсолютний корінь
  * @param {Array<object>} all результат scanForDocFiles
- * @param {{ overwrite: boolean, retryDegraded: boolean }} mode режими
+ * @param {{ overwrite: boolean }} mode режими
  * @returns {Array<object>} відфільтровані цілі
  */
-function selectTargets(root, all, { overwrite, retryDegraded }) {
-  if (retryDegraded) {
-    return all.filter(f => {
-      if (f.stale) return false
-      const { score } = readDocQuality(join(root, f.docPath))
-      return score !== null && score < QUALITY_THRESHOLD
-    })
-  }
+export function selectTargets(root, all, { overwrite }) {
   if (overwrite) return all
-  return all.filter(f => f.stale)
-}
-
-/**
- * Preflight локального бекенда: для omlx-моделі — мінімальний chat-виклик.
- * @returns {string|null} текст фатальної проблеми або null якщо можна генерувати
- */
-function preflightProblem() {
-  if (!DEFAULT_LOCAL_MODEL) {
-    return 'модель не задано. Вистав N_LOCAL_MIN_MODEL (напр. omlx/mlx-community--gemma-4-e4b-it-OptiQ-4bit) і повтори.'
-  }
-  if (pickBackend(DEFAULT_LOCAL_MODEL) !== 'omlx') return null
-  const hc = omlxHealthCheck({ model: DEFAULT_LOCAL_MODEL })
-  if (hc.ok) return null
-  if (hc.reason === 'memory-guard') {
-    return `omlx memory-guard: модель не влазить у динамічну стелю пам'яті (машина зайнята).\n  Звільни пам'ять або повтори прогін пізніше.\n  ${hc.detail}`
-  }
-  if (hc.reason === 'down') {
-    return `omlx-сервер не відповідає. Запусти \`omlx serve\` і повтори.\n  ${hc.detail}`
-  }
-  if (hc.reason === 'auth') {
-    return `omlx вимагає API-ключ. Вистав N_CURSOR_OMLX_KEY (auth.api_key з ~/.omlx/settings.json).\n  ${hc.detail}`
-  }
-  return `omlx помилка: ${hc.detail}`
+  return all.filter(f => {
+    if (f.stale) return true
+    const { score, retried } = readDocQuality(join(root, f.docPath))
+    return score !== null && score < QUALITY_THRESHOLD && !retried
+  })
 }
 
 /**
  * Текст-суфікс режиму для прогрес-рядка.
- * @param {{ overwrite: boolean, retryDegraded: boolean }} mode режими
- * @returns {string} ` (--overwrite)` / ` (--retry-degraded)` / порожній рядок
+ * @param {{ overwrite: boolean }} mode режими
+ * @returns {string} ` (--overwrite)` або порожній рядок
  */
-function modeSuffix({ overwrite, retryDegraded }) {
-  if (overwrite) return ' (--overwrite)'
-  if (retryDegraded) return ' (--retry-degraded)'
-  return ''
+function modeSuffix({ overwrite }) {
+  return overwrite ? ' (--overwrite)' : ''
 }
 
 /**
@@ -146,8 +119,13 @@ async function generateOne(file, root, progress, stats) {
     const result = await generateDoc(sourceAbs, { existingMd })
     const crc = crc32(readFileSync(sourceAbs))
     mkdirSync(dirname(docAbs), { recursive: true })
+    // retried: НЕ stale (отже це доретрай при тому ж CRC) і лишився degraded → штампуємо,
+    // щоб наступні `gen` його не чіпали до зміни джерела (сходимість без прапора).
+    const retried = !file.stale && result.degraded
     const quality =
-      result.score === null ? null : { score: result.score, issues: result.degraded ? result.issues : [] }
+      result.score === null
+        ? null
+        : { score: result.score, issues: result.degraded ? result.issues : [], retried, judge: result.judge }
     writeFileSync(docAbs, stampDoc(result.md, file.sourcePath, crc, quality, result.model))
     stats.ok++
     if (result.degraded) {
@@ -189,7 +167,7 @@ function reportStats(stats) {
     for (const e of stats.skipped) console.log(`  - ${e}`)
   }
   if (stats.degraded > 0) {
-    console.log(`Degraded-доки перегенеровуються пізніше: npx @nitra/cursor fix-doc-files --retry-degraded`)
+    console.log('Degraded-доки автоматично доретраюються наступним `gen` (один раз на версію джерела).')
   }
 }
 
@@ -200,27 +178,39 @@ function reportStats(stats) {
  */
 export async function runDocFilesGenCli(argv) {
   const root = resolveRoot(argv)
-  const { from, limit, overwrite, retryDegraded } = parseGenArgs(argv)
+  const { from, limit, overwrite } = parseGenArgs(argv)
 
   const all = scanForDocFiles(root)
-  const targets = selectTargets(root, all, { overwrite, retryDegraded }).slice(from, from + limit)
+  const targets = selectTargets(root, all, { overwrite }).slice(from, from + limit)
 
   if (targets.length === 0) {
-    console.log(
-      retryDegraded
-        ? '✓ doc-files: degraded-док немає. Нічого переганяти.'
-        : '✓ doc-files: усі файлові доки свіжі. Нічого генерувати.'
-    )
+    console.log('✓ doc-files: усі файлові доки свіжі й не-degraded. Нічого генерувати.')
     return 0
   }
 
-  const problem = preflightProblem()
+  return runGenerationBatch(targets, root, {
+    headline: `📋 doc-files: до генерації ${targets.length} файл(ів)${modeSuffix({ overwrite })}`
+  })
+}
+
+/**
+ * Спільне ядро генерації: preflight локального бекенда → послідовний прогін
+ * `targets` через `generateOne` з circuit-breaker'ом (K systemic-збоїв підряд →
+ * abort) → підсумковий звіт. Перевикористовують і батч-CLI (`runDocFilesGenCli`),
+ * і opportunistic lint-крок doc-files (scoped-набір змінених файлів).
+ * @param {Array<object>} targets елементи scanForDocFiles (sourcePath/docPath)
+ * @param {string} root абсолютний корінь
+ * @param {{ headline?: string }} [opts] headline — рядок-шапка прогону у stdout
+ * @returns {Promise<number>} 0 — без помилок; 1 — фейл preflight або є помилки; 2 — systemic-abort
+ */
+export async function runGenerationBatch(targets, root, { headline } = {}) {
+  const problem = preflightLocalModel(DEFAULT_LOCAL_MODEL)
   if (problem) {
     console.error(`✗ fix-doc-files: ${problem}`)
     return 1
   }
 
-  console.log(`📋 doc-files: до генерації ${targets.length} файл(ів)${modeSuffix({ overwrite, retryDegraded })}`)
+  if (headline) console.log(headline)
   const stats = { ok: 0, degraded: 0, err: 0, errors: [], skipped: [] }
 
   let done = 0

package/rules/doc-files/js/docgen-gen.mjs

@@ -9,6 +9,7 @@ import { docPathForSource } from './docgen-scan.mjs'
 import { extractFacts } from './docgen-extract.mjs'
 import { extractAnchors, anchorTokens } from './docgen-extract-anchors.mjs'
 import { QUALITY_THRESHOLD } from './docgen-crc.mjs'
+import { JUDGE_ENABLED, JUDGE_MODEL, judgeDoc, judgeFailsDoc } from './docgen-judge.mjs'
 import {
   oneShotMessages,
   sectionMessages,
@@ -449,6 +450,18 @@ export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUA
     }
   }
 
+  // Stage 3 (опц.): семантичний judge-гейт — лише за N_CURSOR_DOCGEN_JUDGE=1 і на
+  // доках, що ПРОЙШЛИ det-скорер (там ховаються false-positives). Scope: inaccurate.
+  let judge = null
+  if (JUDGE_ENABLED && score >= threshold) {
+    try {
+      judge = { ...judgeDoc(src, r.md), model: JUDGE_MODEL }
+      if (judgeFailsDoc(judge)) issues = [...issues, `judge:inaccurate:${judge.confidence}`]
+    } catch (error) {
+      issues = [...issues, `judge:error: ${error.message.slice(0, 80)}`]
+    }
+  }
+
   return {
     ...r,
     ms: Date.now() - t0,
@@ -456,7 +469,8 @@ export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUA
     llmCalls: llmMeter.calls,
     score,
     issues,
-    degraded: score < threshold,
+    judge,
+    degraded: score < threshold || judgeFailsDoc(judge),
     model
   }
 }

package/rules/doc-files/js/docgen-judge-measure.mjs

@@ -14,7 +14,7 @@
  *
  * Usage:
  *   node docgen-judge-measure.mjs <file1> <file2> ...
- *   MEASURE_CACHE=/tmp/x N_CURSOR_DOCGEN_JUDGE_MODEL=openai-codex/gpt-5.4 node docgen-judge-measure.mjs ...
+ *   MEASURE_CACHE=/tmp/x N_CLOUD_MIN_MODEL=openai-codex/gpt-5.4 node docgen-judge-measure.mjs ...
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs'
 import { createHash } from 'node:crypto'
@@ -25,7 +25,7 @@ import { QUALITY_THRESHOLD } from './docgen-crc.mjs'
 
 const env = process.env
 const GEN_MODEL = env.N_LOCAL_MIN_MODEL ?? 'omlx/gemma-4-e4b-it-OptiQ-4bit'
-const JUDGE_MODEL = env.N_CURSOR_DOCGEN_JUDGE_MODEL ?? 'openai-codex/gpt-5.4-mini'
+const JUDGE_MODEL = env.N_CLOUD_MIN_MODEL ?? 'openai-codex/gpt-5.4-mini'
 const THRESHOLD = Number(env.N_CURSOR_DOC_FILES_THRESHOLD ?? QUALITY_THRESHOLD) || 70
 const CACHE_DIR = env.MEASURE_CACHE ?? '/tmp/docgen-judge-measure'
 const JUDGE_TIMEOUT = Number(env.MEASURE_JUDGE_TIMEOUT_MS ?? 120_000)
@@ -48,7 +48,12 @@ function cacheSet(key, val) {
   writeFileSync(join(CACHE_DIR, key + '.json'), JSON.stringify(val))
 }
 
-/** Генерує (з кешем за хешем src). */
+/**
+ * Генерує док (з кешем за хешем src).
+ * @param {string} file абсолютний шлях джерела
+ * @param {string} src вміст файлу
+ * @returns {{md: string, score: number|null, issues: string[], degraded: boolean, cached: boolean}} результат генерації
+ */
 function genCached(file, src) {
   const key = 'gen-' + sha(GEN_MODEL + '\0' + src)
   const hit = cacheGet(key)
@@ -59,7 +64,12 @@ function genCached(file, src) {
   return { ...out, cached: false }
 }
 
-/** Судить (з кешем за хешем src+doc). */
+/**
+ * Судить док сильною моделлю (з кешем за хешем src+doc).
+ * @param {string} src вміст вихідного файлу
+ * @param {string} doc згенерована документація
+ * @returns {{verdict: string, confidence: number, reason: string, offending?: string[], cached: boolean}} verdict судді
+ */
 function judgeCached(src, doc) {
   const key = 'judge-' + sha(JUDGE_MODEL + '\0' + src + '\0' + doc)
   const hit = cacheGet(key)
@@ -67,7 +77,7 @@ function judgeCached(src, doc) {
   const user = `SOURCE FILE:\n\`\`\`\n${src.slice(0, 12000)}\n\`\`\`\n\nGENERATED DOC:\n\`\`\`md\n${doc.slice(0, 8000)}\n\`\`\`\n\nReturn the JSON verdict.`
   const raw = callLlm([{ role: 'system', content: SYSTEM }, { role: 'user', content: user }], JUDGE_MODEL, { timeoutMs: JUDGE_TIMEOUT, temperature: 0 })
   const a = raw.indexOf('{'), b = raw.lastIndexOf('}')
-  if (a < 0 || b < 0) throw new Error('no JSON in judge reply: ' + raw.slice(0, 160))
+  if (a === -1 || b === -1) throw new Error('no JSON in judge reply: ' + raw.slice(0, 160))
   const v = JSON.parse(raw.slice(a, b + 1))
   cacheSet(key, v)
   return { ...v, cached: false }
@@ -85,11 +95,11 @@ function main() {
   for (const [i, file] of files.entries()) {
     const tag = `(${i + 1}/${files.length}) ${file}`
     let src
-    try { src = readFileSync(file, 'utf8') } catch (e) { console.error(`[skip] ${tag}: read ${e.message}`); continue }
+    try { src = readFileSync(file, 'utf8') } catch (error) { console.error(`[skip] ${tag}: read ${error.message}`); continue }
 
     let gen
-    try { gen = genCached(file, src) } catch (e) { console.error(`[gen-err] ${tag}: ${e.message.slice(0, 120)}`); rows.push({ file, error: 'gen', detail: e.message.slice(0, 200) }); continue }
-    if (gen.score == null) { console.error(`[unsupported] ${tag}`); rows.push({ file, score: null, unsupported: true }); continue }
+    try { gen = genCached(file, src) } catch (error) { console.error(`[gen-err] ${tag}: ${error.message.slice(0, 120)}`); rows.push({ file, error: 'gen', detail: error.message.slice(0, 200) }); continue }
+    if (gen.score === null) { console.error(`[unsupported] ${tag}`); rows.push({ file, score: null, unsupported: true }); continue }
 
     const passed = gen.score >= THRESHOLD
     const row = { file, score: gen.score, degraded: gen.degraded, passed, genCached: gen.cached }
@@ -100,7 +110,7 @@ function main() {
         const v = judgeCached(src, gen.md)
         row.verdict = v.verdict; row.confidence = v.confidence; row.reason = v.reason; row.offending = v.offending; row.judgeCached = v.cached
         console.error(`  [judge${v.cached ? '*' : ''}] ${v.verdict} (${v.confidence}) — ${(v.reason || '').slice(0, 90)}`)
-      } catch (e) { row.judgeError = e.message.slice(0, 200); console.error(`  [judge-err] ${e.message.slice(0, 120)}`) }
+      } catch (error) { row.judgeError = error.message.slice(0, 200); console.error(`  [judge-err] ${error.message.slice(0, 120)}`) }
     }
     rows.push(row)
   }

package/rules/doc-files/js/docgen-judge.mjs

@@ -0,0 +1,72 @@
+/** @see ./docs/docgen-judge.md */
+/**
+ * docgen-judge — опціональний семантичний verdict-гейт (spec
+ * `docs/specs/2026-06-14-docgen-judge-design.md`).
+ *
+ * Доповнює детермінований `scoreDoc`: ловить `inaccurate`-доки (твердження, що
+ * суперечать джерелу), яких структурно-лексичний скорер не бачить у принципі.
+ * Активується АВТОМАТИЧНО, якщо задано `N_CLOUD_MIN_MODEL` (бо суддя потребує
+ * сильнішої за генератор хмарної моделі — без неї судити нема чим). Працює лише на
+ * доках що ПРОЙШЛИ det-скорер (`score ≥ threshold`) — саме там ховаються
+ * false-positives. Scope строго `inaccurate` (вимір показав generic=0%). Без
+ * `N_CLOUD_MIN_MODEL` → 0 змін поведінки. Патерн дзеркалить `scripts/coverage-classify`.
+ */
+import { env } from 'node:process'
+import { callLlm } from '../../../lib/llm.mjs'
+import { CLOUD_MIN } from '../../../lib/models.mjs'
+
+/** Модель-суддя = `N_CLOUD_MIN_MODEL` (хмарний cloud-min tier). */
+export const JUDGE_MODEL = CLOUD_MIN
+/** Гейт активується АВТОМАТИЧНО, коли задано `N_CLOUD_MIN_MODEL` (без нього нема надійного судді). */
+export const JUDGE_ENABLED = Boolean(CLOUD_MIN)
+/** Мін. впевненість, щоб verdict `inaccurate` позначив док як degraded. */
+export const JUDGE_CONFIDENCE = Number(env.N_CURSOR_DOCGEN_JUDGE_THRESHOLD ?? 0.7) || 0.7
+
+const JUDGE_SYSTEM = `You are a strict technical-documentation reviewer. You receive a SOURCE file and an auto-generated Markdown DOC describing it. Classify the DOC into exactly one verdict:
+- "accurate": specific to THIS file AND every factual claim is supported by the source.
+- "generic": vague/boilerplate; could describe almost any file of this kind.
+- "inaccurate": contains at least one claim NOT supported by, or contradicted by, the source code (e.g. wrong return behavior, false "no network"/"read-only", invented symbols/fields).
+Prefer "inaccurate" if any claim is wrong. Respond with ONLY a JSON object, no prose:
+{"verdict":"accurate|generic|inaccurate","confidence":0.0-1.0,"reason":"<10-300 chars>"}`
+
+const VERDICTS = new Set(['accurate', 'generic', 'inaccurate'])
+
+/**
+ * Витягує й валідує verdict-JSON із сирої відповіді LLM (як `parseVerdict` у coverage-classify).
+ * @param {string} rawText сира текстова відповідь судді
+ * @returns {{verdict: string, confidence: number, reason: string}} провалідований verdict
+ * @throws {Error} якщо JSON відсутній/невалідний або не відповідає схемі
+ */
+export function parseDocVerdict(rawText) {
+  const a = rawText.indexOf('{')
+  const b = rawText.lastIndexOf('}')
+  if (a === -1 || b === -1) throw new Error('judge: no JSON object in response')
+  const v = JSON.parse(rawText.slice(a, b + 1))
+  if (!VERDICTS.has(v.verdict)) throw new Error(`judge: bad verdict "${v.verdict}"`)
+  if (typeof v.confidence !== 'number' || v.confidence < 0 || v.confidence > 1) {
+    throw new Error('judge: bad confidence')
+  }
+  return { verdict: v.verdict, confidence: v.confidence, reason: String(v.reason ?? '').slice(0, 500) }
+}
+
+/**
+ * Судить згенерований док сильною моделлю проти джерела.
+ * @param {string} src вміст вихідного файлу
+ * @param {string} doc згенерована документація
+ * @param {{model?: string, timeoutMs?: number}} [opts] override моделі/таймауту
+ * @returns {{verdict: string, confidence: number, reason: string}} verdict судді
+ */
+export function judgeDoc(src, doc, { model = JUDGE_MODEL, timeoutMs = 120_000 } = {}) {
+  const user = `SOURCE FILE:\n\`\`\`\n${src.slice(0, 12_000)}\n\`\`\`\n\nGENERATED DOC:\n\`\`\`md\n${doc.slice(0, 8000)}\n\`\`\`\n\nReturn the JSON verdict.`
+  const raw = callLlm([{ role: 'system', content: JUDGE_SYSTEM }, { role: 'user', content: user }], model, { timeoutMs, temperature: 0 })
+  return parseDocVerdict(raw)
+}
+
+/**
+ * Чи позначає verdict док як degraded (лише `inaccurate` із достатньою впевненістю).
+ * @param {{verdict: string, confidence: number}|null} verdict verdict судді або null
+ * @returns {boolean} true якщо док треба вважати degraded через семантичну неточність
+ */
+export function judgeFailsDoc(verdict) {
+  return verdict !== null && verdict.verdict === 'inaccurate' && verdict.confidence >= JUDGE_CONFIDENCE
+}

package/rules/doc-files/js/docgen-scan.mjs

@@ -234,7 +234,7 @@ function toRelSource(root, candidate) {
 /**
  * `doc-files check --degraded` — інформаційний список свіжих за CRC док зі
  * `score < QUALITY_THRESHOLD` (локальний конвеєр не дотягнув; ADR 260610-2228).
- * Не блокує (exit 0): degraded — борг для `gen --retry-degraded`, а не гейт.
+ * Не блокує (exit 0): degraded — борг, що автоматично доретраюється наступним `gen`, а не гейт.
  * @param {string} root абсолютний корінь
  * @returns {number} exit-код: завжди 0
  */
@@ -256,7 +256,7 @@ function runDegradedReport(root) {
     })
     .join('\n')
   console.log(
-    `⚠ doc-files: degraded-док ${degraded.length} (score < ${QUALITY_THRESHOLD}):\n${list}\n→ перегенеруй: npx @nitra/cursor fix-doc-files --retry-degraded`
+    `⚠ doc-files: degraded-док ${degraded.length} (score < ${QUALITY_THRESHOLD}):\n${list}\n→ доретраюються автоматично наступним \`gen\` (один раз на версію джерела).`
   )
   return 0
 }

package/rules/doc-files/js/docs/docgen-judge-measure.md

@@ -1,7 +1,7 @@
 ---
 docgen:
   source: npm/rules/doc-files/js/docgen-judge-measure.mjs
-  crc: b40b626c
+  crc: 7f72e520
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
@@ -10,20 +10,21 @@ docgen:
 
 ## Огляд
 
-Файл аналізує вміст визначеного списку файлів, створюючи технічну документацію на основі вихідного коду. Процес спирається на конфігурацію, визначену в report.json. Для кожного файлу відбувається кешування результатів у межах прогону. Якість згенерованої документації оцінюється хмарною моделлю шляхом порівняння з пороговими значеннями, заданими в report.json. Результати аналізу агрегуються, обчислюється відсоток хибнопозитивних спрацювань та зберігаються у report.json.
+Файл зчитує список файлів для аналізу, спираючись на конфігурацію `report.json`. Для кожного файлу генерується технічна документація за допомогою локальної моделі. Після генерації документація оцінюється хмарною моделлю. Результати оцінки кешуються у межах прогону, а потім збираються у звіт. Звіт зберігається у `report.json` та виводиться у консоль.
 
 ## Поведінка
 
-1. Зчитує список файлів для аналізу.
+1. Зчитує список файлів для аналізу з командного рядка.
 2. Для кожного файлу зчитує його вміст.
-3. Генерує технічну документацію для файлу, використовуючи кеш за вмістом вихідного коду.
-4. Якщо документація згенерована, перевіряє її якість за встановленим порогом.
-5. Якщо якість документації відповідає порогу, передає вміст вихідного коду та згенеровану документацію для оцінки.
-6. Оцінює документацію за допомогою сильної хмарної моделі, використовуючи кеш за вмістом вихідного коду та документації.
-7. Збирає результати для кожного файлу.
-8. Агрегує результати, обчислюючи відсоток хибнопозитивних спрацювань (false-positive rate) серед документів, які пройшли порогову перевірку та були оцінені.
-9. Зберігає повний звіт у файл `report.json` у директорії кешу.
-10. Виводить консольний звіт про результати вимірювання.
+3. Генерує документацію для файлу, використовуючи локальну модель. Результат кешується за хешем вмісту джерела.
+4. Якщо генерація документації неможлива або не пройшла встановлений поріг якості, фіксує це як помилку або непідтримуваний файл.
+5. Якщо документація пройшла поріг якості, вона передається для оцінки.
+6. Оцінює згенеровану документацію за допомогою потужної хмарної моделі. Результат оцінки кешується за хешем вмісту джерела та документації.
+7. Якщо оцінка неможлива, фіксує помилку оцінки.
+8. Збирає результати для всіх файлів.
+9. Обчислює звіт, включаючи загальну кількість файлів, кількість успішно згенерованих та оцінених, а також відсоток хибнопозитивних результатів (false-positive rate).
+10. Зберігає повний звіт у файл `report.json` у каталозі кешу.
+11. Виводить консольний звіт з ключовими показниками.
 
 ## Гарантії поведінки
 

package/rules/doc-files/js/docs/docgen-judge.md

@@ -0,0 +1,35 @@
+---
+docgen:
+  source: npm/rules/doc-files/js/docgen-judge.mjs
+  crc: c6ab093a
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+# docgen-judge.mjs
+
+## Огляд
+
+Модуль оцінює згенеровану документацію, порівнюючи її з вихідним файлом за допомогою великої мовної моделі. Це дозволяє визначити відповідність та якість документації. Модуль надає функції для запуску оцінки (`judgeDoc`, `judgeFailsDoc`), отримання результатів (`parseDocVerdict`), визначення моделі (`JUDGE_MODEL`), перевірки статусу оцінювача (`JUDGE_ENABLED`) та отримання рівня впевненості (`JUDGE_CONFIDENCE`).
+
+## Поведінка
+
+JUDGE_MODEL — Вказує модель, яку використовує суддя для оцінки документації.
+JUDGE_ENABLED — Позначає, чи активна функціональність судді.
+JUDGE_CONFIDENCE — Визначає мінімальний рівень впевненості, необхідний для позначення документації як деградованої.
+parseDocVerdict — Витягує та валідує об'єкт з оцінкою документації з сирого текстового виводу судді.
+judgeDoc — Виконує оцінку згенерованої документації проти вмісту вихідного файлу за допомогою великої мовної моделі.
+judgeFailsDoc — Визначає, чи слід вважати документацію деградованою на основі оцінки судді.
+
+## Публічний API
+
+JUDGE_MODEL — Визначає модель-суддю як `N_CLOUD_MIN_MODEL` (хмарний мінімальний рівень).
+JUDGE_ENABLED — Автоматично вмикає механізм судді, якщо обрано `N_CLOUD_MIN_MODEL`.
+JUDGE_CONFIDENCE — Встановлює мінімальний рівень впевненості, необхідний для позначення документа як погіршеного (degraded) за неточним вердиктом.
+parseDocVerdict — Витягує та перевіряє структуру вердикту у форматі JSON із сирих даних від великої мовної моделі.
+judgeDoc — Оцінює згенерований документ потужною моделлю, порівнюючи його з вихідним джерелом.
+judgeFailsDoc — Визначає, чи повинен документ бути позначений як погіршений (degraded) на підставі вердикту, якщо він неточний і має достатню впевненість.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/rules/doc-files/js/lint.mjs

@@ -1,5 +1,6 @@
 /**
- * Адаптер агрегатора `n-cursor lint` для правила doc-files.
+ * Адаптер агрегатора `n-cursor lint` для правила doc-files (opportunistic LLM-fix
+ * tier, спека docs/specs/2026-06-15-opportunistic-llm-fix-tier.md).
  *
  * Quick-фаза отримує список змінених файлів і мапить їх у пари в **обидва** боки:
  *  - змінене **джерело** (`.js/.mjs/.ts/.vue/.py/.rs`) → перевірка його доки `<dir>/docs/<stem>.md`;
@@ -7,8 +8,11 @@
  *    (той самий stem у каталозі над текою `docs`).
  * Ci-фаза (files === undefined) проганяє повний скан дерева.
  *
- * Порушення — `missing` ∪ `crc-mismatch` (детермінований CRC-детект, 0 LLM-токенів);
- * degraded не блокує. Exit 1 — є stale; 0 — все свіже (конвенція агрегатора).
+ * Детект — `missing` ∪ `crc-mismatch` (детермінований CRC, 0 LLM-токенів); degraded не блокує.
+ * Поведінка за осями (правило має `meta.json: llmFix:true`):
+ *  - `readOnly` (CI/hook): **лише детект** — нуль мутацій/LLM, exit 1 на stale (детермінований гейт);
+ *  - fix-by-default + omlx **піднято**: opportunistic-генерація stale-доків → re-detect → 0 якщо полагоджено;
+ *  - fix-by-default + omlx **недоступно**: fix пропущено (повідомлення) + exit 1 — гейт тримається, без false-green.
  */
 import { join, dirname, basename, extname } from 'node:path'
 import { existsSync, readdirSync } from 'node:fs'
@@ -79,18 +83,34 @@ function reportStale(stale) {
 }
 
 /**
- * Крок агрегатора lint для doc-files.
+ * Збирає застарілі (missing ∪ crc-mismatch) описи у scope кроку.
  * @param {string[] | undefined} files quick: лише ці файли; undefined: весь репозиторій
- * @param {string} [cwd] корінь репо
- * @returns {Promise<number>} 0 — OK, 1 — є застарілі доки
+ * @param {string} cwd корінь репо
+ * @returns {Array<{sourcePath:string, docPath:string, reason:string|null}>} stale-описи (готові як targets генерації)
  */
-export function lint(files, cwd = process.cwd()) {
-  if (files === undefined) {
-    const stale = scanForDocFiles(cwd).filter(f => f.stale)
-    return Promise.resolve(reportStale(stale))
-  }
+function collectStale(files, cwd) {
+  if (files === undefined) return scanForDocFiles(cwd).filter(f => f.stale)
   const sources = sourcesFromChanged(files, cwd)
-  if (sources.length === 0) return Promise.resolve(0)
-  const stale = sources.map(src => describeFile(cwd, src)).filter(f => f.stale)
-  return Promise.resolve(reportStale(stale))
+  return sources.map(src => describeFile(cwd, src)).filter(f => f.stale)
+}
+
+/**
+ * Крок агрегатора lint для doc-files (opportunistic LLM-fix tier).
+ * @param {string[] | undefined} files quick: лише ці файли; undefined: весь репозиторій
+ * @param {string} [cwd] корінь репо
+ * @param {{ readOnly?: boolean }} [opts] readOnly: лише детект (CI/hook), без мутацій/LLM
+ * @returns {Promise<number>} 0 — доки свіжі; 1 — є застарілі (детект, fix пропущено чи помилка генерації)
+ */
+export async function lint(files, cwd = process.cwd(), { readOnly = false } = {}) {
+  const stale = collectStale(files, cwd)
+  if (stale.length === 0) return 0
+  if (readOnly) return reportStale(stale)
+
+  // fix-by-default: opportunistic-генерація через спільне ядро (preflight omlx →
+  // батч із circuit-breaker'ом). omlx недоступний → runGenerationBatch друкує причину
+  // й повертає !=0; ми re-detect'имо й через reportStale віддаємо exit 1 (гейт тримається).
+  process.stdout.write(`ℹ️  doc-files: ${stale.length} застарілих — пробую авто-фікс (omlx)…\n`)
+  const { runGenerationBatch } = await import('./docgen-files-batch.mjs')
+  await runGenerationBatch(stale, cwd, { headline: `📋 doc-files: генерація ${stale.length} файл(ів)` })
+  return reportStale(collectStale(files, cwd))
 }

package/rules/doc-files/meta.json

@@ -1 +1 @@
-{ "auto": "завжди", "lint": "per-file" }
+{ "auto": "завжди", "lint": "per-file", "llmFix": true }

package/rules/text/lint/cspell-fix.mjs

@@ -1,20 +1,33 @@
 /**
- * cspell у ланцюжку lint-text із omlx-автофіксом (point 4 спеки).
+ * cspell у ланцюжку lint-text із omlx-класифікацією (нова схема — спека
+ * docs/specs/2026-06-15-opportunistic-llm-fix-tier.md).
  *
- * cspell не має нативного `--fix`. У fix-режимі: детект (захоплення виводу) → групування
- * знахідок по файлах → per-file omlx-фікс справжніх одруків (`llmLintFix`) → re-detect.
- * У read-only: лише детект (нуль мутацій). Валідні терміни omlx лишає — їх ловить повторний
- * cspell (далі — у словник `@nitra/cspell-dict`).
+ * cspell не має нативного `--fix`, а емпірично ~90% «Unknown word» на укр+тех-репо —
+ * валідні терміни, не одруки (вимір: 1406 знахідок / 292 файли, ~90% словникові
+ * кандидати). Тому fix-режим НЕ переписує файли (старий whole-file `llmLintFix`
+ * таймаутив/парс-фейлив — bounded-output принцип спеки), а **класифікує** знахідки:
+ *   detect → omlx-класифікація distinct-слів (bounded JSON-вихід) → валідні слова
+ *   авто-дописуються у `.cspell.json#words` (sorted/dedup, видно в diff) → ймовірні
+ *   одруки лишаються списком на рев'ю (НЕ авто-виправляються — апплай небезпечний) →
+ *   re-detect. read-only: лише детект (нуль мутацій).
+ *
+ * Гейт: валідні слова після дописування у словник зникають; нерозкласифіковані та
+ * typo лишаються → cspell повертає !=0 → exit 1 (людина доправляє одруки вручну).
  */
 import { spawnSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
 
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
-import { llmLintFix } from '../../../scripts/lib/fix/llm-lint-fix.mjs'
+import { callLlm, preflightLocalModel } from '../../../lib/llm.mjs'
+
+/** Слово у рядку cspell: `<file>:<line>:<col> - Unknown word (xxx)`. */
+const UNKNOWN_WORD_RE = /Unknown word \(([^)]+)\)/u
+/** Максимум distinct-слів під класифікацію за прогін (без тихого обрізання — логуємо надлишок). */
+const MAX_CLASSIFY_WORDS = 80
 
-/** Рядок cspell: `<file>:<line>:<col> - Unknown word (xxx)`. */
-const CSPELL_LINE_RE = /^(.+?):\d+:\d+\s+-\s+Unknown word/u
-/** Максимум файлів під omlx-фікс за прогін (без тихого обрізання — логуємо надлишок). */
-const MAX_FIX_FILES = 25
+/** Локальна fix-модель (рішення: єдиний knob `N_LOCAL_MIN_MODEL`). */
+const fixModel = () => process.env.N_LOCAL_MIN_MODEL || ''
 
 /**
  * Запускає `cspell .` із захопленням виводу.
@@ -28,34 +41,76 @@ function detectCspell(cwd, bin) {
 }
 
 /**
- * Групує cspell-знахідки за файлом.
+ * Унікальні «Unknown word» зі stdout cspell.
  * @param {string} out вивід cspell
- * @returns {Map<string, string[]>} файл → рядки знахідок
+ * @returns {string[]} distinct-слова у порядку першої появи
  */
-export function groupFindingsByFile(out) {
-  /** @type {Map<string, string[]>} */
-  const byFile = new Map()
+export function unknownWords(out) {
+  const set = new Set()
   for (const line of out.split('\n')) {
-    const m = CSPELL_LINE_RE.exec(line.trim())
-    if (!m) continue
-    const file = m[1]
-    if (!byFile.has(file)) byFile.set(file, [])
-    byFile.get(file).push(line.trim())
+    const m = UNKNOWN_WORD_RE.exec(line)
+    if (m) set.add(m[1])
+  }
+  return [...set]
+}
+
+/**
+ * Промпт класифікації: для укр+тех-репо bias у «valid» (додати валідне слово безпечно,
+ * «виправити» валідне — шкода). Вихід bounded — JSON-масив вердиктів.
+ * @param {string[]} words distinct-слова
+ * @returns {string} prompt
+ */
+function classifyPrompt(words) {
+  return [
+    'You triage cspell "unknown word" findings for a Ukrainian + technical codebase.',
+    'For each word decide:',
+    '- "valid": correct technical term, identifier, abbreviation, transliteration, jargon, or intentional Ukrainian word → dictionary candidate.',
+    '- "typo": a genuine misspelling of a real word.',
+    'Default to "valid" when unsure (adding a real word to the dictionary is safe; "fixing" a valid word is harmful).',
+    'Return ONLY a JSON array, no markdown fences: [{"w":"<word>","verdict":"valid"|"typo","fix":"<correction or null>"}]',
+    'Words:',
+    ...words.map(w => `- ${w}`)
+  ].join('\n')
+}
+
+/**
+ * Витягує JSON-масив із відповіді моделі (бере від першої «[» до останньої «]» — зрізає прозу й markdown-обрамлення).
+ * @param {string} text відповідь
+ * @returns {Array<{w:string, verdict:string, fix:string|null}>|null} вердикти або null
+ */
+function parseClassify(text) {
+  const start = text.indexOf('[')
+  const end = text.lastIndexOf(']')
+  if (start === -1 || end <= start) return null
+  try {
+    const arr = JSON.parse(text.slice(start, end + 1))
+    return Array.isArray(arr) ? arr : null
+  } catch {
+    return null
   }
-  return byFile
 }
 
-const CSPELL_INSTRUCTION = [
-  'Correct genuine spelling typos in the file(s).',
-  'Each flagged "Unknown word" is listed below.',
-  'ONLY fix obvious misspellings of real words.',
-  'If a flagged token is a valid identifier, technical term, abbreviation, proper noun, URL,',
-  'or an intentional non-English word, leave it UNCHANGED (it will be added to the dictionary).',
-  'Preserve all code, formatting, and unrelated text exactly.'
-].join(' ')
+/**
+ * Дописує слова у `.cspell.json#words` (sorted/dedup) — видно в git diff для рев'ю.
+ * @param {string} cwd корінь
+ * @param {string[]} words валідні слова
+ * @returns {number} к-сть фактично доданих (нових) слів
+ */
+export function appendWordsToDict(cwd, words) {
+  const cfgPath = join(cwd, '.cspell.json')
+  if (words.length === 0 || !existsSync(cfgPath)) return 0
+  const cfg = JSON.parse(readFileSync(cfgPath, 'utf8'))
+  const set = new Set(cfg.words)
+  const before = set.size
+  for (const w of words) set.add(w)
+  if (set.size === before) return 0
+  cfg.words = [...set].toSorted((a, b) => a.localeCompare(b))
+  writeFileSync(cfgPath, `${JSON.stringify(cfg, null, 2)}\n`)
+  return set.size - before
+}
 
 /**
- * cspell-крок lint-text з omlx-автофіксом.
+ * cspell-крок lint-text: класифікація → словник (нова схема).
  * @param {string} [cwd] корінь
  * @param {boolean} [readOnly] true → лише детект (нуль мутацій)
  * @returns {number} 0 — чисто; 1 — лишились знахідки / помилка середовища
@@ -74,30 +129,50 @@ export function runCspellText(cwd = process.cwd(), readOnly = false) {
     return first.code
   }
 
-  // Fix-режим: omlx по файлах зі справжніми одруками.
-  const byFile = groupFindingsByFile(first.out)
-  const files = [...byFile.keys()]
-  if (files.length === 0) {
+  // Fix-режим: класифікація знахідок (bounded JSON-вихід), валідні → у словник.
+  const model = fixModel()
+  const problem = preflightLocalModel(model)
+  if (problem) {
+    process.stdout.write(`⚠️  cspell: класифікацію пропущено (${problem})\n`)
+    process.stdout.write(first.out)
+    return first.code
+  }
+
+  const words = unknownWords(first.out)
+  const batch = words.slice(0, MAX_CLASSIFY_WORDS)
+  if (words.length > MAX_CLASSIFY_WORDS) {
+    process.stdout.write(`ℹ️  cspell: класифікація перших ${MAX_CLASSIFY_WORDS}/${words.length} слів (решта — наступний прогін)\n`)
+  }
+
+  let text
+  try {
+    text = callLlm([{ role: 'user', content: classifyPrompt(batch) }], model, { caller: 'cspell-classify', maxTokens: 4000 })
+  } catch (error) {
+    process.stdout.write(`⚠️  cspell: omlx-класифікація впала (${error.message}) — без авто-словника\n`)
     process.stdout.write(first.out)
     return first.code
   }
-  const targets = files.slice(0, MAX_FIX_FILES)
-  if (files.length > MAX_FIX_FILES) {
-    process.stdout.write(`ℹ️  cspell: omlx-фікс перших ${MAX_FIX_FILES}/${files.length} файлів (решта — наступний прогін)\n`)
+
+  const parsed = parseClassify(text)
+  if (!parsed) {
+    process.stdout.write('⚠️  cspell: не вдалося розпарсити класифікацію — без авто-словника\n')
+    process.stdout.write(first.out)
+    return first.code
   }
 
-  for (const file of targets) {
-    const res = llmLintFix({
-      tool: 'cspell',
-      instruction: CSPELL_INSTRUCTION,
-      findings: byFile.get(file).join('\n'),
-      filePaths: [file],
-      projectRoot: cwd
-    })
-    process.stdout.write(res.ok ? `  ⚡ cspell omlx-фікс: ${file}\n` : `  ⚠️  cspell omlx-фікс пропущено (${file}): ${res.error}\n`)
+  const valid = parsed.filter(x => x.verdict === 'valid' && typeof x.w === 'string').map(x => x.w)
+  const typos = parsed.filter(x => x.verdict === 'typo' && typeof x.w === 'string')
+  const added = appendWordsToDict(cwd, valid)
+  process.stdout.write(`✓ cspell: +${added} валідних слів у .cspell.json (з ${valid.length} класифікованих)\n`)
+  if (typos.length > 0) {
+    process.stdout.write("⚠️  cspell: ймовірні одруки на рев'ю (НЕ виправлено авто):\n")
+    for (const t of typos) {
+      const arrow = t.fix ? ` → ${t.fix}` : ''
+      process.stdout.write(`  - ${t.w}${arrow}\n`)
+    }
   }
 
-  // Re-detect: що лишилось (валідні терміни → у словник).
+  // Re-detect: валідні тепер у словнику → лишаються одруки/нерозкласифіковане → exit 1.
   const second = detectCspell(cwd, bin)
   if (second.code !== 0) process.stdout.write(second.out)
   return second.code

package/schemas/rule-meta.json

@@ -11,6 +11,10 @@
       "enum": ["per-file", "full"],
       "description": "Scope lint-кроку: per-file (декомпозиція по змінених файлах, дельта vs origin) або full (нероздільно крос-файловий, лише `lint --full`)."
     },
+    "llmFix": {
+      "type": "boolean",
+      "description": "Opt-in opportunistic LLM-fix: у fix-by-default (не --read-only) lint-крок намагається виправити порушення локальною моделлю (omlx), якщо її піднято; інакше пропускає й лишає exit 1. Лише для контент-правил (doc-files, cspell) — НЕ для логічних лінтерів (зміна коду може змінити поведінку). Деталі: docs/specs/2026-06-15-opportunistic-llm-fix-tier.md."
+    },
     "auto": {
       "description": "Умова автоактивації правила: \"завжди\", масив id правил-залежностей, glob, або іменований предикат.",
       "oneOf": [