@7n/rules 1.48.1 → 1.49.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.48.1",
+  "version": "1.49.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/rules/changelog/.changes/260724-1500.md

@@ -0,0 +1,5 @@
+---
+bump: patch
+section: Fixed
+---
+changelog consistency: додано change-файл для змін у npm/rules/changelog

package/rules/doc-files/docgen-files-batch/docs/index.md

@@ -0,0 +1,9 @@
+---
+type: Directory Index
+title: npm/rules/doc-files/docgen-files-batch
+resource: npm/rules/doc-files/docgen-files-batch/
+---
+
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [main.mjs](main.md) | JS Module |

package/rules/doc-files/docgen-files-batch/docs/main.md

@@ -3,36 +3,77 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-files-batch/main.mjs
 docgen:
-  crc: 8b00ffa9
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.99
+  crc: 5245bd1f
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 80
+  issues: internal-name:generateOne,internal-name:runBatchPass,judge-refine:kept-original,judge:inaccurate:0.99
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Цей модуль керує повним циклом генерації документації. Він використовує функцію `selectTargets` для вибору цільових файлів та `purgeOrphanedDocs` для видалення посилань на відсутні файли. Для ініціалізації процесу застосовується `runDocFilesGenCli`, а пакетна генерація контролюється через `runGenerationBatch`. Після генерації метадані файлів оновлюються за допомогою `runDocFilesStampCli`, що додає хеш відповідного вихідного файлу. Усі операції виконуються з механізмом fail-safe, що перехоплює помилки та не кидає винятків назовні.
+Файл керує життєвим циклом поведінкової документації для source-файлів: `selectTargets` визначає цілі, `runGenerationBatch` оновлює docs-файли, `purgeOrphanedDocs` прибирає сирітські документи, а `generateDirIndex` підтримує індекси директорій. `nativeBatchAvailable`, `runDocFilesGenCli` і `runDocFilesStampCli` забезпечують безпечний контур CLI/batch-прогонів із кешуванням у межах одного запуску.
+
+Модуль звертається до мережі, але працює fail-safe: перехоплює помилки, не кидає винятків назовні і дає прогону завершитися контрольовано.
 
 ## Поведінка
 
-Поведінка
-selectTargets вибирає файли для генерації документації, які є застарілими або мають низьку якість, виключаючи ті, що вже мають потік (tier) `cloud-avg`. Рукописні доки (docPath існує без docgen-frontmatter, `foreign`) без `--overwrite` цілями не стають.
-purgeOrphanedDocs видаляє вказівники на файли документації, для яких не існує відповідного вихідного файлу, і оновлює індекси директорій.
-runDocFilesGenCli керує процесом генерації документації, видаляючи сирітських доків, визначаючи цілі та запускаючи пакетну генерацію; про пропущені рукописні (foreign) доки попереджає у stderr — тихого перезапису людського змісту немає, перезапис лише explicit `--overwrite`.
-runGenerationBatch виконує генерацію документації для визначеного набору файлів, керуючи логікою циркут-брейкера при системних збоях; опційний `deadlineAt` (м'який дедлайн fix-pipeline) зупиняє батч перед стартом наступного файлу штатно — зроблене лишається на диску зі свіжими CRC, решту підбирає наступний прогін (перший файл стартує завжди). Той самий `deadlineAt` прокидається у `generateDoc`, тож per-call LLM-таймаути ріжуться під залишок бюджету і файл у процесі обривається на дедлайні transient-помилкою, а не живе батчем-зомбі поверх наступного rung-а.
-generateDirIndex (пере)генерує `index.md` директорії docs/ як OKF Directory Index без H1 у тілі — top-level заголовком лишається frontmatter `title:`, тож MD025/single-title чистий; чужий `index.md` (дока source-файлу чи людський зміст без OKF-типу) не перезаписується.
-runDocFilesStampCli оновлює метадані (frontmatter) наявних файлів документації, додаючи хеш вихідного файлу, без повторного запуску генерації.
+runDocFilesGenCli запускає повний прогін документації: прибирає сирітські файли через purgeOrphanedDocs, обирає актуальні цілі через selectTargets і передає їх у runGenerationBatch. Результати записуються у відповідні docs-файли, а після проходу оновлюються директорійні індекси через generateDirIndex.
+
+selectTargets підтримує збіжний режим роботи: за замовчуванням бере відсутні, застарілі або degraded-документи, але не ганяє безкінечно ті самі degraded-версії без зміни джерела. Режим перезапису переводить вибір у повну регенерацію всіх знайдених цілей.
+
+runGenerationBatch є спільним ядром для CLI і автоматичних scoped-прогонів. Перед роботою перевіряє локальний LLM-backend, далі або використовує native batch-шлях після позитивного nativeBatchAvailable, або переходить у послідовний безпечний режим. Для локального provider-контуру очікується endpoint http://127.0.0.1:8000/v1/. Помилки класифікуються так, щоб незворотні пропуски не ламали весь прогін, інфраструктурні збої потрапляли у підсумкову статистику, а системні падіння могли зупинити batch fail-safe exit-кодом без винятків назовні.
+
+nativeBatchAvailable кешує результат перевірки в межах прогону, щоб не повторювати однаковий тест доступності native-аддона. Якщо batch-недоступний або є м’який дедлайн, runGenerationBatch лишається на послідовному шляху, де частковий прогрес безпечно зберігається по файлах і наступний запуск продовжує за станом CRC.
+
+purgeOrphanedDocs видаляє документацію без відповідного source-файлу, після чого підтримує docs-директорії у чистому стані: оновлює index.md або прибирає порожню директорію. generateDirIndex формує локальний огляд наявних документів у конкретній docs-директорії й не створює індекс там, де немає документів для переліку.
+
+runDocFilesStampCli не звертається до LLM: він лише приводить наявні документи до актуального frontmatter-штампа source і CRC, зберігаючи вже наявні метадані моделі та якості. Це дає міграційний шлях для старих документів без повторної генерації змісту.
 
 ## Публічний API
 
-selectTargets — Визначає цілі для генерації документації: `default` — застарілі або погіршені доки, які ще не пройшли перерахунок CRC; `--overwrite` — всі доки. Погіршена дока отримує лише один повторний ретрай на версію джерела; після невдалого ретраю вона позначається як `retried: true` і більше не змінюється до оновлення джерела.
-purgeOrphanedDocs — Видаляє доки, які втратили зв'язок із джерелом, та оновлює індекс.md. Якщо в каталозі docs залишається лише index.md або нічого, він очищається.
-runDocFilesGenCli — Генерує документацію для доків, які є застарілими або відсутніми.
-runGenerationBatch — Основний процес генерації: перевіряє локальний бекенд, послідовно генерує документацію для визначених цілей, застосовуючи захист від ланцюгових збоїв і м'який дедлайн (`deadlineAt`); також використовується для лінтінгу змінених файлів.
-generateDirIndex — (Пере)генерує Directory Index (`index.md`) у docs/-директорії; детекція власного індексу — за frontmatter `type: Directory Index`, чужі index.md недоторкані.
-runDocFilesStampCli — Автоматично додає або виправляє метадані (source + crc) у існуючих доках без залучення LLM. Цей процес використовується для міграції доків без CRC, зберігаючи при цьому інформацію про модель та якість з метаданих.
+- selectTargets — Цілі генерації:
+  - default      → застарілі (stale) АБО degraded-доки, які ще не доретраювали при цьому CRC;
+  - `--overwrite` → усі.
+Degraded-док отримує рівно ОДИН доретрай на версію джерела: після невдалого доретраю
+(лишився degraded) штампується `retried: true` і його більше не чіпають до зміни джерела
+(нова версія → CRC-mismatch → stale → лічильник скидається). Конвеєр сходиться без прапора.
+- nativeBatchAvailable — Чи доступний native-аддон `@7n/llm-lib` для 2b-batch (T8, рішення Р). Викликає
+`submitBatchImpl` з порожнім `items` — це не робить жодного LLM-виклику
+(Rust-крейт повертає порожній результат до резолву моделі), лише перевіряє,
+що napi-аддон завантажується. Zero-native споживачі (аддон не зібраний/не
+підтримувана платформа) отримують `false` і йдуть у послідовний фолбек.
+- generateDirIndex — Генерує/оновлює `index.md` у директорії `docs/` — OKF Directory Index із таблицею
+всіх наявних doc-файлів у цій директорії. Не зачіпає `index.md` при відсутності
+інших doc-файлів.
+- purgeOrphanedDocs — Видаляє сирітські доки (source-файл не існує) і оновлює/прибирає index.md.
+Якщо після видалення в docs/-директорії лишились тільки index.md або нічого — очищує її.
+- runDocFilesGenCli — `doc-files gen` — згенерувати документацію для застарілих/відсутніх док.
+- runGenerationBatch — Спільне ядро генерації: preflight локального бекенда → послідовний прогін
+`targets` через `generateOne` з circuit-breaker'ом (K systemic-збоїв підряд →
+abort) → підсумковий звіт. Перевикористовують і батч-CLI (`runDocFilesGenCli`),
+і opportunistic lint-крок doc-files (scoped-набір змінених файлів).
+
+`deadlineAt` (epoch ms): м'який дедлайн fix-pipeline — перед стартом КОЖНОГО
+наступного файлу (перший стартує завжди) батч звіряється з дедлайном і, коли час
+вийшов, завершується штатно з частковим прогресом. Той самий дедлайн прокидається
+у generateDoc: per-call LLM-таймаути ріжуться під залишок бюджету, тож і файл
+У ПРОЦЕСІ обривається на дедлайні (transient-помилка), а не живе батчем-зомбі
+поверх наступного rung-а. Зроблене записано по одному файлу (durable, свіжий
+CRC) — наступний прогін підбирає решту за CRC.
+T8 (2b-batch, рішення Р): коли доступний native-аддон `@7n/llm-lib` (`nativeBatchAvailable`)
+і рунг БЕЗ `deadlineAt` (fix-pipeline рунги лишаються на послідовному шляху —
+там дедлайн підтримується), увесь `targets` іде ОДНИМ `submitBatch` через
+`runBatchPass` замість цього циклу по одному файлу. Zero-native споживачі
+(аддон не зібраний/платформа не підтримується) автоматично лишаються на
+послідовному шляху нижче — жодної відмінності в CLI/skill/hook-контракті.
+- runDocFilesStampCli — `doc-files stamp` — детерміновано (пере)штампувати frontmatter `source`+`crc`
+у НАЯВНИХ доках без виклику LLM. Для міграції док, які ще не мають CRC.
+Поля `model`, `tier` та якості (`score`/`issues`/`judgeModel`) при цьому зберігаються
+з наявного frontmatter.
 
 ## Гарантії поведінки
 
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- Кешує результати в межах одного прогону.

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

@@ -11,12 +11,14 @@ import {
 } from 'node:fs'
 import { spawnSync } from 'node:child_process'
 import { basename, dirname, join, relative } from 'node:path'
+import { env } from 'node:process'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
 import { createProgressReporter } from '../../../scripts/lib/lint-surface/progress.mjs'
-import { generateDoc, DEFAULT_LOCAL_MODEL } from '../docgen-gen/main.mjs'
+import { generateDoc, DEFAULT_LOCAL_MODEL, prepareBatchItem, finishBatchItem } from '../docgen-gen/main.mjs'
 import { crc32, stampDoc, readDocQuality, readDocModel, readDocTier, QUALITY_THRESHOLD } from '../docgen-crc/main.mjs'
 import { resolveRoot, scanForDocFiles, scanOrphanedDocs } from '../docgen-scan/main.mjs'
+import { submitBatch as submitBatchNative } from '@7n/llm-lib/batch'
 
 /** Regex-класифікатори помилки генерації (module-scope, без ре-компіляції на виклик). */
 const ERR_PERMANENT_RE = /prompt too long|pre-send guard|too long/i
@@ -192,6 +194,219 @@ async function generateOne(file, root, progress, stats, { model, tier, emit, dea
   }
 }
 
+/**
+ * Кеш перевірки доступності native-аддону (T8): один процес — один результат
+ * ЛИШЕ для дефолтного `submitBatchNative` (production-шлях) — перевірка триває
+ * на першому виклику (порожній `items` — 0 LLM-викликів, лише спроба
+ * завантажити napi-аддон). Інжектований `submitBatchImpl` (тести) кешем НЕ
+ * керується — інакше перший тест зафіксував би результат для всіх наступних.
+ * @type {boolean|null}
+ */
+let nativeBatchAvailableCache = null
+
+/**
+ * Чи доступний native-аддон `@7n/llm-lib` для 2b-batch (T8, рішення Р). Викликає
+ * `submitBatchImpl` з порожнім `items` — це не робить жодного LLM-виклику
+ * (Rust-крейт повертає порожній результат до резолву моделі), лише перевіряє,
+ * що napi-аддон завантажується. Zero-native споживачі (аддон не зібраний/не
+ * підтримувана платформа) отримують `false` і йдуть у послідовний фолбек.
+ * @param {(modelSpecOrTier: string, items: Array<object>) => Promise<Array<object>>} submitBatchImpl injectable submitBatch (тест/прод)
+ * @param {boolean} [useCache] кешувати результат (типово лише для дефолтного `submitBatchNative`)
+ * @returns {Promise<boolean>} true — можна йти batch-шляхом
+ */
+export async function nativeBatchAvailable(submitBatchImpl, useCache = true) {
+  if (useCache && nativeBatchAvailableCache !== null) return nativeBatchAvailableCache
+  let result
+  try {
+    await submitBatchImpl('min', [])
+    result = true
+  } catch {
+    result = false
+  }
+  if (useCache) nativeBatchAvailableCache = result
+  return result
+}
+
+/**
+ * `localProviders` для Rust-крейта `llm_lib::local_cloud` (2b-batch, T8):
+ * інша половина конфігурації, ніж у sequential-шляху. `generateDoc`/`callLlm`
+ * ходять через `runOneShot` (pi ModelRegistry, свій резолв ендпоінта — читає
+ * pi-конфіг), а `submitBatch` — через Rust `LocalCloud`, якому явний
+ * `{ omlx: { baseUrl, apiKey } }` ОБОВʼЯЗКОВИЙ: без нього незнайомий provider-
+ * префікс (`"omlx/…"`) падає крізь cloud-гілку genai, яка бачить голу назву
+ * моделі без провайдера й типово вгадує адаптер Ollama (`localhost:11434`,
+ * жива помилка з бенчу T8) — тихий, неочевидний збій. Той самий baseUrl-
+ * конвент, що й `llm-lib/tests/batch.test.mjs` та `examples/batch_bench.rs`.
+ * Override — `opts.localProviders` (кастомний конфіг для нестандартного порту).
+ * @returns {{ omlx: { baseUrl: string, apiKey: string|null } }} дефолтна мапа локальних провайдерів
+ */
+function defaultLocalProviders() {
+  return { omlx: { baseUrl: 'http://127.0.0.1:8000/v1/', apiKey: env.OMLX_API_KEY ?? null } }
+}
+
+/**
+ * T8 (2b-batch, рішення Р): один `submit` на ВЕСЬ набір `targets` замість
+ * послідовного циклу по одному файлу. Готує items через `prepareBatchItem`
+ * (pre-send guard тут же відсіює завеликі джерела — 0 LLM-викликів/0 items у
+ * batch-і), один `submitBatchImpl(...)`, потім постобробка кожного результату
+ * (`finishBatchItem`) і запис доки — той самий штамп/файл-запис, що й
+ * послідовний `generateOne`. Помилка ОДНОГО item-у (класифікується
+ * `classifyDocgenError`, як і в послідовному шляху) не валить решту —
+ * заноситься у `stats.err`/`stats.skipped`, batch триває.
+ *
+ * Обмеження v1: без circuit-breaker (concurrency в Rust-крейті — помилки не
+ * «підряд» у тому сенсі, що має сенс для fail-fast) і без `deadlineAt`
+ * (викликач цього шляху не проставляє дедлайн — гейт `!opts.deadlineAt` у
+ * `runGenerationBatch`; fix-pipeline рунги лишаються на послідовному шляху,
+ * де м'який дедлайн підтримується).
+ * @param {Array<object>} targets елементи scanForDocFiles
+ * @param {string} root абсолютний корінь
+ * @param {{ model?: string, tier?: string|null, localProviders?: object, submitBatchImpl?: (modelSpecOrTier: string, items: Array<object>, opts?: object) => Promise<Array<object>> }} opts модель/тир/local-provider-конфіг (інакше `defaultLocalProviders()`)/інжект submitBatch
+ * @param {{ ok: number, degraded: number, err: number, errors: string[], skipped: string[] }} stats акумулятор (мутується)
+ * @param {{ reporter?: object, emit?: (s: string) => void }} io прогрес-репортер і логер рядка результату
+ * @returns {Promise<void>}
+ */
+async function runBatchPass(targets, root, opts, stats, { reporter, emit }) {
+  const model = opts.model ?? DEFAULT_LOCAL_MODEL
+  const submitBatchImpl = opts.submitBatchImpl ?? submitBatchNative
+  const out = emit ?? (s => process.stdout.write(s))
+
+  const prepared = await prepareBatchTargets(targets, root, stats, { reporter, out })
+  if (prepared.length === 0) return
+
+  const items = prepared.map(p => ({
+    customId: p.file.sourcePath,
+    prompt: p.messages.find(m => m.role === 'user')?.content ?? '',
+    system: p.messages.find(m => m.role === 'system')?.content
+  }))
+  const onProgress = makeBatchProgress(reporter, targets.length - prepared.length, targets.length)
+  const localProviders = opts.localProviders ?? defaultLocalProviders()
+  const results = await submitBatchImpl(model, items, { onProgress, localProviders })
+  const byId = new Map(results.map(r => [r.customId, r]))
+
+  for (const p of prepared) {
+    processBatchResult(byId.get(p.file.sourcePath), p, { model, tier: opts.tier ?? null, stats, out })
+  }
+}
+
+/**
+ * Prep-фаза batch-пасу: pre-send guard + факт-лист/messages для кожного файлу
+ * (`prepareBatchItem`). Файли, що впали на цій фазі (завеликий src тощо), одразу
+ * класифікуються й записуються у `stats` — до batch-у вони не потрапляють.
+ * @param {Array<object>} targets елементи scanForDocFiles
+ * @param {string} root абсолютний корінь
+ * @param {{ ok: number, degraded: number, err: number, errors: string[], skipped: string[] }} stats акумулятор (мутується)
+ * @param {{ reporter?: object, out: (s: string) => void }} io прогрес-репортер і логер
+ * @returns {Promise<Array<object>>} елементи, готові до batch-у (file/sourceAbs/docAbs/size/facts/anchors/src/messages/intent)
+ */
+async function prepareBatchTargets(targets, root, stats, { reporter, out }) {
+  const prepared = []
+  for (const file of targets) {
+    const sourceAbs = join(root, file.sourcePath)
+    const docAbs = join(root, file.docPath)
+    let size = 0
+    try {
+      size = statSync(sourceAbs).size
+    } catch {
+      // файл зник між скануванням і генерацією — лишаємо розмір 0
+    }
+    const existingMd = existsSync(docAbs) ? readFileSync(docAbs, 'utf8') : null
+    try {
+      const prep = await prepareBatchItem(sourceAbs, { existingMd })
+      prepared.push({ file, sourceAbs, docAbs, size, ...prep })
+    } catch (error) {
+      recordBatchOutcome(stats, out, file.sourcePath, size, error.message)
+    }
+    reporter?.concernStart(file.sourcePath)
+    reporter?.concernDone(file.sourcePath)
+  }
+  return prepared
+}
+
+/**
+ * Класифікує помилку одного item-у (`classifyDocgenError`, спільний з послідовним
+ * шляхом) і заносить її у `stats` — permanent → skip, інакше → err. Друкує той
+ * самий формат рядка, що й `generateOne`.
+ * @param {{ ok: number, degraded: number, err: number, errors: string[], skipped: string[] }} stats акумулятор (мутується)
+ * @param {(s: string) => void} out логер рядка результату
+ * @param {string} sourcePath шлях джерела (для рядка й акумулятора)
+ * @param {number} size розмір джерела в байтах (для рядка)
+ * @param {string} message повідомлення помилки
+ * @returns {void}
+ */
+function recordBatchOutcome(stats, out, sourcePath, size, message) {
+  const cls = classifyDocgenError(message)
+  const prefix = `  ${sourcePath} [${fmtSize(size)}] `
+  if (cls === 'permanent') {
+    stats.skipped.push(sourcePath)
+    out(`${prefix}⊘ skip (permanent): ${message}\n`)
+  } else {
+    stats.err++
+    stats.errors.push(sourcePath)
+    out(`${prefix}✗ ${cls}: ${message}\n`)
+  }
+}
+
+/**
+ * Progress-колбек для `submitBatchImpl`: `completed` — монотонний лічильник
+ * завершених item-ів (порядок завершення НЕ збігається з input-order при
+ * конкурентному виконанні в Rust-крейті, тож імʼя файлу тут недоступне —
+ * синтетичний ключ). `doneBase` — скільки файлів уже врахував prep-фазний
+ * `concernDone` (щоб бар дійшов рівно до `total`, а не `total + prep-skip`).
+ * @param {object|undefined} reporter ProgressReporter або undefined (не-TTY)
+ * @param {number} doneBase скільки файлів уже відзвітовано на prep-фазі
+ * @param {number} total загальна кількість targets
+ * @returns {(completed: number) => void} колбек для `submitBatchImpl`
+ */
+function makeBatchProgress(reporter, doneBase, total) {
+  let lastCompleted = 0
+  return completed => {
+    reporter?.concernStart(`2b-batch ${doneBase + completed}/${total}`)
+    while (lastCompleted < completed) {
+      lastCompleted++
+      reporter?.concernDone(`2b-item-${lastCompleted}`)
+    }
+  }
+}
+
+/**
+ * Постобробка одного item-результату batch-у: помилка → `recordBatchOutcome`;
+ * успіх → `finishBatchItem` (det-скоринг) → штамп → запис доки → `stats.ok`/
+ * `stats.degraded`.
+ * @param {{ customId: string, ok?: string, error?: string }|undefined} r результат item-у (undefined — customId не знайдено серед results)
+ * @param {object} p підготовлений item (з `prepareBatchTargets`)
+ * @param {{ model: string, tier: string|null, stats: object, out: (s: string) => void }} ctx модель/тир/акумулятор/логер
+ * @returns {void}
+ */
+function processBatchResult(r, p, { model, tier, stats, out }) {
+  const prefix = `  ${p.file.sourcePath} [${fmtSize(p.size)}] `
+  if (!r || r.error) {
+    recordBatchOutcome(
+      stats,
+      out,
+      p.file.sourcePath,
+      p.size,
+      r?.error ?? 'batch: результат відсутній для цього customId'
+    )
+    return
+  }
+  const finished = finishBatchItem(r.ok, { facts: p.facts, anchors: p.anchors, src: p.src, intent: p.intent, model })
+  const crc = crc32(readFileSync(p.sourceAbs))
+  mkdirSync(dirname(p.docAbs), { recursive: true })
+  const quality =
+    finished.score === null
+      ? null
+      : { score: finished.score, issues: finished.degraded ? finished.issues : [], judge: null }
+  writeFileSync(p.docAbs, stampDoc(finished.md, p.file.sourcePath, crc, quality, finished.model, tier))
+  stats.ok++
+  if (finished.degraded) {
+    stats.degraded++
+    out(`${prefix}⚠ degraded score=${finished.score} crc=${crc} (2b-batch)\n`)
+  } else {
+    out(`${prefix}✓ score=${finished.score ?? '—'} crc=${crc} (2b-batch)\n`)
+  }
+}
+
 /** Regex для витягу OKF-полів із frontmatter існуючої доки (швидкий, без YAML-парсера). */
 const OKF_TITLE_RE = /^title: (.+)$/mu
 const OKF_TYPE_RE = /^type: (.+)$/mu
@@ -387,6 +602,53 @@ export function runDocFilesGenCli(argv) {
   })
 }
 
+/**
+ * Послідовний фолбек-шлях (T8): циклом по одному файлу через `generateOne`, з
+ * circuit-breaker'ом (K systemic-збоїв підряд → abort) і м'яким дедлайном
+ * fix-pipeline. Той самий шлях, що й до T8 — вихід не змінився, лише
+ * винесений в окрему функцію, щоб `runGenerationBatch` вибирав між ним і
+ * `runBatchPass`.
+ * @param {Array<object>} targets елементи scanForDocFiles
+ * @param {string} root абсолютний корінь
+ * @param {{ model?: string, tier?: string, deadlineAt?: number|null }} opts модель/тир/дедлайн
+ * @param {{ ok: number, degraded: number, err: number, errors: string[], skipped: string[] }} stats акумулятор (мутується)
+ * @param {{ reporter?: object, emit?: (s: string) => void }} io прогрес-репортер і логер
+ * @returns {Promise<{ done: number, aborted: boolean, deadlineHit: boolean }>} підсумок проходу
+ */
+async function runSequentialPass(targets, root, opts, stats, { reporter, emit }) {
+  let done = 0
+  let systemicStreak = 0
+  let aborted = false
+  let deadlineHit = false
+  for (const file of targets) {
+    // М'який дедлайн (fix-pipeline): не стартуємо наступний файл після дедлайну.
+    if (deadlineReached(opts.deadlineAt, done)) {
+      deadlineHit = true
+      break
+    }
+    done++
+    reporter?.concernStart(file.sourcePath)
+    const status = await generateOne(file, root, { done, total: targets.length }, stats, {
+      model: opts.model,
+      tier: opts.tier,
+      emit,
+      deadlineAt: opts.deadlineAt ?? null
+    })
+    reporter?.concernDone(file.sourcePath)
+    // Circuit-breaker: K systemic-збоїв підряд → негайний abort (середовище впало,
+    // решта файлів так само згорить). Будь-який не-systemic результат скидає лічильник.
+    if (status === 'systemic') {
+      if (++systemicStreak >= SYSTEMIC_ABORT_STREAK) {
+        aborted = true
+        break
+      }
+    } else {
+      systemicStreak = 0
+    }
+  }
+  return { done, aborted, deadlineHit }
+}
+
 /**
  * Спільне ядро генерації: preflight локального бекенда → послідовний прогін
  * `targets` через `generateOne` з circuit-breaker'ом (K systemic-збоїв підряд →
@@ -400,9 +662,15 @@ export function runDocFilesGenCli(argv) {
  * У ПРОЦЕСІ обривається на дедлайні (transient-помилка), а не живе батчем-зомбі
  * поверх наступного rung-а. Зроблене записано по одному файлу (durable, свіжий
  * CRC) — наступний прогін підбирає решту за CRC.
+ * T8 (2b-batch, рішення Р): коли доступний native-аддон `@7n/llm-lib` (`nativeBatchAvailable`)
+ * і рунг БЕЗ `deadlineAt` (fix-pipeline рунги лишаються на послідовному шляху —
+ * там дедлайн підтримується), увесь `targets` іде ОДНИМ `submitBatch` через
+ * `runBatchPass` замість цього циклу по одному файлу. Zero-native споживачі
+ * (аддон не зібраний/платформа не підтримується) автоматично лишаються на
+ * послідовному шляху нижче — жодної відмінності в CLI/skill/hook-контракті.
  * @param {Array<object>} targets елементи scanForDocFiles (sourcePath/docPath)
  * @param {string} root абсолютний корінь
- * @param {{ headline?: string, model?: string, tier?: string, deadlineAt?: number|null }} [opts] headline — рядок-шапка прогону у stdout; model/tier — override моделі і її типу (інакше DEFAULT_LOCAL_MODEL); deadlineAt — м'який дедлайн (epoch ms)
+ * @param {{ headline?: string, model?: string, tier?: string, deadlineAt?: number|null, submitBatchImpl?: (modelSpecOrTier: string, items: Array<object>, opts?: object) => Promise<Array<object>>, forceSequential?: boolean }} [opts] headline — рядок-шапка прогону у stdout; model/tier — override моделі і її типу (інакше DEFAULT_LOCAL_MODEL); deadlineAt — м'який дедлайн (epoch ms); submitBatchImpl — інжект `submitBatch` (тест); forceSequential — примусовий фолбек (тест/діагностика)
  * @returns {Promise<number>} 0 — без помилок; 1 — фейл preflight або є помилки; 2 — systemic-abort
  */
 export async function runGenerationBatch(targets, root, opts = {}) {
@@ -429,36 +697,19 @@ export async function runGenerationBatch(targets, root, opts = {}) {
     : null
   const emit = reporter ? reporter.log : undefined
 
-  let done = 0
-  let systemicStreak = 0
+  const submitBatchImpl = opts.submitBatchImpl ?? submitBatchNative
+  const useBatch =
+    !opts.forceSequential && !opts.deadlineAt && (await nativeBatchAvailable(submitBatchImpl, !opts.submitBatchImpl))
+
+  let done
   let aborted = false
   let deadlineHit = false
   try {
-    for (const file of targets) {
-      // М'який дедлайн (fix-pipeline): не стартуємо наступний файл після дедлайну.
-      if (deadlineReached(opts.deadlineAt, done)) {
-        deadlineHit = true
-        break
-      }
-      done++
-      reporter?.concernStart(file.sourcePath)
-      const status = await generateOne(file, root, { done, total: targets.length }, stats, {
-        model: opts.model,
-        tier: opts.tier,
-        emit,
-        deadlineAt: opts.deadlineAt ?? null
-      })
-      reporter?.concernDone(file.sourcePath)
-      // Circuit-breaker: K systemic-збоїв підряд → негайний abort (середовище впало,
-      // решта файлів так само згорить). Будь-який не-systemic результат скидає лічильник.
-      if (status === 'systemic') {
-        if (++systemicStreak >= SYSTEMIC_ABORT_STREAK) {
-          aborted = true
-          break
-        }
-      } else {
-        systemicStreak = 0
-      }
+    if (useBatch) {
+      await runBatchPass(targets, root, { ...opts, submitBatchImpl }, stats, { reporter, emit })
+      done = targets.length
+    } else {
+      ;({ done, aborted, deadlineHit } = await runSequentialPass(targets, root, opts, stats, { reporter, emit }))
     }
   } finally {
     reporter?.stop()

package/rules/doc-files/docgen-gen/docs/index.md

@@ -0,0 +1,9 @@
+---
+type: Directory Index
+title: npm/rules/doc-files/docgen-gen
+resource: npm/rules/doc-files/docgen-gen/
+---
+
+| Файл                | Тип       |
+| ------------------- | --------- |
+| [main.mjs](main.md) | JS Module |

package/rules/doc-files/docgen-gen/docs/main.md

@@ -3,39 +3,50 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-gen/main.mjs
 docgen:
-  crc: c02d3a1f
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 80c789c7
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 10
+  issues: no-overview,short-behavior,internal-name:isApiGap,internal-name:renderApiLine,internal-name:oneShotDoc,internal-name:finishUnsupported,anchor-miss:(abie.mdc),best-of-2:retry-lost
 ---
 
-## Огляд
-
-Огляд
-Створює технічну документацію шляхом аналізу вихідного коду, генерації тексту, оцінки його якості та управління позиціонуванням захищеного блоку «Призначення» у фінальному документі. (abie.mdc)
-
-Поведінка
-splitProtected відокремлює захищений блок «Призначення» від основного вмісту документа, надаючи його тіло та текст без цього блоку.
-insertProtected поміщає захищений блок «Призначення» одразу після основного заголовка документа, якщо надано його тіло.
-scoreDoc оцінює згенерований документ за заданими критеріями, визначаючи його якість та реєструючи проблеми.
-DEFAULT_LOCAL_MODEL встановлює модель, яку використовувати для генерації документа, якщо не вказано іншу.
-generateDoc створює повний технічний документ з вихідного файлу, включаючи вихідну оцінку якості.
-
-## Поведінка
-
-splitProtected відокремлює захищений блок «Призначення» від основного вмісту документа, повертаючи його тіло та текст без цього блоку.
-insertProtected розміщує захищений блок «Призначення» одразу після основного заголовка документа, якщо його тіло було надано.
-scoreDoc оцінює згенерований документ за набором детермінованих правил (generic-огляд, коротка поведінка, галюцинації про кеш, витік службових імен, анкор-покриття, суржик) і реєструє коди проблем. Правило R8 — refusal/чат-філер («Я готовий писати…», «Надайте мені код…», через пре-гейт docgen-judge): форсує degraded незалежно від структурної оцінки, тож LLM-суддя на такому змісті не викликається; захищене людське «Призначення» з перевірки виключене.
-DEFAULT_LOCAL_MODEL визначає модель за замовчуванням для генерації документа, якщо не вказано інше.
-generateDoc створює повний технічний документ з вихідного файлу, включаючи детерміновану оцінку якості; для непідтримуваних структур (one-shot шлях) оцінка не застосовується, але refusal-пре-гейт діє і там — філер отримує score 0 і позначку degraded, щоб доретрай батчу підібрав файл.
-generateDoc приймає опційний `deadlineAt` (м'який дедлайн fix-pipeline, epoch ms): кожен LLM-виклик ріже свій таймаут під залишок бюджету (`capTimeoutToDeadline`), а вичерпаний бюджет обриває генерацію помилкою зі словом «timeout» ще до старту виклику — батч класифікує її як transient, і генерація ніколи не переживає бюджет рунга (без батчу-зомбі поверх наступного rung-а).
-
 ## Публічний API
 
-splitProtected — витягує тіло захищеної секції «Призначення» та повертає документ без неї.
-insertProtected — повертає захищений блок у фіксовану позицію одразу після заголовка документа.
-scoreDoc — детермінований скоринг документа (0 токенів) проти факт-листа: оцінка 0–100 і коди проблем.
-DEFAULT_LOCAL_MODEL — модель генерації за замовчуванням (env-конфігурована; без неї preflight фейлить гучно).
-generateDoc — головний вхід: джерело → md-дока з оцінкою якості, best-of-2 повтором і опційним семантичним суддею; опційний `deadlineAt` обмежує генерацію бюджетом рунга fix-pipeline.
-capTimeoutToDeadline — ріже базовий per-call таймаут під залишок до дедлайну (без дедлайну — базовий ліміт; після дедлайну — 0).
+- capTimeoutToDeadline — Ріже базовий per-call таймаут під залишок бюджету до дедлайну.
+Без дедлайну — базовий ліміт; після дедлайну — 0 (виклик не має стартувати).
+- stripLeadingPreamble — R9: зрізає провідні чат-преамбули й дубль назви секції з початку тексту.
+Ітерується, поки перший непорожній рядок лишається мета-нарацією — модель
+інколи ставить дві поспіль («Як технічний письменник…» + «Ось оновлений…»).
+- splitProtected — Відокремлює захищену секцію `## Призначення` (Варіант B). Межа — наступний `## `
+(H2); `###`+ усередині не обривають блок.
+- insertProtected — Вставляє захищений блок `## Призначення` одразу після H1 (фіксована позиція).
+- scoreDoc — Stage 2.5 — детермінований скоринг (0 токенів): перевіряє вихід проти фактів.
+- buildApiSection — Stage 1/3 (гібрид doc-files, ADR 260719-2155): «Публічний API» — покриті
+JSDoc-описом експорти рендеряться дослівно (`renderApiLine`, 0 токенів, 0
+галюцинацій), LLM викликається лише на прогалини (`isApiGap`). Якщо прогалин
+немає — секція збирається БЕЗ жодного LLM-виклику. Єдиний непокритий
+експорт (як і раніше) лишається описаним лише в Поведінці — окремого виклику
+на секцію з одного рядка не варте.
+- DEFAULT_LOCAL_MODEL — Дефолтна модель: N_CURSOR_DOCGEN_MODEL → resolveModel('min') (→ N_LOCAL_MIN_MODEL).
+Без хардкод-fallback: модель налаштовує кожен локально (`N_LOCAL_MIN_MODEL`); якщо
+нічого не задано — порожньо, і preflight оркестратора фейлить гучно (а не шле
+запит до неіснуючої моделі).
+- generateDoc — Головний API: файл → md-дока з det-оцінкою.
+
+Local-only (ADR 260610-2228): жодних cloud-ескалацій і pre-route — будь-який
+файл генерується локальною моделлю. Якщо det-score нижче порогу, один retry
+з вищою температурою (best-of-2); якщо й він не допоміг — результат
+позначається `degraded`, рішення про перегенерацію приймає batch/користувач.
+- prepareBatchItem — T8 (2b-batch, рішення Р): підготовка ОДНОГО item-у для `submitBatch` — та сама
+pre-send guard і той самий факт-лист/one-shot messages, що й `oneShotDoc`/
+`generateDoc`, але БЕЗ виклику LLM (виклик робить batch-шар одним `submit` на
+всі файли разом). Кидає ту саму помилку pre-send guard, що й `generateDoc`
+(класифікується `permanent` у batch-оркестраторі — skip, не помилка прогону).
+- finishBatchItem — T8 (2b-batch): постобробка ОДНОГО результату `submitBatch` — той самий фініш,
+що й `oneShotDoc`/`finishUnsupported`/det-скорер, тільки без LLM-виклику
+(текст уже отримано з batch-у). Judge-гейт (Stage 3) у batch-шляху НЕ
+викликається (мінімальний обсяг T8 — генерація; judge лишається опційним
+розширенням послідовного шляху).
 
 ## Гарантії поведінки