@7n/rules 1.44.0 → 1.45.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [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
+
+- worktree-only скіли (n-lint/n-taze/n-adr-normalize): preflight і ensureRunningInWorktree визнають .claude/worktrees/ (harness Claude Code) як вже ізольований worktree — не пропонують створювати вкладене .worktrees/ дерево
+
 ## [1.44.0] - 2026-07-22
 
 ### Added

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.0",
+  "version": "1.45.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/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/scripts/lib/auto-worktree.mjs

@@ -28,7 +28,9 @@ async function defaultConfirm(message) {
  * Гарантує, що подальші кроки виконуються в ізольованому worktree
  * (`main.json.worktree: true`-контракт), навіть коли викликач — детермінований
  * JS-код, що не годує SKILL.md жодному LLM-агенту (тож агентський preflight-блок
- * з `worktree-notice.mjs` нікому виконувати). Якщо `cwd` вже під `.worktrees/` —
+ * з `worktree-notice.mjs` нікому виконувати). Якщо `cwd` вже під `.worktrees/`
+ * (репо-конвенція) або `.claude/worktrees/` (worktree харнесу Claude Code,
+ * куди `npx \@7n/mt worktree create` класти заборонено — `n-worktree.mdc`) —
  * повертає його без змін. Інакше сам створює `.worktrees/<branch>-<suffix>`
  * (`npx \@7n/mt worktree create`) і ставить залежності (`bun install`).
  *
@@ -62,8 +64,12 @@ export async function ensureRunningInWorktree(
 ) {
   const toplevelResult = spawnFn('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' })
   const toplevel = toplevelResult.status === 0 ? toplevelResult.stdout.trim() : ''
-  const segments = new Set(toplevel.replaceAll('\\', '/').split('/'))
-  if (segments.has('.worktrees')) return { cwd, autoCreated: false, branchArg: null }
+  const pathSegments = toplevel.replaceAll('\\', '/').split('/')
+  const segments = new Set(pathSegments)
+  const isClaudeHarnessWorktree = pathSegments.some(
+    (seg, i) => seg === '.claude' && pathSegments[i + 1] === 'worktrees'
+  )
+  if (segments.has('.worktrees') || isClaudeHarnessWorktree) return { cwd, autoCreated: false, branchArg: null }
 
   const branchResult = spawnFn('git', ['branch', '--show-current'], { cwd, encoding: 'utf8' })
   const currentBranch = branchResult.status === 0 ? branchResult.stdout.trim() : ''

package/scripts/lib/docs/auto-worktree.md

@@ -3,28 +3,66 @@ type: JS Module
 title: auto-worktree.mjs
 resource: npm/scripts/lib/auto-worktree.mjs
 docgen:
-  crc: bae09068
-  model: openai-codex/gpt-5.4-mini
-  score: 100
-  issues: judge:inaccurate:0.98
-  judgeModel: openai-codex/gpt-5.4-mini
+  crc: 2a9e7bfd
+  model: omlx/gemma-4-e2b-it-4bit
+  tier: local-min-retry
+  score: 90
 ---
 
 ## Огляд
 
-Файл керує запуском у ізольованому worktree, щоб підготувати зміни в окремому середовищі, потім викликати bringChangesBackToOriginal для повернення результату до вихідного дерева і removeAutoCreatedWorktree для очищення тимчасового worktree. Поведінка спирається на конфіг main.json.
+Функції забезпечують ізоляцію роботи з кодом у worktree, перенесення змін між робочими середовищами та керування життєвим циклом створеного worktree. ensureRunningInWorktree гарантує роботу в ізольованому середовищі, bringChangesBackToOriginal переносить модифікації з worktree назад до основного репозиторію, використовуючи механізм копіювання, а не git merge, removeAutoCreatedWorktree забезпечує прибирання, видаляючи сам worktree після завершення операції.
 
 ## Поведінка
 
-- `ensureRunningInWorktree` — перевіряє, чи виконання вже йде в ізольованому worktree; якщо ні, за потреби створює його для поточної гілки, ставить залежності й повертає новий `cwd`.
-- `bringChangesBackToOriginal` — переносить зміни з автоствореного worktree назад у вихідне дерево як untracked/незакомічені правки, включно з додаванням, оновленням і видаленням файлів; перейменування переносить лише в нову назву.
-- `removeAutoCreatedWorktree` — прибирає автостворений worktree разом із його ефемерною гілкою після перенесення змін назад, а у разі збою лише повідомляє про ручне прибирання.
+Поведінка: Функції взаємодіють для ізоляції роботи з кодом у worktree, перенесенні змін між робочими середовищами та керування життєвим циклом створюваного worktree. `ensureRunningInWorktree` гарантує роботу в ізольованому середовищі, тоді як `bringChangesBackToOriginal` переносить модифікації з worktree назад до основного репозиторію, використовуючи механізм копіювання, а не git merge. `removeAutoCreatedWorktree` забезпечує прибирання, видаляючи сам worktree, що виконується лише після завершення операції з `bringChangesBackToOriginal`.
 
 ## Публічний API
 
-- ensureRunningInWorktree — Гарантує ізольований worktree для наступних кроків; якщо вже працюєш у `.worktrees/`, лишає поточний каталог без змін, інакше створює окремий worktree та ставить залежності. За замовчуванням на брудному дереві питає в терміналі (y/N) дозвіл закомить і запушити зараз через `npx @7n/n push`, і лише на "ні" (або поза TTY) кидає; це можна послабити (`requireCleanTree: false`) лише там, де чистоту вже забезпечили іншим способом.
-- bringChangesBackToOriginal — Повертає зміни з автоствореного worktree у початкове дерево простим копіюванням файлів: нові й змінені файли переносять, видалені — прибирають у вихідному дереві. Працює як перенесення фактичного стану, а не як merge.
-- removeAutoCreatedWorktree — Прибирає тимчасовий worktree та пов’язану з ним ephemeral branch після того, як зміни вже перенесено назад; якщо прибирання не вдалось, залишає worktree для ручного розбору.
+- ensureRunningInWorktree — Гарантує, що подальші кроки виконуються в ізольованому worktree
+(`main.json.worktree: true`-контракт), навіть коли викликач — детермінований
+JS-код, що не годує SKILL.md жодному LLM-агенту (тож агентський preflight-блок
+з `worktree-notice.mjs` нікому виконувати). Якщо `cwd` вже під `.worktrees/`
+(репо-конвенція) або `.claude/worktrees/` (worktree харнесу Claude Code,
+куди `npx \@7n/mt worktree create` класти заборонено — `n-worktree.mdc`) —
+повертає його без змін. Інакше сам створює `.worktrees/<branch>-<suffix>`
+(`npx \@7n/mt worktree create`) і ставить залежності (`bun install`).
+
+**Гейт на чисте дерево.** Auto-create читає стан і потім переносить зміни
+назад копіюванням файлів (`bringChangesBackToOriginal`) — а не git merge.
+Якщо у вихідному `cwd` вже є незакомічені зміни, вони НЕ потраплять у щойно
+створений worktree (той — checkout HEAD), і перенесення назад мовчки
+затерло б їх версією з worktree. Тому за замовчуванням (`requireCleanTree:
+true`) на брудному дереві auto-create питає в терміналі (`deps.confirm`,
+дефолт — y/N через stdin; поза TTY одразу "ні") дозвіл закомить і
+запушити зараз через `npx \@7n/n push` (сквош усього робочого дерева в один
+коміт + push у origin — сама команда підтвердження не питає, тому питаємо
+ми, ДО виклику). На "ні"/поза TTY — кидає, як і раніше. Викликач, що
+гарантує чистоту дерева сам (наприклад taze — SKILL.md вимагає цього як
+передумову ще ДО виклику), може передати `requireCleanTree: false`, щоб не
+платити за зайву git-команду і не питати підтвердження.
+- bringChangesBackToOriginal — Переносить зміни з автоствореного worktree назад у вихідне дерево як
+**untracked/незакомічені** правки (просте копіювання файлів, без git
+merge/cherry-pick). Джерело істини — `git status --porcelain` у worktree:
+для кожного шляху копіює файл, якщо він існує (модифікація/додавання), або
+видаляє його у вихідному дереві, якщо existsSync каже, що в worktree його
+вже нема (видалення). Перейменування (`old -> new` у porcelain) переносять
+лише нову назву — стара лишається як була, прийнятний компроміс для
+інструментів, що самі файли не перейменовують (ефект можливий лише як
+побічний результат LLM-рефакторингу чи форматера).
+
+**Untracked-директорія цілком.** Git схлопує щойно створену untracked
+директорію в один porcelain-рядок із `/` на кінці (якщо в ній нема жодного
+файлу, вже відомого git) — `copyFile` на такий шлях впав би (`EISDIR`/`ENOENT`)
+і обривав би цикл, гублячи все, що йшло по порядку ітерації ДАЛІ. Такий
+рядок (суфікс `/` або реальний каталог на диску) копіюється рекурсивно
+(`copyDirectoryRecursive`) — весь вміст, а не один `copyFile`.
+- removeAutoCreatedWorktree — Прибирає автостворений worktree разом з його ефемерною git-гілкою
+(`npx \@7n/mt worktree remove <branch>`) — викликати лише ПІСЛЯ
+`bringChangesBackToOriginal`, інакше зміни згорять разом з деревом.
+Не кидає при провалі — це прибирання, а не крок, від якого залежить
+результат прогону; провал лише логується, worktree лишається для
+ручного розбору.
 
 ## Гарантії поведінки
 

package/scripts/lib/docs/worktree-notice.md

@@ -3,25 +3,80 @@ type: JS Module
 title: worktree-notice.mjs
 resource: npm/scripts/lib/worktree-notice.mjs
 docgen:
-  crc: 174d1f15
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 4feb8b6c
+  model: omlx/gemma-4-e2b-it-4bit
+  tier: local-min-retry
   score: 100
 ---
 
-Управляє вставкою інструкцій для виконання команд у ізольованому git-worktree у синкнутий `SKILL.md` (рішення D2 зі spec). Коли `main.json.worktree === true`, інструкції вставляються між маркерами `WORKTREE_START` та `WORKTREE_END`. Це забезпечує ре-синк ідемпотентність: наявний блок замінюється, а при `main.json.worktree === false` — видаляється. Механізм адаптований для агента, який читає `SKILL.md`.
+## Огляд
+
+Цей файл містить інструкції для вбудовування вказівки про використання worktree-гілки в синкнутий текст `SKILL.md`. Він забезпечує ідемпотентне заміщення або видалення цього блоку залежно від значення `main.json.worktree`, забезпечуючи зв'язок з інструкціями щодо роботи з окремими Git-репозиторіями та інструментами для управління залежностями та бінарними викликами.
+
+## Behavior
+Транслітерує кирилицю в ASCII для короткого suffix
+@param {string} value вхідний текст
+@returns {string} транслітерований текст
+
+### deriveSuffix
+Робить короткий безпечний suffix для worktree-гілки з назви скіла
+@param {string} content вміст `SKILL.md`
+@returns {string} suffix до 10 символів
+викликає: transliterate
+
+### buildNoticeBody
+Тіло worktree-інструкції з конкретним суфіксом, щоб агент не питав назву гілки
+@param {string} suffix короткий suffix задачі
+@returns {string} markdown-блок без маркерів
+
+### buildBlock
+Канонічний блок worktree-інструкції
+@param {string} content вміст `SKILL.md`
+@returns {string} текст блоку від START до END
+викликає: buildNoticeBody
+
+### injectWorktreeNotice
+Вставляє / оновлює / видаляє worktree-блок у вмісті `SKILL.md`
+@param {string} content вміст `SKILL.md`
+@param {boolean} enabled чи має бути блок значення `main.json.worktree`
+@returns {string} оновлений вміст ідемпотентно
 
 ## Поведінка
 
-WORKTREE_START: Позначає початок блоку інструкцій для роботи в окремому git-worktree.
-WORKTREE_END: Позначає кінець блоку інструкцій для роботи в окремому git-worktree.
-injectWorktreeNotice: Вставляє, оновлює або видаляє блок інструкцій для роботи в worktree у вмісті SKILL.md залежно від булевого значення.
+Транслітерує кирилицю в ASCII для короткого suffix
+@param {string} value вхідний текст
+@returns {string} транслітерований текст
+
+### deriveSuffix
+Робить короткий безпечний suffix для worktree-гілки з назви скіла
+@param {string} content вміст `SKILL.md`
+@returns {string} suffix до 10 символів
+викликає: transliterate
+
+### buildNoticeBody
+Тіло worktree-інструкції з конкретним суфіксом, щоб агент не питав назву гілки
+@param {string} suffix короткий suffix задачі
+@returns {string} markdown-блок без маркерів
+
+### buildBlock
+Канонічний блок worktree-інструкції
+@param {string} content вміст `SKILL.md`
+@returns {string} текст блоку від START до END
+викликає: buildNoticeBody, deriveSuffix
+
+### injectWorktreeNotice
+Вставляє / оновлює / видаляє worktree-блок у вмісті `SKILL.md`
+@param {string} content вміст `SKILL.md`
+@param {boolean} enabled чи має бути блок значення `main.json.worktree`
+@returns {string} оновлений вміст ідемпотентно
+викликає: buildBlock
 
 ## Публічний API
 
-WORKTREE_START — Позначає початок блоку, що описує робоче дерево.
-WORKTREE_END — Позначає кінець блоку, що описує робоче дерево.
-injectWorktreeNotice — Додає, змінює або видаляє блок робочого дерева у файлі `SKILL.md`.
+- WORKTREE_START — Маркер початку worktree-блоку (стабільний, не залежить від тексту всередині).
+- WORKTREE_END — Маркер кінця worktree-блоку.
+- injectWorktreeNotice — Вставляє / оновлює / видаляє worktree-блок у вмісті `SKILL.md`.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/scripts/lib/worktree-notice.mjs

@@ -133,7 +133,9 @@ git branch --show-current
 
 **Root-assert.** Якщо \`pwd\` **не** збігається з виводом \`git rev-parse --show-toplevel\` — ти в **піддиректорії** робочого дерева (worktree-шляхи нижче відносні до кореня репо). Спершу перейди в корінь: \`cd <toplevel>\` (literal-шлях із виводу), і лише тоді продовжуй preflight. Не створюй worktree з піддиректорії — \`cd .worktrees/<…>\` звідти впаде.
 
-Якщо \`git rev-parse --show-toplevel\` показав, що ти **не** в \`.worktrees/\`, візьми вивід \`git branch --show-current\` як \`<current-branch>\` і виконай **literal-команди без shell expansion** (без command substitution, variable expansion чи backticks). Наприклад, якщо поточна гілка \`feature/x\`:
+**Вже ізольований — нічого не створюй.** Якщо \`git rev-parse --show-toplevel\` містить сегмент \`.worktrees/<…>\` (репо-конвенція) **або** \`.claude/worktrees/<…>\` (worktree харнесу Claude Code — туди \`npx @7n/mt worktree create\` класти заборонено, \`n-worktree.mdc\`) — ти вже виконуєшся в окремому git-worktree. Preflight пройдено: нічого не створюй, нікого не питай про назву гілки — переходь одразу до Кроку 0.1.
+
+Інакше, якщо toplevel не містить жодного з цих сегментів, візьми вивід \`git branch --show-current\` як \`<current-branch>\` і виконай **literal-команди без shell expansion** (без command substitution, variable expansion чи backticks). Наприклад, якщо поточна гілка \`feature/x\`:
 
 \`\`\`bash
 npx @7n/mt worktree create "feature/x-${suffix}" "n-${suffix}: worktree-only skill"
@@ -142,10 +144,10 @@ cd ".worktrees/feature-x-${suffix}"
 
 Тобто branch-argument лишає slash як у git-гілці, а шлях для \`cd\` бере sanitized форму: slash → \`-\`.
 
-**Крок 0.1 — bootstrap у новому дереві (після \`cd\`).** Дерево щойно створене й **без** \`node_modules\`. Постав залежності локально — тоді \`npx @7n/rules <cmd>\` бере локальну копію без походу в реєстр:
+**Крок 0.1 — bootstrap (якщо в дереві ще нема \`node_modules\`).** Свіжостворений worktree (Крок 0) точно без \`node_modules\`; вже ізольований harness-worktree може мати їх або ні — постав локально, тоді \`npx @7n/rules <cmd>\` бере локальну копію без походу в реєстр:
 
 \`\`\`bash
-bun install
+test -d node_modules || bun install
 \`\`\``
 }
 

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`) замість винятку.
+- Кешує результати на диску для повторного використання між прогонами й репозиторіями.