@7n/rules 1.43.1 → 1.44.1

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/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/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/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/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