@7n/rules 1.0.0

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

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/doc-files/docgen-files-batch/main.mjs
+docgen:
+  crc: 6237a73f
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей модуль керує повним циклом генерації документації. Він використовує функцію `selectTargets` для вибору цільових файлів та `purgeOrphanedDocs` для видалення посилань на відсутні файли. Для ініціалізації процесу застосовується `runDocFilesGenCli`, а пакетна генерація контролюється через `runGenerationBatch`. Після генерації метадані файлів оновлюються за допомогою `runDocFilesStampCli`, що додає хеш відповідного вихідного файлу. Усі операції виконуються з механізмом fail-safe, що перехоплює помилки та не кидає винятків назовні.
+
+## Поведінка
+
+Поведінка
+selectTargets вибирає файли для генерації документації, які є застарілими або мають низьку якість, виключаючи ті, що вже мають потік (tier) `cloud-avg`. Рукописні доки (docPath існує без docgen-frontmatter, `foreign`) без `--overwrite` цілями не стають.
+purgeOrphanedDocs видаляє вказівники на файли документації, для яких не існує відповідного вихідного файлу, і оновлює індекси директорій.
+runDocFilesGenCli керує процесом генерації документації, видаляючи сирітських доків, визначаючи цілі та запускаючи пакетну генерацію; про пропущені рукописні (foreign) доки попереджає у stderr — тихого перезапису людського змісту немає, перезапис лише explicit `--overwrite`.
+runGenerationBatch виконує генерацію документації для визначеного набору файлів, керуючи логікою циркут-брейкера при системних збоях; опційний `deadlineAt` (м'який дедлайн fix-pipeline) зупиняє батч перед стартом наступного файлу штатно — зроблене лишається на диску зі свіжими CRC, решту підбирає наступний прогін (перший файл стартує завжди).
+generateDirIndex (пере)генерує `index.md` директорії docs/ як OKF Directory Index без H1 у тілі — top-level заголовком лишається frontmatter `title:`, тож MD025/single-title чистий; чужий `index.md` (дока source-файлу чи людський зміст без OKF-типу) не перезаписується.
+runDocFilesStampCli оновлює метадані (frontmatter) наявних файлів документації, додаючи хеш вихідного файлу, без повторного запуску генерації.
+
+## Публічний 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, зберігаючи при цьому інформацію про модель та якість з метаданих.
+
+## Гарантії поведінки
+
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

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

@@ -0,0 +1,517 @@
+/** @see ./docs/docgen-files-batch.md */
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync
+} from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { basename, dirname, join, relative } from 'node:path'
+
+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 { crc32, stampDoc, readDocQuality, readDocModel, readDocTier, QUALITY_THRESHOLD } from '../docgen-crc/main.mjs'
+import { resolveRoot, scanForDocFiles, scanOrphanedDocs } from '../docgen-scan/main.mjs'
+
+/** Regex-класифікатори помилки генерації (module-scope, без ре-компіляції на виклик). */
+const ERR_PERMANENT_RE = /prompt too long|pre-send guard|too long/i
+const ERR_SYSTEMIC_RE = /registry:|session:|не знайдена|memory|enomem|connection refused|econnrefused/i
+const ERR_TRANSIENT_RE = /timeout|etimedout/i
+
+/**
+ * Класифікує помилку генерації для batch-логіки (замінює `classifyOmlxError` після
+ * pi-міграції — помилки приходять як винятки з generateDoc/pi-one-shot):
+ *   - `permanent` — pre-send guard «Prompt too long» → skip (не ретраїти);
+ *   - `systemic`  — модель/сервер/registry/RAM упали → circuit-breaker abort;
+ *   - `transient` — таймаут (можна було б ретраїти);
+ *   - `infra`     — інше (рахуємо як помилку, але без abort).
+ * @param {string} msg повідомлення помилки
+ * @returns {'permanent'|'systemic'|'transient'|'infra'} клас
+ */
+function classifyDocgenError(msg) {
+  if (ERR_PERMANENT_RE.test(msg)) return 'permanent'
+  if (ERR_SYSTEMIC_RE.test(msg)) return 'systemic'
+  if (ERR_TRANSIENT_RE.test(msg)) return 'transient'
+  return 'infra'
+}
+
+/**
+ * Парсить `--limit N` / `--from N` / прапори режимів для дозапуску великого прогону.
+ * @param {string[]} argv аргументи
+ * @returns {{ from: number, limit: number, overwrite: boolean }} зріз і режими
+ */
+function parseGenArgs(argv) {
+  const num = (flag, dflt) => {
+    const i = argv.indexOf(flag)
+    return i !== -1 && argv[i + 1] ? Number(argv[i + 1]) || dflt : dflt
+  }
+  return {
+    from: num('--from', 0),
+    limit: num('--limit', Infinity),
+    overwrite: argv.includes('--overwrite')
+  }
+}
+
+/**
+ * Цілі генерації:
+ *   - default      → застарілі (stale) АБО degraded-доки, які ще не доретраювали при цьому CRC;
+ *   - `--overwrite` → усі.
+ * Degraded-док отримує рівно ОДИН доретрай на версію джерела: після невдалого доретраю
+ * (лишився degraded) штампується `retried: true` і його більше не чіпають до зміни джерела
+ * (нова версія → CRC-mismatch → stale → лічильник скидається). Конвеєр сходиться без прапора.
+ * @param {string} root абсолютний корінь
+ * @param {Array<object>} all результат scanForDocFiles
+ * @param {{ overwrite: boolean }} mode режими
+ * @returns {Array<object>} відфільтровані цілі
+ */
+export function selectTargets(root, all, { overwrite }) {
+  if (overwrite) return all
+  return all.filter(f => {
+    if (f.stale) return true
+    const docAbs = join(root, f.docPath)
+    const { score } = readDocQuality(docAbs)
+    return score !== null && score < QUALITY_THRESHOLD && readDocTier(docAbs) !== 'cloud-avg'
+  })
+}
+
+/**
+ * Текст-суфікс режиму для прогрес-рядка.
+ * @param {{ overwrite: boolean }} mode режими
+ * @returns {string} ` (--overwrite)` або порожній рядок
+ */
+function modeSuffix({ overwrite }) {
+  return overwrite ? ' (--overwrite)' : ''
+}
+
+/**
+ * Форматує мілісекунди у секунди з одним знаком (`1234` → `1.2s`).
+ * @param {number} ms тривалість у мілісекундах
+ * @returns {string} напр. `1.2s`
+ */
+function fmtSeconds(ms) {
+  return `${(ms / 1000).toFixed(1)}s`
+}
+
+/**
+ * Рядок таймінгу одного файлу: загальний час, час у LLM (і кількість викликів)
+ * та залишок — оркестрація (екстракт фактів, скоринг, парсинг, IO). Дає зрозуміти,
+ * скільки коштує сама модель проти JS-оркестрації.
+ * @param {{ ms: number, llmMs?: number, llmCalls?: number }} r результат generateDoc
+ * @returns {string} напр. `12.3s (llm 11.8s/7 calls, orch 0.5s)`
+ */
+function fmtTiming(r) {
+  const llmMs = r.llmMs ?? 0
+  return `${fmtSeconds(r.ms)} (llm ${fmtSeconds(llmMs)}/${r.llmCalls ?? 0} calls, orch ${fmtSeconds(r.ms - llmMs)})`
+}
+
+/** Скільки systemic-збоїв підряд → негайний abort батчу (fail-fast, без cooldown). */
+const SYSTEMIC_ABORT_STREAK = 3
+
+/**
+ * Чи настав м'який дедлайн батчу. Перший файл стартує завжди (done=0) — інакше
+ * прогін без жодного прогресу ніколи не зійдеться.
+ * @param {number|null|undefined} deadlineAt дедлайн (epoch ms) або null/undefined
+ * @param {number} done скільки файлів уже оброблено
+ * @returns {boolean} true — наступний файл не стартуємо
+ */
+function deadlineReached(deadlineAt, done) {
+  return Boolean(deadlineAt) && done > 0 && Date.now() >= deadlineAt
+}
+
+/**
+ * Діагностика розміру джерела (для дослідження, що роздуває контекст):
+ * байти + груба оцінка токенів (~bytes/4). Без size-guard-гейта — лише вивід.
+ * @param {number} bytes розмір файлу в байтах
+ * @returns {string} напр. `12.3KB ~3.1k tok`
+ */
+function fmtSize(bytes) {
+  return `${(bytes / 1024).toFixed(1)}KB ~${(bytes / 4 / 1000).toFixed(1)}k tok`
+}
+
+/**
+ * Генерує й штампує доку для одного файлу, оновлюючи лічильники й прогрес.
+ * Помилку класифікує (`classifyOmlxError`): `permanent` → skip (не «помилка для
+ * перегону»), `systemic`/`transient` → у `errors`. Повертає клас для циклу
+ * (circuit-breaker рахує systemic-підряд).
+ * Рядок результату складається цілком і друкується один раз через `emit` — у TTY
+ * він іде над прогрес-баром (multibar.log), тому часткові write-и на тому ж рядку
+ * неможливі.
+ * @param {object} file елемент scanForDocFiles
+ * @param {string} root абсолютний корінь
+ * @param {{ done: number, total: number }} progress позиція у прогресі
+ * @param {{ ok: number, degraded: number, err: number, errors: string[], skipped: string[] }} stats акумулятор
+ * @param {{ model?: string, tier?: string|null, emit?: (s: string) => void }} [opts] модель/тир для штампу; emit — логер рядка результату
+ * @returns {Promise<'ok'|'permanent'|'systemic'|'transient'>} результат для керування циклом
+ */
+async function generateOne(file, root, progress, stats, { model, tier, emit } = {}) {
+  const out = emit ?? (s => process.stdout.write(s))
+  const sourceAbs = join(root, file.sourcePath)
+  let size = 0
+  try {
+    size = statSync(sourceAbs).size
+  } catch {
+    // файл зник між скануванням і генерацією — лишаємо розмір 0
+  }
+  const prefix = `  [${progress.done}/${progress.total}] ${file.sourcePath} [${fmtSize(size)}] … `
+  try {
+    const docAbs = join(root, file.docPath)
+    // Варіант B: передаємо наявну доку, щоб зберегти захищену секцію «Призначення»
+    const existingMd = existsSync(docAbs) ? readFileSync(docAbs, 'utf8') : null
+    const result = await generateDoc(sourceAbs, { existingMd, model })
+    const crc = crc32(readFileSync(sourceAbs))
+    mkdirSync(dirname(docAbs), { recursive: true })
+    const quality =
+      result.score === null
+        ? null
+        : { score: result.score, issues: result.degraded ? result.issues : [], judge: result.judge }
+    writeFileSync(docAbs, stampDoc(result.md, file.sourcePath, crc, quality, result.model, tier ?? null))
+    stats.ok++
+    if (result.degraded) {
+      stats.degraded++
+      out(`${prefix}⚠ degraded score=${result.score} crc=${crc}  ${fmtTiming(result)}\n`)
+    } else {
+      out(`${prefix}✓ score=${result.score ?? '—'} crc=${crc}  ${fmtTiming(result)}\n`)
+    }
+    return 'ok'
+  } catch (error) {
+    const cls = classifyDocgenError(error.message)
+    if (cls === 'permanent') {
+      stats.skipped.push(file.sourcePath)
+      out(`${prefix}⊘ skip (permanent): ${error.message}\n`)
+    } else {
+      stats.err++
+      stats.errors.push(file.sourcePath)
+      out(`${prefix}✗ ${cls}: ${error.message}\n`)
+    }
+    return cls
+  }
+}
+
+/** Regex для витягу OKF-полів із frontmatter існуючої доки (швидкий, без YAML-парсера). */
+const OKF_TITLE_RE = /^title: (.+)$/mu
+const OKF_TYPE_RE = /^type: (.+)$/mu
+const OKF_RESOURCE_RE = /^resource:[ \t]+(\S[^\n]*)$/mu
+/** Суфікс `.md` для деривації заголовка з імені файлу. */
+const MD_SUFFIX_RE = /\.md$/u
+
+/**
+ * Витягує тіло YAML-frontmatter (між першим `---\n` та наступним рядком `---`).
+ * Лінійний пошук по рядках без backtracking-regex.
+ * @param {string} md вміст markdown-файлу
+ * @returns {string} тіло frontmatter (без обгортаючих `---`) або `''` якщо frontmatter відсутній
+ */
+function extractFrontmatter(md) {
+  if (!md.startsWith('---\n')) return ''
+  const lines = md.slice(4).split('\n')
+  const closeIdx = lines.findIndex(line => line.startsWith('---'))
+  if (closeIdx === -1) return ''
+  return lines.slice(0, closeIdx).join('\n')
+}
+
+/**
+ * Генерує/оновлює `index.md` у директорії `docs/` — OKF Directory Index із таблицею
+ * всіх наявних doc-файлів у цій директорії. Не зачіпає `index.md` при відсутності
+ * інших doc-файлів.
+ * @param {string} docsAbsDir абсолютний шлях директорії `docs/`
+ * @param {string} root абсолютний корінь проєкту
+ * @returns {void}
+ */
+export function generateDirIndex(docsAbsDir, root) {
+  const allMd = readdirSync(docsAbsDir)
+    .filter(f => f.endsWith('.md'))
+    .toSorted()
+
+  // Чужий index.md — не чіпаємо: дока source-файлу (`index.*` → type JS Module тощо)
+  // або людський зміст (без OKF-frontmatter взагалі). Перезаписуємо лише власний
+  // Directory Index (детекція за frontmatter `type:`, не за H1).
+  if (allMd.includes('index.md')) {
+    const existingFm = extractFrontmatter(readFileSync(join(docsAbsDir, 'index.md'), 'utf8'))
+    const existingType = existingFm.match(OKF_TYPE_RE)?.[1]?.trim() ?? ''
+    if (existingType !== 'Directory Index') return
+  }
+
+  const files = allMd.filter(f => f !== 'index.md')
+  if (files.length === 0) return
+
+  const sourceDirRel = relative(root, dirname(docsAbsDir)) || '.'
+
+  const rows = files.map(f => {
+    const md = readFileSync(join(docsAbsDir, f), 'utf8')
+    const fm = extractFrontmatter(md)
+    const resource = fm.match(OKF_RESOURCE_RE)?.[1]?.trim()
+    const title = fm.match(OKF_TITLE_RE)?.[1]?.trim() ?? (resource ? basename(resource) : f.replace(MD_SUFFIX_RE, ''))
+    const type = fm.match(OKF_TYPE_RE)?.[1]?.trim() ?? 'Source File'
+    return `| [${title}](${f}) | ${type} |`
+  })
+
+  // Без H1: frontmatter `title:` вже є top-level заголовком для MD025 (single-title) —
+  // H1 у тілі давав `MD025 Multiple top-level headings` на кожному згенерованому індексі.
+  const content = `---
+type: Directory Index
+title: ${sourceDirRel}
+resource: ${sourceDirRel}/
+---
+
+| Файл | Тип |
+|---|---|
+${rows.join('\n')}
+`
+  const indexPath = join(docsAbsDir, 'index.md')
+  writeFileSync(indexPath, content)
+  spawnSync('oxfmt', [indexPath], { stdio: 'ignore' })
+}
+
+/**
+ * Повідомлення про дострокову зупинку батчу: systemic-abort (середовище впало) або
+ * м'який дедлайн рунга fix-pipeline. В обох випадках зроблене лишилось на диску
+ * (свіжі CRC) — наступний прогін підбирає решту.
+ * @param {{ aborted: boolean, deadlineHit: boolean, done: number, total: number }} state стан зупинки
+ * @returns {void}
+ */
+function reportEarlyStop({ aborted, deadlineHit, done, total }) {
+  if (aborted) {
+    console.error(
+      `\n✗ doc-files: ${SYSTEMIC_ABORT_STREAK} systemic-збої підряд (omlx memory-guard / сервер) — abort на ${done}/${total}.\n  Звільни RAM або перезапусти omlx і повтори — зроблене лишилось, решта підбереться за CRC.`
+    )
+  }
+  if (deadlineHit) {
+    console.log(
+      `\n⏸ doc-files: м'який дедлайн рунга — зупинка на ${done}/${total}; зроблене лишилось (свіжі CRC), решту підбере наступний rung/прогін.`
+    )
+  }
+}
+
+/**
+ * Підсумковий звіт прогону у stdout.
+ * @param {{ ok: number, degraded: number, err: number, errors: string[], skipped: string[] }} stats статистика
+ * @returns {void}
+ */
+function reportStats(stats) {
+  console.log(
+    `\n${'─'.repeat(50)}\n✓ OK: ${stats.ok}  ⚠ degraded: ${stats.degraded}  ✗ Err: ${stats.err}  ⊘ Skip: ${stats.skipped.length}`
+  )
+  if (stats.errors.length > 0) {
+    console.log('Помилки:')
+    for (const e of stats.errors) console.log(`  - ${e}`)
+  }
+  if (stats.skipped.length > 0) {
+    console.log('Пропущено (permanent — завеликий контекст / модель відсутня):')
+    for (const e of stats.skipped) console.log(`  - ${e}`)
+  }
+  if (stats.degraded > 0) {
+    console.log('Degraded-доки автоматично доретраюються наступним `gen` (один раз на версію джерела).')
+  }
+}
+
+/**
+ * Видаляє сирітські доки (source-файл не існує) і оновлює/прибирає index.md.
+ * Якщо після видалення в docs/-директорії лишились тільки index.md або нічого — очищує її.
+ * @param {string} root абсолютний корінь
+ * @returns {number} кількість видалених doc-файлів
+ */
+export function purgeOrphanedDocs(root) {
+  const orphans = scanOrphanedDocs(root)
+  if (orphans.length === 0) return 0
+  let deleted = 0
+  const docsDirs = new Set()
+  for (const docRel of orphans) {
+    try {
+      unlinkSync(join(root, docRel))
+      docsDirs.add(dirname(join(root, docRel)))
+      deleted++
+    } catch {
+      // race condition або вже видалено — ігноруємо
+    }
+  }
+  for (const docsAbsDir of docsDirs) {
+    if (!existsSync(docsAbsDir)) continue
+    const remaining = readdirSync(docsAbsDir)
+    const docFiles = remaining.filter(f => f.endsWith('.md') && f !== 'index.md')
+    if (docFiles.length === 0) {
+      // Лише index.md або порожня директорія — прибираємо повністю
+      const indexPath = join(docsAbsDir, 'index.md')
+      if (existsSync(indexPath)) unlinkSync(indexPath)
+      try {
+        rmdirSync(docsAbsDir)
+      } catch {
+        /* не порожня — пропускаємо */
+      }
+    } else {
+      generateDirIndex(docsAbsDir, root)
+    }
+  }
+  return deleted
+}
+
+/**
+ * `doc-files gen` — згенерувати документацію для застарілих/відсутніх док.
+ * @param {string[]} argv аргументи після назви субкоманди
+ * @returns {Promise<number>} exit-код: 0 — без помилок; 1 — помилки/фейл preflight; 2 — systemic-abort
+ */
+export function runDocFilesGenCli(argv) {
+  const root = resolveRoot(argv)
+  const { from, limit, overwrite } = parseGenArgs(argv)
+
+  // Видаляємо orphan-доки до генерації (незалежно від наявності stale)
+  const deleted = purgeOrphanedDocs(root)
+  if (deleted > 0) {
+    console.log(`🗑 doc-files: видалено ${deleted} сирітських доки(ів)`)
+  }
+
+  const all = scanForDocFiles(root)
+  // Рукописні доки (docPath існує без docgen:-frontmatter) — чужі: без --overwrite не
+  // чіпаємо і попереджаємо, щоб перезапис людського змісту не пройшов мовчки.
+  const foreign = all.filter(f => f.foreign)
+  if (foreign.length > 0 && !overwrite) {
+    console.warn(
+      `⚠ doc-files: ${foreign.length} рукописна(их) дока(и) без docgen-frontmatter — пропускаю (перезапис лише з --overwrite):`
+    )
+    for (const f of foreign) console.warn(`  - ${f.docPath}`)
+  }
+  const targets = selectTargets(root, all, { overwrite }).slice(from, from + limit)
+
+  if (targets.length === 0) {
+    if (deleted === 0) {
+      console.log('✓ doc-files: усі файлові доки свіжі й не-degraded. Нічого генерувати.')
+    }
+    return 0
+  }
+
+  return runGenerationBatch(targets, root, {
+    headline: `📋 doc-files: до генерації ${targets.length} файл(ів)${modeSuffix({ overwrite })}`
+  })
+}
+
+/**
+ * Спільне ядро генерації: preflight локального бекенда → послідовний прогін
+ * `targets` через `generateOne` з circuit-breaker'ом (K systemic-збоїв підряд →
+ * abort) → підсумковий звіт. Перевикористовують і батч-CLI (`runDocFilesGenCli`),
+ * і opportunistic lint-крок doc-files (scoped-набір змінених файлів).
+ *
+ * `deadlineAt` (epoch ms): м'який дедлайн fix-pipeline — перед стартом КОЖНОГО
+ * наступного файлу (перший стартує завжди) батч звіряється з дедлайном і, коли час
+ * вийшов, завершується штатно з частковим прогресом. Зроблене записано по одному
+ * файлу (durable, свіжий CRC) — наступний прогін підбирає решту за CRC.
+ * @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)
+ * @returns {Promise<number>} 0 — без помилок; 1 — фейл preflight або є помилки; 2 — systemic-abort
+ */
+export async function runGenerationBatch(targets, root, opts = {}) {
+  const { headline } = opts
+  if (!opts.model && !DEFAULT_LOCAL_MODEL) {
+    console.error('✗ doc-files: локальну модель не задано (N_LOCAL_MIN_MODEL)')
+    return 1
+  }
+
+  if (headline) console.log(headline)
+  const stats = { ok: 0, degraded: 0, err: 0, errors: [], skipped: [] }
+
+  // ProgressReporter (канон scripts.mdc): бар по файлах лише в TTY; не-TTY лишає
+  // поточні append-рядки [done/total] без дубльованого ⏱-зведення.
+  const isTTY = process.stdout.isTTY === true
+  const reporter = isTTY
+    ? createProgressReporter({
+        total: targets.length,
+        log: s => process.stdout.write(s),
+        isTTY,
+        unitLabel: 'файлів',
+        withFixed: false
+      })
+    : null
+  const emit = reporter ? reporter.log : undefined
+
+  let done = 0
+  let systemicStreak = 0
+  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
+      })
+      reporter?.concernDone(file.sourcePath)
+      // Circuit-breaker: K systemic-збоїв підряд → негайний abort (середовище впало,
+      // решта файлів так само згорить). Будь-який не-systemic результат скидає лічильник.
+      if (status === 'systemic') {
+        if (++systemicStreak >= SYSTEMIC_ABORT_STREAK) {
+          aborted = true
+          break
+        }
+      } else {
+        systemicStreak = 0
+      }
+    }
+  } finally {
+    reporter?.stop()
+  }
+  reportEarlyStop({ aborted, deadlineHit, done, total: targets.length })
+
+  reportStats(stats)
+
+  // Оновлюємо index.md у кожній docs/-директорії, якої торкнувся цей батч
+  const docsDirs = new Set(targets.map(f => dirname(join(root, f.docPath))))
+  for (const docsAbsDir of docsDirs) {
+    if (existsSync(docsAbsDir)) generateDirIndex(docsAbsDir, root)
+  }
+
+  if (aborted) return 2
+  return stats.err > 0 ? 1 : 0
+}
+
+/**
+ * `doc-files stamp` — детерміновано (пере)штампувати frontmatter `source`+`crc`
+ * у НАЯВНИХ доках без виклику LLM. Для міграції док, які ще не мають CRC.
+ * Поля `model`, `tier` та якості (`score`/`issues`/`judgeModel`) при цьому зберігаються
+ * з наявного frontmatter.
+ * @param {string[]} argv аргументи після назви субкоманди
+ * @returns {number} exit-код: 0 — успіх
+ */
+export function runDocFilesStampCli(argv) {
+  const root = resolveRoot(argv)
+  let stamped = 0
+  for (const file of scanForDocFiles(root)) {
+    const docAbs = join(root, file.docPath)
+    if (!existsSync(docAbs)) continue
+    const sourceAbs = join(root, file.sourcePath)
+    const crc = crc32(readFileSync(sourceAbs))
+    const md = readFileSync(docAbs, 'utf8')
+    const { score, issues, judgeModel } = readDocQuality(docAbs)
+    const model = readDocModel(docAbs)
+    const tier = readDocTier(docAbs)
+    const quality = score === null ? null : { score, issues, ...(judgeModel && { judge: { model: judgeModel } }) }
+    writeFileSync(docAbs, stampDoc(md, file.sourcePath, crc, quality, model, tier))
+    stamped++
+  }
+  console.log(`✓ doc-files stamp: оновлено frontmatter у ${stamped} доці(ах).`)
+
+  // Після stamp — оновити index.md у всіх docs/-директоріях
+  const docsDirs = new Set(
+    scanForDocFiles(root)
+      .map(f => dirname(join(root, f.docPath)))
+      .filter(d => existsSync(d))
+  )
+  for (const docsAbsDir of docsDirs) generateDirIndex(docsAbsDir, root)
+
+  return 0
+}
+
+if (isRunAsCli(import.meta.url)) {
+  const [sub, ...rest] = process.argv.slice(2)
+  const argv = sub === 'gen' || sub === 'stamp' ? rest : process.argv.slice(2)
+  process.exitCode = sub === 'stamp' ? runDocFilesStampCli(argv) : await runDocFilesGenCli(argv)
+}

package/rules/doc-files/docgen-fix-worker/concern.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
+}

package/rules/doc-files/docgen-gen/concern.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json"
+}

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

@@ -0,0 +1,40 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/doc-files/docgen-gen/main.mjs
+docgen:
+  crc: bef08f19
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+---
+
+## Огляд
+
+Огляд
+Створює технічну документацію шляхом аналізу вихідного коду, генерації тексту, оцінки його якості та управління позиціонуванням захищеного блоку «Призначення» у фінальному документі. (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, щоб доретрай батчу підібрав файл.
+
+## Публічний API
+
+splitProtected — витягує тіло захищеної секції «Призначення» та повертає документ без неї.
+insertProtected — повертає захищений блок у фіксовану позицію одразу після заголовка документа.
+scoreDoc — детермінований скоринг документа (0 токенів) проти факт-листа: оцінка 0–100 і коди проблем.
+DEFAULT_LOCAL_MODEL — модель генерації за замовчуванням (env-конфігурована; без неї preflight фейлить гучно).
+generateDoc — головний вхід: джерело → md-дока з оцінкою якості, best-of-2 повтором і опційним семантичним суддею.
+
+## Гарантії поведінки
+
+- Кешує результати в межах одного прогону.