@nitra/cursor 11.1.0 → 11.3.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [11.3.0] - 2026-06-15
+
+### Changed
+
+- lint: opt-in `meta.json: llmFix:true` тепер реально дротується (раніше прапор був декоративний — opportunistic LLM-fix біг просто на `!readOnly`). `runLint` читає `llmFix` з meta правила й передає в `lint(files, cwd, { readOnly, llmFix })`; правило без прапора лишається detect-only. Це й забезпечує safety-тріаж зі спеки (логічні лінтери не вмикають LLM-fix випадково). doc-files і text позначені `llmFix:true`; cspell-класифікація гейтиться через `llmFix` (проведено `runLintTextCli`/`runLintTextSteps`/`runCspellText`), standalone `lint-text` передає `llmFix:true`. Принагідно: justified `no-unsanitized/method`-disable на package-internal динамічний import у `runLint` (pre-existing).
+
+## [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

package/bin/n-cursor.js

@@ -1568,7 +1568,8 @@ try {
     case 'lint-text': {
       // Канонічний lint-text: cspell → shellcheck → dotenv → markdownlint → v8r (text.mdc).
       // `--read-only` (CI): без авто-фіксу (markdownlint/shellcheck/dotenv) — нуль мутацій.
-      process.exitCode = await runLintTextCli({ readOnly: args.includes('--read-only') })
+      // `llmFix:true` — text llmFix-capable, тож standalone lint-text робить omlx-класифікацію cspell.
+      process.exitCode = await runLintTextCli({ readOnly: args.includes('--read-only'), llmFix: true })
 
       break
     }

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.1.0",
+  "version": "11.3.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 якщо можна генерувати
- */
-export 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,22 +178,18 @@ 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
   }
 
   return runGenerationBatch(targets, root, {
-    headline: `📋 doc-files: до генерації ${targets.length} файл(ів)${modeSuffix({ overwrite, retryDegraded })}`
+    headline: `📋 doc-files: до генерації ${targets.length} файл(ів)${modeSuffix({ overwrite })}`
   })
 }
 
@@ -230,7 +204,7 @@ export async function runDocFilesGenCli(argv) {
  * @returns {Promise<number>} 0 — без помилок; 1 — фейл preflight або є помилки; 2 — systemic-abort
  */
 export async function runGenerationBatch(targets, root, { headline } = {}) {
-  const problem = preflightProblem()
+  const problem = preflightLocalModel(DEFAULT_LOCAL_MODEL)
   if (problem) {
     console.error(`✗ fix-doc-files: ${problem}`)
     return 1

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

@@ -9,7 +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, judgeDoc, judgeFailsDoc } from './docgen-judge.mjs'
+import { JUDGE_ENABLED, JUDGE_MODEL, judgeDoc, judgeFailsDoc } from './docgen-judge.mjs'
 import {
   oneShotMessages,
   sectionMessages,
@@ -455,7 +455,7 @@ export function generateDoc(file, { model = DEFAULT_LOCAL_MODEL, threshold = QUA
   let judge = null
   if (JUDGE_ENABLED && score >= threshold) {
     try {
-      judge = judgeDoc(src, r.md)
+      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)}`]

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/lint.mjs

@@ -98,13 +98,14 @@ function collectStale(files, cwd) {
  * Крок агрегатора lint для doc-files (opportunistic LLM-fix tier).
  * @param {string[] | undefined} files quick: лише ці файли; undefined: весь репозиторій
  * @param {string} [cwd] корінь репо
- * @param {{ readOnly?: boolean }} [opts] readOnly: лише детект (CI/hook), без мутацій/LLM
+ * @param {{ readOnly?: boolean, llmFix?: boolean }} [opts] readOnly: лише детект (CI/hook);
+ *   llmFix: opt-in opportunistic-генерація (з `meta.json: llmFix:true`) — без нього detect-only
  * @returns {Promise<number>} 0 — доки свіжі; 1 — є застарілі (детект, fix пропущено чи помилка генерації)
  */
-export async function lint(files, cwd = process.cwd(), { readOnly = false } = {}) {
+export async function lint(files, cwd = process.cwd(), { readOnly = false, llmFix = false } = {}) {
   const stale = collectStale(files, cwd)
   if (stale.length === 0) return 0
-  if (readOnly) return reportStale(stale)
+  if (readOnly || !llmFix) return reportStale(stale)
 
   // fix-by-default: opportunistic-генерація через спільне ядро (preflight omlx →
   // батч із circuit-breaker'ом). omlx недоступний → runGenerationBatch друкує причину

package/rules/lint/js/orchestrate.mjs

@@ -108,15 +108,23 @@ export async function runLint(opts = {}) {
     return 0
   }
 
-  const ids = selectLintRules(readAllMeta(rulesDir), full)
+  const metaById = readAllMeta(rulesDir)
+  const ids = selectLintRules(metaById, full)
   for (const id of ids) {
     const lintPath = join(rulesDir, id, 'js', 'lint.mjs')
     if (!existsSync(lintPath)) {
       log(`⚠️  lint: правило ${id} має lint-фазу, але немає js/lint.mjs — пропускаю.\n`)
       continue
     }
+    // lintPath = join(rulesDir, id, …) — суто package-internal (rulesDir пакета + id зі
+    // selectLintRules за власним meta), не зовнішній вхід → ін'єкції немає.
+    // eslint-disable-next-line no-unsanitized/method
     const mod = await import(lintPath)
-    const code = await mod.lint(changed, cwd, { readOnly })
+    // `llmFix` (opt-in opportunistic LLM-fix, спека 2026-06-15): лише правила з
+    // `meta.json: llmFix:true` отримують fix-сходинку; решта — detect-only. Це й
+    // забезпечує safety-тріаж (логічні лінтери не вмикають LLM-fix випадково).
+    const llmFix = metaById[id]?.llmFix === true
+    const code = await mod.lint(changed, cwd, { readOnly, llmFix })
     if (code !== 0) return code
   }
 

package/rules/text/js/lint.mjs

@@ -6,9 +6,10 @@ import { runLintTextCli } from '../lint/lint.mjs'
 /**
  * @param {string[] | undefined} _files ігнорується (whole-repo аналіз)
  * @param {string} [_cwd] корінь (ігнорується — CLI працює від process.cwd())
- * @param {{ readOnly?: boolean }} [opts] readOnly → детект без авто-фіксу (нуль мутацій)
+ * @param {{ readOnly?: boolean, llmFix?: boolean }} [opts] readOnly → детект без авто-фіксу (нуль мутацій);
+ *   llmFix → opt-in omlx-класифікація cspell (з `meta.json: llmFix:true`)
  * @returns {Promise<number>} exit code
  */
 export function lint(_files, _cwd, opts = {}) {
-  return runLintTextCli({ readOnly: opts.readOnly === true })
+  return runLintTextCli({ readOnly: opts.readOnly === true, llmFix: opts.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,39 +41,82 @@ 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 → лише детект (нуль мутацій)
+ * @param {boolean} [llmFix] opt-in omlx-класифікація (з `meta.json: llmFix:true`); без нього — лише детект
  * @returns {number} 0 — чисто; 1 — лишились знахідки / помилка середовища
  */
-export function runCspellText(cwd = process.cwd(), readOnly = false) {
+export function runCspellText(cwd = process.cwd(), readOnly = false, llmFix = false) {
   const bin = resolveCmd('npx')
   if (!bin) {
     process.stderr.write('❌ npx не знайдено в PATH (cspell).\n')
@@ -69,35 +125,55 @@ export function runCspellText(cwd = process.cwd(), readOnly = false) {
 
   const first = detectCspell(cwd, bin)
   if (first.code === 0) return 0
-  if (readOnly) {
+  if (readOnly || !llmFix) {
+    process.stdout.write(first.out)
+    return first.code
+  }
+
+  // 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
   }
 
-  // Fix-режим: omlx по файлах зі справжніми одруками.
-  const byFile = groupFindingsByFile(first.out)
-  const files = [...byFile.keys()]
-  if (files.length === 0) {
+  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/rules/text/lint/lint.mjs

@@ -97,9 +97,10 @@ function preflight(dep) {
 /**
  * Внутрішні кроки `lint-text` без локу.
  * @param {boolean} [readOnly] true → лише детект без авто-фіксу (нуль мутацій — CI/pre-commit)
+ * @param {boolean} [llmFix] opt-in omlx-класифікація cspell (інші кроки фіксяться детерміновано за readOnly)
  * @returns {number} 0 — все OK, інакше — код першого кроку, що впав
  */
-function runLintTextSteps(readOnly = false) {
+function runLintTextSteps(readOnly = false, llmFix = false) {
   // Auto-install: throws on failure → propagates as exit 1 from runStandardLint
   ensureTool('shellcheck')
   ensureTool('dotenv-linter')
@@ -107,8 +108,8 @@ function runLintTextSteps(readOnly = false) {
   // patch потрібен лише для авто-фіксу shellcheck; у read-only пропускаємо preflight.
   if (!readOnly && !preflight(PATCH_PREFLIGHT)) return 1
 
-  console.log(`\n▶ cspell (${readOnly ? 'перевірка' : 'omlx-автофікс одруків + перевірка'})`)
-  const cspellCode = runCspellText(process.cwd(), readOnly)
+  console.log(`\n▶ cspell (${!readOnly && llmFix ? 'omlx-класифікація + словник + перевірка' : 'перевірка'})`)
+  const cspellCode = runCspellText(process.cwd(), readOnly, llmFix)
   if (cspellCode !== 0) return cspellCode
 
   console.log(`\n▶ shellcheck (${readOnly ? 'перевірка' : 'авто-фікс + фінальна перевірка'} *.sh)`)
@@ -129,8 +130,9 @@ function runLintTextSteps(readOnly = false) {
 
 /**
  * Публічна CLI-форма: серіалізує через `withLock('lint-text')` + дедуп за станом git-дерева.
- * @param {{ readOnly?: boolean }} [opts] readOnly → детект без авто-фіксу
+ * @param {{ readOnly?: boolean, llmFix?: boolean }} [opts] readOnly → детект без авто-фіксу;
+ *   llmFix → omlx-класифікація cspell (opt-in із `meta.json: llmFix:true`)
  * @returns {Promise<number>} код виходу
  */
 export const runLintTextCli = (opts = {}) =>
-  runStandardLint(import.meta.dirname, () => runLintTextSteps(opts.readOnly === true))
+  runStandardLint(import.meta.dirname, () => runLintTextSteps(opts.readOnly === true, opts.llmFix === true))

package/rules/text/meta.json

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