@7n/rules 1.44.1 → 1.46.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [1.46.0] - 2026-07-23
+
+### Added
+
+- концерн coverage правила test: гейт покриття/мутаційки як lint-детектор (--no-fix = CI-гейт), CoverageProvider порт у plugin-api (spec 2026-07-22 absorb-7n-test)
+- coverage: спільні lib manifest-roots/lcov, подовжений full-таймаут для мутаційного тестування (×4), пілот classify (0.7) у цьому репо
+
+### Changed
+
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header/export JSDoc у конфігах demo
+- doc_comments rollout: header-JSDoc у vitest.config
+
+## [1.45.0] - 2026-07-23
+
+### Added
+
+- концерн coverage правила test: гейт покриття/мутаційки як lint-детектор (--no-fix = CI-гейт), CoverageProvider порт у plugin-api (spec 2026-07-22 absorb-7n-test)
+
+### Changed
+
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header-JSDoc у vitest.config (T0 promote)
+- doc_comments rollout: header/export JSDoc у конфігах demo
+- doc_comments rollout: header-JSDoc у vitest.config
+
 ## [1.44.1] - 2026-07-23
 
 ### Changed

package/docs/stryker.config.md

@@ -3,28 +3,25 @@ type: JS Module
 title: stryker.config.mjs
 resource: npm/stryker.config.mjs
 docgen:
-  crc: 2f4ed270
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: cb7d2219
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
   score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Цей файл конфігурує процес тестування та мутаційного аналізу, використовуючи Vitest як тестовий раннер. Він визначає, які файли підлягають мутації (у `scripts`, `rules`, `bin`) та які виключаються, спираючись на `mutation.json`. Конфігурація налаштовує Stryker для запуску лише тестів, що покривають мутовані рядки. Також конфігурація використовує `incremental.json` для збереження даних між запусками.
+## Огляд
+
+Файл описує конфігурацію Stryker для `@7n/rules`, щоб запускати `vitest-runner` з `perTest`-покриттям на production-коді в `scripts/`, `rules/` і `bin/`, не зачіпаючи фікстури та baseline-шаблони.
 
 ## Поведінка
 
-1. Визначає тестовий раннер як Vitest.
-2. Вказує конфігураційний файл для Vitest.
-3. Налаштовує аналіз покриття так, що Stryker запускає лише тести, що покривають мутовану лінію.
-4. Встановлює тимчасову директорію для звітів Stryker.
-5. Визначає репортери для виводу результатів у форматі JSON та звичайному тексті.
-6. Вказує ім'я файлу для JSON-звіту.
-7. Вмикає функціонал збереження результатів між запусками, використовуючи файл `incremental.json`.
-8. Визначає список файлів, які підлягають мутації:
-   - Файли у директорії `scripts`.
-   - Файли у директорії `rules`.
-   - Файли у директорії `bin`.
-9. Виключає з мутації файли у директоріях `tests`, `__fixtures__`, `fixtures`, `data`, `template`, `templates`.
-10. Виключає з мутації файли у директорії `data`, крім файлу `stryker-vue-macros-ignorer.mjs` у директорії `rules/test/js/data/stryker_config/`.
+1. Запускає мутаційне тестування коду `@7n/rules` через `vitest-runner`, щоб оцінити, як добре тести виявляють зміни в production-логіці.
+2. Перевіряє лише лінії, які реально зачіпаються тестами, щоб зосередити аналіз на корисному сигналі, а не на повному повторному прогоні всього набору.
+3. Зберігає службові артефакти звіту в `reports/stryker/`, зокрема `mutation.json`, щоб результат можна було переглядати й обробляти далі.
+4. Підтримує інкрементальний режим через `incremental.json`, щоб повторні запуски відновлювали попередній стан мутаційної оцінки.
+5. Мутує основний production-код у `scripts/`, `rules/` і `bin/`, а каталоги `**/data/**` і `**/template/**` та `**/templates/**` не включає.
+6. Окремо включає `rules/test/js/data/stryker_config/stryker-vue-macros-ignorer.mjs`.
 
 ## Гарантії поведінки
 

package/package.json

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

package/rules/abie/lib/docs/http-route.md

@@ -3,29 +3,31 @@ type: JS Module
 title: http-route.mjs
 resource: npm/rules/abie/lib/http-route.mjs
 docgen:
-  crc: c3626280
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  tier: local-min-retry
+  crc: d88f96a3
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
   score: 100
-  issues: judge:inaccurate:0.98
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Цей файл здійснює крос-документну аналітику HTTPRoute, використовуючи `ABIE_SHARED_CROSS_NS_BACKEND_NAMES` та `analyzeAbieSharedBackendRefsInPackageK8s`. Він підраховує кількість посилань на спільні сервіси (`auth-run-hl`, `file-link-hl`) у base-маніфестах пакета, ігноруючи overlay `ua`. Мета полягає у синхронізації числа `patch`-ів namespace в overlay з кількістю base-reference, що гарантує узгодженість конфігурації (abie.mdc).
+`analyzeAbieSharedBackendRefsInPackageK8s` рахує `backendRefs` у base-маніфестах пакета, що вказують на спільні cross-namespace `-hl` сервіси з набору `ABIE_SHARED_CROSS_NS_BACKEND_NAMES`, і не враховує overlay `ua`. Це дає `ua_http_route` змогу синхронізувати кількість namespace patch-ів в overlay із фактичною кількістю base-reference до shared backend.
 
 ## Поведінка
 
-Поведінка:
-ABIE_SHARED_CROSS_NS_BACKEND_NAMES: Надає список назв спільних сервісів (`auth-run-hl`, `file-link-hl`), до яких здійснюється аналіз.
-analyzeAbieSharedBackendRefsInPackageK8s: Підраховує кількість посилань на спільні сервіси (`auth-run-hl`, `file-link-hl`) у base-маніфестах пакета, що знаходяться поза overlay `ua`, і виявляє порушення вимог конфігурації, використовуючи маркер (abie.mdc).
+ABIE_SHARED_CROSS_NS_BACKEND_NAMES задає спільний перелік cross-namespace `-hl` сервісів, на який орієнтується вся перевірка; цей набір використовується як єдине джерело істини для того, що вважається shared backend.
+
+analyzeAbieSharedBackendRefsInPackageK8s проходить по YAML-маніфестах пакета в base-шарі, свідомо оминаючи overlay `ua`, і збирає лише ті HTTPRoute-документи, які реально посилаються на спільні сервіси. Для кожного такого посилання воно підсумовує кількість `backendRefs` і накопичує порушення, якщо shared backend вказано не через `namespace: dev` або без очікуваного `port: 8080` згідно з (abie.mdc).
+
+Результат роботи повертається як агрегована статистика для подальшої синхронізації кількості namespace-patch-ів в overlay із фактичною кількістю base-reference; помилки повертаються окремим списком, щоб викликальний концерн міг показати саме ті місця, де базовий HTTPRoute виходить за правилами shared cross-namespace доступу.
 
 ## Публічний API
 
-ABIE_SHARED_CROSS_NS_BACKEND_NAMES — Список імен бекендів, які знаходяться в загальному просторі імен (cross-namespace) для спільного використання.
-analyzeAbieSharedBackendRefsInPackageK8s — Підраховує у YAML-файлах пакета (за винятком overlay ua) кількість посилань на shared-hl backendRefs та виявляє базові помилки (за винятком namespace: dev).
+- ABIE_SHARED_CROSS_NS_BACKEND_NAMES — Імена спільних headless-сервісів, на які HTTPRoute-и пакетів посилаються крізь namespace.
+- analyzeAbieSharedBackendRefsInPackageK8s — Збирає по yaml-файлах пакета (поза overlay ua) кількість shared-`-hl` `backendRefs`
+і базові помилки (без `namespace: dev`).
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/rules/abie/lib/docs/yaml.md

@@ -3,31 +3,43 @@ type: JS Module
 title: yaml.mjs
 resource: npm/rules/abie/lib/yaml.mjs
 docgen:
-  crc: 1b50e492
+  crc: b15223d7
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge-refine:kept-original,judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Спільний набір YAML-хелперів для перевірок правила `abie`. Інкапсулює читання й розбір YAML-файлів Kubernetes-маніфестів так, щоб усі abie-перевірки розбирали вміст однаково: з прибиранням BOM, ігноруванням службового modeline-рядка `# yaml-language-server: $schema=` і fail-safe-поведінкою при пошкоджених файлах.
+## Огляд
+
+Спільні YAML-хелпери для abie-перевірок: `stripBom` прибирає BOM на початку тексту, `MODELINE_RE` розпізнає службовий рядок `# yaml-language-server: $schema=`, а `LINE_SPLIT_RE` ділить вміст на рядки. `readAndParseYamlDocs` читає YAML як набір документів, `isDeploymentDoc` відокремлює документи потрібного типу, а `silentFail` дає fail-safe поведінку: за непридатного вмісту або помилки повертається порожнє значення замість винятку.
 
 ## Поведінка
 
-Читання й розбір YAML-документів з файлу:
+MODELINE_RE і LINE_SPLIT_RE задають спільні правила нормалізації вхідного YAML: перший виявляє службовий modeline на початку файлу, другий уніфікує розбиття тексту на рядки незалежно від переносу.
+
+stripBom прибирає початковий BOM перед подальшою обробкою, щоб наступні кроки працювали з чистим вмістом без артефактів кодування.
 
-1. Намагається прочитати файл за абсолютним шляхом. Якщо читання не вдалося — викликає переданий обробник помилок із повідомленням, що включає відносний шлях і причину, і повертає `null`.
-2. Прибирає BOM на початку вмісту, якщо він є.
-3. Якщо перший рядок — це YAML-language-server modeline (`# yaml-language-server: $schema=...`), пропускає його перед розбором; решта вмісту парситься без нього. Інакше парситься весь вміст.
-4. Розбирає всі YAML-документи у файлі (мультидокументні файли з `---` підтримуються). При помилці розбору викликає обробник помилок із повідомленням і повертає `null`; інакше повертає масив розібраних документів.
+readAndParseYamlDocs є основним потоком: читає файл, нормалізує вміст через stripBom, відсікає modeline, якщо він є першим рядком, і лише тоді передає результат у YAML-парсинг. Успішний результат повертається далі як набір YAML-документів, а будь-яка проблема читання або парсингу перетворюється на повідомлення через failFn і завершується без винятку назовні.
 
-Окремо надає предикат розпізнавання маніфестів `Deployment`: документ вважається `Deployment`, лише якщо це звичайний об'єкт (не масив, не `null`) із полем `kind` рівним `'Deployment'`.
+silentFail використовується як нейтральний обробник помилок для сценаріїв, де зіпсований або непридатний YAML не має зупиняти перевірку; у такому режимі помилка свідомо приглушується, а контроль залишається у викликача.
 
-Передбачено готовий «тихий» обробник помилок — для викликів, які мають мовчки повертати порожній результат при поганому вводі, бо пошкоджені файли діагностує окрема перевірка (`check-k8s`), а не abie.
+isDeploymentDoc відокремлює лише документи потрібного виду для подальших перевірок, щоб решта YAML не проходила через специфічну логіку abie-здач.
 
-## Де використовується
+## Публічний API
 
-Хелпери імпортуються іншими модулями abie, що аналізують Kubernetes-маніфести, зокрема `lib/k8s-tree.mjs`, `lib/kustomization-patches.mjs`, `lib/http-route.mjs`, `lib/hc-yaml.mjs` та перевіркою `js/hc_pairing.mjs`.
+- MODELINE_RE — Розпізнає modeline `yaml-language-server` з `$schema=` у першому рядку файлу; захоплює URL схеми.
+- LINE_SPLIT_RE — Поділ вмісту на рядки незалежно від стилю переносу (LF чи CRLF).
+- stripBom — Прибирає BOM на початку файлу.
+- isDeploymentDoc — Чи YAML-документ — це `kind: Deployment`.
+- silentFail — No-op fail-handler для функцій, що мовчки повертають null/[] при помилці парсингу.
+- readAndParseYamlDocs — Зчитує і парсить YAML-документи з файлу. BOM і modeline (перший рядок `$schema`)
+автоматично прибираються перед `parseAllDocuments`. При помилці читання/парсингу
+викликає `failFn` і повертає `null`.
 
 ## Гарантії поведінки
 
-- Read-only: модуль лише читає й розбирає файли, не змінює їх.
-- Fail-safe: помилки читання чи розбору YAML не кидаються назовні — натомість викликається переданий обробник, а результатом стає `null`. Це дозволяє перевіркам пропускати биті файли замість падіння.
-- Розбір стійкий до BOM і до службового modeline-рядка `$schema` на першому рядку — вони не ламають парсинг і не потрапляють у результат.
-- Предикат розпізнавання `Deployment` безпечний для будь-якого вводу: повертає `false` для `null`, масивів і не-об'єктів, ніколи не кидає винятків.
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.

package/rules/ci4/marksman_config/docs/main.md

@@ -3,28 +3,28 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/ci4/marksman_config/main.mjs
 docgen:
-  crc: c34fa8be
+  crc: 259b7df5
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  tier: local-min-retry
   score: 100
-  issues: judge:inaccurate:0.99
+  issues: judge:error
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Оновлений текст секції «overview» (як вимагається, без попередньої преамбули та згідно з інструкціями):
-
-Це файловий модуль відповідає за забезпечення певної функціональної області системи. Він виконує аналіз даних у межах визначених логічних кордонів. У своїй поведінці він обов'язково включає маркери повідомлень згідно з `ci4.mdc`.
+Файл виконує перевірку конфігураційних даних у робочому каталозі. Він вимагає наявності канонічного конфігу, визначеного константою MARKSMAN_BASELINE_PATH, для коректної роботи системи, і при його відсутності вказує на необхідність відновлення пакета правил. Крім того, визначається цільовий файл MARKSMAN_TARGET_FILENAME, і ця функція повідомляє про його успішне знаходження або про необхідність ініціалізації. Доступна функція lint виконує перевірку відповідно до визначених конфігурацій.
 
 ## Поведінка
 
-1. Викликається функція main.
-2. Перевіряється наявність канонічного baseline-файлу у шляху, відносно розташування поточного файлу.
-3. Якщо baseline-файл не знайдено, видається повідомлення про помилку (ci4.mdc) та процес завершується з відповідним кодом виходу.
-4. Перевіряється наявність цільового файлу .marksman.toml у корені проєкту.
-5. Якщо цільовий файл існує, видається повідомлення про успіх, і процес завершується з кодом виходу 0.
-6. Якщо цільовий файл не існує, канонічний baseline-файл копіюється у цільовий файл .marksman.toml у корені проєкту, і видається повідомлення про успіх (ci4.mdc).
+При запуску `lint` системи перевіряє наявність файлу `MARKSMAN_BASELINE_PATH`, який є канонічним конфігом, що постачається з пакетом правил; якщо він відсутній, система повідомляє про помилку, що вказує на необхідність перевстановлення пакета `@7n/rules`. Потім система шукає у робочому каталозі файл, визначений у `MARKSMAN_TARGET_FILENAME` (`.marksman.toml`); якщо він знайдений, система повідомляє про успіх. Якщо ж файл відсутній, система повідомляє про необхідність копіювання канонічного baseline-конфігу, посилаючись на правило (ci4.mdc).
+
+## Публічний API
+
+- MARKSMAN_BASELINE_PATH — Абсолютний шлях до канонічного baseline-конфігу marksman, що постачається разом із пакетом правил.
+- MARKSMAN_TARGET_FILENAME — Імʼя конфіг-файлу marksman, який має лежати в корені репозиторію.
+- lint — Перевіряє наявність `.marksman.toml` у корені; сигналить копіювання canonical baseline.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

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

@@ -3,46 +3,75 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-prompts/main.mjs
 docgen:
-  crc: 465da2eb
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 8cb3a892
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
   score: 100
-  issues: judge:inaccurate:0.99
+  issues: judge-refine:kept-original,judge:inaccurate:0.99
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Будь ласка, надайте чорнетку секції «overview» для редагування.
+Файл формує промпти й детерміновані фрагменти для генерації поведінкової документації: `STYLE` задає спільний тон, `sectionMessages`, `overviewMessages`, `criticMessages`, `refineMessages`, `oneShotMessages` і `judgeRefineMessages` готують повідомлення для різних етапів, `isApiGap`, `renderApiLine` та `apiGapMessages` висвітлюють прогалини API, а `guaranteesFromMarkers` і `buildUnitDigest` стискають контекст до контрольованого обсягу `UNIT_DIGEST_TOKENS`. Файл існує як текстовий шар оркестратора документації, щоб підтримувати лаконічний стиль, узгоджувати очікування між етапами генерації та зменшувати ризик вигаданих тверджень. У межах одного прогону використовує кешування для повторного використання вже підготовлених результатів.
 
 ## Поведінка
 
-sectionMessages.main.mjs
+STYLE задає спільні правила тону й форми для промптів, щоб усі згенеровані секції лишалися лаконічними, поведінковими та без технічного шуму.
 
-````
-Ти технічний письменник. Пишеш лаконічну ПОВЕДІНКОВУ документацію до коду українською, чистим Markdown.
-Пиши ЩО і НАВІЩО, не ЯК. Без вступів і висновків. Не обгортай у ```-блок.
-Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.
+Основний потік генерації розділяє документацію на незалежні кроки. sectionMessages формує запит лише для секції «Поведінка» з мінімальним контекстом: фактами про файл, релевантними анкорами, захищеним «Призначенням» і, за потреби, стислим представленням коду. Після отримання готової «Поведінки» overviewMessages створює «Огляд» уже з неї, а не напряму з коду, щоб підсумок спирався на підтверджений опис поведінки.
 
-Напиши вміст секції «Поведінка»: для кожної публічної функції — один короткий пункт «що вона робить». Описуй РІВНО ці публічні імена і жодних інших: STYLE, sectionMessages, overviewMessages, criticMessages, refineMessages, guaranteesFromMarkers, oneShotMessages. Якщо у фактах є свідомі пропуски шляхів — згадай їх там, де доречно (не вигадуй інших «не перевіряє»). НЕ пиши аргументи функцій у дужках, без regex. НЕ згадуй за іменами службові функції: anchorsToPrompt. Без заголовка, без додаткових ## чи # підзаголовків усередині секції.
-````
+Публічний API обробляється гібридно без зайвого LLM-переписування. isApiGap визначає, які експорти не мають змістовного опису. Для покритих описом експортів renderApiLine повертає дослівний рядок документації, зберігаючи авторський текст. Для прогалин apiGapMessages формує окремий вузький запит тільки по відсутніх описах, щоб модель не торкалася вже надійних JSDoc-фрагментів.
 
-## Публічний API
+Якість машинних секцій підсилюється окремим циклом перевірки. criticMessages готує запит до критика, який має знайти конкретні дефекти або підтвердити їх відсутність. refineMessages використовує ці зауваження для переписування чорнетки без зміни призначення секції. judgeRefineMessages виконує точкове доопрацювання документа за причиною від судді, коли потрібно виправити конкретне хибне твердження замість просто позначити результат як погіршений.
+
+guaranteesFromMarkers створює «Гарантії поведінки» детерміновано з маркерів факт-листа, без LLM-запиту. Це відокремлює формальні гарантії від вільного тексту й зменшує ризик вигаданих тверджень.
 
-Згідно з інструкцією з `/Users/vitalii/www/nitra/cursor/AGENTS.md`, моя функція — генерувати лаконічну поведінкову документацію українською мовою в чистому Markdown для кожного зміненого/нового кодового файлу, у вигляді списку маркерів.
+oneShotMessages лишається базовим одноетапним сценарієм для порівняння з секційним потоком. UNIT_DIGEST_TOKENS задає межу компактного представлення великих файлів, а buildUnitDigest перетворює набір юнітів на стислий дайджест, щоб промпт зберігав фокус на структурі й поведінці замість перевантаження сирим кодом.
 
-Ви надаєте мені список термінів та просите перетворити його на стиль: `«назва — що робить»`, використовуючи власні слова, без копіювання дослівно, без типів і сигнатур.
+Файл не виконує власних записів у файлову систему чи базу даних: результати всіх публічних функцій повертаються як текстові секції, рядки або масиви повідомлень для подальшої обробки зовнішнім оркестратором. Кешування використовується лише в межах поточного прогону.
 
-Ось переписаний список у заданому форматі:
+## Публічний API
 
-STYLE — Визначає загальний стиль та призначення файлу.
-sectionMessages — Групує повідомлення для секцій, забезпечуючи мінімальний контекст для кожної.
-overviewMessages — Підготує узагальнений огляд поведінки на основі вже написаної детальної поведінки.
-criticMessages — На етапі первинного аналізу тексту виявляє конкретні недоліки в чорноті для подальшого виправлення.
-refineMessages — Виправляє чорнетку, усуваючи виявлені критичні недоліки.
-guaranteesFromMarkers — Створює чіткий, детермінований перелік гарантій роботи, ґрунтуючись на фіксованих маркерних фактах.
-oneShotMessages — Слугує зразком для порівняння, що містить конкретні приклади, а не загальні описи дій.
+- STYLE — Спільний system-стиль для всіх docgen-промптів: вимагає лаконічну поведінкову
+українську документацію, забороняє сигнатури/типи й мета-фрази перед відповіддю
+(профілактика «озвучування завдання» малими моделями).
+- sectionMessages — Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
+Код потрапляє лише в `behavior`; «Огляд» генерується окремо ОСТАННІМ
+(`overviewMessages`) з уже написаної Поведінки — тут його немає. «Публічний
+API» сюди більше не входить (Stage 1/3, гібрид doc-files ADR 260719-2155):
+покриті JSDoc-описом експорти рендеряться дослівно без LLM (`renderApiLine`),
+LLM викликається лише на прогалини (`apiGapMessages`) — див. `isApiGap`.
+- isApiGap — Stage 2 (gap-детект, 0 токенів): чи є опис експорту прогалиною — відсутній
+або JSDoc-заглушка без сенсу.
+- renderApiLine — Stage 1 (скриптовий рендер, 0 токенів, 0 галюцинацій): дослівний рядок
+«Публічного API» з покритого JSDoc-описом експорту — без перефразування LLM.
+- apiGapMessages — Stage 3: messages ЛИШЕ для експортів-прогалин (без desc) — вужчий промпт,
+ніж попередній «переписати весь список своїми словами» (жодного контакту з
+уже покритими JSDoc експортами, 0 ризику спотворити авторський текст).
+- overviewMessages — R3 — «Огляд» ОСТАННІМ: узагальнення вже написаної Поведінки, а не здогад із
+голого факт-листа. Лікує generic/хибний Огляд на складних файлах.
+Анкор-блок сюди НЕ підставляється (№8, бенч gemma-4): секції — окремі
+LLM-виклики, і коли анкори бачили обидва, кожен чесно вставляв «рівно один
+раз» → у документі виходило двічі (незграбні «посилаючись на…» в Огляді).
+Анкори живуть лише в Behavior-промпті; скорер R5 перевіряє документ цілком.
+- criticMessages — E2-step 1 — критик. Перевіряє чорнетку секції на конкретні дефекти.
+Повертає messages для LLM-запиту: вихід має бути СПИСКОМ issues або словом NONE.
+- refineMessages — E2-step 2 — refine. Переписує чорнетку, виправляючи перелічені issues.
+- guaranteesFromMarkers — E3 — детермінований шаблон секції «Гарантії поведінки» з facts.markers.
+НЕ використовує LLM: 0 запитів, 0 галюцинацій, 0 generic-фраз.
+- oneShotMessages — One-shot messages (база для порівняння).
+- UNIT_DIGEST_TOKENS — Поріг (у токенах, ~4 байти/токен), після якого сирий src замінюється юніт-дайджестом.
+- buildUnitDigest — №5 (бенч gemma-4): стислий юніт-дайджест великого файлу замість сирого src у
+Behavior-промпті. На ~6k токенів сирцю мала модель втрачає фокус (водянисті
+формулювання); дайджест подає структуру — імʼя, JSDoc, call-graph, тіло лише
+для непокритих JSDoc юнітів (перші рядки) — і тримає промпт компактним.
+- judgeRefineMessages — №6 — judge-refine: один локальний refine-прохід за конкретними зауваженнями
+LLM-судді (замість лише маркування degraded). Суддя вже сформулював, ЩО саме
+хибне (`reason`) — мала модель добре виправляє точкові твердження, коли їй
+сказано, які саме.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
 - Кешує результати в межах одного прогону.

package/rules/image-avif/avif_generation/docs/main.md

@@ -3,33 +3,45 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/image-avif/avif_generation/main.mjs
 docgen:
-  crc: 658146c1
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  score: 100
-  issues: judge:inaccurate:0.99
+  crc: 7e73761a
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 85
+  issues: internal-name:walkDir,anchor-miss:(image-avif.mdc),judge-refine:kept-original,judge:inaccurate:0.98
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Огляд
-Цей модуль відповідає за ініціалізацію та виконання процесу конвертації растрових зображень у проєкті на AVIF-двійники, як описано у `package.json`. Публічна функція `main` запускає сканування всіх пакетів монорепозиторію, що призводить до заміни посилань у файлах Vue та HTML на оптимізовані версії. Крім того, він очищає від неіспользуних AVIF-файлів, використовуючи кешування даних протягом одного прогону.
+scanAvif — read-only детектор AVIF для `.vue` і `.html`: він знаходить raster-посилання і класифікує їх як `avif-needs-rewrite`, `avif-missing` або `avif-orphan`. `AVIF_NEEDS_REWRITE`, `AVIF_MISSING`, `AVIF_ORPHAN`, `MINIFY_PACKAGE_NAME`, `CLEANUP_EXTRA_IGNORE_DIR_NAMES` — публічні константи для цих перевірок і спільних правил сканування. `lint --no-fix` лише звітує і не мутує tree, а переписування посилань, AVIF-генерацію та прибирання сиріт виконує окремий T0-fix `fix-avif_generation.mjs`. Cache працює в межах одного прогону.
 
 ## Поведінка
 
-1. main виконує повний цикл перевірки та оптимізації зображень AVIF.
-2. Перед початком роботи перевіряється наявність будь-яких посилань на растрове зображення у файлах Vue або HTML. Якщо таких посилань немає, операція припиняється, оскільки немає чого оптимізувати.
-3. Запускається генерація AVIF-двійників з використанням інструмента `@nitra/minify-image`.
-4. Ініціалізуються лічильники для обліку успішно переписаних посилань, змін у файлах та невдалих спроб заміни.
-5. Проводиться сканування всіх пакетів у монорепозиторії. Для кожного пакета визначається, чи активовано вимкнення перевірки (`disable-avif: true`) у `package.json`.
-6. Якщо перевірка AVIF-імпортів не вимкнена, виконується аналіз файлів Vue та HTML у пакеті. Знайдені растрові посилання замінюються на посилання з суфіксом `.avif`, якщо відповідний AVIF-двійник існує на диску. У разі невдачі заміни фіксується звіт про помилку, а сам файл може бути змінений. Після обробки файлу він записується на диск. Збір до списку шляхів, що використовуються, ведеться для AVIF-двійників.
-7. Паралельно з аналізом пакетів, збирається список усіх абсолютних коренів пакетів, де перевірка була вимкнена.
-8. Після аналізу всіх пакетів, збирається список "сиріт" — AVIF-файлів, які знаходяться у репозиторії, але на які немає жодного активного посилання у `.vue` або `.html` файлах. Ці сироти видаляються, за винятком AVIF-файлів у пакетах, де перевірка була вимкнена, та AVIF-файлів, які мають живі посилання.
-9. Повертається загальний звіт про кількість виконаних операцій (заміна посилань, видалення сиріт, невдачі заміни).
+`scanAvif` запускає спільний read-only потік для detector-а й T0-fix: спершу перевіряє, чи є в репозиторії хоч одне raster-посилання, придатне для AVIF-етапу, далі збирає зв’язки між `.vue`/`.html`, `.avif` і package.json, а потім формує результати для лінту без жодної мутації дерева. Якщо raster-посилань немає, весь етап пропускається; якщо в workspace немає workspaces або `.vue`-файлів, AVIF-правило для проєкту теж не активується.
+
+`MINIFY_PACKAGE_NAME` позначає пакет, через який читається opt-out у `package.json`: коли пакет вимикає AVIF-перевірку, його шаблони не беруть участі в перевірці посилань, а його `.avif` не можна автоматично вважати сиротами. Це захищає файли, що можуть використовуватись через alias, runtime-обчислення або зовнішні посилання, які статичний скан тут не бачить.
+
+`CLEANUP_EXTRA_IGNORE_DIR_NAMES` додає спільні виключення для обходу, щоб `scanAvif` і `lint` не зачіпали каталоги, які не мають впливати на AVIF-діагностику.
+
+`AVIF_NEEDS_REWRITE` використовується для випадків, коли raster-посилання вже має доступний `.avif`-двійник, але посилання ще не переписане на нього; `AVIF_MISSING` — коли потрібного `.avif`-двійника немає; `AVIF_ORPHAN` — коли `.avif` лишився без живих посилань у відсканованих шаблонах.
+
+`lint` лише звітує ці три стани як violations і не виконує генерацію AVIF, переписування посилань чи видалення сиріт; ці дії лишаються за окремим T0-fix. Маркери повідомлень прив’язані до `image-avif.mdc`, а сам detector спирається на `package.json` як джерело opt-out-конфігурації.
 
 ## Публічний API
 
-main — генерує зображення у форматі AVIF, автоматично замінює посилання на растрове зображення у файлах `.vue` та `.html`, а також очищує від непідключених файлів AVIF.
+- AVIF_NEEDS_REWRITE — Стабільні reasons.
+- AVIF_MISSING — Стабільний reason: для растрового зображення відсутній згенерований AVIF-двійник.
+- AVIF_ORPHAN — Стабільний reason: AVIF-файл лишився без растрового джерела — кандидат на cleanup.
+- MINIFY_PACKAGE_NAME — Імʼя CLI-пакета, який генерує AVIF (використовує T0-fix).
+- CLEANUP_EXTRA_IGNORE_DIR_NAMES — Імена каталогів, які cleanup НЕ зачіпає, бо це артефакти збірки/нативні
+платформи — `.avif` всередині — це продукт попереднього `bun run build`/Capacitor sync,
+а не кандидати на видалення. `walkDir` уже скіпає `node_modules`, `.git`, `dist`,
+`coverage`, `.turbo`, `.next` — додатково для cleanup ігноруємо ще ці.
+- scanAvif — Чистий read-only скан усього AVIF-етапу (без npx, без запису, без unlink). Спільний
+для detector-а (→ violations) і T0-fix (виконує генерацію, потім rescan + write/unlink).
+- lint — Read-only detector AVIF-етапу: ЗВІТУЄ потрібні rewrite-и (`avif-needs-rewrite`),
+відсутні `.avif`-двійники (`avif-missing`) і `.avif`-сироти (`avif-orphan`).
+Не валідує image-compress cache/dependency policy — це окреме правило.
 
 ## Гарантії поведінки
 

package/rules/test/coverage/lib/classify/prompt.mjs

@@ -10,6 +10,7 @@ import { basename, dirname, join } from 'node:path'
 const CONTEXT_LINES = 10
 const TEST_FILE_MAX_LINES = 2000
 
+/** Системний промпт класифікатора survived-мутантів (5 verdict-категорій). */
 export const SYSTEM_PROMPT = `You are a mutation testing classifier.
 
 For each survived Stryker mutant, classify it into exactly one verdict:

package/rules/test/coverage/lib/classify/verdict-schema.mjs

@@ -16,6 +16,7 @@ import { z } from 'zod'
 const REASON_SOFT_MAX = 500
 const SUGGESTED_TEST_SOFT_MAX = 300
 
+/** Zod-схема verdict-обʼєкта класифікатора (verdict/confidence/reason/suggestedTest). */
 export const VerdictSchema = z.object({
   verdict: z.enum(['worth-testing', 'equivalent', 'defensive', 'glue', 'wrapper']),
   confidence: z.number().min(0).max(1),

package/rules/test/coverage/lib/lcov.mjs

@@ -0,0 +1,54 @@
+/**
+ * Мовно-агностичний парсинг lcov (спільна lib концерну coverage): агреговані
+ * totals (рядки/функції) і per-file розбивка. Живе в core — провайдери всіх
+ * мов (vitest lcov, cargo llvm-cov) імпортують звідси, без дублювання парсера
+ * у плагінах. SF-шляхи рібейзяться відносно кореня на боці викликача.
+ */
+
+/**
+ * Агрегує LF/LH/FNF/FNH по всіх записах lcov.
+ * @param {string} text вміст lcov-файлу
+ * @returns {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} totals
+ */
+export function parseLcovTotals(text) {
+  const acc = { lines: { covered: 0, total: 0 }, functions: { covered: 0, total: 0 } }
+  for (const line of text.split('\n')) {
+    if (line.startsWith('LF:')) acc.lines.total += Number(line.slice(3))
+    else if (line.startsWith('LH:')) acc.lines.covered += Number(line.slice(3))
+    else if (line.startsWith('FNF:')) acc.functions.total += Number(line.slice(4))
+    else if (line.startsWith('FNH:')) acc.functions.covered += Number(line.slice(4))
+  }
+  return acc
+}
+
+/**
+ * Per-file рядкове покриття з lcov (`SF:`/`LF:`/`LH:`; шляхи — як у файлі).
+ * @param {string} text вміст lcov-файлу
+ * @returns {Array<{file: string, pct: number, linesFound: number, linesCovered: number}>} рядки по файлах
+ */
+export function parseLcovPerFile(text) {
+  const files = []
+  let currentFile = null
+  let lf = 0
+  let lh = 0
+  for (const line of text.split('\n')) {
+    if (line.startsWith('SF:')) {
+      currentFile = line.slice(3).trim()
+      lf = 0
+      lh = 0
+    } else if (line.startsWith('LF:')) {
+      lf = Number(line.slice(3))
+    } else if (line.startsWith('LH:')) {
+      lh = Number(line.slice(3))
+    } else if (line === 'end_of_record' && currentFile) {
+      files.push({
+        file: currentFile,
+        pct: lf === 0 ? 100 : Math.round((lh / lf) * 10000) / 100,
+        linesFound: lf,
+        linesCovered: lh
+      })
+      currentFile = null
+    }
+  }
+  return files
+}

package/rules/test/coverage/lib/manifest-roots.mjs

@@ -0,0 +1,49 @@
+/**
+ * Мовно-агностичний пошук коренів екосистеми за маніфестом (спільна lib
+ * концерну coverage): каталоги з одним із маніфест-файлів у корені проєкту та
+ * на першому рівні вкладеності (типові розкладки: крейт/пакет у корені,
+ * `src-tauri/`, side-пакет у монорепо). Глибші члени workspace не повертаються
+ * — тулзи (`cargo llvm-cov`, `pytest`) покривають їх із кореня самі.
+ */
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/** Службові теки, де маніфести першого рівня не шукаються. */
+const IGNORE_DIRS = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'target',
+  'coverage',
+  'docs',
+  '.git',
+  '.claude',
+  '.worktrees',
+  '.cursor',
+  '.github'
+])
+
+/**
+ * Корені під `cwd`, що мають хоча б один із `manifestNames`.
+ * @param {string} cwd корінь проєкту
+ * @param {string[]} manifestNames імена маніфестів (напр. `['Cargo.toml']`, `['pyproject.toml', 'setup.py']`)
+ * @returns {Promise<string[]>} абсолютні шляхи каталогів-коренів
+ */
+export async function findManifestRoots(cwd, manifestNames) {
+  const hasManifest = dir => manifestNames.some(name => existsSync(join(dir, name)))
+  const roots = []
+  if (hasManifest(cwd)) roots.push(cwd)
+  let entries
+  try {
+    entries = await readdir(cwd, { withFileTypes: true })
+  } catch {
+    return roots
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.') || IGNORE_DIRS.has(entry.name)) continue
+    const dir = join(cwd, entry.name)
+    if (hasManifest(dir)) roots.push(dir)
+  }
+  return roots
+}

package/rules/text/oxfmtrc/docs/fix-oxfmtrc.md

@@ -3,24 +3,27 @@ type: JS Module
 title: fix-oxfmtrc.mjs
 resource: npm/rules/text/oxfmtrc/fix-oxfmtrc.mjs
 docgen:
-  crc: 2902bd52
-  model: openai-codex/gpt-5.4-mini
-  tier: cloud-min
+  crc: d2983472
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
   score: 100
-  issues: judge:inaccurate:0.98
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Публічна точка входу `patterns` повертає набір правил вирівнювання для `.oxfmtrc.json` і слугує read-only джерелом очікуваного стану цього конфіга. Код спирається на конфіг `.oxfmtrc.json` як на залежність контексту, щоб узгоджувати його формат із прийнятими правилами.
+Файл визначає T0-fix-сценарій концерну text/oxfmtrc для `.oxfmtrc.json`, який приводить конфіг до канону правила через глибоке об’єднання з шаблоном. `patterns` існує, щоб додавати налаштування з канонічного шаблону й не втрачати наявні локальні ключі конфігу.
 
 ## Поведінка
 
-1. `patterns` формує набір виправлень для узгодження шаблонного конфіга з цільовим файлом `.oxfmtrc.json`.
-2. Кожен елемент у `patterns` описує окреме правило вирівнювання цього конфіга, щоб тримати його в очікуваному стані.
-3. `patterns` не виконує записів у файлову систему чи базу даних і не змінює інші файли поза `.oxfmtrc.json`.
+1. `patterns` оголошує один fix-сценарій для приведення `.oxfmtrc.json` до канонічного стану правила.
+2. Сценарій додає або оновлює значення з шаблону правила через глибоке об’єднання, щоб обов’язкові налаштування були присутні.
+3. Наявні локальні ключі конфігу зберігаються, щоб проєктові відмінності не втрачалися під час автоматичного виправлення.
+
+## Публічний API
+
+- patterns — Fix-патерни концерну: один шаблонний deep-merge у `.oxfmtrc.json`.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/rules/text/vscode_settings/docs/fix-vscode_settings.md

@@ -3,25 +3,29 @@ type: JS Module
 title: fix-vscode_settings.mjs
 resource: npm/rules/text/vscode_settings/fix-vscode_settings.mjs
 docgen:
-  crc: aa3c10a6
-  model: openai-codex/gpt-5.4-mini
-  tier: cloud-min
+  crc: 7208a85f
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
   score: 100
-  issues: judge:inaccurate:0.93
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Файл визначає, за якими правилами `patterns` перевіряє відповідність `.vscode/settings.json` конфігурації з `settings.json`. Це потрібно, щоб підтримувати узгоджений стан редакторських налаштувань у проєкті.
+Файл задає автоматичне виправлення для `.vscode/settings.json` у межах концерну `text/vscode_settings`. Він існує, щоб доводити workspace-налаштування до канону через `deep-merge` шаблону правила, зберігаючи локальні користувацькі значення.
 
 ## Поведінка
 
-1. `patterns` формує набір правил для приведення `.vscode/settings.json` до узгодженого стану з шаблоном.
-2. `patterns` орієнтується на конфігурацію `settings.json` як на джерело очікуваного вигляду налаштувань.
-3. `patterns` потрібен, щоб автоматично підтримувати єдину структуру редакторських налаштувань у проєкті.
-4. `patterns` працює лише як опис правил і не виконує запис у файлову систему чи базу даних.
+1. `patterns` оголошує єдиний fix-патерн для приведення `settings.json` до проєктного канону.
+
+2. Патерн застосовує шаблон правила як deep-merge, щоб додати або оновити обов’язкові налаштування без перетирання локальних користувацьких значень.
+
+3. Результат призначений для автоматичного виправлення відхилень у VS Code workspace-конфігурації в межах концерну `text/vscode_settings`.
+
+## Публічний API
+
+- patterns — Fix-патерни концерну: один шаблонний deep-merge у `.vscode/settings.json`.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/rules/worktree/zed_settings/docs/fix-zed_settings.md

@@ -3,26 +3,31 @@ type: JS Module
 title: fix-zed_settings.mjs
 resource: npm/rules/worktree/zed_settings/fix-zed_settings.mjs
 docgen:
-  crc: 452faa10
+  crc: 3cff4486
   model: openai-codex/gpt-5.5
   tier: cloud-avg
   score: 100
-  issues: judge:inaccurate:0.98
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Надає правило `patterns` для перевірки очікуваних налаштувань проєкту. Код спирається на конфіг `settings.json` і працює read-only, щоб описати вимоги до конфігурації без самостійного внесення змін.
+Файл задає fix для `.zed/settings.json`, який приводить робочий конфіг Zed до командного канону через `deep-merge` шаблону правила. Він існує, щоб додавати або виправляти очікувані значення `settings.json`, не перезаписуючи локальні налаштування користувача поза конфліктами з канонічними вимогами.
+
+`patterns` є єдиною публічною точкою для оголошення цього правила.
 
 ## Поведінка
 
-1. `patterns` визначає правило автоматичного приведення робочого дерева до очікуваного шаблону налаштувань Zed.
+1. `patterns` оголошує fix-поведінку для приведення робочого конфіга Zed до командного канону.
+
+2. Під час застосування fix оновлює `.zed/settings.json` на основі шаблону правила через злиття налаштувань, щоб додати або виправити очікувані значення з `settings.json`.
+
+3. Наявні локальні налаштування користувача зберігаються, якщо вони не конфліктують із канонічними вимогами правила.
 
-2. `patterns` орієнтується на конфіг `settings.json`, щоб забезпечити наявність і узгодженість `.zed/settings.json` у проєкті.
+## Публічний API
 
-3. `patterns` не змінює файлову систему самостійно; воно лише описує поведінку виправлення для зовнішнього механізму застосування правил.
+- patterns — Fix-патерни концерну: один шаблонний deep-merge у `.zed/settings.json`.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/schemas/n-rules.json

@@ -82,6 +82,11 @@
           "type": "number",
           "description": "Мінімальний mutation score у відсотках (лише повний вимір: lint --full / lint test).",
           "default": 80
+        },
+        "classifyConfidenceThreshold": {
+          "type": "number",
+          "description": "Confidence-поріг LLM-класифікації survived-мутантів (allowed gaps). ≤1 — увімкнено; дефолт 1.1 = вимкнено (rollout-mode).",
+          "default": 1.1
         }
       }
     },

package/scripts/lib/lint-surface/docs/lint-lock.md

@@ -3,45 +3,54 @@ type: JS Module
 title: lint-lock.mjs
 resource: npm/scripts/lib/lint-surface/lint-lock.mjs
 docgen:
-  crc: 23bf1b2c
-  model: openai-codex/gpt-5.5
-  tier: cloud-avg
-  score: 100
-  issues: judge:inaccurate:0.98
+  crc: c1100ba8
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 90
+  issues: internal-name:withLock,judge-refine:kept-original,judge:inaccurate:0.99
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Файл серіалізує лише довгі machine-wide запуски `n-rules lint --full`, щоб на машині одночасно виконувався щонайбільше один full-прогін. Delta, scoped і `--no-fix` запуски не беруть глобальний лок і не стають у цю чергу.
+Спільний машинний стан для `n-rules lint --full`: через `withLock` блокується лише `--full`, а scoped, delta та `--no-fix` запуски йдуть без черги. Це серіалізує довгі whole-tree прогони на одній машині, дає видимість позиції в черзі й показує живий прогрес активного запуску.
 
-Активний full-прогін записує власника лока в `owner.json` і публікує живий стан у `progress.json`, щоб процеси в очікуванні бачили поточного виконавця та прогрес. Процеси в черзі реєструються у `queue/<enqueuedAt>-<pid>.json`, що дає видимий список очікування й позицію кожного запуску.
+`GLOBAL_CACHE_DIR` лежить в `os.tmpdir` і працює machine-wide. У ньому зберігаються `lock/owner.json` для власника лока, `queue/<enqueuedAt>-<pid>.json` для черги процесів і `progress.json` для знімка активного прогресу.
 
-Дедуплікація спирається на fingerprint і TTL у механіці лока, а не на файли стану. За неможливості безпечно дочекатися черги запуск завершується fail-closed, щоб не допустити мовчазного паралельного full-прогону.
+`lintLockFingerprint` домішує варіант виклику до знімка дерева, щоб scoped-успіх не хибно перекривав ширший прогін. `staleThreshold` піднято до 6 год, `waitTimeout` — 45 хв; після цього очікування завершується fail-closed, а не мовчазним паралельним запуском.
+
+`createProgressPublisher` оновлює `progress.json`, `renderWaitLine` відображає чергу й прогрес, а `withGlobalLintLock` є спільною точкою доступу до цього режиму.
 
 ## Поведінка
 
-- `GLOBAL_CACHE_DIR` задає спільне machine-wide місце стану для черги full-лінту, включно з `owner.json` і `progress.json`.
+`GLOBAL_CACHE_DIR` — спільний машинний кеш для всіх full-запусків lint: тут зберігаються власник лока, черга очікування і живий прогрес активного прогону. Саме цей стан робить чергу видимою між процесами та дозволяє не запускати кілька повних прогонів паралельно.
 
-- `lintLockFingerprint` формує ключ дедуплікації для full-лінту з урахуванням стану дерева й варіанта запуску; повертає порожнє значення, коли безпечно дедуплікувати неможливо.
+`lintLockFingerprint` визначає, чи можна безпечно застосувати TTL-дедуплікацію для конкретного варіанта lint. Якщо знімок дерева недоступний або виклик не відповідає поточному робочому дереву, дедуплікація вимикається і запуск іде далі по черзі. Інакше fingerprint враховує і стан дерева, і варіант виклику, щоб короткий scoped-успіх не підміняв ширший full-прогін.
 
-- `createProgressPublisher` публікує throttled-знімки прогресу активного full-прогону в `progress.json`, щоб процеси в черзі бачили живий стан без зайвого навантаження на диск.
+`withGlobalLintLock` — точка входу для повного запуску: non-full варіанти проходять одразу, а full-прогони стають у глобальну чергу, чекають звільнення лока й виконуються по одному. Після входу в лок активний запуск публікує свій прогрес у `progress.json`, а процеси в черзі читають його та показують актуальний стан очікування. Якщо запуск уже був успішно дедуплікований, результат повертається без повторного виконання.
 
-- `renderWaitLine` створює однорядковий статус очікування з позицією в черзі, поточним власником лока з `owner.json`, прогресом із `progress.json` і рештою очікувачів.
+`createProgressPublisher` пов’язує репортер прогресу активного прогону зі спільним станом: нові знімки потрапляють у файл прогресу з обмеженням частоти оновлення, щоб черга бачила живий, але стабільний стан. Це джерело правди для всіх очікувальних процесів.
 
-- `withGlobalLintLock` серіалізує лише `--full` запуски лінту через глобальну чергу, а короткі дельта/scoped/`--no-fix` запуски пропускає одразу; при timeout завершується fail-closed, щоб не допустити паралельний full-прогін.
+`renderWaitLine` збирає однорядковий статус очікування з трьох джерел: поточного власника лока, живої черги і знімка прогресу активного прогону. У результаті процес у черзі бачить, хто зараз працює, яка в нього стадія, і яке місце займає сам у загальному порядку.
 
 ## Публічний API
 
-- GLOBAL_CACHE_DIR — зберігає спільний machine-wide стан лока й черги для всіх repo та worktree; спирається на owner.json і progress.json.
-- lintLockFingerprint — формує ключ для TTL-дедуплікації за станом робочого дерева та режимом запуску lint; повертає null поза git-repo або коли --cwd відрізняється від process cwd, щоб не прив’язати прогін до чужого дерева.
-- createProgressPublisher — публікує прогрес активного lint-прогону в progress.json, щоб процеси в черзі бачили актуальний progress bar власника лока.
-- renderWaitLine — показує стан очікування в черзі: позицію процесу, поточного власника з pid і текою, його прогрес та інші queued процеси.
-- withGlobalLintLock — запускає full lint під глобальним локом і чергою; delta, scoped та --no-fix прогони стартують одразу без очікування.
+- GLOBAL_CACHE_DIR — Machine-wide директорія стану лока/черги — спільна для всіх репо й worktree.
+- lintLockFingerprint — Fingerprint для TTL-дедуплікації: стан робочого дерева + варіант виклику lint.
+null (→ дедуплікація вимкнена, черга працює) коли:
+  - не в git-репо (worktreeFingerprint дасть null);
+  - `--cwd` вказує не на процесний cwd — git-команди fingerprint-а виконуються
+    у `process.cwd()`, тож знімок відповідав би не тому дереву, що лінтиться.
+- createProgressPublisher — Publisher прогресу активного прогону: приймає знімки від
+`createProgressReporter({ onUpdate })` і (throttled) пише їх у стан-файл,
+звідки процеси в черзі читають прогрес-бар активного прогону.
+- renderWaitLine — Рядок стану черги для процесу, що стоїть у черзі: позиція, хто працює (pid + тека),
+прогрес-бар власника і перелік решти черги.
+- withGlobalLintLock — Виконує `runFn` під глобальним локом full-прогонів. Не-full варіанти
+(дельта/scoped/`--no-fix`) виконуються одразу, без лока й черги.
 
 ## Гарантії поведінки
 
-- У кожен момент на машині виконується щонайбільше один `lint --full`; запуски в черзі стартують у порядку постановки.
-- Файлові операції стану (реєстрація в черзі, публікація прогресу, читання чужих записів) — best-effort: їх збій не валить прогін, лише зменшує видимість; записи мертвих PID прибираються при читанні списку.
-- Таймаут очікування черги — виняток (fail-closed), а не мовчазний паралельний запуск.
-- Ідентичний повторний `--full` на незміненому дереві дедуплікується за fingerprint у межах TTL (exit 0 без повторної роботи); поза git-репо чи при `--cwd` не на процесний cwd дедуплікація вимикається, черга лишається.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Кешує результати в межах одного прогону.

package/scripts/lib/lint-surface/lint-lock.mjs

@@ -46,6 +46,14 @@ const PROGRESS_FILE = join(GLOBAL_CACHE_DIR, 'progress.json')
 /** Дедлайн очікування в черзі: full-прогони довгі, 20 хв дефолту withLock замало. */
 const WAIT_TIMEOUT_MS = 45 * 60_000
 
+/**
+ * Дедлайн, коли активний/очікуваний прогін включає концерн coverage правила
+ * `test` (spec absorb-7n-test, ризик 3.4): повне мутаційне тестування
+ * (Stryker/cargo-mutants) на великому проєкті не вкладається у 45 хв —
+ * інженерний запас ×4 замість вгадування точної тривалості.
+ */
+const WAIT_TIMEOUT_WITH_COVERAGE_MS = 4 * WAIT_TIMEOUT_MS
+
 /** Поріг time-based staleness (див. модульний коментар). */
 const STALE_THRESHOLD_MS = 6 * 3_600_000
 
@@ -235,10 +243,13 @@ export function withGlobalLintLock(variant, runFn, opts = {}) {
   if (!variant.full) return Promise.resolve(runFn())
   const { isTTY, log, queueDir, progressFile, ...lockOpts } = opts
   const ui = createWaitUi({ isTTY, log, queueDir, progressFile })
+  // Full-прогін завжди включає концерн coverage (мутаційне тестування) —
+  // черга чекає з покриттєвим запасом; scoped `lint test` під лок не йде
+  // (variant.full=false), тож окремої осі для нього не треба.
   return withLock('lint-full', runFn, {
     cacheDir: GLOBAL_CACHE_DIR,
     staleThreshold: STALE_THRESHOLD_MS,
-    waitTimeout: WAIT_TIMEOUT_MS,
+    waitTimeout: WAIT_TIMEOUT_WITH_COVERAGE_MS,
     onWaitTimeout: 'fail',
     getFingerprint: () => lintLockFingerprint(variant),
     ...ui,

package/skills/taze/js/docs/migration-cache.md

@@ -3,35 +3,51 @@ type: JS Module
 title: migration-cache.mjs
 resource: npm/skills/taze/js/migration-cache.mjs
 docgen:
-  crc: 5f264929
-  model: openai-codex/gpt-5.4-mini
-  tier: cloud-min
+  crc: c9ebf692
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
   score: 100
-  issues: judge:inaccurate:0.98
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Модуль керує кешем уже відомих міграцій на диску (`~/.cache/n-rules/taze-migrations` за замовчуванням) — кеш персистентний і спільний для всіх repo/worktree на машині, не обмежений одним прогоном. `migrationCacheKey` формує ключ для запису, `readMigrationCache` і `writeMigrationCache` працюють із кешованими даними, а `withKnownMigrationNotes` підставляє вже відомі відомості там, де це доречно. Читання fail-safe (`readMigrationCache` перехоплює помилки й повертає `null` замість винятку); запис (`writeMigrationCache`) винятків не перехоплює.
+Файл підтримує дисковий кеш нотаток про міграції пакетів між версіями для повторного використання між прогонами й репозиторіями, щоб повторне звернення до тих самих даних не виконувало зайву роботу. `DEFAULT_CACHE_DIR`, `migrationCacheKey`, `readMigrationCache`, `writeMigrationCache` і `withKnownMigrationNotes` задають спільні точки доступу до цього кешу.
+
+Якщо кеш недоступний, запис непридатний або операція читання кешу не може бути виконана, обробка продовжується без винятків назовні й за потреби повертає порожнє значення замість збою.
 
 ## Поведінка
 
-- `DEFAULT_CACHE_DIR` — задає спільний каталог кешу міграцій для всіх репозиторіїв на цій машині.
-- `migrationCacheKey` — перетворює пару версій пакета на безпечний крос-репо ключ кешу.
-- `readMigrationCache` — читає кешований запис міграції для конкретної пари версій; якщо запису немає або він пошкоджений, повертає `null` без помилки.
-- `writeMigrationCache` — зберігає запис про вже проаналізовану міграцію в кеш, щоб не повторювати той самий аналіз у наступних прогонових середовищах.
-- `withKnownMigrationNotes` — додає до промпта підсумок відомої міграції з кешу й підказує пропустити повторне дослідження та перейти до перевірки в поточному проєкті.
+DEFAULT_CACHE_DIR задає спільне місце зберігання результатів аналізу міграцій для всіх репозиторіїв на машині. Кеш не прив’язаний до поточного проєкту, тому повторне оновлення того самого пакета між тими самими версіями може повторно використати вже підготовлені нотатки.
+
+migrationCacheKey формує стабільний безпечний ключ для пари пакет-версії. Цей ключ використовують readMigrationCache і writeMigrationCache, щоб звертатися до одного й того самого запису незалежно від репозиторію чи worktree.
+
+writeMigrationCache зберігає підсумок ізольованого LLM-аналізу міграції. Дані потрапляють у спільний кеш і стають доступними для наступних прогонів із тим самим ключем.
+
+readMigrationCache на початку наступного прогону шукає готовий запис у спільному кеші. Якщо запис відсутній або непридатний для читання, кеш вважається недоступною оптимізацією й повертається порожній результат замість помилки; основний процес міграції має продовжитися без кешованих нотаток.
+
+Коли readMigrationCache знаходить запис, withKnownMigrationNotes додає його підсумок до базового промпта. Результат спрямовує runner не повторювати вже виконане CHANGELOG/diff-дослідження, а одразу перевіряти використання API в поточному проєкті та застосовувати релевантні зміни.
 
 ## Публічний API
 
-- DEFAULT_CACHE_DIR — Спільний каталог для кешу міграцій на цій машині, незалежний від конкретного repo чи worktree.
-- migrationCacheKey — Перетворює `pkg`, `from` і `to` на безпечну назву файла для спільного кешу.
-- readMigrationCache — Повертає збережені дані про вже відому міграцію для тієї самої пари версій, або `null`, якщо запису немає чи він пошкоджений.
-- writeMigrationCache — Записує результат вже розібраної міграції в кеш, щоб наступний repo з тим самим оновленням не починав дослідження заново.
-- withKnownMigrationNotes — Додає до prompt короткий підсумок знайденої міграції і пропускає початковий етап з пошуком у CHANGELOG та diff.
+- DEFAULT_CACHE_DIR — Каталог за замовчуванням для кешу міграцій — спільний для всіх репо на цій
+машині (не прив'язаний до конкретного worktree/репо), бо ключ кешу — сам
+пакет+діапазон версій, а не проєкт.
+- migrationCacheKey — Санітизує `(pkg, from, to)` у безпечне імʼя файлу — крос-репо ключ кешу.
+Той самий `(pkg, from, to)` у різних репо/воркспейсах дає той самий ключ.
+- readMigrationCache — Читає кешований запис міграції для `(pkg, from, to)`, якщо інший
+repo/worktree на цій машині вже проганяв через LLM ту саму пару версій.
+Відсутній/побитий файл — `null` (мовчки, не провал прогону: кеш —
+оптимізація, а не залежність, від якої залежить коректність).
+- writeMigrationCache — Зберігає результат ізольованого LLM-виклику для `(pkg, from, to)` — щоб
+наступний репо з тим самим bump-ом на цій машині не повторював
+CHANGELOG-дослідження з нуля (див. `readMigrationCache`).
+- withKnownMigrationNotes — Дописує до промпта `provider.promptFor(entry)` підсумок відомої міграції,
+якщо кеш її знайшов — каже runner-у пропустити крок 1 (CHANGELOG/diff-
+дослідження) і одразу шукати використання в поточному проєкті.
 
 ## Гарантії поведінки
 
-- `readMigrationCache` перехоплює помилки читання/парсингу й повертає `null` замість винятку (fail-safe); `writeMigrationCache` винятків не перехоплює.
-- Кеш персистентний на диску і спільний для всіх repo/worktree на машині — не обмежений одним прогоном.
+- Перехоплює помилки операцій кешу, для яких кеш є необовʼязковою оптимізацією, і не пропускає їх назовні.
+- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.
+- Кешує результати на диску для повторного використання між прогонами й репозиторіями.