@7n/rules 1.0.0

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

@@ -0,0 +1,43 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/doc-files/docgen-judge/main.mjs
+docgen:
+  crc: ac56c24b
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+---
+
+## Огляд
+
+Огляд: Цей файл визначає інтерфейс для механізму семантичного судження якості згенерованої технічної документації за допомогою мовної моделі. Він конфігурує параметри (`JUDGE_MODEL`, `JUDGE_ENABLED`, `JUDGE_CONFIDENCE`) та надає read-only функції для ініціації судження та інтерпретації його результатів. Додатково містить детермінований пре-гейт `detectRefusalFiller` (0 токенів): курований список refusal/чат-філер фраз моделі («Я готовий писати…», «Надайте мені код…»), які структурний скорер і суддя пропускали (живий кейс: score=95 на доці з суцільним філером).
+
+Поведінка:
+JUDGE_MODEL — конфігурує LLM, яка використовується для семантичного судження якості документації.
+JUDGE_ENABLED — вказує, чи активовано семантичний гейт для перевірки точності документації.
+JUDGE_CONFIDENCE — встановлює мінімальний поріг впевненості, необхідний для визначення документації неточним (degraded).
+parseDocVerdict — аналізує та валідує структуру судження (вердикт, впевненість, причина) з сирого тексту відповіді моделі.
+judgeDoc — виконує семантичне судження згенерованої документації проти вмісту вихідного файлу через LLM.
+judgeFailsDoc — визначає, чи вважати документацію неякісною, якщо вердикт 'inaccurate' перевищує заданий поріг впевненості.
+
+## Поведінка
+
+JUDGE_MODEL — визначає модель, яка використовується для семантичного судження якості документації.
+JUDGE_ENABLED — вказує, чи активовано семантичний гейт для перевірки точності документації.
+JUDGE_CONFIDENCE — встановлює мінімальний рівень впевненості для визначення документації неточним (degraded).
+parseDocVerdict — витягує та валідує структуру судження (вердикт, впевненість, причина) із сирого тексту відповіді моделі.
+judgeDoc — виконує семантичне судження згенерованої документації, порівнюючи її з вмістом вихідного файлу за допомогою потужної LLM.
+judgeFailsDoc — визначає, чи слід вважати документацію неякісною, якщо вердикт був 'inaccurate' і його впевненість перевищує встановлений поріг.
+
+## Публічний API
+
+JUDGE_MODEL — Використовується модель-суддя із наймінімальнішим хмарним рівнем.
+JUDGE_ENABLED — Гейт для перевірки роботи судді вмикається автоматично, якщо вказана модель `N_CLOUD_MIN_MODEL`.
+JUDGE_CONFIDENCE — Мінімальний рівень впевненості, необхідний, щоб суддя визнав документ як знижений у якості (degraded), якщо вирок є неточним.
+parseDocVerdict — Отримує та перевіряє структуру JSON із висновком (verdict) з відповіді LLM.
+judgeDoc — Оцінює згенерований документ потужною моделлю, порівнюючи його з оригінальним джерелом.
+judgeFailsDoc — Визначає, чи має вирок від судді статус зниженого документа (degraded) на підставі неточності (`inaccurate`) та високої впевненості.
+detectRefusalFiller — Повертає першу знайдену refusal/філер-фразу в тексті доки (або null); використовується скорером генерації, щоб форсувати degraded незалежно від структурної оцінки й не викликати LLM-суддю на завідомо порожньому змісті.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,116 @@
+/** @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 { runOneShot } from '@7n/llm-lib/one-shot'
+import { CLOUD_MIN } from '@7n/llm-lib/model-tiers'
+
+/** Модель-суддя = `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'])
+
+/**
+ * Детермінований пре-гейт (0 токенів) ПЕРЕД LLM-суддею: чат-філер/refusal локальної
+ * моделі замість документації. Живий кейс: дока зі score=95, де секції — суцільне
+ * «Я готовий писати поведінкову документацію… Надайте мені код» (gemma) — судді
+ * структура здалась валідною. Курований безпечний список (перша особа/імператив до
+ * користувача не трапляються у нормальній поведінковій доці); без `\b` — кирилиця
+ * не ASCII-`\w`, JS-межі слова не спрацьовують.
+ */
+const REFUSAL_FILLER_RES = [
+  /я готов(?:ий|а)/iu,
+  /надайте(?:\s+мені)?\s+(?:код|файл|вміст|джерело)/iu,
+  /надішліть(?:\s+мені)?\s+(?:код|файл)/iu,
+  /будь ласка,?\s+надайте/iu,
+  /не можу\s+(?:згенерувати|створити|написати)/iu,
+  /чекаю на\s+(?:код|файл|вміст)/iu,
+  /давайте почнемо/iu,
+  /as an ai(?: language)? model/iu,
+  /i(?:['’]m| am)\s+(?:ready to|unable to)/iu,
+  /please provide(?: the| me)?\s+(?:code|file|source)/iu
+]
+
+/**
+ * Шукає у тексті доки refusal/filler-фразу моделі.
+ * @param {string} text машинні секції доки (без захищеного людського «Призначення»)
+ * @returns {string|null} перший збіг (для issue/діагностики) або null — фраз немає
+ */
+export function detectRefusalFiller(text) {
+  for (const re of REFUSAL_FILLER_RES) {
+    const m = text.match(re)
+    if (m) return m[0]
+  }
+  return null
+}
+
+/**
+ * Витягує й валідує 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 async function judgeDoc(src, doc, { model = JUDGE_MODEL, timeoutMs = 120_000, chain = null } = {}) {
+  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 res = await runOneShot({
+    messages: [
+      { role: 'system', content: JUDGE_SYSTEM },
+      { role: 'user', content: user }
+    ],
+    modelSpec: model,
+    timeoutMs,
+    caller: 'docgen-judge',
+    chain
+  })
+  if (res.error) throw new Error(res.error)
+  return parseDocVerdict(res.content)
+}
+
+/**
+ * Чи позначає 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/docgen-prompts/concern.json

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

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

@@ -0,0 +1,48 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/doc-files/docgen-prompts/main.mjs
+docgen:
+  crc: 3fbc97f2
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Будь ласка, надайте чорнетку секції «overview» для редагування.
+
+## Поведінка
+
+sectionMessages.main.mjs
+
+````
+Ти технічний письменник. Пишеш лаконічну ПОВЕДІНКОВУ документацію до коду українською, чистим Markdown.
+Пиши ЩО і НАВІЩО, не ЯК. Без вступів і висновків. Не обгортай у ```-блок.
+Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.
+
+Напиши вміст секції «Поведінка»: для кожної публічної функції — один короткий пункт «що вона робить». Описуй РІВНО ці публічні імена і жодних інших: STYLE, sectionMessages, overviewMessages, criticMessages, refineMessages, guaranteesFromMarkers, oneShotMessages. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex. НЕ згадуй за іменами службові функції: anchorsToPrompt. Без заголовка, без додаткових ## чи # підзаголовків усередині секції.
+````
+
+## Публічний API
+
+Згідно з інструкцією з `/Users/vitalii/www/nitra/cursor/AGENTS.md`, моя функція — генерувати лаконічну поведінкову документацію українською мовою в чистому Markdown для кожного зміненого/нового кодового файлу, у вигляді списку маркерів.
+
+Ви надаєте мені список термінів та просите перетворити його на стиль: `«назва — що робить»`, використовуючи власні слова, без копіювання дослівно, без типів і сигнатур.
+
+Ось переписаний список у заданому форматі:
+
+STYLE — Визначає загальний стиль та призначення файлу.
+sectionMessages — Групує повідомлення для секцій, забезпечуючи мінімальний контекст для кожної.
+overviewMessages — Підготує узагальнений огляд поведінки на основі вже написаної детальної поведінки.
+criticMessages — На етапі первинного аналізу тексту виявляє конкретні недоліки в чорноті для подальшого виправлення.
+refineMessages — Виправляє чорнетку, усуваючи виявлені критичні недоліки.
+guaranteesFromMarkers — Створює чіткий, детермінований перелік гарантій роботи, ґрунтуючись на фіксованих маркерних фактах.
+oneShotMessages — Слугує зразком для порівняння, що містить конкретні приклади, а не загальні описи дій.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

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

@@ -0,0 +1,222 @@
+/** @see ./docs/docgen-prompts.md */
+
+import { anchorsToPrompt } from '../docgen-extract-anchors/main.mjs'
+
+export const STYLE = [
+  'Ти технічний письменник. Пишеш лаконічну ПОВЕДІНКОВУ документацію до коду українською, чистим Markdown.',
+  'Пиши ЩО і НАВІЩО, не ЯК. Без вступів і висновків. Не обгортай у ```-блок.',
+  'Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.'
+].join(' ')
+
+/**
+ * Окремий блок інструкцій з анкорами — підставляється коли вони є.
+ * @param {object|null} anchors анкори файлу (або null)
+ * @returns {string} текстовий блок для system-промпта або порожній рядок
+ */
+function anchorsBlock(anchors) {
+  if (!anchors) return ''
+  const txt = anchorsToPrompt(anchors)
+  return txt ? `\n\n${txt}` : ''
+}
+
+/**
+ * Короткий людиночитний витяг фактів (без коду).
+ * @param {object} facts факт-лист про файл
+ * @returns {string} текстовий блок «factsTxt» для system-prompt
+ */
+function factsSummary(facts) {
+  const m = facts.markers || {}
+  const lines = []
+  if (facts.header) lines.push(`Намір файлу: ${facts.header.replaceAll('\n', ' ')}`)
+  if (facts.exports?.length) lines.push(`Публічні функції: ${facts.exports.map(e => e.name).join(', ')}`)
+  if (m.skips?.length) lines.push(`Свідомо пропускає шляхи: ${m.skips.join(', ')}`)
+  // «Фабрикація > мовчання»: лише ПОЗИТИВНІ high-confidence сигнали; жодних дефолтних
+  // негативів (read-only «ні», «мережа: немає») — модель echo-їть їх як хибну гарантію.
+  if (m.readOnly) lines.push('Read-only: не пише (ФС/БД)')
+  if (m.network) lines.push('Звертається до мережі')
+  if (m.catchesErrors) lines.push('Перехоплює помилки (fail-safe), не кидає винятків назовні')
+  if (m.returnsFalsyOnFail) lines.push('За певних помилок повертає порожнє значення (напр. null) замість винятку')
+  lines.push(m.caches ? 'Кешування: так, у межах прогону' : 'Кешування: НЕМАЄ — не згадуй кеш у гарантіях')
+  return lines.join('\n')
+}
+
+/**
+ * Пара system+user messages для одного виклику.
+ * @param {string} system system-промпт
+ * @param {string} user user-промпт
+ * @returns {Array<{role:string, content:string}>} messages-масив
+ */
+const msgs = (system, user) => [
+  { role: 'system', content: system },
+  { role: 'user', content: user }
+]
+
+/**
+ * Блок read-only авторитетного контексту із захищеної секції «Призначення»
+ * (Варіант B): машинні секції мають узгоджуватися з ним і НЕ дублювати його.
+ * @param {string|null} intent тіло секції «Призначення» або null
+ * @returns {string} текстовий блок для system-промпта або порожній рядок
+ */
+function intentContext(intent) {
+  if (!intent) return ''
+  return `\n\nАВТОРИТЕТНИЙ КОНТЕКСТ (секція «Призначення», написана людиною — НЕ повторюй дослівно, узгоджуйся й доповнюй):\n${intent}`
+}
+
+/**
+ * Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
+ * Код потрапляє лише в `behavior`; «Огляд» генерується окремо ОСТАННІМ
+ * (`overviewMessages`) з уже написаної Поведінки — тут його немає.
+ * @param {object} facts факт-лист про файл
+ * @param {string} src вміст файлу
+ * @param {object|null} [anchors] анкори файлу для обовʼязкового включення
+ * @param {string|null} [intent] захищена секція «Призначення» як read-only контекст
+ * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів (behavior[, api])
+ */
+export function sectionMessages(facts, src, anchors = null, intent = null) {
+  const factsTxt = factsSummary(facts)
+  const anch = anchorsBlock(anchors)
+  const intentCtx = intentContext(intent)
+  const multi = (facts.exports?.length || 0) > 1
+
+  // R6: Поведінка описує РІВНО експортовані імена, не службові помічники
+  const exportNames = (facts.exports ?? []).map(e => e.name)
+  const behaviorTask = multi
+    ? 'для кожної публічної функції — один короткий пункт «що вона робить»'
+    : 'нумерований алгоритм у бізнес-термінах'
+  const onlyExports = exportNames.length
+    ? ` Описуй РІВНО ці публічні імена і жодних інших: ${exportNames.join(', ')}.`
+    : ''
+  const noInternal = facts.internalSymbols?.length
+    ? ` НЕ згадуй за іменами службові функції: ${facts.internalSymbols.join(', ')}.`
+    : ''
+  const behavior = {
+    key: 'behavior',
+    numPredict: 500,
+    messages: msgs(
+      `${STYLE}\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\`\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}${intentCtx}`,
+      `Напиши вміст секції «Поведінка»: ${behaviorTask}.${onlyExports} Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex.${noInternal} Без заголовка, без додаткових ## чи # підзаголовків усередині секції.`
+    )
+  }
+
+  // API — лише список експортів (без коду)
+  if (!multi && !facts.exports?.some(e => e.desc)) return [behavior]
+  const list = facts.exports.map(e => `- ${e.name}: ${e.desc || '(сформулюй стисло з наміру файлу)'}`).join('\n')
+  const api = {
+    key: 'api',
+    numPredict: 320,
+    messages: msgs(
+      `${STYLE}${anch}`,
+      `Перепиши цей список як стислі маркери «назва — що робить», СВОЇМИ словами (не копіюй дослівно), без типів і сигнатур. Використовуй РІВНО ці назви, не додавай і не прибирай:\n${list}\nБез заголовка. Без generic-фраз «застосовує логіку», «перевіряє коректність» — пиши конкретно ЩО саме застосовує/перевіряє.`
+    )
+  }
+  return [behavior, api]
+}
+
+/**
+ * R3 — «Огляд» ОСТАННІМ: узагальнення вже написаної Поведінки, а не здогад із
+ * голого факт-листа. Лікує generic/хибний Огляд на складних файлах.
+ * @param {object} facts факт-лист про файл
+ * @param {string} behaviorText готовий текст секції «Поведінка»
+ * @param {object|null} [anchors] анкори файлу
+ * @param {string|null} [intent] захищена секція «Призначення» як read-only контекст
+ * @returns {Array<{role:string,content:string}>} messages-масив для Огляду
+ */
+export function overviewMessages(facts, behaviorText, anchors = null, intent = null) {
+  const factsTxt = factsSummary(facts)
+  const anch = anchorsBlock(anchors)
+  const dedup = intent ? ' Не дублюй секцію «Призначення».' : ''
+  return msgs(
+    `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsTxt}${anch}${intentContext(intent)}`,
+    `На основі вже написаної секції «Поведінка» (нижче) напиши «Огляд»: 1-3 речення — що файл робить і навіщо існує (роль у системі). Узагальнюй САМЕ описану поведінку, не додавай нових фактів. Без заголовка, без переліку функцій. Заборонені абстрактні формули без конкретики («перевірка/валідація/обробка даних», «відповідність контракту», «застосовує логіку») — пиши, ЩО саме і за яким контрактом.${dedup}\n\nПОВЕДІНКА:\n${behaviorText}`
+  )
+}
+
+/**
+ * E2-step 1 — критик. Перевіряє чорнетку секції на конкретні дефекти.
+ * Повертає messages для LLM-запиту: вихід має бути СПИСКОМ issues або словом NONE.
+ * @param {'overview'|'behavior'|'api'} sectionKey ключ секції
+ * @param {string} draft вже згенерована чорнетка секції
+ * @param {object} facts факт-лист
+ * @param {ReturnType<import('../docgen-extract-anchors/main.mjs').extractAnchors>} anchors анкори файлу
+ * @returns {Array<{role:string,content:string}>} messages-масив для критика
+ */
+export function criticMessages(sectionKey, draft, facts, anchors) {
+  const anch = anchorsBlock(anchors)
+  const criteria = [
+    'generic-фрази без конкретики («забезпечує перевірку», «виконує валідацію», «застосовує логіку»)',
+    "пропущені обов'язкові АНКОРИ з контексту (URLs, magic-string constants, error-маркери, конфіги, code-приклади)",
+    'граматичні помилки українською («перед їх застосування», «моделіне», англіцизми як «applys», «moduleline»)',
+    'h1/h2/h3 підзаголовки всередині секції — їх не повинно бути',
+    'дослівна копія JSDoc-сигнатури або параметрів у дужках',
+    'вигадані факти, відсутні у ВІДОМИХ ФАКТАХ і АНКОРАХ'
+  ].join('\n  - ')
+  return [
+    {
+      role: 'system',
+      content: `Ти жорсткий редактор технічної документації українською. Знаходиш конкретні дефекти у чорнетці. ВІДОМІ ФАКТИ:\n${factsSummary(facts)}${anch}`
+    },
+    {
+      role: 'user',
+      content: `Перевір цю чорнетку секції «${sectionKey}» за критеріями:\n  - ${criteria}\n\nЧЕРНЕТКА:\n${draft}\n\nВідповідь — короткий нумерований список знайдених issues (1-5 пунктів). Якщо дефектів немає — поверни одне слово: NONE.`
+    }
+  ]
+}
+
+/**
+ * E2-step 2 — refine. Переписує чорнетку, виправляючи перелічені issues.
+ * @param {'overview'|'behavior'|'api'} sectionKey ключ секції
+ * @param {string} draft чорнетка секції
+ * @param {string} issues список issues від critic
+ * @param {object} facts факт-лист
+ * @param {ReturnType<import('../docgen-extract-anchors/main.mjs').extractAnchors>} anchors анкори файлу
+ * @returns {Array<{role:string,content:string}>} messages-масив для переписування
+ */
+export function refineMessages(sectionKey, draft, issues, facts, anchors) {
+  const anch = anchorsBlock(anchors)
+  return [
+    {
+      role: 'system',
+      content: `${STYLE}\n\nВІДОМІ ФАКТИ:\n${factsSummary(facts)}${anch}`
+    },
+    {
+      role: 'user',
+      content: `Перепиши чорнетку секції «${sectionKey}», прибравши перелічені issues. Збережи мову (українська) і формат (без додаткових ## підзаголовків, без обгортки \`\`\`). Якщо issues вимагають включення АНКОРІВ — додай їх дослівно.\n\nЧЕРНЕТКА:\n${draft}\n\nISSUES ВІД РЕДАКТОРА:\n${issues}\n\nПоверни ЛИШЕ оновлений текст секції без преамбули.`
+    }
+  ]
+}
+
+/**
+ * E3 — детермінований шаблон секції «Гарантії поведінки» з facts.markers.
+ * НЕ використовує LLM: 0 запитів, 0 галюцинацій, 0 generic-фраз.
+ * @param {object} facts факт-лист
+ * @returns {string} текст секції (без `## Гарантії` — це додає assemble())
+ */
+export function guaranteesFromMarkers(facts) {
+  const m = facts.markers || {}
+  const lines = []
+  // «Фабрикація > мовчання»: лише ПОЗИТИВНІ high-confidence гарантії. Жодних
+  // негативів/дефолтів (no-network, determinism) — їх не довести file-local аналізом.
+  if (m.readOnly) lines.push('- Read-only: не виконує операцій запису (ФС/БД).')
+  if (m.catchesErrors) lines.push('- Перехоплює помилки і не пропускає винятків назовні (fail-safe).')
+  if (m.returnsFalsyOnFail) lines.push('- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.')
+  if (m.caches) lines.push('- Кешує результати в межах одного прогону.')
+  if (m.skips?.length) {
+    lines.push(`- Свідомо пропускає шляхи: ${m.skips.map(s => '`' + s + '`').join(', ')}.`)
+  }
+  if (!lines.length) return '- (специфічних машинно-виведених гарантій немає)'
+  return lines.join('\n')
+}
+
+/**
+ * One-shot messages (база для порівняння).
+ * @param {object} facts факт-лист про файл
+ * @param {string} src вміст файлу
+ * @returns {Array<object>} messages-масив для LLM API
+ */
+export function oneShotMessages(facts, src) {
+  const multi = (facts.exports?.length || 0) > 1
+  return msgs(
+    STYLE,
+    `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``
+  )
+}

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

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

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

@@ -0,0 +1,52 @@
+---
+type: JS Module
+title: main.mjs
+resource: npm/rules/doc-files/docgen-scan/main.mjs
+docgen:
+  crc: 23cec34d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.99
+---
+
+## Огляд
+
+Модуль визначає, які файли є джерелами та обчислює відповідні шляхи для їхньої документації. Він сканує систему на наявність ізольованих або застарілих документів і надає засоби для ініціалізації сканування та перевірки якості існуючих документів.
+
+## Поведінка
+
+isSourceFile визначає, чи є ім'я файлу кодовим джерелом для генерації документації, виключаючи файли тестів і файли декларацій типів.
+docPathForSource обчислює очікуваний шлях до markdown-документа для заданого кодового джерельного шляху, розміщуючи його у теці `docs` поруч із джерелом.
+isDocCandidate визначає, чи повинен файл підлягати документуванню, перевіряючи його тип, статус тесту, статус ігнорування та чи не є він частиною системних документації.
+describeFile описує кодовий файл, надаючи шлях джерела та шлях до відповідного документа, а також статус його застарілості за CRC. Якщо док-файл існує, але без `docgen:`-CRC у frontmatter (рукописна дока), файл позначається `foreign: true` і НЕ вважається застарілим — людський зміст рахується чинною документацією і мовчки не перезаписується (перезапис лише explicit `--overwrite` у batch-CLI).
+scanOrphanedDocs знаходить markdown-документи, які мають метадані про джерело, але відповідний код-файл більше не існує.
+scanForDocFiles обходить дерево від кореня і повертає список всіх кодових файлів, для яких може бути згенерована документація, з інформацією про їхній статус застарілості, виключаючи ті, що ігноруються через Git.
+resolveRoot визначає абсолютний кореневий каталог для сканування, беручи його з аргументів або використовуючи поточний робочий каталог.
+runDocFilesScanCli сканує вказане дерево та виводить у форматі JSON список усіх кодових файлів з їхнім статусом застарілості.
+runDocFilesCheckCli виконує перевірку на застарілість документації: може перевіряти один файл із stdin, групу змінених файлів через `git diff`, або звітувати про неякісні документи, блокуючи процес при знаходженні застарілого коду.
+
+## Публічний API
+
+isSourceFile — визначає, чи є файл кодовим джерелом, що підлягає документуванню.
+docPathForSource — розраховує шлях до відповідного Markdown-документа, розміщуючи його в теці `docs/` поруч із кодом.
+isDocCandidate — вирішує, чи повинен файл підлягати документуванню: перевіряє розширення, виключення тестів, ігнорованих файлів та системних кореневих доків.
+describeFile — створює опис одного кодового файлу, включаючи його розташування, шлях доки, статус застарілості за CRC та ознаку `foreign` (рукописна дока без docgen-frontmatter — не ціль генерації).
+scanOrphanedDocs — шукає Markdown-документи, у яких вказано неіснуючий кодовий файл через `resource:` та `docgen.crc` у метаданих.
+scanForDocFiles — рекурсивно збирає всі кодові файли з дерева, повертаючи їх разом із статусом застарілості, фільтруючи за допомогою `git check-ignore`.
+resolveRoot — визначає корінь проекту для сканування, використовуючи аргумент `--root` або поточний робочий каталог.
+runDocFilesScanCli — сканує дерево та виводить у форматі JSON список усіх кодових файлів зі статусом застарілості.
+runDocFilesCheckCli — виконує перевірку на застарілість доків для хуків та CLI-інструментів.
+
+Режими роботи:
+--hook — перевіряє один файл, отриманий із вхідних даних, у контексті хука після використання інструменту.
+--git — порівнює з поточним станом Git, блокуючи процес, якщо знайдено застарілі доки, перевищуючи встановлений поріг.
+--degraded — виводить інформаційний звіт про доки, які не відповідають встановленому порогу.
+<paths...> — обробляє перелічені користувачем шляхи як джерела для документування.
+
+Вихідний код (Exit 2) — вказує на знаходження застарілих доків (блокування хука); вихідний код (Exit 0) — вказує на відсутність проблем або успішне проходження понад встановлений поріг.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.