@7n/rules 1.49.26 → 1.50.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [1.50.0] - 2026-07-27
+
+### Added
+
+- doc-files без LLM рендерить test-сценарії та повністю прокоментовані JS, Rust і Python файли, а для коротких comments додає лише відсутню «Поведінку»
+
+### Fixed
+
+- Прискорено k8s full lint і додано live статус черги
+
 ## [1.49.26] - 2026-07-27
 
 ### Fixed

package/package.json

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

package/rules/doc-files/check/docs/index.md

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

package/rules/doc-files/check/docs/main.md

@@ -3,7 +3,7 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/check/main.mjs
 docgen:
-  crc: b5921123
+  crc: d13133e6
 ---
 
 ## Огляд
@@ -16,6 +16,8 @@ Lint-детектор doc-files: знаходить застарілі файл
 
 Реверс-мапінг: якщо серед змінених файлів трапляється сама `.md`-дока (а не її джерело), `sourceForDoc` шукає відповідний вихідний файл поруч (той самий basename, легальне розширення) і саме його передає далі в перевірку застарілості — так зміна доки теж тригерить звірку CRC її джерела.
 
+Якщо змінено test/spec-файл, `sourceFilesForTest` через спільний source↔tests index знаходить лише пов’язані source-файли. Їхня документація також перевіряється на застарілість, тому зміна підтвердженого usage-сценарію не лишає docs зі старим CRC.
+
 Якщо мапа doc-files-розширень від активних плагінів порожня, а хоча б один плагін явно задекларований у `.n-rules.json`, але не встановлений у `node_modules` — детектор додає `diagnostics`-запис (`level: 'warn'`) з підказкою запустити `bun install`. Це відрізняє "плагін не встановлено" від "усі доки актуальні": без нього обидва випадки виглядають як 0 порушень.
 
 ## Публічний API
@@ -25,5 +27,5 @@ Lint-детектор doc-files: знаходить застарілі файл
 ## Гарантії поведінки
 
 - Read-only: не пише і не видаляє жодних файлів.
-- Перехоплює помилки читання файлової системи (напр. нечитабельна тека) — не пропускає винятків назовні.
+- Містить локальні fail-safe гілки для недоступних тек; інші помилки можуть поширюватися назовні.
 - Diagnostics-попередження про невстановлений плагін рендериться лише при `--verbose` на explicit CLI-виклику (`lint doc-files --no-fix --verbose`) — у PostToolUse-хуку (без `verbose`) обчислюється, але ніколи не друкується.

package/rules/doc-files/check/main.mjs

@@ -1,11 +1,12 @@
 /**
  * lint-поверхня doc-files: детект застарілих файлових документацій (per-file, з reverse-mapом).
  */
-import { join, dirname, basename, extname } from 'node:path'
+import { join, dirname, basename, extname, relative } from 'node:path'
 import { existsSync, readdirSync } from 'node:fs'
 
 import { describeFile, isDocCandidate, isSourceFile, scanForDocFiles, scanOrphanedDocs } from '../docgen-scan/main.mjs'
 import { unavailableDocFilesPlugins } from '../docgen-scan/lang-extensions.mjs'
+import { buildTestEvidenceIndex, isDocgenTestFile, sourceFilesForTest } from '../docgen-test-context/main.mjs'
 
 const DOC_MD_RE = /(?:^|\/)docs\/[^/]+\.md$/u
 
@@ -38,15 +39,21 @@ function sourceForDoc(cwd, docRel) {
  * Зводить перелік змінених файлів до множини вихідних кодових файлів.
  * @param {string[]} files змінені шляхи (джерела або .md-доки)
  * @param {string} cwd робочий каталог
+ * @param {ReturnType<typeof buildTestEvidenceIndex>} testIndex source↔tests index
  * @returns {string[]} відносні шляхи джерел
  */
-function sourcesFromChanged(files, cwd) {
+function sourcesFromChanged(files, cwd, testIndex) {
   const out = new Set()
   for (const raw of files) {
     const rel = raw.split('\\').join('/')
     if (DOC_MD_RE.test(rel)) {
       const src = sourceForDoc(cwd, rel)
       if (src) out.add(src)
+    } else if (isDocgenTestFile(basename(rel))) {
+      for (const sourceAbs of sourceFilesForTest(join(cwd, rel), testIndex)) {
+        const sourceRel = relative(cwd, sourceAbs).split('\\').join('/')
+        if (isDocCandidate(cwd, sourceRel)) out.add(sourceRel)
+      }
     } else if (isDocCandidate(cwd, rel) && existsSync(join(cwd, rel))) {
       out.add(rel)
     }
@@ -61,8 +68,9 @@ function sourcesFromChanged(files, cwd) {
  */
 export function collectStale(files, cwd) {
   if (files === undefined) return scanForDocFiles(cwd).filter(f => f.stale)
-  const sources = sourcesFromChanged(files, cwd)
-  return sources.map(src => describeFile(cwd, src)).filter(f => f.stale)
+  const testIndex = buildTestEvidenceIndex(cwd)
+  const sources = sourcesFromChanged(files, cwd, testIndex)
+  return sources.map(src => describeFile(cwd, src, testIndex)).filter(f => f.stale)
 }
 
 /**

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

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

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

@@ -3,44 +3,65 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-crc/main.mjs
 docgen:
-  crc: 8976f6f8
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: fdddffc3
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
   score: 100
-  issues: judge:inaccurate:0.99
+  issues: judge:error
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Модуль забезпечує керування якістю, метаданими та актуальністю документації. Він дозволяє встановлювати мінімальний поріг якості за допомогою `QUALITY_THRESHOLD`, обчислювати та зчитувати контрольні суми (CRC32) за допомогою `crc32` та `readDocCrc`, а також парсити та генерувати метадані документації за допомогою `parseDocFrontmatter` та `buildDocFrontmatter`.
+`crc32` обчислює детермінований 8-символьний hex CRC для рядка або Buffer; `documentationCrc` і `parseDocFrontmatter` зв’язують вміст документа з його frontmatter. `buildDocFrontmatter` і `stampDoc` записують fresh metadata для `CRC`, `model`, `tier` та `quality`, причому `stampDoc` ще й керує маркером `degraded`. `readDocCrc`, `readDocModel`, `readDocTier` і `readDocQuality` відновлюють ці значення з доки, а `QUALITY_THRESHOLD` задає дефолтний поріг 70. `staleness` порівнює source і doc, щоб відрізняти `missing`, `crc-mismatch` і `fresh`.
 
 ## Поведінка
 
-Поведінка:
-QUALITY_THRESHOLD — Встановлює поріг якості документації, нижче якого доки вважаються неякісними.
-crc32 — Обчислює та повертає CRC32 вмісту у вигляді 8-символьного шестнадцяткового рядка.
-parseDocFrontmatter — Розбирає вміст markdown-файлу, виділяючи метадані з блоку frontmatter та повертаючи тіло документа.
-buildDocFrontmatter — Формує YAML-блок frontmatter, сумісний з OKF, для посилання на джерело та його метаданих.
-stampDoc — Генерує повний markdown-документ, вставляючи новостворений frontmatter у тіло документа.
-readDocCrc — Зчитує та повертає CRC32, збережений у frontmatter markdown-документа.
-readDocQuality — Зчитує зі frontmatter markdown-документа оцінку якості та пов'язані з нею помилки.
-readDocModel — Зчитує зі frontmatter markdown-документа ідентифікатор моделі, яка створила документ.
-readDocTier — Зчитує зі frontmatter markdown-документа рівень моделі-генератора.
-staleness — Визначає, чи застарілий markdown-документ порівняно з його вихідним джерелом за допомогою CRC32.
+QUALITY_THRESHOLD задає дефолтний поріг оцінки якості для читання й маркування доки; у перевірених сценаріях цей поріг дорівнює 70.
+
+crc32 дає детермінований 8-символьний hex для рядка або Buffer; однаковий вміст завжди дає той самий CRC, а різний — інший; відомий вектор `123456789` зводиться до `cbf43926`.
+
+documentationCrc обчислює CRC для поведінкової документації не лише з джерела, а й з пов’язаного evidence тестів, якщо він є; без пов’язаних тестів лишається сумісним із CRC самого source, тож зміна лише сценарію використання робить доку застарілою.
+
+parseDocFrontmatter відокремлює frontmatter від тіла доки й повертає нормалізовані метадані; якщо frontmatter немає, тіло лишається без змін, а метадані відсутні; старі доки без частини полів читаються як сумісні: відсутні `model`, `tier`, `score`, `issues` та `judgeModel` стають порожніми значеннями.
+
+buildDocFrontmatter формує frontmatter так, щоб спочатку були OKF-поля джерела, а потім вкладений блок якості та генератора; `model` і `tier` додаються лише коли вони є, а `issues` скорочуються до YAML-безпечних кодів і мають обмеження на кількість; quality може співіснувати з model, причому score та issues зберігаються й читаються назад без втрат.
+
+stampDoc переоформлює існуючу MD-доку: знімає старий frontmatter і додає свіжий, не змінюючи тіло; коли quality є, у frontmatter лишається degraded-сигнал разом із score/issues, а коли quality зникає — цей стан теж знімається; `model` переноситься у новий frontmatter разом із рештою актуальних метаданих.
+
+readDocCrc повертає CRC, уже записаний у frontmatter; якщо доки немає або CRC не зафіксований, результат `null`.
+
+readDocQuality читає збережену оцінку доки; за відсутності доки або score повертає `score: null`, порожній список issues і `judgeModel: null`; коли якість записана, значення відновлюються назад без втрат.
+
+readDocModel повертає збережену модель генератора або `null`, якщо доки немає чи поле не записане.
+
+readDocTier повертає tier моделі генератора або `null`, якщо доки немає чи поле не записане.
+
+staleness порівнює evidence source з CRC, записаним у відповідній доці: коли доки немає, стан `missing`; коли CRC не збігається, `crc-mismatch`; при збігу дока свіжа; для пов’язаних тестів у evidence враховується й їхній вплив на CRC доки, тому зміна сценарію використання може зробити документацію stale навіть без зміни source.
 
 ## Публічний API
 
-QUALITY_THRESHOLD — визначає нижню межу якості документа; оцінки нижче цієї межі вважаються неякісними.
-crc32 — генерує хеш вмісту документа у 8-символьтному hex-форматі, використовуючи нативний модуль `node:zlib.crc32`.
-parseDocFrontmatter — витягує метадані з початку документа. Якщо метаданих немає, повертає порожні дані та вхідний текст.
-buildDocFrontmatter — створює блок метаданих, сумісний зі стандартом OKF. Він містить основні поля OKF та вкладений блок `docgen:` з інформацією про CRC, модель та якість.
-stampDoc — додає інформацію про створення або оновлення документа (наприклад, CRC та метки) до самого вмісту.
-readDocCrc — зчитує хеш документа з метаданих. Повертає `null`, якщо метадані відсутні або хеш не знайдено.
-readDocQuality — зчитує оцінку якості документа з його метаданих.
-readDocModel — зчитує назву моделі, яка генерувала документ, із метаданих. Повертає `null`, якщо це поле не визначено.
-readDocTier — зчитує рівень (tier) моделі-генератора з метаданих. Повертає `null`, якщо поле відсутнє.
-staleness — визначає, чи є документ актуальним порівняно з його джерелом. Позначає як `missing` (якщо документа немає), `crc-mismatch` (якщо хеш у документа не збігається з хешем джерела) або "свіжий" (інакше).
+- QUALITY_THRESHOLD — Поріг degraded: дока зі `score` нижче вважається неякісною.
+- crc32 — CRC32 вмісту у hex (8 символів, з провідними нулями). Делегує у нативний
+`node:zlib.crc32` — без ручної бітової арифметики.
+- documentationCrc — CRC повного evidence для файлової доки. Без повʼязаних тестів лишається
+back-compatible CRC самого source; за наявності тестів додає їхні шляхи та
+вміст, тому зміна usage-сценарію детерміновано робить доку stale.
+- parseDocFrontmatter — Парсить frontmatter файлової доки. Без блоку — `data:null` і `body` дорівнює входу.
+Поля `model`/`score`/`issues` опційні (back-compat зі старими доками): без них —
+`model:null`, `score:null`, `issues:[]`.
+- buildDocFrontmatter — Будує OKF-сумісний frontmatter-блок: OKF-поля верхнього рівня + вкладений `docgen:`
+з CRC/model/quality. OKF-поля виводяться першими, щоб будь-який OKF-парсер міг їх
+читати незалежно від `docgen:`-простору назв.
+- stampDoc — (Пере)штампує frontmatter у md-доку: знімає наявний блок і додає свіжий.
+- readDocCrc — CRC, збережений у frontmatter доки; `null` — доки немає або CRC відсутній.
+- readDocQuality — Якість, збережена у frontmatter доки.
+- readDocModel — Модель-генератор, збережена у frontmatter доки; `null` — доки немає або поле відсутнє
+(старі доки до введення `model`).
+- readDocTier — Tier моделі-генератора зі frontmatter доки; `null` — доки немає або поле відсутнє.
+- staleness — Стан застарілості доки відносно evidence: source + повʼязані тести.
+`missing` — доки немає; `crc-mismatch` — evidence CRC ≠ CRC у доці; інакше свіжа.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

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

@@ -4,6 +4,7 @@ import { basename, extname } from 'node:path'
 import { crc32 as zlibCrc32 } from 'node:zlib'
 import { env } from 'node:process'
 import { pluginDocFilesExtensions } from '../docgen-scan/lang-extensions.mjs'
+import { testEvidenceForSource } from '../docgen-test-context/main.mjs'
 
 /** Поріг degraded: дока зі `score` нижче вважається неякісною. */
 export const QUALITY_THRESHOLD = Number(env.N_CURSOR_DOC_FILES_THRESHOLD ?? 70) || 70
@@ -19,6 +20,21 @@ export function crc32(input) {
   return zlibCrc32(buf).toString(16).padStart(8, '0')
 }
 
+/**
+ * CRC повного evidence для файлової доки. Без повʼязаних тестів лишається
+ * back-compatible CRC самого source; за наявності тестів додає їхні шляхи та
+ * вміст, тому зміна usage-сценарію детерміновано робить доку stale.
+ * @param {string} sourceAbsPath абсолютний шлях source-файлу
+ * @param {ReturnType<import('../docgen-test-context/main.mjs').buildTestEvidenceIndex>|null} [testIndex] source↔tests index
+ * @returns {string} CRC32 source + повʼязаних тестів
+ */
+export function documentationCrc(sourceAbsPath, testIndex = null) {
+  const source = readFileSync(sourceAbsPath)
+  if (!testIndex) return crc32(source)
+  const { crcPayload } = testEvidenceForSource(sourceAbsPath, testIndex)
+  return crc32(crcPayload ? Buffer.concat([source, Buffer.from(crcPayload, 'utf8')]) : source)
+}
+
 /** Провідний YAML-frontmatter-блок `---\n…\n---`. */
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/u
 const RESOURCE_RE = /^resource:[ \t]+(\S.*)$/mu
@@ -186,16 +202,17 @@ export function readDocTier(docAbsPath) {
 }
 
 /**
- * Стан застарілості доки відносно її джерела.
- * `missing` — доки немає; `crc-mismatch` — CRC джерела ≠ CRC у доці; інакше свіжа.
+ * Стан застарілості доки відносно evidence: source + повʼязані тести.
+ * `missing` — доки немає; `crc-mismatch` — evidence CRC ≠ CRC у доці; інакше свіжа.
  * @param {string} sourceAbsPath абсолютний шлях джерела
  * @param {string} docAbsPath абсолютний шлях md-доки
+ * @param {ReturnType<import('../docgen-test-context/main.mjs').buildTestEvidenceIndex>|null} [testIndex] source↔tests index
  * @returns {{ stale: boolean, reason: 'missing'|'crc-mismatch'|null }} стан застарілості
  */
-export function staleness(sourceAbsPath, docAbsPath) {
+export function staleness(sourceAbsPath, docAbsPath, testIndex = null) {
   const docCrc = readDocCrc(docAbsPath)
   if (docCrc === null) return { stale: true, reason: 'missing' }
-  const srcCrc = crc32(readFileSync(sourceAbsPath))
+  const srcCrc = documentationCrc(sourceAbsPath, testIndex)
   if (srcCrc !== docCrc) return { stale: true, reason: 'crc-mismatch' }
   return { stale: false, reason: null }
 }

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

@@ -3,33 +3,33 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-files-batch/main.mjs
 docgen:
-  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
+  crc: 309bc059
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 75
+  issues: internal-name:generateOne,internal-name:runBatchPass,anchor-miss:http://127.0.0.1:8000/v1/,judge-refine:kept-original,judge:inaccurate:0.99
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Файл керує життєвим циклом поведінкової документації для source-файлів: `selectTargets` визначає цілі, `runGenerationBatch` оновлює docs-файли, `purgeOrphanedDocs` прибирає сирітські документи, а `generateDirIndex` підтримує індекси директорій. `nativeBatchAvailable`, `runDocFilesGenCli` і `runDocFilesStampCli` забезпечують безпечний контур CLI/batch-прогонів із кешуванням у межах одного запуску.
-
-Модуль звертається до мережі, але працює fail-safe: перехоплює помилки, не кидає винятків назовні і дає прогону завершитися контрольовано.
+Визначає цілі для оновлення, генерує й синхронізує docs/ з кодом, оновлює directory index і прибирає orphaned docs, які більше не прив’язані до актуальних джерел. Працює як fail-safe: мережеві звернення не виносять винятки назовні, а результати прогону кешуються в межах одного запуску.
 
 ## Поведінка
 
-runDocFilesGenCli запускає повний прогін документації: прибирає сирітські файли через purgeOrphanedDocs, обирає актуальні цілі через selectTargets і передає їх у runGenerationBatch. Результати записуються у відповідні docs-файли, а після проходу оновлюються директорійні індекси через generateDirIndex.
+Генерація документації стартує з виявлення цілей через selectTargets: у звичайному режимі беруться застарілі або degraded-доки, які ще не отримували повторної спроби для поточної версії джерела; у режимі overwrite обробляються всі. Це робить прогін сходинковим: після невдалої спроби degraded-док більше не чіпається, доки не зміниться джерело, а новий CRC автоматично повертає його в потік.
+
+runDocFilesGenCli збирає підсумковий сценарій: спершу прибирає сирітські доки, потім запускає генерацію для відібраних цілей, а в кінці оновлює індекс директорії. Якщо прогін зупиняється достроково або через помилки, зроблене лишається на диску з актуальними CRC, тому наступний запуск підхоплює тільки пропущене.
 
-selectTargets підтримує збіжний режим роботи: за замовчуванням бере відсутні, застарілі або degraded-документи, але не ганяє безкінечно ті самі degraded-версії без зміни джерела. Режим перезапису переводить вибір у повну регенерацію всіх знайдених цілей.
+runGenerationBatch є спільним ядром усієї генерації. Воно бере відібрані цілі, робить preflight для локального бекенда і далі вибирає між послідовним шляхом та batch-шляхом. Якщо доступний native batch-аддон і немає м’якого дедлайну, весь набір іде одним submitBatch, і результати розкладаються назад по файлах. Якщо batch-режим недоступний або примусово вимкнений, обробка йде по одному файлу з fail-safe обробкою помилок та circuit-breaker для системних збоїв підряд. М’який дедлайн підтримується лише на послідовному шляху: перший файл завжди стартує, а наступні зупиняються, коли час вичерпано. Усі стани та лічильники накопичуються в спільній статистиці, а вихідний код відображає лише підсумок прогону.
 
-runGenerationBatch є спільним ядром для CLI і автоматичних scoped-прогонів. Перед роботою перевіряє локальний LLM-backend, далі або використовує native batch-шлях після позитивного nativeBatchAvailable, або переходить у послідовний безпечний режим. Для локального provider-контуру очікується endpoint http://127.0.0.1:8000/v1/. Помилки класифікуються так, щоб незворотні пропуски не ламали весь прогін, інфраструктурні збої потрапляли у підсумкову статистику, а системні падіння могли зупинити batch fail-safe exit-кодом без винятків назовні.
+nativeBatchAvailable використовується як перемикач між batch і fallback-потоком. Перевірка не виконує LLM-виклику, а лише підтверджує, що native-реалізація доступна; результат кешується в межах прогону, щоб не повторювати однакову перевірку.
 
-nativeBatchAvailable кешує результат перевірки в межах прогону, щоб не повторювати однаковий тест доступності native-аддона. Якщо batch-недоступний або є м’який дедлайн, runGenerationBatch лишається на послідовному шляху, де частковий прогрес безпечно зберігається по файлах і наступний запуск продовжує за станом CRC.
+generateDirIndex підтримує актуальний directory index у docs/ після будь-яких змін у наборах доків. Він читає наявні markdown-файли, витягує frontmatter і будує оглядову таблицю лише для реальних документів; сам index.md не чіпається, якщо в директорії більше нічого немає.
 
-purgeOrphanedDocs видаляє документацію без відповідного source-файлу, після чого підтримує docs-директорії у чистому стані: оновлює index.md або прибирає порожню директорію. generateDirIndex формує локальний огляд наявних документів у конкретній docs-директорії й не створює індекс там, де немає документів для переліку.
+purgeOrphanedDocs прибирає доки, для яких уже немає source-файлів, і після цього синхронізує індекс директорії. Це тримає docs/ у стані, де в ньому лишається тільки те, що ще прив’язане до коду, а порожні директорії очищуються до мінімально можливого стану.
 
-runDocFilesStampCli не звертається до LLM: він лише приводить наявні документи до актуального frontmatter-штампа source і CRC, зберігаючи вже наявні метадані моделі та якості. Це дає міграційний шлях для старих документів без повторної генерації змісту.
+runDocFilesStampCli працює окремо від генерації: він детерміновано оновлює frontmatter у вже наявних доках без звернення до LLM. Це корисно для міграції та для відновлення метаданих, коли треба синхронізувати source і crc без зміни тексту документа.
 
 ## Публічний API
 
@@ -73,6 +73,12 @@ T8 (2b-batch, рішення Р): коли доступний native-аддон
 Поля `model`, `tier` та якості (`score`/`issues`/`judgeModel`) при цьому зберігаються
 з наявного frontmatter.
 
+## Сценарії використання
+
+- `npm/rules/doc-files/docgen-files-batch/tests/docgen-files-batch.test.mjs` (runDocFilesGenCli — circuit-breaker / класифікація; selectTargets — stale + degraded-once guard) — 3 systemic підряд → abort, exit 2, решта не обробляється; permanent → skip, прогін триває, exit 0; ok між systemic скидає streak → без abort; default: stale | degraded-not-cloud-avg → обрано; good | degraded-cloud-avg → пропущено; --overwrite → усі цілі незалежно від стану; ще 14
+- `npm/rules/doc-files/docgen-files-batch/tests/docgen-files-stamp.test.mjs` (runDocFilesStampCli — збереження frontmatter-полів) — stamp оновлює crc і НЕ губить tier/judgeModel/model/score/issues; stamp доки без quality-полів не вигадує їх і зберігає tier
+- `npm/rules/doc-files/docgen-files-batch/tests/generate-dir-index.test.mjs` (generateDirIndex — MD025/single-title; generateDirIndex — чужий index.md не перезаписується) — згенерований index.md без H1 у тілі; markdownlint не репортить MD025; контроль чутливості: frontmatter title + H1 у тілі → markdownlint репортить MD025; людський index.md без frontmatter лишається недоторканим; index.md як дока source-файлу (type JS Module) лишається недоторканою; власний Directory Index перегенеровується; без інших док index не створюється
+
 ## Гарантії поведінки
 
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).

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

@@ -16,8 +16,16 @@ 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, prepareBatchItem, finishBatchItem } from '../docgen-gen/main.mjs'
-import { crc32, stampDoc, readDocQuality, readDocModel, readDocTier, QUALITY_THRESHOLD } from '../docgen-crc/main.mjs'
+import {
+  documentationCrc,
+  stampDoc,
+  readDocQuality,
+  readDocModel,
+  readDocTier,
+  QUALITY_THRESHOLD
+} from '../docgen-crc/main.mjs'
 import { resolveRoot, scanForDocFiles, scanOrphanedDocs } from '../docgen-scan/main.mjs'
+import { buildTestEvidenceIndex } from '../docgen-test-context/main.mjs'
 import { submitBatch as submitBatchNative } from '@7n/llm-lib/batch'
 
 /** Regex-класифікатори помилки генерації (module-scope, без ре-компіляції на виклик). */
@@ -147,10 +155,16 @@ function fmtSize(bytes) {
  * @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, deadlineAt?: number|null }} [opts] модель/тир для штампу; emit — логер рядка результату; deadlineAt — мʼякий дедлайн fix-pipeline для generateDoc
+ * @param {{ model?: string, tier?: string|null, emit?: (s: string) => void, deadlineAt?: number|null, testIndex?: ReturnType<typeof buildTestEvidenceIndex> }} [opts] модель/тир для штампу; emit — логер рядка результату; deadlineAt — мʼякий дедлайн fix-pipeline для generateDoc; testIndex — спільний source↔tests index
  * @returns {Promise<'ok'|'permanent'|'systemic'|'transient'>} результат для керування циклом
  */
-async function generateOne(file, root, progress, stats, { model, tier, emit, deadlineAt = null } = {}) {
+async function generateOne(
+  file,
+  root,
+  progress,
+  stats,
+  { model, tier, emit, deadlineAt = null, testIndex = buildTestEvidenceIndex(root) } = {}
+) {
   const out = emit ?? (s => process.stdout.write(s))
   const sourceAbs = join(root, file.sourcePath)
   let size = 0
@@ -164,8 +178,8 @@ async function generateOne(file, root, progress, stats, { model, tier, emit, dea
     const docAbs = join(root, file.docPath)
     // Варіант B: передаємо наявну доку, щоб зберегти захищену секцію «Призначення»
     const existingMd = existsSync(docAbs) ? readFileSync(docAbs, 'utf8') : null
-    const result = await generateDoc(sourceAbs, { existingMd, model, deadlineAt })
-    const crc = crc32(readFileSync(sourceAbs))
+    const result = await generateDoc(sourceAbs, { existingMd, model, deadlineAt, testIndex })
+    const crc = documentationCrc(sourceAbs, testIndex)
     mkdirSync(dirname(docAbs), { recursive: true })
     const quality =
       result.score === null
@@ -261,7 +275,7 @@ function defaultLocalProviders() {
  * де м'який дедлайн підтримується).
  * @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 {{ model?: string, tier?: string|null, localProviders?: object, submitBatchImpl?: (modelSpecOrTier: string, items: Array<object>, opts?: object) => Promise<Array<object>>, testIndex: ReturnType<typeof buildTestEvidenceIndex> }} opts модель/тир/local-provider-конфіг (інакше `defaultLocalProviders()`)/інжект submitBatch/source↔tests index
  * @param {{ ok: number, degraded: number, err: number, errors: string[], skipped: string[] }} stats акумулятор (мутується)
  * @param {{ reporter?: object, emit?: (s: string) => void }} io прогрес-репортер і логер рядка результату
  * @returns {Promise<void>}
@@ -271,20 +285,28 @@ async function runBatchPass(targets, root, opts, stats, { reporter, emit }) {
   const submitBatchImpl = opts.submitBatchImpl ?? submitBatchNative
   const out = emit ?? (s => process.stdout.write(s))
 
-  const prepared = await prepareBatchTargets(targets, root, stats, { reporter, out })
+  const prepared = await prepareBatchTargets(targets, root, stats, { reporter, out }, opts.testIndex)
   if (prepared.length === 0) return
 
-  const items = prepared.map(p => ({
+  // Авторські comments уже є джерелом істини: штампуємо такі документи тут,
+  // не створюючи порожній native batch і не торкаючись LLM.
+  const llmPrepared = prepared.filter(p => p.mode !== 'comment-only')
+  for (const p of prepared.filter(p => p.mode === 'comment-only')) {
+    processBatchResult({ ok: '' }, p, { model, tier: opts.tier ?? null, stats, out })
+  }
+  if (llmPrepared.length === 0) return
+
+  const items = llmPrepared.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 onProgress = makeBatchProgress(reporter, targets.length - llmPrepared.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) {
+  for (const p of llmPrepared) {
     processBatchResult(byId.get(p.file.sourcePath), p, { model, tier: opts.tier ?? null, stats, out })
   }
 }
@@ -297,9 +319,10 @@ async function runBatchPass(targets, root, opts, stats, { reporter, emit }) {
  * @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)
+ * @param {ReturnType<typeof buildTestEvidenceIndex>} testIndex source↔tests index
+ * @returns {Promise<Array<object>>} елементи, готові до batch-у або 0-LLM запису (file/sourceAbs/docAbs/size/facts/anchors/src/mode/messages/intent/testIndex)
  */
-async function prepareBatchTargets(targets, root, stats, { reporter, out }) {
+async function prepareBatchTargets(targets, root, stats, { reporter, out }, testIndex) {
   const prepared = []
   for (const file of targets) {
     const sourceAbs = join(root, file.sourcePath)
@@ -312,8 +335,8 @@ async function prepareBatchTargets(targets, root, stats, { reporter, out }) {
     }
     const existingMd = existsSync(docAbs) ? readFileSync(docAbs, 'utf8') : null
     try {
-      const prep = await prepareBatchItem(sourceAbs, { existingMd })
-      prepared.push({ file, sourceAbs, docAbs, size, ...prep })
+      const prep = await prepareBatchItem(sourceAbs, { existingMd, testIndex })
+      prepared.push({ file, sourceAbs, docAbs, size, testIndex, ...prep })
     } catch (error) {
       recordBatchOutcome(stats, out, file.sourcePath, size, error.message)
     }
@@ -390,8 +413,15 @@ function processBatchResult(r, p, { model, tier, stats, out }) {
     )
     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))
+  const finished = finishBatchItem(r.ok, {
+    facts: p.facts,
+    anchors: p.anchors,
+    src: p.src,
+    intent: p.intent,
+    model,
+    mode: p.mode
+  })
+  const crc = documentationCrc(p.sourceAbs, p.testIndex)
   mkdirSync(dirname(p.docAbs), { recursive: true })
   const quality =
     finished.score === null
@@ -632,7 +662,8 @@ async function runSequentialPass(targets, root, opts, stats, { reporter, emit })
       model: opts.model,
       tier: opts.tier,
       emit,
-      deadlineAt: opts.deadlineAt ?? null
+      deadlineAt: opts.deadlineAt ?? null,
+      testIndex: opts.testIndex
     })
     reporter?.concernDone(file.sourcePath)
     // Circuit-breaker: K systemic-збоїв підряд → негайний abort (середовище впало,
@@ -682,6 +713,8 @@ export async function runGenerationBatch(targets, root, opts = {}) {
 
   if (headline) console.log(headline)
   const stats = { ok: 0, degraded: 0, err: 0, errors: [], skipped: [] }
+  const testIndex = buildTestEvidenceIndex(root)
+  const runOpts = { ...opts, testIndex }
 
   // ProgressReporter (канон scripts.mdc): бар по файлах лише в TTY; не-TTY лишає
   // поточні append-рядки [done/total] без дубльованого ⏱-зведення.
@@ -706,10 +739,10 @@ export async function runGenerationBatch(targets, root, opts = {}) {
   let deadlineHit = false
   try {
     if (useBatch) {
-      await runBatchPass(targets, root, { ...opts, submitBatchImpl }, stats, { reporter, emit })
+      await runBatchPass(targets, root, { ...runOpts, submitBatchImpl }, stats, { reporter, emit })
       done = targets.length
     } else {
-      ;({ done, aborted, deadlineHit } = await runSequentialPass(targets, root, opts, stats, { reporter, emit }))
+      ;({ done, aborted, deadlineHit } = await runSequentialPass(targets, root, runOpts, stats, { reporter, emit }))
     }
   } finally {
     reporter?.stop()
@@ -738,12 +771,13 @@ export async function runGenerationBatch(targets, root, opts = {}) {
  */
 export function runDocFilesStampCli(argv) {
   const root = resolveRoot(argv)
+  const testIndex = buildTestEvidenceIndex(root)
   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 crc = documentationCrc(sourceAbs, testIndex)
     const md = readFileSync(docAbs, 'utf8')
     const { score, issues, judgeModel } = readDocQuality(docAbs)
     const model = readDocModel(docAbs)

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

@@ -3,13 +3,33 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-gen/main.mjs
 docgen:
-  crc: 80c789c7
+  crc: 55d2b8ff
   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
+  score: 50
+  issues: internal-name:isApiGap,internal-name:renderApiLine,internal-name:oneShotDoc,internal-name:finishUnsupported,anchor-miss:(foo.mdc),anchor-miss:(abie.mdc),best-of-2:retry-lost
 ---
 
+## Огляд
+
+Модуль формує лаконічну поведінкову документацію для коду через набір публічних кроків: `prepareBatchItem` готує окремий елемент, `generateDoc` створює текст документації, а `finishBatchItem` завершує обробку результату. Для локальних сценаріїв використовується `DEFAULT_LOCAL_MODEL`, а кешування працює у межах прогону, щоб повторні звернення в одному запуску не дублювали однакову роботу. Додаткові операції підтримують цілісність вхідного контексту (`capTimeoutToDeadline`, `stripLeadingPreamble`, `splitProtected`, `insertProtected`) і керують якістю та складом вихідного опису (`scoreDoc`, `buildApiSection`, `hasCompleteCommentDocumentation`, `commentDocumentationMode`, `insertTestScenarios`).
+
+## Поведінка
+
+Документ збирається як керований конвеєр: джерело й факти проходять preflight, після чого модуль або бере повністю детермінований шлях, або підключає локальну LLM-генерацію з подальшою перевіркою якості. Бюджет часу ріжеться через capTimeoutToDeadline, тож будь-який виклик не виходить за межі дедлайну; коли бюджет вичерпано, генерація зупиняється без старту нового запиту.
+
+Початковий текст моделі очищується stripLeadingPreamble, щоб прибрати чатову самореференцію, а splitProtected та insertProtected зберігають захищену секцію «Призначення» під час усіх перетворень. Це важливо для повторних прогонів: наявний намір із попередньої документації не губиться, навіть якщо решта документа перегенеровується.mdc) мають зберігатися в точному вигляді, бо вони використовуються як дослівні якорі для перевірки відповідності.
+
+Оцінка якості через scoreDoc працює на зібраному Markdown, а не на сирому відповіді моделі: секції спочатку нормалізуються, потім порівнюються з фактами, захищеним блоком і дослівними якорями. Саме цей score визначає, чи результат придатний одразу, чи потрібен повторний прохід, і чи слід позначати документ degraded. buildApiSection додає в документ лише те, що справді випливає з уже відомого public API, тому не дублює очевидне й не вигадує відсутні деталі.
+
+hasCompleteCommentDocumentation і commentDocumentationMode керують тим, чи можна обійтися без LLM або обмежитися мінімальним доповненням з авторських коментарів. Якщо header і змістовні описи вже повністю покривають документ, генерація лишається детермінованою; якщо ж є лише часткові підказки, запускається comment-only або змішаний режим із коротким добудовуванням поведінки. У такому випадку commentDocumentationMode лише вибирає маршрут, а не переписує зміст.
+
+insertTestScenarios додає окрему секцію сценаріїв з test/spec-файлів поверх уже зібраного Markdown, не змішуючи їх із поведінковим описом. Це дає змогу зберігати один і той самий основний текст документа незалежно від того, чи прийшов він із one-shot, batch або коментованого режиму.
+
+DEFAULT_LOCAL_MODEL задає локальну модель за замовчуванням для всього конвеєра, а generateDoc є головною точкою входу: вона читає файл, отримує факти, вибирає режим, збирає промпт, викликає генерацію, рахує score і повертає готовий документ з метаданими. Якщо початкова версія не дотягує до порогу, виконується один повторний прохід із більш агресивним налаштуванням; якщо й він не допоміг, результат лишається degraded, але не ламає весь прогін.
+
+prepareBatchItem і finishBatchItem ділять batch-потік на підготовку та фіналізацію: перша частина збирає все потрібне до submit, друга — перетворює вже отриманий текст у такий самий результат, як у послідовному шляху. Це забезпечує однакові правила для single-file і batch-режиму, але без дублювання LLM-викликів у batch-шарі та без змішування стану між файлами.
+
 ## Публічний API
 
 - capTimeoutToDeadline — Ріже базовий per-call таймаут під залишок бюджету до дедлайну.
@@ -27,6 +47,14 @@ JSDoc-описом експорти рендеряться дослівно (`re
 немає — секція збирається БЕЗ жодного LLM-виклику. Єдиний непокритий
 експорт (як і раніше) лишається описаним лише в Поведінці — окремого виклику
 на секцію з одного рядка не варте.
+- hasCompleteCommentDocumentation — Чи коментарі автора повністю покривають машинну документацію: header дає
+«Огляд», а змістовні описи всіх public API — відповідну секцію. У такому
+разі LLM не потрібна: текст зберігається дослівно для JS, Rust і Python.
+- commentDocumentationMode — Вибирає гібридний режим для повністю прокоментованого source. Короткий
+header майже напевно є pointer-ом, а середній header разом із явним flow у
+коді потребує короткого LLM-доповнення. Детальний наратив лишається 0-LLM.
+- insertTestScenarios — Додає test-сценарії до one-shot/batch-документа. Для unsupported мов основний
+Markdown ще повертає LLM, але test-секція лишається виключно JS-рендером.
 - DEFAULT_LOCAL_MODEL — Дефолтна модель: N_CURSOR_DOCGEN_MODEL → resolveModel('min') (→ N_LOCAL_MIN_MODEL).
 Без хардкод-fallback: модель налаштовує кожен локально (`N_LOCAL_MIN_MODEL`); якщо
 нічого не задано — порожньо, і preflight оркестратора фейлить гучно (а не шле
@@ -48,6 +76,10 @@ pre-send guard і той самий факт-лист/one-shot messages, що й
 викликається (мінімальний обсяг T8 — генерація; judge лишається опційним
 розширенням послідовного шляху).
 
+## Сценарії використання
+
+- `npm/rules/doc-files/docgen-gen/tests/docgen-gen.test.mjs` (scoreDoc — R4 generic-overview; scoreDoc — R6 витік службових імен) — абстрактний Огляд штрафується і опускає score під поріг; конкретний Огляд не штрафується; неекспортована функція у Поведінці → internal-name; пропущений валідний анкор → anchor-miss + штраф; наявний анкор → без штрафу; ще 58
+
 ## Гарантії поведінки
 
 - Кешує результати в межах одного прогону.