@7n/rules 1.43.0 → 1.44.0

package/scripts/lib/adr/docs/normalize-pipeline.md

@@ -3,42 +3,58 @@ type: JS Module
 title: normalize-pipeline.mjs
 resource: npm/scripts/lib/adr/normalize-pipeline.mjs
 docgen:
-  crc: f8bd18e2
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 7840afd7
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  issues: judge-refine:kept-original,judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Реалізує локально-орієнтований конвеєр для нормалізації ADR. У цій системі JavaScript виконує оркестрацію, тоді як LLM відповідає виключно на вузькі, верифіковані питання. Процес включає відбір кандидатів на основі лексичної схожості (Stage 0: retrieval), бінарне судження між записами (Stage 1: edge-judge) та класифікацію драфтів (Stage 1b: kind-judge). Система об'єднує підтверджені ребра через алгоритм Union-Find (Stage 1c: cluster) для вибору опорного елемента (anchor) та призначення операцій. Далі, LLM вилучає секції в JSON (Stage 2: gen-MADR), після чого JS збирає канон. На фінальній стадії, LLM створює прозу про змін (Stage 3: gen-merge), яку JS додає до документа з відповідним заголовком.
+## Огляд
+
+Файл готує ADR-чернетки до застосування як `operations[]` у тому самому контракті, що й single-shot-пайплайн, сумісному з `apply-ops`: створення нового MADR, доповнення наявного ADR або пропуск. Він існує як локально-орієнтована альтернатива для малої LLM `omlx/gemma-4b`, де JS керує retrieval, кластерами, датами, MADR-каркасом і після кластеризації призначає `op`, а модель дає лише вузькі перевірювані судження та фрагменти змісту.
 
 ## Поведінка
 
-Поведінка
-tokenize токенізує назву чи слаг, повертаючи множину значущих токенів, фільтруючи стоп-слова та занадто короткі елементи.
-jaccard обчислює коефіцієнт Jaccard між двома множинами токенів.
-draftTitle витягує заголовок з тіла чернетки, використовуючи специфічні шаблони або шукаючи перший заголовок H1, не класифікований як секція MADR.
-isNoDecision перевіряє тіло чернетки на наявність маркерів, що свідчать про те, що рішення не було прийняте, без використання LLM.
-buildEdges будує пари (ребра) між чернетками та між чернетками і список чистих ADR, виходячи з лексичної схожості.
-validateMadr перевіряє згенерований текст MADR на відповідність формату OKF (наприклад, наявність YAML frontmatter, заголовок, статуси та секції).
-madrDate визначає стандартну ISO-дату для ADR, використовуючи або поле `captured` з чернетки, або префікс імені файлу.
-normalizeSections перетворює сирий JSON-вивід моделі на структурований об'єкт, нормалізуючи типи даних (наприклад, рядок у масив).
-assembleMadr збирає канонічний текст MADR, комбінуючи наданий заголовок, ISO-дату та нормалізовані секції, створюючи кінцевий markdown.
-genMadr викликає LLM для вилучення змісту ADR із чернетки, а потім конструює та валідує повний MADR за допомогою `assembleMadr` та `validateMadr`.
-normalizePipeline виконує повний конвеєр: ідентифікує кластери чернеток, визначає операції (delete, rewrite, merge-anchor тощо) та ініціює виклики LLM для генерації контенту та додатків.
+`normalizePipeline` приймає батч ADR-чернеток і список уже чистих ADR, після чого веде їх через послідовність дрібних перевірюваних рішень. Глобальні рішення про зв’язки, кластери, цільові документи й фінальні operations залишаються в JS; LLM використовується лише для вузьких локальних суджень і генерації контрольованих фрагментів.
+
+На початку потоку `draftTitle` дістає робочу назву кожної чернетки, а `isNoDecision` відсікає записи, де рішення явно не прийняте. Для решти `buildEdges` створює кандидатні зв’язки між чернетками та між чернетками і clean ADR: назви й слаги проходять через `tokenize`, а близькість кандидатів оцінює `jaccard`. Це retrieval-етап: він лише звужує простір порівнянь, а не приймає остаточне рішення про злиття.
+
+Далі `normalizePipeline` перевіряє кандидатні зв’язки через LLM-судження «те саме рішення чи ні», консервативно об’єднує підтверджені зв’язки в кластери й призначає для кожної чернетки дію: створити новий ADR, доповнити наявний або пропустити як тривіальну/непридатну. Ізольовані чернетки додатково класифікуються як standalone або trivial, щоб не створювати ADR без достатньої змістовної ваги.
+
+Коли потрібен новий ADR, `genMadr` перетворює одну чернетку на MADR-документ. Дату для канонічного каркаса визначає `madrDate`; модель повертає лише зміст секцій, який приводить до стабільної форми `normalizeSections`. Після цього `assembleMadr` збирає повний MADR із контрольованим заголовком, датою, статусом, назвами секцій, fallback-текстами й bullet-структурою. `validateMadr` є фінальним quality gate: невалідний документ не потрапляє в operations як готовий вміст.
+
+Коли чернетка має доповнити наявний ADR, `normalizePipeline` генерує лише новий зміст оновлення, а службовий заголовок оновлення та дата лишаються під контролем JS через ту саму політику дат. Це зберігає однаковий формат для створення нових ADR і для merge-доповнень.
+
+Результатом `normalizePipeline` є operations у тому самому контракті, що й single-shot-пайплайн, разом зі статистикою та діагностичним trace. Подальше застосування змін виконується спільною apply-логікою поза цим файлом; цей конвеєр лише готує перевірені наміри змін і не покладається на кешування.
 
 ## Публічний API
 
-Here is the rewritten list as concise bullet points:
-
-* tokenize — Перетворює назву чи слаг у набір значущих слів, розділених пробілами та дефісами.
-* jaccard — Обчислює ступінь схожості між двома наборами слів.
-* draftTitle — Знаходить основний заголовок чернетки, починаючи з ADR-рядка; якщо його немає, шукає перший H1, інакше бере назву файлу.
-* isNoDecision — Автоматично виявляє чернетки, де рішення відсутнє (наприклад, через переривання транскрипту), щоб їх не обробляти LLM.
-* buildEdges — Створює потенційні зв'язки між елементами на основі схожості слів.
-* validateMadr — Перевіряє якість згенерованого документа MADR автоматично.
-* madrDate — Визначає дату документа у форматі ISO, використовуючи дані з метаданих чернетки або дату створення файлу.
-* normalizeSections — Стандартизує вивід генеративної моделі в чітку структуру секцій, виправляючи невеликі помилки формату.
-* assembleMadr — Збирає повний документ MADR у версії 4.0.0, використовуючи фіксовану структуру та контент від інших частин.
-* genMadr — Генерує чернетку документа MADR на основі заданих даних.
-* normalizePipeline — Виконує послідовність усіх кроків обробки даних, повертаючи список виконаних операцій та статистику.
+- tokenize — Токенізує назву/слаг у множину значущих токенів (kebab + пробіли, без стоп-слів).
+- jaccard — Jaccard-схожість двох множин токенів.
+- draftTitle — Витягує заголовок драфта. Капчер пише `## ADR <title>` — він у пріоритеті
+(чернетка може мати контент-заголовки раніше або взагалі не мати ADR-рядка).
+Fallback-и: перший h1, що не є MADR-секцією, інакше '' (caller бере імʼя файлу).
+- isNoDecision — Детермінований no-decision гейт (харднінг #1). Чернетка, де у `Decision Outcome`
+рішення явно НЕ прийняте (transcript обірвався) — не варта окремого ADR: gold
+(sonnet) такі видаляє. Ловимо без LLM, щоб не покладатися на kind-judge малої моделі.
+- buildEdges — Будує кандидати-ребра за лексичною схожістю.
+- validateMadr — Детермінований гейт якості згенерованого MADR.
+- madrDate — Детермінована ISO-дата для поля **Date:**. Пріоритет — `captured` frontmatter
+(перші 10 символів ISO-стемпа); fallback — timestamp-префікс імені файлу
+(`YYMMDD-…` → `20YY-MM-DD`). Каркас MADR не повинен залежати від LLM навіть тут.
+- normalizeSections — Нормалізує сирий JSON-вивід gen-моделі у строгу форму секцій. Толерантна до
+дрібних відхилень малої моделі: рядок замість масиву → масив із одного елемента,
+число/null → рядок/порожньо, обрізає пробіли й порожні елементи.
+- assembleMadr — Детермінована збірка канонічного MADR 4.0.0 з заголовка, дати й секцій-контенту.
+Увесь каркас (Status, назви секцій, шаблон "Chosen option…", fallback-фрази,
+bullets) — тут, не в моделі. Заголовок і дата — JS-власність (draftTitle/captured),
+модель їх не торкається.
+- genMadr — Stage 2: перетворює одну чернетку на валідний MADR-документ. Модель лише
+витягує зміст секцій як JSON; каркас збирає JS, результат проганяється через
+валідатор із ретраями каскаду. При невдачі повертає `valid: false` без вмісту.
+- normalizePipeline — Головний конвеєр. Повертає operations[] (контракт single-shot) + stats.
 
 ## Гарантії поведінки
 

package/scripts/lib/adr/normalize-pipeline.mjs

@@ -459,6 +459,17 @@ export function assembleMadr({ title, date, sections: s }) {
   ].join('\n')
 }
 
+/**
+ * Stage 2: перетворює одну чернетку на валідний MADR-документ. Модель лише
+ * витягує зміст секцій як JSON; каркас збирає JS, результат проганяється через
+ * валідатор із ретраями каскаду. При невдачі повертає `valid: false` без вмісту.
+ * @param {string} title заголовок рішення
+ * @param {string} body тіло чернетки (обрізається до безпечного розміру)
+ * @param {string} captured момент фіксації чернетки (для дати MADR)
+ * @param {{allowCloud: boolean, stats: object}} cfg конфіг каскаду й лічильники
+ * @param {string} [file] шлях чернетки — fallback-джерело дати
+ * @returns {Promise<{content: string | null, slug: string, valid: boolean, error?: string}>} зібраний документ або позначка невдачі
+ */
 export async function genMadr(title, body, captured, cfg, file = '') {
   const date = madrDate(captured, file)
   const slug = slugify(title)

package/scripts/lib/docs/inline-template-links.md

@@ -3,23 +3,32 @@ type: JS Module
 title: inline-template-links.mjs
 resource: npm/scripts/lib/inline-template-links.mjs
 docgen:
-  crc: 35230d2d
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: dde8124c
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
   score: 100
+  issues: judge-refine:kept-original,judge:inaccurate:0.96
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Модуль збагачує текстовий контент, використовуючи конфігурації з package.json.snippet.json та package.json. Функція inlineTemplateLinks замінює текстові посилання на шаблони вбудованими блоками, якщо відповідні файли знаходяться у директорії правил. Функція appendDiscoveredMdcFiles доповнює текст вмістом усіх знайдених файлів `.mdc` з піддиректорій `js/` та `policy/` у директорії правил.
+## Огляд
+
+Перетворює markdown-лінки на файли з `template/` у fenced-блоки з фактичним вмістом цих файлів і додає знайдені `.mdc`-правила, щоб зібраний `.mdc` лишався самодостатнім для подальшого використання без відносних шляхів. Поведінку реалізують `inlineTemplateLinks` і `appendDiscoveredMdcFiles`.
 
 ## Поведінка
 
-inlineTemplateLinks замінює посилання на шаблони в тексті на вбудовані блоки з вмістом файлу, якщо ці файли існують у вказаній директорії правил.
-appendDiscoveredMdcFiles додає до кінця тексту вміст усіх знайдених файлів `.mdc` з піддиректорій `js/` та `policy/` у директорії правил.
+inlineTemplateLinks спочатку підбирає лише ті markdown-лінки, що ведуть у template-піддерево, і замінює їх самодостатнім вбудованим фрагментом із фактичним вмістом файлу; так правило перестає залежати від відносних посилань. Для вкладених прикладів і слот-файлів відновлюється читабельна назва цілі, зокрема для `package.json.snippet.json` і `package.json`, а формат fenced-блока обирається за розширенням вмісту. Якщо ціль не знайдено, обробка зупиняється з помилкою, щоб згенерований `.mdc` не містив битих посилань.
+
+appendDiscoveredMdcFiles далі доповнює вже оброблений текст усіма знайденими `.mdc`-файлами з піддиректорій, які позначені через `concern.json`; це дає змогу зібрати повний пакет правил без ручного перелічення допоміжних файлів. Порядок стабільний: спочатку директори сортуються, потім файли всередині кожного каталогу, а результати додаються в кінець як один суцільний блок. Якщо таких директорій немає, початковий текст лишається без змін.
 
 ## Публічний API
 
-inlineTemplateLinks — Замінює посилання на шаблони в Markdown на вбудовані блоки, якщо шлях містить `/template/`. Помилка виникає, якщо цільовий файл посилання відсутній.
-appendDiscoveredMdcFiles — Додає всі знайдені файли `.mdc` з папок `js/` та `policy/<concern>/`. Файли з `js/` йдуть першими, а потім файли з підпапок `policy/<concern>/` (у алфавітному порядку за `concern`, а потім за назвою файлу).
+- inlineTemplateLinks — Finds markdown links whose path contains /template/ and replaces them with
+inline fenced blocks. Reads file from join(ruleDir, rel-path).
+Throws Error if a matched link target doesn't exist (fail loud — user must know).
+- appendDiscoveredMdcFiles — Appends all *.mdc files from concern subdirectories (those with concern.json).
+Concerns ordered alphabetically; files within each concern ordered alphabetically.
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/scripts/lib/docs/plugin-api.md

@@ -3,7 +3,7 @@ type: JS Module
 title: plugin-api.mjs
 resource: npm/scripts/lib/plugin-api.mjs
 docgen:
-  crc: c614a880
+  crc: 72b55c0e
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98

package/scripts/lib/inline-template-links.mjs

@@ -1,3 +1,8 @@
+/**
+ * Інлайн template-посилань у .mdc-правилах: markdown-лінки на файли з тек
+ * template/ замінюються fenced-блоками з фактичним вмістом файлу, щоб
+ * згенероване правило було самодостатнім без відносних шляхів.
+ */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { basename, extname, join } from 'node:path'

package/scripts/lib/lint-surface/docs/run-detectors.md

@@ -3,42 +3,45 @@ type: JS Module
 title: run-detectors.mjs
 resource: npm/scripts/lib/lint-surface/run-detectors.mjs
 docgen:
-  crc: a0f45fc3
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: e9224e37
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
   score: 100
-  issues: judge:inaccurate:0.98
+  issues: judge-refine:kept-original,judge:inaccurate:0.99
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Цей файл є детектором для уніфікованої поверхні лінту, який сканує код без внесення змін. Він виконує процес вибору області перевірки (`scope-selection`), збирає всі виявлені порушення (`normalized violations`) для кожного аспекту (`concern`) відповідно до конфігурації `.n-rules.json`. Цей компонент працює у режимі `Detect-only`, тобто він не вносить жодних мутацій і не використовує LLM. Порушення передаються до пайплайну виправлення (Fix-pipeline) для подальшої обробки.
+Файл формує єдину поверхню для `n-rules lint --no-fix`: від discovery правил і вибору меж запуску до виконання `lint` для кожного concern та збору нормалізованих violations. Його результатом є список порушень, який використовує fix-pipeline для подальшої обробки, тоді як сам detect не змінює дерево файлів.
 
 ## Поведінка
 
-Поведінка
-DEFAULT_RULES_DIR визначає шлях до стандартної директорії з правилами.
-buildDetectPlan створює впорядкований план прогону лінтера, збираючи всі відповідні концерни та визначаючи область їх сканування.
-detectAll виконує прохід лінтера у режим детекції, збираючи всі виявлені порушення та повертаючи код виходу.
+DEFAULT_RULES_DIR задає базовий корінь правил, від якого стартує discovery, коли споживач не передав власні каталоги.
 
-**Внутрішній паралелізм (ADR 260716-1354-внутрішній-паралелізм-lint-оркестратора).** `detectAll` читає `N_RULES_LINT_CONCURRENCY` (дефолт `1` — production-паралелізм ще не пройшов benchmark-gates ADR): за замовчуванням план виконується повністю послідовно (`detectPlanSequentially`), спостережувано ідентично до-ADR поведінці. При `concurrency > 1` план ділиться на два лейни через `blocking-inventory.mjs` (`isSerialLane`) і виконується через `scheduler.mjs` (`runPlanConcurrently`, `detectPlanConcurrently`): parallel lane — доведені non-blocking concern-и, bounded pool до `concurrency`; serial lane — решта, строго послідовно. Перший `DetectorError` (будь-який лейн) зупиняє нові старти, `AbortController` сигналізує вже запущеним async-детекторам (`ctx.signal`), а вже завершені concern-и лишаються в результаті — `exitCode 2` пріоритетний над частковими violations. Фінальний масив violations завжди стабільно сортується за `(ruleId, concernId, file, data.line, reason)` — незалежно від порядку завершення (`sortViolations`), навіть при `concurrency=1`.
+buildDetectPlan спочатку визначає набір rules-каталогів, потім відбирає лише доступні concern-и з урахуванням capability, далі будує план виконання за режимом прогону: scoped, delta, full або repo-wide. Сам план фіксує, які concern-и запускаються whole-repo, а які лише по перетину з файлами, щоб detect і fix-pipeline працювали з однаковою картиною.
 
-## Публічний API
-
-* DEFAULT_RULES_DIR — Містить набір стандартних правил для перевірок.
-* buildDetectPlan — Створює план виконання перевірок, охоплюючи визначені області.
-* detectAll — Виконує повний прохід пошуку проблем і повертає всі виявлені порушення та код виходу.
-* loadEnabledLintRules — Discovery-фасад для споживачів поза detect/fix-конвеєром (`ci plan`): concerns за rule-id + set активних правил.
-* computeActiveDomains — Активність доменів для файлового набору (лише per-file concerns) — єдине джерело правди для `ci plan`: «plan сказав true» ⇔ «lint щось запустить».
+loadEnabledLintRules використовує той самий discovery-ланцюжок, але повертає не план, а повну мапу concern-и за rule-id разом із множиною активних правил. Це потрібно зовнішнім споживачам, які мають знати, що реально доступно для прогону, не запускаючи сам detector-цикл.
 
-**Осі плану (сервіс-канон):** scoped + explicit files (`lint js --path <dir>`) → лише per-file concerns названих правил × перетин; `pathMode` (дефолтний `--path`) → full-scope concerns виключені з delta-плану; `repoWide` (`--repo-wide`) → ЛИШЕ full-scope concerns enabled-правил, whole-repo (окремий CI-workflow, не гейтить деплой).
+computeActiveDomains дає скорочений зріз цієї ж моделі: для заданого набору файлів показує, які rule-id справді активуються хоча б одним per-file concern-ом. Full-scope перевірки тут навмисно не враховуються, бо їхня зона відповідає repo-wide прогону.
 
-## Гарантії поведінки
+detectAll бере готовий план, виконує його, збирає normalized violations і повертає ще й derived exitCode. Увесь шлях read-only: нічого не записує в дерево, не змінює конфіг і не покладається на мутації поза межами збирання результатів. Фільтрація та видимість правил спираються на .n-rules.json, тож саме він визначає, які rules каталоги й concern-и вважаються активними.
 
-- Read-only: не виконує операцій запису (ФС/БД).
+## Публічний API
 
-**Multi-dir (плагіни):** `effectiveRulesDirs` додає rules-каталоги плагінів з `.n-rules.json` (hot-path: без install, quiet); `readLintConcernsByRuleMulti` зливає концерни за іменем (перший власник виграє) — плагін може додавати концерни до правила ядра (mixin).
+- DEFAULT_RULES_DIR — Цей файл: npm/scripts/lib/lint-surface/run-detectors.mjs → PACKAGE_ROOT = npm (4 dirname угору).
+- buildDetectPlan — Будує план прогону для заданих опцій (discovery + scope-table).
+Спільне джерело для detect-only і fix-pipeline.
+- loadEnabledLintRules — Discovery-фасад для споживачів поза detect/fix-конвеєром (`ci plan`):
+concerns за rule-id (ядро + плагіни, capability-фільтр) і set активних правил.
+- computeActiveDomains — Активність доменів (rule-id) для заданого файлового набору — єдине джерело
+правди для `ci plan`: домен «активний», якщо хоч один його **per-file**
+concern тригериться на цих файлах (та сама таблиця planConcernForDelta, що
+й `lint <domain> --path` → «plan сказав true» ⇔ «lint щось запустить»).
+Правила без жодного per-file concern не потрапляють у результат (їхні
+full-scope перевірки — справа `--repo-wide`).
+- detectAll — Запускає detect-only прохід. Повертає всі violations і похідний exitCode.
 
-**Capability-гейт:** `filterByCapabilities` відкидає концерни з незадоволеним `requires.capability` (capabilities надають встановлені плагіни через маніфест `n-rules.capabilities`; явний `opts.capabilities` у тестах перекриває резолв).
+## Гарантії поведінки
 
-**Warning про rule-id без concern-ів:** якщо rule-id з `.n-rules.json#rules` не має жодного concern-а серед усіх `rulesDirs` (ядро + плагіни) — `console.error` попереджає про можливий дрейф конфігу (типово: правило переїхало в плагін, якого консюмер не підключив у `plugins[]`). Rule-id з існуючим каталогом, але без `concern.json` (документаційні правила на кшталт `feedback`), warning не тригерить.
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.

package/scripts/lib/lint-surface/docs/tier-sampling-experiment.md

@@ -3,32 +3,48 @@ type: JS Module
 title: tier-sampling-experiment.mjs
 resource: npm/scripts/lib/lint-surface/tier-sampling-experiment.mjs
 docgen:
-  crc: f6a46f92
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 959712b3
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
   score: 100
-  issues: judge:inaccurate:0.98
+  issues: judge:error
   judgeModel: openai-codex/gpt-5.4-mini
 ---
 
 ## Огляд
 
-Файл слугує експериментальною обгорткою для перевірки процесу виправлення (lint fix ladder). Він моделює ізольовані потенційні рішення для певного рівня, відкочуючи робоче дерево до початкового стану S1 перед кожною спробою. Мета модуля — ізольовано протестувати кандидати, які пройшли автоматичне виявлення чистоти, щоб оцінити їхню цінність через механізм зворотного зв'язку.
+Експериментальний harness моделює isolated sampling для окремого tier-а lint fix ladder: будує experiment-only rung-и, проганяє sampling-кандидатів із відкотом до S1 і лишає лише candidate, що пройшов canonical detect. Файл існує, щоб перевіряти sampling/consensus поза production `runFixPipeline`, залишаючи judge/consensus тільки джерелом feedback, а не рішенням про patch.
+
+Публічні точки входу: `EXPERIMENT_TIER_ORDER`, `buildExperimentLadder`, `samplingProfilesForTier`, `chooseCleanCandidate`, `runTierSamplingExperiment`.
+
+Модуль працює fail-safe: перехоплює помилки й не кидає винятків назовні.
 
 ## Поведінка
 
-EXPERIMENT_TIER_ORDER визначає фіксований порядок експериментальних рівнів.
-buildExperimentLadder конструює список експериментальних етапів на основі наданих моделей для кожного tier.
-samplingProfilesForTier генерує список можливих профілів відбору для певного tier.
-chooseCleanCandidate вибирає найкращий кандидат серед усіх спроб, які пройшли перевірку на чистоту.
-runTierSamplingExperiment виконує послідовність випробувань (sampling) для заданого tier, тестуючи кандидатів, обираючи найкращого та застосовуючи його патч для фінальної перевірки.
+`EXPERIMENT_TIER_ORDER` задає порядок експериментальних tier-ів, за яким формується ladder для isolated sampling поверх lint fix pipeline.
+
+`buildExperimentLadder` створює окремий experiment-only ladder із підтримкою `cloud-max`, не змінюючи production-послідовність `runFixPipeline`. Дані про моделі й timeouts перетворюються на набір rung-ів, які далі використовуються як сценарії окремих випробувань.
+
+`samplingProfilesForTier` визначає набір sampling-кандидатів для конкретного tier-а. Якщо для tier-а передані перевизначення, вони стають джерелом профілів; інакше використовується стандартний набір для цього рівня.
+
+`runTierSamplingExperiment` бере violations, базовий контекст, rung і sampling-кандидатів, після чого послідовно тестує кожного кандидата в ізольованому стані S1. Для кожної спроби робоче дерево відкочується до початкового snapshot, запускається worker, фіксуються змінені файли, виконується canonical detect і записується результат спроби разом із telemetry та latency.
+
+Після всіх спроб `chooseCleanCandidate` обирає лише чистий candidate: пріоритет має менша кількість змінених файлів, менший patch і коротша latency. Якщо чистого кандидата немає, експеримент завершується без застосування patch до робочого дерева.
+
+Якщо чистий candidate знайдено, `runTierSamplingExperiment` застосовує саме його зміни як фінальний результат tier sampling. Judge/consensus не приймає рішення про застосування patch: його відповідь повертається тільки як feedback поруч із attempts, selected candidate, фінальними violations і clean-статусом.
+
+Модуль працює fail-safe: помилки окремих кандидатів або допоміжних етапів перетворюються на результати спроб і не викидаються назовні. Кешування між запусками або кандидатами не використовується.
 
 ## Публічний API
 
-* EXPERIMENT_TIER_ORDER — Визначає пріоритетність випробувань (tiers).
-* buildExperimentLadder — Створює ієрархію для експериментів, не впливаючи на конфігурацію продакшену.
-* samplingProfilesForTier — Повідомляє про доступні варіанти збору зразків для конкретного рівня випробувань.
-* chooseCleanCandidate — Вибирає оптимальний варіант з усіх тестових спроб, базуючись на мінімальній кількості змін у файлах, розмірі патчу та латентності.
-* runTierSamplingExperiment — Проводить комплекс випробувань для одного рівня: для кожного варіанту повертається до початкового стану, запускається робочий процес, оцінюється якість, а при виборі — застосовується відповідний виправлення.
+- EXPERIMENT_TIER_ORDER — Порядок tier-ів експериментального ladder — від локальної моделі до найсильнішої хмарної.
+- buildExperimentLadder — Будує experiment-only ladder із `cloud-max`. Production ladder це не змінює.
+- samplingProfilesForTier — Повертає можливі sampling profiles для заданого tier-а.
+- chooseCleanCandidate — Дефолтний вибір найкращого (clean) кандидата серед усіх спроб.
+Вибір відбувається за критеріями: менша кількість змінених файлів, менший розмір patch, менша латентність.
+- runTierSamplingExperiment — Виконує послідовність випробувань (sampling) для одного tier.
+Для кожного кандидата виконується rollback до S1, запускається worker,
+оцінюється чистота, і якщо кандидат обраний, застосовується його patch.
 
 ## Гарантії поведінки
 

package/scripts/lib/lint-surface/run-detectors.mjs

@@ -25,7 +25,7 @@ import { renderViolations, renderDiagnostics } from './render.mjs'
 import { createProgressReporter } from './progress.mjs'
 import { runPlanConcurrently } from './scheduler.mjs'
 
-// Цей файл: npm/scripts/lib/lint-surface/run-detectors.mjs → PACKAGE_ROOT = npm (4 dirname угору).
+/** Цей файл: npm/scripts/lib/lint-surface/run-detectors.mjs → PACKAGE_ROOT = npm (4 dirname угору). */
 export const DEFAULT_RULES_DIR = join(dirname(dirname(dirname(dirname(fileURLToPath(import.meta.url))))), 'rules')
 
 /**

package/scripts/lib/lint-surface/tier-sampling-experiment.mjs

@@ -10,6 +10,7 @@ import { dirname } from 'node:path'
 
 import { createSnapshot } from './snapshot.mjs'
 
+/** Порядок tier-ів експериментального ladder — від локальної моделі до найсильнішої хмарної. */
 export const EXPERIMENT_TIER_ORDER = Object.freeze(['local-min', 'cloud-min', 'cloud-avg', 'cloud-max'])
 
 const DEFAULT_LOCAL_TIMEOUT_MS = 300_000

package/scripts/lib/plugin-api.mjs

@@ -78,6 +78,52 @@ export const PLUGIN_API_VERSION = 1
 const REQUIRED_PROVIDER_FUNCTIONS = ['detect', 'available', 'backup', 'bump', 'diff', 'promptFor', 'cleanup']
 const REQUIRED_PROVIDER_STRINGS = ['id', 'title', 'manifestNoun', 'skillSection']
 
+/**
+ * @typedef {object} CoverageRow
+ * Агрегований вимір однієї області (`JS`, `Vue (Storybook)`, `Rust`, …).
+ * @property {string} area назва рядка звіту
+ * @property {{lines:{covered:number,total:number}, functions:{covered:number,total:number}}} coverage line/function coverage
+ * @property {{caught:number, total:number}} mutation вбиті/всі мутанти (0/0 — мутаційне тестування не вимірювалось)
+ * @property {Array<{file:string, mutants:Array<object>, exampleTest?:object|null, recommendationText?:string|null}>} survived вцілілі мутанти по файлах (шляхи relative до cwd)
+ */
+
+/**
+ * @typedef {object} CoverageProvider
+ * Порт мовної екосистеми для концерну `coverage` правила `test` (spec
+ * 2026-07-22 absorb-7n-test). Ядро викликає: `detect` → повний вимір
+ * `collect` (full/`lint test`) АБО делта-вимір `collectPerFile` (делта-lint,
+ * без мутаційного тестування). Реєстрація — `contributes.handlers.coverage`
+ * у маніфесті плагіна, default-експорт handler-модуля.
+ * @property {string} id стабільний ідентифікатор екосистеми (напр. `js`)
+ * @property {string} title заголовок для звітів/повідомлень
+ * @property {(cwd: string) => Promise<boolean>} detect чи застосовний вимір у проєкті (false → тихий skip виміру)
+ * @property {(cwd: string, opts?: {changedFiles?: string[], base?: string|null, runner?: object}) => Promise<CoverageRow[]>} collect повний вимір: coverage + мутаційне тестування по всіх workspaces
+ * @property {(cwd: string, opts: {files: string[], runner?: object}) => Promise<Array<{file:string, pct:number, linesFound:number, linesCovered:number, reason?:string}>>} collectPerFile легкий делта-вимір per-file line coverage змінених файлів (без мутаційного тестування)
+ */
+
+const REQUIRED_COVERAGE_FUNCTIONS = ['detect', 'collect', 'collectPerFile']
+const REQUIRED_COVERAGE_STRINGS = ['id', 'title']
+
+/**
+ * Валідує форму coverage-провайдера з модуля плагіна.
+ * @param {unknown} candidate default-експорт handler-модуля плагіна
+ * @param {string} source ім'я плагіна/шлях модуля для повідомлення
+ * @returns {CoverageProvider} той самий обʼєкт, якщо валідний
+ */
+export function assertCoverageProvider(candidate, source) {
+  if (!candidate || typeof candidate !== 'object') {
+    throw new TypeError(`plugin-api: ${source} — default-експорт не є обʼєктом CoverageProvider`)
+  }
+  const missing = [
+    ...REQUIRED_COVERAGE_STRINGS.filter(k => typeof candidate[k] !== 'string' || candidate[k] === ''),
+    ...REQUIRED_COVERAGE_FUNCTIONS.filter(k => typeof candidate[k] !== 'function')
+  ]
+  if (missing.length > 0) {
+    throw new TypeError(`plugin-api: ${source} — CoverageProvider без обовʼязкових полів: ${missing.join(', ')}`)
+  }
+  return /** @type {CoverageProvider} */ (candidate)
+}
+
 /**
  * Валідує форму провайдера з модуля плагіна — зрозуміла помилка замість
  * «undefined is not a function» глибоко в оркестраторі.

package/scripts/utils/docs/walkDir.md

@@ -3,31 +3,42 @@ type: JS Module
 title: walkDir.mjs
 resource: npm/scripts/utils/walkDir.mjs
 docgen:
-  crc: 6f26e08f
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  crc: 1bbc24bc
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
   score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Публічна функція `walkDir` здійснює рекурсивний пошук файлів у вказаному каталозі. Вона обходить файлову систему, ігноруючи каталоги `.git`, `node_modules` та worktree-чекаути (`.worktrees/`, `.claude/worktrees/` — повні копії репо від сесійних git-worktree Claude/агентів). Знаходячи кожен файл, вона передає його повний шлях у колбек для подальшої обробки. Компонент є read-only, тобто не виконує записів у файлову систему чи бази даних. При роботі з файловою системою він перехоплює помилки, забезпечуючи безпечну роботу без викидання винятків.
+## Огляд
+
+Файл описує правила пропуску службових і агентських шляхів під час читання репозиторію. `WORKTREE_CHECKOUT_GLOBS` задає шаблони агентських worktree-копій, `ALWAYS_IGNORE` фіксує завжди ігноровані `.git` і `node_modules`.
+
+`isWorktreeCheckoutPath` перевіряє вже відомий відносний шлях на належність до агентського worktree. `walkDir` виконує fail-safe обхід файлового дерева: перехоплює помилки читання і не передає винятки назовні.
 
 ## Поведінка
 
-1. Викликається функція walkDir для початку рекурсивного обходу каталогу.
-2. Система розшифровує вхідний шлях до кореня обходу.
-3. Система формує додаткові правила ігнорування на основі наданих шляхів.
-4. Система завжди ігнорує каталоги .git, node_modules і worktree-чекаути (.worktrees/, .claude/worktrees/) на будь-якій глибині.
-5. Система виконує пошук усіх файлів у каталозі, застосовуючи правила ігнорування, включаючи ті, що визначені в .gitignore.
-6. У разі виникнення помилки під час пошуку, процес обходу припиняється без генерації винятку.
-7. Для кожного знайденого файлу система викликає наданий колбек, передаючи йому повний абсолютний шлях до цього файлу.
+`WORKTREE_CHECKOUT_GLOBS` задає спільне правило безпеки для агентських worktree-копій, щоб обхід не сприймав дублікати репозиторію як робочий код.
+
+`ALWAYS_IGNORE` розширює це правило постійними пропусками `.git` і `node_modules`; ці винятки застосовуються під час повного обходу незалежно від налаштувань репозиторію.
+
+`walkDir` приймає корінь обходу, додає до спільних правил додаткові локальні винятки, читає файлове дерево з урахуванням `.gitignore` і передає знайдені файли далі як абсолютні шляхи. Якщо обхід неможливий, він завершується без помилки назовні, щоб перевірки залишались fail-safe.
+
+`isWorktreeCheckoutPath` використовує те саме смислове правило пропуску worktree-чекаутів для уже наявних відносних шляхів, які не проходять через `walkDir`, наприклад зі списків git.
 
 ## Публічний API
 
-- walkDir — рекурсивно переглядає файли та папки, ігноруючи ті, що вказані у файлі `.gitignore`.
-- isWorktreeCheckoutPath — предикат для відносного posix-шляху: чи лежить він усередині worktree-чекаута (`.worktrees/` або `.claude/worktrees/`). Для фільтрації git-списків, що не проходять через walkDir (наприклад, delta-список змінених файлів).
-- ALWAYS_IGNORE, WORKTREE_CHECKOUT_GLOBS — експортовані glob-константи безумовних пропусків обходу.
+- WORKTREE_CHECKOUT_GLOBS — Сесійні git-worktree чекаути (Claude/агенти): повні копії репо, не робочий код.
+Споживацькі репо часто не мають цих шляхів у .gitignore, тож без safety net
+lint-обхід бачив би дубль усього дерева.
+- ALWAYS_IGNORE — .git ніколи не потрапляє в .gitignore — пропускаємо завжди.
+node_modules — safety net: проєкт може не мати .gitignore або запускатись поза git-репо.
+- isWorktreeCheckoutPath — Чи лежить відносний posix-шлях усередині worktree-чекаута (`.worktrees/` або
+`.claude/worktrees/`). Для фільтрації git-списків, що не проходять через walkDir.
+- walkDir — Рекурсивно обходить каталог, поважаючи .gitignore (включно з вкладеними).
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Власних операцій запису (ФС/БД) у файлі немає; виклики імпортованих модулів можуть писати.
 - Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- Свідомо пропускає шляхи: `.git`, `node_modules`, `.worktrees/`, `.claude/worktrees/`.
+- Свідомо пропускає шляхи: `.git`, `node_modules`.

package/scripts/utils/docs/worktree-fingerprint.md

@@ -3,29 +3,30 @@ type: JS Module
 title: worktree-fingerprint.mjs
 resource: npm/scripts/utils/worktree-fingerprint.mjs
 docgen:
-  crc: df297382
+  crc: 38831a93
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Файл надає унікальний відбиток робочої директорії. Цей відбиток використовується для ідентифікації та порівняння робочих директорій, забезпечуючи їх унікальність у системі. Він слугує базовим інструментом для відстеження та управління версіями.
+## Огляд
+
+`worktreeFingerprint` формує стабільний fingerprint git-робочого дерева з `HEAD`, diff і `untracked`-файлів. Це потрібно, щоб розпізнавати той самий стан дерева й дедуплікувати повторні `lint --full` прогони без змін.
 
 ## Поведінка
 
-1.  Отримує поточний SHA256 хеш коміту, який знаходиться в гілці HEAD.
-2.  Отримує текст зміни між комітом HEAD та робочим каталогом.
-3.  Отримує список не відстежених файлів у робочому каталозі, не включаючи стандартні файли, що ігноруються.
-4.  Для кожного не відстеженого файлу отримує його SHA256 хеш.
-5.  Об'єднує SHA256 хеш коміту, текст зміни та пари "файл:хеш" не відстежених файлів, розділяючи їх новими рядками.
-6.  Обчислює SHA256 хеш отриманого текстового рядка.
-7.  Повертає отриманий SHA256 хеш у форматі 64-значної шестнадцяткової строки.
-8.  Якщо виникає помилка під час виконання будь-якої з операцій, повертає `null`.
+1. worktreeFingerprint визначає, чи поточне git-робоче дерево вже має унікальний стан для повторного повного lint-прогону.
+2. Якщо дерево не належить git-репо або перевірку неможливо виконати, повертає `null`.
+3. Інакше бере базовий стан з `HEAD`, додає різницю від `HEAD` і враховує всі untracked-файли, щоб зміна вмісту або набору нових файлів впливала на результат.
+4. Для untracked-файлів формує впорядковану сукупність «шлях + вміст», щоб однаковий набір файлів давав той самий fingerprint незалежно від порядку їх виявлення.
+5. На основі цього зводить весь стан дерева в один SHA-256 fingerprint у вигляді hex-рядка.
+6. Використовується як стабільний маркер незміненого дерева для відсікання повторних повних lint-прогонів.
 
 ## Публічний API
 
-worktreeFingerprint — генерує унікальний відбиток поточного стану репозиторію Git.
+- worktreeFingerprint — Fingerprint поточного стану git-робочого дерева.
 
 ## Гарантії поведінки
 
-- Функція повертає `true`, якщо відбиток дерева робіт успішно обчислено.
-- Функція повертає `null`, якщо обчислення відбитка дерева робіт не вдалося.
-- Функція не викликає винятків.
-- Функція не використовує кеш.
+- (специфічних машинно-виведених гарантій немає)

package/scripts/utils/walkDir.mjs

@@ -2,13 +2,17 @@
 import { join, relative, resolve, sep } from 'node:path'
 import { globby } from 'globby'
 
-// Сесійні git-worktree чекаути (Claude/агенти): повні копії репо, не робочий код.
-// Споживацькі репо часто не мають цих шляхів у .gitignore, тож без safety net
-// lint-обхід бачив би дубль усього дерева.
+/**
+ * Сесійні git-worktree чекаути (Claude/агенти): повні копії репо, не робочий код.
+ * Споживацькі репо часто не мають цих шляхів у .gitignore, тож без safety net
+ * lint-обхід бачив би дубль усього дерева.
+ */
 export const WORKTREE_CHECKOUT_GLOBS = ['**/.worktrees/**', '**/.claude/worktrees/**']
 
-// .git ніколи не потрапляє в .gitignore — пропускаємо завжди.
-// node_modules — safety net: проєкт може не мати .gitignore або запускатись поза git-репо.
+/**
+ * .git ніколи не потрапляє в .gitignore — пропускаємо завжди.
+ * node_modules — safety net: проєкт може не мати .gitignore або запускатись поза git-репо.
+ */
 export const ALWAYS_IGNORE = ['.git/**', 'node_modules/**', ...WORKTREE_CHECKOUT_GLOBS]
 
 const WORKTREE_CHECKOUT_RE = /(?:^|\/)(?:\.worktrees|\.claude\/worktrees)\//u

package/scripts/utils/worktree-fingerprint.mjs

@@ -1,3 +1,8 @@
+/**
+ * Fingerprint git-робочого дерева (HEAD + diff + untracked-файли) —
+ * використовується для дедуплікації повторних lint --full прогонів на
+ * незміненому дереві.
+ */
 import { spawnSync } from 'node:child_process'
 import { createHash } from 'node:crypto'