@nitra/cursor 11.0.0 → 11.1.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [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/package.json

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

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

@@ -63,7 +63,7 @@ function selectTargets(root, all, { overwrite, retryDegraded }) {
  * Preflight локального бекенда: для omlx-моделі — мінімальний chat-виклик.
  * @returns {string|null} текст фатальної проблеми або null якщо можна генерувати
  */
-function preflightProblem() {
+export function preflightProblem() {
   if (!DEFAULT_LOCAL_MODEL) {
     return 'модель не задано. Вистав N_LOCAL_MIN_MODEL (напр. omlx/mlx-community--gemma-4-e4b-it-OptiQ-4bit) і повтори.'
   }
@@ -214,13 +214,29 @@ export async function runDocFilesGenCli(argv) {
     return 0
   }
 
+  return runGenerationBatch(targets, root, {
+    headline: `📋 doc-files: до генерації ${targets.length} файл(ів)${modeSuffix({ overwrite, retryDegraded })}`
+  })
+}
+
+/**
+ * Спільне ядро генерації: 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 = preflightProblem()
   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, 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)
+      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/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/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": [