@nitra/cursor 10.2.0 → 11.0.0

package/.claude-template/hooks/normalize-decisions.sh

@@ -268,18 +268,48 @@ CURSOR_MODEL="${ADR_NORMALIZE_CURSOR_MODEL:-claude-4.6-sonnet-medium}"
 
 RESPONSE_FILE="$TMP_DIR/response.txt"
 
-if command -v claude >/dev/null 2>&1; then
-  log "using claude CLI (model: $CLAUDE_MODEL)"
-  claude -p --model "$CLAUDE_MODEL" < "$FULL_PROMPT_FILE" > "$RESPONSE_FILE" 2>>"$LOG" || true
-elif command -v cursor-agent >/dev/null 2>&1; then
-  log "using cursor-agent CLI (model: $CURSOR_MODEL)"
-  FULL_PROMPT=$(cat "$FULL_PROMPT_FILE")
-  cursor-agent -p --mode ask --output-format text --model "$CURSOR_MODEL" -- "$FULL_PROMPT" > "$RESPONSE_FILE" 2>>"$LOG" || true
-else
-  log "no LLM CLI found, skipping"
-  exit 0
+# Backend selection. `local` — конвеєр на малій локальній моделі (privacy + $0,
+# `npm/scripts/lib/adr/normalize-pipeline.mjs`); `claude`/`cursor` — single-shot
+# у хмару. Auto-default: local, якщо налаштовано `N_LOCAL_MIN_MODEL`, інакше
+# claude → cursor. Команда local-бекенда override-иться через ADR_NORMALIZE_LOCAL_CMD
+# (для тестів/in-repo: `node npm/bin/n-cursor.js adr-normalize-local`).
+BACKEND="${ADR_NORMALIZE_BACKEND:-}"
+if [ -z "$BACKEND" ]; then
+  if [ -n "${N_LOCAL_MIN_MODEL:-}" ]; then
+    BACKEND=local
+  elif command -v claude >/dev/null 2>&1; then
+    BACKEND=claude
+  elif command -v cursor-agent >/dev/null 2>&1; then
+    BACKEND=cursor
+  else
+    BACKEND=none
+  fi
 fi
 
+ADR_LOCAL_CMD="${ADR_NORMALIZE_LOCAL_CMD:-npx --no @nitra/cursor adr-normalize-local}"
+
+case "$BACKEND" in
+  local)
+    log "using local pipeline backend (model: ${N_LOCAL_MIN_MODEL:-?})"
+    # local-бекенд будує власні дрібні промпти з батча — FULL_PROMPT_FILE не потрібен.
+    # shellcheck disable=SC2086
+    $ADR_LOCAL_CMD --batch "$BATCH_LIST" --clean "$CLEAN_LIST" --adr-dir "$ADR_DIR" > "$RESPONSE_FILE" 2>>"$LOG" || true
+    ;;
+  claude)
+    log "using claude CLI (model: $CLAUDE_MODEL)"
+    claude -p --model "$CLAUDE_MODEL" < "$FULL_PROMPT_FILE" > "$RESPONSE_FILE" 2>>"$LOG" || true
+    ;;
+  cursor)
+    log "using cursor-agent CLI (model: $CURSOR_MODEL)"
+    FULL_PROMPT=$(cat "$FULL_PROMPT_FILE")
+    cursor-agent -p --mode ask --output-format text --model "$CURSOR_MODEL" -- "$FULL_PROMPT" > "$RESPONSE_FILE" 2>>"$LOG" || true
+    ;;
+  *)
+    log "no LLM backend available, skipping"
+    exit 0
+    ;;
+esac
+
 if [ ! -s "$RESPONSE_FILE" ]; then
   log "empty LLM response"
   exit 0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [11.0.0] - 2026-06-15
+
+### Removed
+
+- CLI: прибрано надлишкові точки входу заради мінімальної поверхні. `lint-ci` видалено — це був чистий аліас `lint --read-only --full` (CI лишається тим самим прапор-комбо). Deprecated-аліас `doc-files <sub>` (`scan|check|gen|stamp`) видалено — 0 живих callerів (hook давно на `lint-doc-files`, скіл на `lint-doc-files`/`fix-doc-files`). Заодно полагоджено застарілу документацію точок входу в `bin/n-cursor.js` (мертві згадки `fix`, опис `lint` → data-driven по `meta.json:lint`) і схему `rule-meta.json` (enum `quick|ci` → `per-file|full`, відповідає реальним значенням і `parseRuleLintSpec`).
+
+## [10.3.0] - 2026-06-15
+
+### Added
+
+- adr-normalize: локальний конвеєр-оркестратор як backend (retrieval→edge-judge→cluster→gen на малій моделі); субкоманда adr-normalize-local + backend-селектор у normalize-decisions.sh (local|claude|cursor)
+
 ## [10.2.0] - 2026-06-15
 
 ### Added

package/bin/n-cursor.js

@@ -26,7 +26,6 @@
  *                                     `markdownlint-cli2 --fix` → `v8r` (json/json5/yaml/yml/toml)
  *   `npx \@nitra/cursor lint-doc-files`  — детермінований детектор застарілості файлових док (`stale`: `missing`|`crc-mismatch`); правило doc-files (ignore-glob у `npm/rules/doc-files/js/docgen-ignore.mjs`; тека `docs/` поряд із джерелом). Режими: повний (exit 1), `--json` (exit 0), `--missing-only`, `--hook`/`--git` (hook-протокол, exit 2), `--degraded`
  *   `npx \@nitra/cursor fix-doc-files`   — JS-оркестрована генерація файлових док (роутинг local/cloud) зі штампом CRC (`--limit`/`--from`/`--overwrite`/`--retry-degraded`); `--stamp` — детерміноване перештампування CRC без LLM
- *   `npx \@nitra/cursor doc-files <sub>` — DEPRECATED-аліас (scan|check|gen|stamp) → `lint-doc-files`/`fix-doc-files`
  *   `npx \@nitra/cursor doc-aggregate modules` — JSON-лістинг логічних модулів (межі за `package.json`) для Tier 2 скілу doc-aggregate
  *   `npx \@nitra/cursor skill list`     — скіли пакета без синку в проєкт
  *   `npx \@nitra/cursor skill taze`     — промпт на stdout
@@ -660,7 +659,7 @@ function buildClaudeDocFilesSectionLines() {
     '',
     '## Файлова документація (`doc-files` — обовʼязковий крок, як lint)',
     '',
-    'Після зміни чи додавання кодового файлу його файлова дока (`<dir>/docs/<stem>.md`) має бути **актуальною** — це **обовʼязковий крок кожної задачі**, нарівні з lint. Застарілість детермінується за **CRC** джерела у frontmatter доки. PostToolUse hook (`doc-files check --hook`) **сигналить** про дрейф після правки; Stop-hook (`doc-files check --git`) **блокує завершення** задачі за наявності застарілих док (виняток — масовий прогін понад поріг `N_CURSOR_DOC_FILES_GATE_MAX`, дефолт 50). Регенерація — `/doc-files` (JS-оркестрована, не диспатч субагентів). Агрегуюча дока (module-summary, доменні) — окремий скіл `/doc-aggregate`, за запитом.',
+    'Після зміни чи додавання кодового файлу його файлова дока (`<dir>/docs/<stem>.md`) має бути **актуальною** — це **обовʼязковий крок кожної задачі**, нарівні з lint. Застарілість детермінується за **CRC** джерела у frontmatter доки. PostToolUse hook (`lint-doc-files --hook`) **сигналить** про дрейф після правки; Stop-hook (`lint-doc-files --git`) **блокує завершення** задачі за наявності застарілих док (виняток — масовий прогін понад поріг `N_CURSOR_DOC_FILES_GATE_MAX`, дефолт 50). Регенерація — `/doc-files` (JS-оркестрована, не диспатч субагентів). Агрегуюча дока (module-summary, доменні) — окремий скіл `/doc-aggregate`, за запитом.',
     ''
   ]
 }
@@ -1506,7 +1505,7 @@ try {
   // .n-cursor.json + bun install, а fix/lint/coverage/change/release переписують файли в CWD —
   // усе це ключиться на cwd(). Запуск із піддиректорії git-репо (типово прямий
   // `bun npm/bin/n-cursor.js` не з кореня) зачепив би не той каталог → STOP. Read-only та
-  // `--root`-команди (trace, graph, lint-doc-files, fix-doc-files, doc-files, doc-aggregate, rename-yaml-extensions) не зачіпаємо.
+  // `--root`-команди (trace, graph, lint-doc-files, fix-doc-files, doc-aggregate, rename-yaml-extensions) не зачіпаємо.
   if (ROOT_GUARDED_COMMANDS.has(command)) {
     assertCwdIsProjectRoot(cwd(), describeRootGuardedAction(command))
   }
@@ -1662,38 +1661,12 @@ try {
 
       break
     }
-    case 'doc-files': {
-      // Делегувальний аліас (deprecated): doc-files scan|check|gen|stamp →
-      // lint-doc-files / fix-doc-files. Зняття — наступний major (спека 2026-06-12).
-      // Зміна exit: plain `check` 2→1 (через lint-doc-files); --hook/--git зберігають 2.
-      console.error('⚠ `doc-files <sub>` застаріло — використовуй `lint-doc-files` / `fix-doc-files`.')
-      const rest = args.slice(1)
-      switch (args[0]) {
-        case 'scan': {
-          const { runLintDocFilesCli } = await import('../rules/doc-files/lint/lint.mjs')
-          process.exitCode = await runLintDocFilesCli(['--json', ...rest])
-          break
-        }
-        case 'check': {
-          const { runLintDocFilesCli } = await import('../rules/doc-files/lint/lint.mjs')
-          process.exitCode = await runLintDocFilesCli(rest)
-          break
-        }
-        case 'gen': {
-          const { runDocFilesGenCli } = await import('../rules/doc-files/js/docgen-files-batch.mjs')
-          process.exitCode = await runDocFilesGenCli(rest)
-          break
-        }
-        case 'stamp': {
-          const { runDocFilesStampCli } = await import('../rules/doc-files/js/docgen-files-batch.mjs')
-          process.exitCode = runDocFilesStampCli(rest)
-          break
-        }
-        default: {
-          console.error('Usage: npx @nitra/cursor lint-doc-files | fix-doc-files [--root <dir>]')
-          process.exitCode = 1
-        }
-      }
+    case 'adr-normalize-local': {
+      // Local-backend ADR-нормалізації: викликається з .claude/hooks/normalize-decisions.sh
+      // як заміна single-shot LLM-виклику. Проганяє конвеєр (retrieval→edge-judge→
+      // cluster→gen) на малій локальній моделі й друкує `{operations}` JSON у stdout.
+      const { runAdrNormalizeLocalCli } = await import('../scripts/lib/adr/normalize-cli.mjs')
+      process.exitCode = await runAdrNormalizeLocalCli(args)
 
       break
     }
@@ -1720,7 +1693,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, post-tool-use-fix, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, lint-doc-files, fix-doc-files, coverage, coverage-fix, taze, start-check, change, release, skill, worktree, trace, doc-files, doc-aggregate`
+        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, post-tool-use-fix, adr-normalize-local, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, lint-doc-files, fix-doc-files, coverage, coverage-fix, taze, start-check, change, release, skill, worktree, trace, doc-aggregate`
       )
       process.exitCode = 1
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "10.2.0",
+  "version": "11.0.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/doc-files/js/docgen-extract.mjs

@@ -49,6 +49,10 @@ const FALSY_RETURN_RE = /catch[\s\S]{0,400}?return\s+(false|null|''|"")/
 // octokit/.request/.query). Хибний false-negative тут = небезпечна гарантія
 // «без мережі», тож свідомо схиляємось до over-detection (м'якший бік помилки).
 const NETWORK_RE = /\bfetch\(|https?:\/\/|\bhttps?\.|axios|\bgot\(|graphql|\.request\(|\.query\(|\.mutate\(|octokit|node-fetch|undici|\bgrpc\b|websocket/i
+// Будь-який `throw` назовні → НЕ можна гарантувати «fail-safe / без винятків».
+const THROW_RE = /\bthrow\s/
+// Запис у БД / зовнішню мутацію → НЕ read-only (навіть якщо нема ФС-запису).
+const MUTATION_RE = /\b(insert|update|delete|upsert|drop|destroy|save)[A-Za-z]*\s*[(,]|[Mm]utation\b|\bmut[A-Z]\w*|\.(save|create|update|delete|insert|destroy|mutate)\(/
 // Кеш — лише за ІМЕНОВАНИМ маркером (`cache`/`Cache`/`memoize`), не за будь-яким
 // `new Map()`: акумулятор (напр. `byPath = new Map()`) — не кеш, а хибна гарантія
 // «Кешує результати» гірша за пропуск (фабрикація > мовчання).
@@ -207,9 +211,11 @@ function extractMarkers(src) {
     if (src.includes(`'${lit}`) || src.includes(`"${lit}`) || src.includes(`/${lit}`)) skips.add(lit)
   }
   return {
-    readOnly: !WRITE_FS_RE.test(src),
-    catchesErrors: CATCH_RE.test(src) || TRY_RE.test(src),
-    returnsFalsyOnFail: FALSY_RETURN_RE.test(src),
+    // «Фабрикація > мовчання»: прапорець true лише за high-confidence; інакше
+    // guaranteesFromMarkers/factsSummary його ОПУСКАЮТЬ (не стверджують протилежне).
+    readOnly: !WRITE_FS_RE.test(src) && !MUTATION_RE.test(src),                    // ні ФС-запису, ні DB-мутацій
+    catchesErrors: (CATCH_RE.test(src) || TRY_RE.test(src)) && !THROW_RE.test(src), // fail-safe лише якщо НЕ кидає
+    returnsFalsyOnFail: FALSY_RETURN_RE.test(src) && !THROW_RE.test(src),
     network: NETWORK_RE.test(src),
     caches: CACHE_RE.test(src),
     skips: [...skips]

package/rules/doc-files/js/docgen-prompts.mjs

@@ -30,12 +30,13 @@ function factsSummary(facts) {
   if (facts.header) lines.push(`Намір файлу: ${facts.header.replaceAll('\n', ' ')}`)
   if (facts.exports?.length) lines.push(`Публічні функції: ${facts.exports.map(e => e.name).join(', ')}`)
   if (m.skips?.length) lines.push(`Свідомо пропускає шляхи: ${m.skips.join(', ')}`)
-  lines.push(`Read-only: ${m.readOnly ? 'так' : 'ні'}`)
+  // «Фабрикація > мовчання»: лише ПОЗИТИВНІ high-confidence сигнали; жодних дефолтних
+  // негативів (read-only «ні», «мережа: немає») — модель echo-їть їх як хибну гарантію.
+  if (m.readOnly) lines.push('Read-only: не пише (ФС/БД)')
+  if (m.network) lines.push('Звертається до мережі')
   if (m.catchesErrors) lines.push('Перехоплює помилки (fail-safe), не кидає винятків назовні')
-  if (m.returnsFalsyOnFail) lines.push('За невдачі повертає значення помилки (false/null/Err) замість винятку чи паніки')
+  if (m.returnsFalsyOnFail) lines.push('За певних помилок повертає порожнє значення (напр. null) замість винятку')
   lines.push(m.caches ? 'Кешування: так, у межах прогону' : 'Кешування: НЕМАЄ — не згадуй кеш у гарантіях')
-  if (m.network) lines.push('Звертається до мережі')
-  else lines.push('Робота з мережею: немає')
   return lines.join('\n')
 }
 
@@ -193,15 +194,16 @@ export function refineMessages(sectionKey, draft, issues, facts, anchors) {
 export function guaranteesFromMarkers(facts) {
   const m = facts.markers || {}
   const lines = []
-  if (m.readOnly) lines.push('- Read-only: файл не виконує операцій запису у файлову систему.')
+  // «Фабрикація > мовчання»: лише ПОЗИТИВНІ high-confidence гарантії. Жодних
+  // негативів/дефолтів (no-network, determinism) — їх не довести file-local аналізом.
+  if (m.readOnly) lines.push('- Read-only: не виконує операцій запису (ФС/БД).')
   if (m.catchesErrors) lines.push('- Перехоплює помилки і не пропускає винятків назовні (fail-safe).')
-  if (m.returnsFalsyOnFail) lines.push('- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.')
+  if (m.returnsFalsyOnFail) lines.push('- За певних помилок повертає порожнє значення (напр. `null`) замість винятку.')
   if (m.caches) lines.push('- Кешує результати в межах одного прогону.')
   if (m.skips?.length) {
     lines.push(`- Свідомо пропускає шляхи: ${m.skips.map(s => '`' + s + '`').join(', ')}.`)
   }
-  if (!m.network) lines.push('- Не звертається до мережі.')
-  if (!lines.length) return '- Поведінка детермінована: результат залежить лише від вхідних даних.'
+  if (!lines.length) return '- (специфічних машинно-виведених гарантій немає)'
   return lines.join('\n')
 }
 

package/rules/doc-files/js/docs/docgen-extract.md

@@ -1,7 +1,8 @@
 ---
 docgen:
   source: npm/rules/doc-files/js/docgen-extract.mjs
-  crc: e790ff64
+  crc: a0680e77
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
@@ -9,31 +10,32 @@ docgen:
 
 ## Огляд
 
-Файл витягує факти про конфігурацію та структуру проекту. Визначає мову та заголовок файлу. Витягує публічні експорти та імпорти з різних джерел. Витягує внутрішні та локальні символи. Документація перевіряє наявність операцій запису, обробки помилок, повернення хибних значень при невдачах, мережевих викликів, механізмів кешування та пропуск певних шляхів.
+Витягує структурований факт-лист з вмісту файлів, аналізуючи їх залежно від мови. Для Rust витягує модульний опис, публічні експорти, локальні символи та класифікує імпорти й поведінкові маркери. Для JavaScript/TypeScript/MJS витягує опис, експортовані елементи з JSDoc, класифікує імпорти та визначає поведінкові маркери. При аналізі ігноруються директорії: .github, .git, node_modules, base/, ua/, .firebase. Звертається до мережі та кешує дані протягом одного прогону.
 
 ## Поведінка
 
-1. Витягується факт про файл.
-2. Визначається мова файлу.
-3. Витягується заголовок файлу.
-4. Витягуються публічні експорти.
-5. Витягуються імпорти, класифіковані за джерелом.
-6. Витягуються внутрішні символи, імпортовані з внутрішніх модулів.
-7. Витягуються локальні символи, неекспортовані функції.
-8. Визначаються евристичні маркери.
-    * readOnly: перевірка на наявність операцій запису.
-    * catchesErrors: перевірка на наявність обробки помилок.
-    * returnsFalsyOnFail: перевірка на повернення хибних значень при невдачах.
-    * network: перевірка на наявність мережевих викликів.
-    * caches: перевірка на наявність механізмів кешування.
-    * skips: пропуск шляхів .github, .git, node_modules, base/, ua/, .firebase.
+1. Витягує факт-лист з вмісту файлу.
+2. Визначає мову файлу за розширенням.
+3. Якщо мова — Rust, виконує аналіз Rust-коду:
+    а. Витягує модульний опис з `//!`.
+    б. Визначає публічні експорти (структури, функції, енуми) на основі `pub` префікса або експозиційних атрибутів.
+    в. Визначає локальні (приватні) символи, які не є публічними.
+    г. Класифікує імпорти (`std`, зовнішні, внутрішні).
+    д. Визначає поведінкові маркери (readOnly, network, caches тощо) на основі специфічних Rust-конструкцій.
+4. Якщо мова — JavaScript/TypeScript/MJS, виконує аналіз JS-коду:
+    а. Витягує загальний опис файлу з верхнього блоку коментарів.
+    б. Витягує експортовані функції та класи разом із їхніми JSDoc-описами.
+    в. Класифікує імпорти на стандартні бібліотеки, NPM-пакети та внутрішні модулі.
+    г. Визначає локальні (неекспортовані) функції та класи.
+    д. Визначає поведінкові маркери (readOnly, network, caches тощо) на основі евристик.
+5. При аналізі JS-коду, свідомо ігнорує шляхи: .github, .git, node_modules, base/, ua/, .firebase.
+6. Повертає структуру фактів, що містить метадані про файл.
 
 ## Публічний API
 
-extractFacts — код файлу перетворює на список фактів
+extractFacts — витягує факти з вмісту файлу.
 
 ## Гарантії поведінки
 
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
 - Кешує результати в межах одного прогону.
 - Свідомо пропускає шляхи: `.github`, `.git`, `node_modules`, `base/`, `ua/`, `.firebase`.

package/rules/doc-files/js/docs/docgen-judge-measure.md

@@ -0,0 +1,30 @@
+---
+docgen:
+  source: npm/rules/doc-files/js/docgen-judge-measure.mjs
+  crc: b40b626c
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+# docgen-judge-measure.mjs
+
+## Огляд
+
+Файл аналізує вміст визначеного списку файлів, створюючи технічну документацію на основі вихідного коду. Процес спирається на конфігурацію, визначену в report.json. Для кожного файлу відбувається кешування результатів у межах прогону. Якість згенерованої документації оцінюється хмарною моделлю шляхом порівняння з пороговими значеннями, заданими в report.json. Результати аналізу агрегуються, обчислюється відсоток хибнопозитивних спрацювань та зберігаються у report.json.
+
+## Поведінка
+
+1. Зчитує список файлів для аналізу.
+2. Для кожного файлу зчитує його вміст.
+3. Генерує технічну документацію для файлу, використовуючи кеш за вмістом вихідного коду.
+4. Якщо документація згенерована, перевіряє її якість за встановленим порогом.
+5. Якщо якість документації відповідає порогу, передає вміст вихідного коду та згенеровану документацію для оцінки.
+6. Оцінює документацію за допомогою сильної хмарної моделі, використовуючи кеш за вмістом вихідного коду та документації.
+7. Збирає результати для кожного файлу.
+8. Агрегує результати, обчислюючи відсоток хибнопозитивних спрацювань (false-positive rate) серед документів, які пройшли порогову перевірку та були оцінені.
+9. Зберігає повний звіт у файл `report.json` у директорії кешу.
+10. Виводить консольний звіт про результати вимірювання.
+
+## Гарантії поведінки
+
+- Кешує результати в межах одного прогону.

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

@@ -1,7 +1,8 @@
 ---
 docgen:
   source: npm/rules/doc-files/js/docgen-prompts.mjs
-  crc: 72ac304f
+  crc: 28c9e818
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
 
@@ -9,31 +10,29 @@ docgen:
 
 ## Огляд
 
-Файл надає інструкції для створення лаконічної поведінкової документації українською мовою. Він містить інструменти для формування, перевірки та виправлення тексту документації, а також для визначення гарантій щодо роботи файлу
+Генерує технічну документацію на основі коду. Створює компоненти документації, такі як огляд (`overviewMessages`), повідомлення для секцій (`sectionMessages`), повідомлення для критики (`criticMessages`), повідомлення для уточнення (`refineMessages`) та гарантії, отримані з маркерів (`guaranteesFromMarkers`), застосовуючи заданий стиль (`STYLE`).
 
 ## Поведінка
 
-Поведінка:
-- STYLE: Надає інструкцію для генерації лаконічної поведінкової документації українською мовою.
-- sectionMessages: Генерує секційні промпти для різних частин документації.
-- overviewMessages: Формує текст для узагальнення ролі та призначення файлу.
-- criticMessages: Створює запити для перевірки чорновиків документації на наявність дефектів.
-- refineMessages: Переписує та виправляє чорновки документації відповідно до критики.
-- guaranteesFromMarkers: Формує список гарантій щодо поведінки файлу на основі маркерів.
-- oneShotMessages: Створює універсальний запит для генерації повної документації.
+STYLE: Пише лаконічну поведінкову документацію до коду українською мовою, використовуючи чистий Markdown.
+sectionMessages: Генерує набір промптів для різних секцій документації, використовуючи метадані файлу та вміст коду.
+overviewMessages: Створює узагальнений огляд файлу, базуючись на вже згенерованій секції «Поведінка».
+criticMessages: Перевіряє чорнетку секції на відповідність технічним критеріям, виявляючи дефекти.
+refineMessages: Переписує чорнетку секції, виправляючи дефекти, виявлені критиком.
+guaranteesFromMarkers: Формує список гарантій поведінки, виходячи з машинно-виведених маркерів файлу.
+oneShotMessages: Генерує базовий промпт для генерації повної документації за один виклик.
 
 ## Публічний API
 
-STYLE — Формулює стиль файлу.
-sectionMessages — Збирає повідомлення з мінімальним контекстом для кожної секції.
-overviewMessages — Надає узагальнення поведінки файлу.
-criticMessages — Виявляє дефекти в чорнетці секції.
-refineMessages — Виправляє чорнетку, усуваючи виявлені дефекти.
-guaranteesFromMarkers — Створює детермінований шаблон гарантій поведінки з фактів.
+STYLE — Визначає загальний стиль та намір файлу.
+sectionMessages — Містить мінімально необхідний контекст для кожної секції.
+overviewMessages — Генерує узагальнений огляд на основі вже визначеної поведінки.
+criticMessages — Виявляє конкретні недоліки у чорновому тексті секції, повертаючи список проблем або відсутність проблем.
+refineMessages — Переписує чорновий текст, виправляючи виявлені недоліки.
+guaranteesFromMarkers — Створює чіткий шаблон секції «Гарантії поведінки» на основі фактів.
+oneShotMessages — Надає приклади для порівняння.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Read-only: не виконує операцій запису (ФС/БД).
 - Кешує результати в межах одного прогону.
-- Не звертається до мережі.

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

@@ -0,0 +1,36 @@
+---
+docgen:
+  source: normalize-cli.mjs
+  crc: ce2f13af
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 90
+---
+
+# normalize-cli.mjs
+
+## Огляд
+
+Цей файл є CLI-обгорткою для локального ADR-нормалізатора (`n-cursor adr-normalize-local`). Він використовується скриптом `.claude/hooks/normalize-decisions.sh` як локальний бекенд для обробки батчу чернеток та списку чистих ADR. Обгортка зчитує шляхи до чернеток та параметри з аргументів командного рядка та змінних середовища, а потім проганяє `normalizePipeline`. Результатом роботи є вивід JSON-контракту з операціями у stdout, який парситься зовнішнім скриптом. Прогрес відображається у stderr.
+
+## Поведінка
+
+1. `runAdrNormalizeLocalCli` парсить вхідні аргументи для визначення шляху до чернеток батчу, списку чистих ADR та каталогу ADR.
+2. Якщо не надано файл батчу, `runAdrNormalizeLocalCli` виводить повідомлення про використання та завершує роботу з кодом помилки.
+3. `runAdrNormalizeLocalCli` зчитує шляхи до чернеток батчу з вказаного файлу.
+4. Для кожної чернетки `runAdrNormalizeLocalCli` зчитує вміст файлу, резолвячи шлях відносно каталогу ADR, і створює об'єкт чернетки.
+5. `runAdrNormalizeLocalCli` зчитує список назв чистих ADR з файлу, якщо він наданий.
+6. `runAdrNormalizeLocalCli` зчитує значення змінних середовища `ADR_NORMALIZE_ALLOW_CLOUD` та `ADR_NORMALIZE_VOTES` для визначення параметрів нормалізації.
+7. `runAdrNormalizeLocalCli` викликає логіку нормалізації, передаючи чернетки, список чистих ADR та параметри, при цьому прогрес виводиться у stderr.
+8. `runAdrNormalizeLocalCli` виводить кількість операцій та статистику нормалізації у stderr.
+9. `runAdrNormalizeLocalCli` виводить деталі рішень нормалізації у stderr.
+10. `runAdrNormalizeLocalCli` друкує JSON-об'єкт, що містить операції, у stdout.
+11. `runAdrNormalizeLocalCli` завершує роботу з кодом успіху.
+
+## Публічний API
+
+runAdrNormalizeLocalCli — запускає субкоманду, виводячи JSON операцій у стандартний вивід та прогрес у стандартний помилковий вивід.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Не звертається до мережі.

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

@@ -0,0 +1,40 @@
+---
+docgen:
+  source: normalize-pipeline.mjs
+  crc: 6619ff48
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+# normalize-pipeline.mjs
+
+## Огляд
+
+Файл реалізує локально-орієнтований конвеєр для нормалізації чернеток ADR. Він використовує LLM лише для вузьких, верифікованих бінарних суджень. Конвеєр працює у послідовних стадіях: JS виконує пошук кандидатів-ребер на основі лексичної схожості, LLM оцінює ці ребра (Stage 1: `same/different`) та драфти (Stage 1b: `standalone/trivial`), JS кластеризує підтверджені ребра (використовуючи `union-find`), LLM реформатує анотера (Stage 2: `gen-MADR`), а LLM генерує доповнення для злиття (Stage 3: `gen-merge`). Глобальний стан (кластери, слаги, покриття) зберігається в JS. Конвеєр повертає операції у форматі `operations[]`, сумісного з контрактом `apply-ops`.
+
+## Поведінка
+
+tokenize токенізує назву або слаг у множину значущих токенів, виключаючи стоп-слова.
+jaccard обчислює Jaccard-схожість між двома множинами токенів.
+draftTitle витягує заголовок чернетки, надаючи пріоритет заголовку ADR.
+isNoDecision визначає, чи не прийнято рішення у чернетці, аналізуючи секцію Decision Outcome.
+buildEdges будує кандидати-ребра між чернетками та між чернетками і чистими ADR на основі лексичної схожості.
+validateMadr перевіряє згенерований контент на відповідність канону чистого MADR.
+normalizePipeline виконує повний конвеєр нормалізації, групуючи чернетки, оцінюючи їх та генеруючи операції для застосування.
+
+## Публічний API
+
+tokenize — розбиває назву чи слаг на значущі частини, замінюючи пробіли та дефіси, і відсіюючи загальні слова.
+jaccard — обчислює ступінь подібності між двома наборами слів.
+draftTitle — витягує заголовок з чернетки, надаючи пріоритет заголовку у форматі `## ADR <title>`, а у відсутності такого — використовує перший не-ADR заголовок або ім'я файлу.
+isNoDecision — визначає, чи не містить чернетка чіткого рішення, що робить її непотрібною для окремого ADR.
+buildEdges — створює потенційні зв'язки між елементами на основі схожості слів.
+validateMadr — перевіряє якість згенерованого документа ADR.
+normalizePipeline — виконує повний процес обробки, повертаючи список виконаних кроків та статистику.
+
+## Гарантії поведінки
+
+- Read-only: файл не виконує операцій запису у файлову систему.
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
+- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
+- Не звертається до мережі.

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

@@ -0,0 +1,73 @@
+/**
+ * CLI-обгортка локального ADR-нормалізатора (`n-cursor adr-normalize-local`).
+ *
+ * Прод-шлях `.claude/hooks/normalize-decisions.sh` викликає цю команду як
+ * local-backend замість single-shot LLM-виклику: bash готує батч і clean-список,
+ * CLI проганяє `normalizePipeline` і друкує у stdout той самий контракт
+ * `{ "operations": [...] }`, що його далі парсить і застосовує bash. Прогрес —
+ * у stderr (потрапляє в normalize-decisions.log).
+ *
+ * Аргументи:
+ *   --batch <file>    newline-список абсолютних шляхів до чернеток батчу
+ *   --clean <file>    newline-список basename-ів clean-ADR (merge-into кандидати)
+ *   --adr-dir <dir>   тека docs/adr (для резолву basename ↔ шлях; default cwd/docs/adr)
+ *
+ * ENV:
+ *   ADR_NORMALIZE_ALLOW_CLOUD=1  дозволити хмарну ескалацію tier-каскаду (default off)
+ *   ADR_NORMALIZE_VOTES=N        голосів self-consistency для clean-ребер (default 2)
+ */
+import { readFileSync } from 'node:fs'
+import { basename, isAbsolute, join } from 'node:path'
+import { normalizePipeline } from './normalize-pipeline.mjs'
+
+/**
+ * Парсить `--key value` пари у плоский об'єкт.
+ * @param {string[]} argv масив аргументів командного рядка
+ * @returns {Record<string, string>} мапа ключ→значення з `--key value` пар
+ */
+function parseArgs(argv) {
+  const out = {}
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a.startsWith('--')) { out[a.slice(2)] = argv[i + 1]; i++ }
+  }
+  return out
+}
+
+const readLines = (file) =>
+  readFileSync(file, 'utf8').split('\n').map((s) => s.trim()).filter(Boolean)
+
+/**
+ * Точка входу субкоманди. Друкує `{operations}` JSON у stdout, прогрес — у stderr.
+ * @param {string[]} argv аргументи після назви команди
+ * @returns {number} exit-code (0 — успіх, 1 — помилка вводу)
+ */
+export function runAdrNormalizeLocalCli(argv) {
+  const args = parseArgs(argv)
+  const adrDir = args['adr-dir'] ?? join(process.cwd(), 'docs/adr')
+  if (!args.batch) {
+    console.error('Usage: n-cursor adr-normalize-local --batch <file> [--clean <file>] [--adr-dir <dir>]')
+    return 1
+  }
+
+  const batchPaths = readLines(args.batch)
+  const drafts = batchPaths.map((p) => {
+    const abs = isAbsolute(p) ? p : join(adrDir, p)
+    return { file: basename(abs), body: readFileSync(abs, 'utf8') }
+  })
+  const cleanList = args.clean ? readLines(args.clean).map((c) => basename(c)) : []
+
+  const allowCloud = process.env.ADR_NORMALIZE_ALLOW_CLOUD === '1'
+  const votes = Number(process.env.ADR_NORMALIZE_VOTES) || 2
+
+  const { operations, stats, trace } = normalizePipeline(drafts, cleanList, {
+    allowCloud,
+    votes,
+    onProgress: (m) => console.error(`adr-normalize-local: ${m}`)
+  })
+
+  console.error(`adr-normalize-local: ${operations.length} операцій, stats=${JSON.stringify(stats)}`)
+  console.error(`adr-normalize-local: decisions=${JSON.stringify(trace.decisions)}`)
+  process.stdout.write(JSON.stringify({ operations }))
+  return 0
+}

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

@@ -0,0 +1,530 @@
+/**
+ * ADR normalize — локально-орієнтований конвеєр (інверсія керування: JS оркеструє,
+ * LLM відповідає лише на вузькі verifiable-питання). Альтернатива single-shot-у
+ * normalize-decisions.sh, заточена під малу локальну модель (omlx/gemma-4b).
+ *
+ * Принцип: модель НІКОЛИ не приймає глобальних рішень і не повертає великих
+ * структур. Глобальний стан (кластери, слаги, покриття) тримає JS. Модель:
+ *   - судить пару записів бінарно «те саме рішення? так/ні» (Stage 1),
+ *   - для ізольованого драфта каже standalone/trivial (Stage 1b),
+ *   - реформатить один драфт у чистий MADR (Stage 2),
+ *   - пише short merge-additions (Stage 3).
+ *
+ * Стадії:
+ *   0. retrieval (JS)   — лексична схожість → кандидати-ребра draft↔draft / draft↔clean
+ *   1. edge-judge (LLM) — бінарне same/different по кожному ребру (self-consistency)
+ *   1b. kind-judge(LLM) — standalone vs trivial для драфтів без ребер
+ *   ── cluster (JS)     — union-find по підтверджених ребрах, вибір anchor, призначення op
+ *   2. gen-MADR (LLM)   — reformat anchor/standalone → чистий MADR + validation gate
+ *   3. gen-merge (LLM)  — additions для merge-драфтів
+ *   ── assemble (JS)    — operations[] у форматі, сумісному з apply-ops
+ *
+ * Повертає той самий operations[]-контракт, що й single-shot — apply-логіка спільна.
+ */
+import { z } from 'zod'
+import { callLlm, classifyOmlxError } from '../../../lib/llm.mjs'
+import { CLOUD_MIN, resolveModel } from '../../../lib/models.mjs'
+
+// ─────────────────────────── Stage 0: retrieval (JS) ───────────────────────────
+
+const STOP = new Set(['adr', 'та', 'для', 'через', 'на', 'в', 'у', 'з', 'із', 'до', 'і', 'й', 'the', 'a', 'of', 'md'])
+
+// Module-scope regex (oxlint prefer-static-regex: без рекомпіляції на кожен виклик).
+const RE_MD_EXT = /\.md$/
+const RE_TS_PREFIX = /^\d{6,8}-\d{4,6}-/
+const RE_FENCE_OPEN = /^\s*```[a-z]*\s*\n?/i
+const RE_FENCE_CLOSE = /\n?```\s*$/i
+const RE_SLUG_NONWORD = /[^a-zа-яіїєґ0-9]+/gi
+const RE_LEAD_HYPHEN = /^-+/
+const RE_TRAIL_HYPHEN = /-+$/
+const RE_UPDATE_HEAD = /^##\s+Update/
+const RE_DECISION_SECTION = /##\s*Decision Outcome\s*([\s\S]{0,500})/i
+const RE_NO_DECISION = /(не\s+обрано|не\s+прийнят|рішення\s+не\s+прийн|не\s+зроблен|no\s+decision|undecided)/i
+const RE_FENCE_LEAD = /^\s*```/
+const RE_FENCE_TRAIL = /```\s*$/
+const RE_FRONTMATTER = /^---\s*$/m
+const RE_SESSION = /\bsession:\s/
+const RE_H1 = /^#\s+\S/m
+const RE_STATUS = /\*\*Status:\*\*/
+const RE_DATE = /\*\*Date:\*\*\s*\d{4}-\d{2}-\d{2}/
+const RE_TOKEN_SPLIT = /[^a-zа-яіїєґ0-9]+/i
+const RE_DRAFT_ADR_TITLE = /^#{1,2}\s+ADR\s+(.+)$/m
+
+/**
+ * Прибирає code-fence-обгортку з LLM-відповіді.
+ * @param {string} raw сира відповідь LLM
+ * @returns {string} текст без обгортки code-fence
+ */
+const stripFence = (raw) => raw.replace(RE_FENCE_OPEN, '').replace(RE_FENCE_CLOSE, '').trim()
+/**
+ * Назва clean-ADR → людський заголовок (без .md і timestamp-префікса).
+ * @param {string} s basename clean-ADR
+ * @returns {string} людський заголовок
+ */
+const stripAdrName = (s) => s.replace(RE_MD_EXT, '').replace(RE_TS_PREFIX, '')
+
+/**
+ * Токенізує назву/слаг у множину значущих токенів (kebab + пробіли, без стоп-слів).
+ * @param {string} s назва або слаг для токенізації
+ * @returns {Set<string>} множина значущих токенів
+ */
+export function tokenize(s) {
+  return new Set(
+    s
+      .toLowerCase()
+      .replace(RE_MD_EXT, '')
+      .replace(RE_TS_PREFIX, '')
+      .split(RE_TOKEN_SPLIT)
+      .filter((t) => t.length > 2 && !STOP.has(t))
+  )
+}
+
+/**
+ * Jaccard-схожість двох множин токенів.
+ * @param {Set<string>} a перша множина токенів
+ * @param {Set<string>} b друга множина токенів
+ * @returns {number} коефіцієнт Jaccard у діапазоні 0..1
+ */
+export function jaccard(a, b) {
+  if (!a.size || !b.size) return 0
+  let inter = 0
+  for (const t of a) if (b.has(t)) inter++
+  return inter / (a.size + b.size - inter)
+}
+
+const MADR_SECTION = /^(Context and Problem|Considered Options|Decision Outcome|Consequences|More Information|report|summary|Attempt|Reason|Update)\b/i
+
+/**
+ * Витягує заголовок драфта. Капчер пише `## ADR <title>` — він у пріоритеті
+ * (чернетка може мати контент-заголовки раніше або взагалі не мати ADR-рядка).
+ * Fallback-и: перший h1, що не є MADR-секцією, інакше '' (caller бере імʼя файлу).
+ * @param {string} body тіло чернетки
+ * @returns {string} заголовок або ''
+ */
+export function draftTitle(body) {
+  const adr = body.match(RE_DRAFT_ADR_TITLE)
+  if (adr) return adr[1].trim()
+  for (const m of body.matchAll(/^#\s+(.+)$/gm)) {
+    if (!MADR_SECTION.test(m[1].trim())) return m[1].trim()
+  }
+  return ''
+}
+
+/**
+ * Детермінований no-decision гейт (харднінг #1). Чернетка, де у `Decision Outcome`
+ * рішення явно НЕ прийняте (transcript обірвався) — не варта окремого ADR: gold
+ * (sonnet) такі видаляє. Ловимо без LLM, щоб не покладатися на kind-judge малої моделі.
+ * @param {string} body тіло чернетки
+ * @returns {boolean} true якщо рішення не прийняте
+ */
+export function isNoDecision(body) {
+  const m = body.match(RE_DECISION_SECTION)
+  if (!m) return false
+  // NB: JS \b не працює з кирилицею — покладаємось на пробіл/межі фрази без \b.
+  return RE_NO_DECISION.test(m[1])
+}
+
+/**
+ * Будує кандидати-ребра за лексичною схожістю.
+ * @param {{file:string, body:string}[]} drafts батч чернеток
+ * @param {string[]} cleanList clean basename-и
+ * @param {{simThreshold?:number, topKClean?:number}} [opts] поріг схожості та ліміт clean-кандидатів
+ * @returns {{dd:[number,number][], dc:[number,string][]}} ребра draft↔draft (dd) і draft↔clean (dc)
+ */
+export function buildEdges(drafts, cleanList, opts = {}) {
+  const simThreshold = opts.simThreshold ?? 0.12
+  const topKClean = opts.topKClean ?? 3
+  const draftTok = drafts.map((d) => tokenize(`${d.file} ${draftTitle(d.body)}`))
+  const cleanTok = new Map(cleanList.map((c) => [c, tokenize(c)]))
+
+  const dd = []
+  for (let i = 0; i < drafts.length; i++) {
+    for (let j = i + 1; j < drafts.length; j++) {
+      if (jaccard(draftTok[i], draftTok[j]) >= simThreshold) dd.push([i, j])
+    }
+  }
+  const dc = []
+  for (let i = 0; i < drafts.length; i++) {
+    const scored = []
+    for (const [c, tok] of cleanTok) {
+      const s = jaccard(draftTok[i], tok)
+      if (s >= simThreshold) scored.push([c, s])
+    }
+    scored.sort((a, b) => b[1] - a[1])
+    for (const [c] of scored.slice(0, topKClean)) dc.push([i, c])
+  }
+  return { dd, dc }
+}
+
+// ─────────────────────────── LLM helper: tier cascade ──────────────────────────
+
+const LOCAL = () => resolveModel('min')
+
+/**
+ * Виклик LLM з локальним ретраєм і (опційно) хмарною ескалацією.
+ * @param {Array<{role:string,content:string}>} messages чат-повідомлення для LLM
+ * @param {(raw:string)=>any} parse валідатор (кидає на невалідному)
+ * @param {{label:string, allowCloud:boolean, attempts?:number, stats:object, maxTokens?:number}} cfg конфіг каскаду (мітка, дозвіл на хмару, спроби, лічильники, ліміт токенів)
+ * @returns {any} результат parse
+ * @throws {Error} якщо всі спроби провалені
+ */
+function callWithCascade(messages, parse, cfg) {
+  const attempts = cfg.attempts ?? 2
+  const temps = [0.1, 0.4, 0.7]
+  let lastErr = null
+  for (let a = 0; a < attempts; a++) {
+    try {
+      cfg.stats.localCalls++
+      const raw = callLlm(messages, LOCAL(), {
+        timeoutMs: 120_000,
+        temperature: temps[a] ?? 0.2,
+        maxTokens: cfg.maxTokens ?? 4096,
+        caller: `adr-pipe:${cfg.label}`
+      })
+      return parse(raw)
+    } catch (error) {
+      lastErr = error
+      if (classifyOmlxError(error.message) === 'infra') break
+    }
+  }
+  if (cfg.allowCloud && CLOUD_MIN) {
+    try {
+      cfg.stats.cloudCalls++
+      cfg.stats.escalations++
+      const raw = callLlm(messages, CLOUD_MIN, { timeoutMs: 120_000, temperature: 0.2, maxTokens: cfg.maxTokens ?? 4096, caller: `adr-pipe:${cfg.label}:cloud` })
+      return parse(raw)
+    } catch (error) {
+      lastErr = error
+    }
+  }
+  cfg.stats.failures++
+  throw lastErr ?? new Error('callWithCascade: no result')
+}
+
+/**
+ * Витяг першого JSON-обʼєкта з raw-тексту.
+ * @param {string} raw сирий текст відповіді LLM
+ * @returns {any} розпарсений JSON-обʼєкт
+ * @throws {Error} якщо у тексті немає JSON-обʼєкта
+ */
+function extractJson(raw) {
+  const s = raw.indexOf('{')
+  const e = raw.lastIndexOf('}')
+  if (s === -1 || e === -1) throw new Error('no JSON object')
+  return JSON.parse(raw.slice(s, e + 1))
+}
+
+// ─────────────────────────── Stage 1: edge-judge (LLM) ─────────────────────────
+
+const EdgeSchema = z.object({
+  same: z.boolean(),
+  confidence: z.number().min(0).max(1),
+  reason: z.string().min(3).max(400)
+})
+
+const EDGE_SYS = `Ти порівнюєш два короткі записи архітектурних рішень (ADR). Визнач, чи вони описують ОДНЕ І ТЕ САМЕ рішення (одну тему/механізм, де другий лише уточнює/доповнює/продовжує перший), чи це РІЗНІ незалежні рішення.
+
+Поверни ЛИШЕ JSON, без markdown:
+{ "same": true|false, "confidence": 0..1, "reason": "<коротко українською>" }
+
+same=true ЛИШЕ якщо це по суті одне рішення (дублікат, уточнення, продовження тієї самої теми). Різні аспекти однієї підсистеми, але окремі рішення → same=false. Якщо сумніваєшся — false.`
+
+/**
+ * Бінарний суддя «те саме рішення?» з self-consistency. Консервативний: `same`
+ * лише якщо ВСІ голоси кажуть same з confidence ≥ minConf. Харднінг #2: для
+ * draft↔draft (ризик over-merge) піднімаємо до 3 голосів і порога 0.6.
+ * @param {string} aTitle заголовок запису A
+ * @param {string} aBody тіло запису A
+ * @param {string} bTitle заголовок запису B
+ * @param {string} bBody тіло запису B
+ * @param {{allowCloud:boolean, votes?:number, stats:object}} cfg конфіг каскаду (дозвіл на хмару, голоси, лічильники)
+ * @param {{votes?:number, minConf?:number}} [vote] override голосів і порога на тип ребра
+ * @returns {{same:boolean, votes:object[]}} підтвердження same та сирі голоси
+ */
+function judgeEdge(aTitle, aBody, bTitle, bBody, cfg, vote = {}) {
+  const nVotes = vote.votes ?? cfg.votes ?? 2
+  const minConf = vote.minConf ?? 0.5
+  const user = `Запис A — "${aTitle}":\n${aBody.slice(0, 1500)}\n\n---\n\nЗапис B — "${bTitle}":\n${bBody.slice(0, 1500)}\n\nЦе одне й те саме рішення?`
+  const parse = (raw) => EdgeSchema.parse(extractJson(raw))
+  const votes = []
+  for (let v = 0; v < nVotes; v++) {
+    try {
+      votes.push(callWithCascade([{ role: 'system', content: EDGE_SYS }, { role: 'user', content: user }], parse, { label: 'edge', allowCloud: cfg.allowCloud, stats: cfg.stats, maxTokens: 300 }))
+    } catch {
+      votes.push({ same: false, confidence: 0, reason: 'judge failed → conservative different' })
+    }
+  }
+  const sameCount = votes.filter((v) => v.same && v.confidence >= minConf).length
+  return { same: sameCount === votes.length, votes }
+}
+
+// ─────────────────────────── Stage 1b: kind-judge (LLM) ────────────────────────
+
+const KindSchema = z.object({
+  kind: z.enum(['standalone', 'trivial']),
+  reason: z.string().min(3).max(400)
+})
+
+const KIND_SYS = `Ти оцінюєш чернетку архітектурного рішення (ADR). Визнач:
+- "standalone" — це самостійне рішення, варте збереження як decision record.
+- "trivial" — порожнє / тривіальне / косметичне / без реального рішення, можна видалити.
+
+Поверни ЛИШЕ JSON: { "kind": "standalone"|"trivial", "reason": "<коротко українською>" }
+Якщо сумніваєшся — "standalone" (краще зберегти).`
+
+function judgeKind(title, body, cfg) {
+  const user = `Чернетка — "${title}":\n${body.slice(0, 2500)}\n\nstandalone чи trivial?`
+  const parse = (raw) => KindSchema.parse(extractJson(raw))
+  try {
+    return callWithCascade([{ role: 'system', content: KIND_SYS }, { role: 'user', content: user }], parse, { label: 'kind', allowCloud: cfg.allowCloud, stats: cfg.stats, maxTokens: 200 })
+  } catch {
+    return { kind: 'standalone', reason: 'judge failed → conservative standalone' }
+  }
+}
+
+// ─────────────────────────── Stage 2: gen-MADR (LLM) ───────────────────────────
+
+const MADR_HEADINGS = [
+  '## Context and Problem Statement',
+  '## Considered Options',
+  '## Decision Outcome',
+  '## More Information'
+]
+
+/**
+ * Детермінований гейт якості згенерованого MADR.
+ * @param {string} content згенерований MADR-текст
+ * @returns {{ok:boolean, errors:string[]}} результат перевірки та перелік порушень
+ */
+export function validateMadr(content) {
+  const errors = []
+  if (!content || content.length < 80) errors.push('too short')
+  if (RE_FENCE_LEAD.test(content) || RE_FENCE_TRAIL.test(content.trim())) errors.push('code-fence wrapper')
+  if (RE_FRONTMATTER.test(content.split('\n').slice(0, 3).join('\n'))) errors.push('has YAML frontmatter')
+  if (RE_SESSION.test(content)) errors.push('leaked session: field')
+  if (!RE_H1.test(content)) errors.push('missing # title')
+  if (!RE_STATUS.test(content)) errors.push('missing Status')
+  if (!RE_DATE.test(content)) errors.push('missing/!ISO Date')
+  for (const h of MADR_HEADINGS) if (!content.includes(h)) errors.push(`missing heading ${h}`)
+  return { ok: errors.length === 0, errors }
+}
+
+const GEN_SYS = `Ти нормалізуєш чернетку ADR у чистий фінальний MADR 4.0.0. Чернетка вже містить секції — твоя задача ОЧИСТИТИ й привести до канону, НЕ вигадуючи нового.
+
+Поверни ЛИШЕ markdown файлу (починається з "# "), без code-fence, без передмови, без YAML frontmatter.
+
+Структура РІВНО така:
+# <Заголовок українською>
+
+**Status:** Accepted
+**Date:** <YYYY-MM-DD з поля captured чернетки, перші 10 символів>
+
+## Context and Problem Statement
+<...>
+
+## Considered Options
+<bullets; якщо альтернатив не було — "Інші варіанти не обговорювалися.">
+
+## Decision Outcome
+Chosen option: "<...>", because <...>.
+
+### Consequences
+<bullets "Good, because ...", "Bad, because ...">
+
+## More Information
+<файли, команди, API; якщо нема — "Додаткової інформації не зафіксовано.">
+
+Не вигадуй альтернатив, наслідків чи контексту, яких нема в чернетці. Прибери YAML frontmatter (session/captured/transcript) повністю.`
+
+const slugify = (title) =>
+  title.toLowerCase().replace(RE_SLUG_NONWORD, '-').replace(RE_LEAD_HYPHEN, '').slice(0, 60).replace(RE_TRAIL_HYPHEN, '') || 'adr'
+
+function genMadr(title, body, captured, cfg) {
+  const date = (captured ?? '').slice(0, 10)
+  const user = `Чернетка "${title}" (captured: ${captured ?? 'невідомо'}):\n\n${body}\n\nПоверни чистий MADR. Date = ${date || 'візьми з captured'}.`
+  const parse = (raw) => {
+    const content = stripFence(raw)
+    const v = validateMadr(content)
+    if (!v.ok) throw new Error(`MADR invalid: ${v.errors.join('; ')}`)
+    return content
+  }
+  try {
+    const content = callWithCascade([{ role: 'system', content: GEN_SYS }, { role: 'user', content: user }], parse, { label: 'gen', allowCloud: cfg.allowCloud, stats: cfg.stats, attempts: 3, maxTokens: 4096 })
+    return { content, slug: slugify(title), valid: true }
+  } catch (error) {
+    cfg.stats.madrInvalid++
+    return { content: null, slug: slugify(title), valid: false, error: error.message }
+  }
+}
+
+// ─────────────────────────── Stage 3: gen-merge (LLM) ──────────────────────────
+
+const MERGE_SYS = `Ти готуєш короткий блок-доповнення до існуючого ADR. Поверни ЛИШЕ markdown-блок (без code-fence), що починається рядком "## Update <YYYY-MM-DD>", і містить ЛИШЕ новий зміст, якого ще нема в цільовому ADR (уточнення/виправлення/продовження). Стисло. Без передмови.`
+
+function genMerge(title, body, captured, targetTitle, cfg) {
+  const date = (captured ?? '').slice(0, 10)
+  const user = `Цільовий ADR: "${targetTitle}".\nЧернетка-доповнення "${title}" (${date}):\n${body.slice(0, 2500)}\n\nДай блок "## Update ${date}" з НОВИМ змістом.`
+  const parse = (raw) => {
+    const t = stripFence(raw)
+    if (!RE_UPDATE_HEAD.test(t)) throw new Error('missing ## Update heading')
+    return t
+  }
+  try {
+    return callWithCascade([{ role: 'system', content: MERGE_SYS }, { role: 'user', content: user }], parse, { label: 'merge', allowCloud: cfg.allowCloud, stats: cfg.stats, attempts: 2, maxTokens: 1500 })
+  } catch {
+    return `## Update ${date}\n\n(доповнення з чернетки "${title}")`
+  }
+}
+
+// ─────────────────────────── union-find ────────────────────────────────────────
+
+function makeDSU(n) {
+  const p = Array.from({ length: n }, (_, i) => i)
+  const find = (x) => (p[x] === x ? x : (p[x] = find(p[x])))
+  const union = (a, b) => { p[find(a)] = find(b) }
+  return { find, union }
+}
+
+const captureField = (body, field) => (body.match(new RegExp(`^${field}:\\s*(.+)$`, 'm')) ?? [])[1]?.trim()
+
+/**
+ * No-op за замовчуванням для onProgress (коли caller не передав логер).
+ * @returns {void} нічого не робить
+ */
+const noop = () => {
+  // навмисно порожньо: тихий fallback для onProgress
+}
+
+// ─────────────────────────── orchestrator ──────────────────────────────────────
+
+/**
+ * Головний конвеєр. Повертає operations[] (контракт single-shot) + stats.
+ * @param {{file:string, body:string}[]} drafts батч чернеток
+ * @param {string[]} cleanList clean basename-и
+ * @param {{allowCloud?:boolean, votes?:number, onProgress?:(m:string)=>void}} [opts] хмарна ескалація, кількість голосів і колбек прогресу
+ * @returns {{operations:object[], stats:object, trace:object}} операції apply-ops, лічильники та діагностичний trace
+ */
+export function normalizePipeline(drafts, cleanList, opts = {}) {
+  const allowCloud = opts.allowCloud ?? false
+  const log = opts.onProgress ?? noop
+  const stats = { localCalls: 0, cloudCalls: 0, escalations: 0, failures: 0, madrInvalid: 0 }
+  const cfg = { allowCloud, votes: opts.votes ?? 2, stats }
+
+  const titles = drafts.map((d) => draftTitle(d.body) || d.file.replace(RE_MD_EXT, ''))
+  const captured = drafts.map((d) => captureField(d.body, 'captured'))
+
+  // Харднінг #1: детермінований no-decision гейт. Такі драфти не кластеризуємо й
+  // не rewrite-имо — одразу delete (без LLM), як це робить gold.
+  const noDec = drafts.map((d) => isNoDecision(d.body))
+  if (noDec.some(Boolean)) log(`no-decision гейт: ${noDec.filter(Boolean).length} драфт(ів) → delete`)
+
+  // Stage 0: retrieval (ребра, що торкаються no-decision драфтів, відкидаємо)
+  const edges = buildEdges(drafts, cleanList)
+  const dd = edges.dd.filter(([i, j]) => !noDec[i] && !noDec[j])
+  const dc = edges.dc.filter(([i]) => !noDec[i])
+  log(`retrieval: ${dd.length} draft-draft ребер, ${dc.length} draft-clean кандидатів`)
+
+  // Stage 1: judge draft↔draft ребра (харднінг #2: 3 голоси, conf ≥ 0.6 проти over-merge)
+  const dsu = makeDSU(drafts.length)
+  const confirmedDD = []
+  for (const [i, j] of dd) {
+    const r = judgeEdge(titles[i], drafts[i].body, titles[j], drafts[j].body, cfg, { votes: 3, minConf: 0.6 })
+    if (r.same) { dsu.union(i, j); confirmedDD.push([i, j]) }
+  }
+  log(`edge-judge: ${confirmedDD.length}/${dd.length} draft-draft ребер підтверджено`)
+
+  // Stage 1: judge draft↔clean → найкращий existing-target на драфт
+  const cleanTarget = Array.from({ length: drafts.length }).fill(null)
+  const dcByDraft = new Map()
+  for (const [i, c] of dc) { if (!dcByDraft.has(i)) dcByDraft.set(i, []); dcByDraft.get(i).push(c) }
+  for (const [i, cands] of dcByDraft) {
+    for (const c of cands) {
+      const cTitle = stripAdrName(c)
+      const r = judgeEdge(titles[i], drafts[i].body, cTitle, cTitle, cfg)
+      if (r.same) { cleanTarget[i] = c; break }
+    }
+  }
+  log(`clean-match: ${cleanTarget.filter(Boolean).length} драфтів вже покриті clean-ADR`)
+
+  // Cluster (JS): групуємо за DSU
+  const clusters = new Map()
+  for (let i = 0; i < drafts.length; i++) {
+    const root = dsu.find(i)
+    if (!clusters.has(root)) clusters.set(root, [])
+    clusters.get(root).push(i)
+  }
+
+  const decision = Array.from({ length: drafts.length }).fill(null)
+  const operations = []
+
+  for (const [, members] of clusters) {
+    if (members.length > 1) {
+      // anchor — лише серед non-noDec (no-decision не може бути канонічним rewrite)
+      const live = members.filter((m) => !noDec[m])
+      // anchor = індекс із найдовшим drafts[idx].body.length; при рівності — перший
+      // зустрінутий (еквівалент reduce з `>=`, що зберігає поточний акумулятор a).
+      const candidates = live.length ? live : members
+      let anchor = candidates[0]
+      for (let k = 1; k < candidates.length; k++) {
+        if (drafts[candidates[k]].body.length > drafts[anchor].body.length) anchor = candidates[k]
+      }
+      decision[anchor] = { op: 'rewrite' }
+      for (const m of members) {
+        if (m === anchor) continue
+        decision[m] = noDec[m] ? { op: 'delete', reason: 'рішення не прийняте (transcript обірвався)' } : { op: 'merge-anchor', anchorIdx: anchor }
+      }
+    } else {
+      const i = members[0]
+      if (noDec[i]) decision[i] = { op: 'delete', reason: 'рішення не прийняте (transcript обірвався)' }
+      else if (cleanTarget[i]) decision[i] = { op: 'merge-existing', target: cleanTarget[i] }
+      else decision[i] = { op: 'kind' }
+    }
+  }
+
+  // одинаки без clean-target → kind-judge
+  for (let i = 0; i < drafts.length; i++) {
+    if (decision[i].op === 'kind') {
+      const k = judgeKind(titles[i], drafts[i].body, cfg)
+      decision[i] = k.kind === 'trivial' ? { op: 'delete', reason: k.reason } : { op: 'rewrite' }
+    }
+  }
+
+  // Stage 2: gen-MADR для всіх rewrite (anchors + standalones)
+  const slugByIdx = Array.from({ length: drafts.length }).fill(null)
+  for (let i = 0; i < drafts.length; i++) {
+    if (decision[i].op !== 'rewrite') continue
+    const g = genMadr(titles[i], drafts[i].body, captured[i], cfg)
+    slugByIdx[i] = g.slug
+    if (g.valid) {
+      operations.push({ op: 'rewrite', file: drafts[i].file, slug: g.slug, content: g.content })
+    } else {
+      decision[i] = { op: 'gen-failed' }
+      log(`gen-MADR FAILED для ${drafts[i].file}: ${g.error}`)
+    }
+  }
+
+  // Stage 3: merges
+  for (let i = 0; i < drafts.length; i++) {
+    const d = decision[i]
+    if (d.op === 'merge-anchor') {
+      const slug = slugByIdx[d.anchorIdx]
+      if (!slug) { log(`merge-anchor ${drafts[i].file}: anchor gen failed → skip`); continue }
+      const add = genMerge(titles[i], drafts[i].body, captured[i], titles[d.anchorIdx], cfg)
+      operations.push({ op: 'merge-into', file: drafts[i].file, target: `${slug}.md`, additions: add })
+    } else if (d.op === 'merge-existing') {
+      const cTitle = stripAdrName(d.target)
+      const add = genMerge(titles[i], drafts[i].body, captured[i], cTitle, cfg)
+      operations.push({ op: 'merge-into', file: drafts[i].file, target: d.target, additions: add })
+    } else if (d.op === 'delete') {
+      operations.push({ op: 'delete', file: drafts[i].file, reason: d.reason })
+    }
+  }
+
+  const trace = {
+    titles,
+    clusters: Array.from(clusters.values(), (m) => m.map((i) => drafts[i].file)),
+    cleanTargets: cleanTarget.map((c, i) => (c ? [drafts[i].file, c] : null)).filter(Boolean),
+    decisions: decision.map((d, i) => [drafts[i].file, d.op])
+  }
+  return { operations, stats, trace }
+}