@nitra/cursor 10.1.0 → 10.3.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
 
+## [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
+
+- tool-surface rule — паритет «UI ↔ LLM ↔ оркестратор»: будь-яка дія фронтенду виконувана без UI через спільний каталог тулів (catalog → dispatch → UI/CLI/LLM-адаптери). Платформо-незалежне ядро; per-stack деталі делегуються правилам tauri/vue/capacitor. Авто-активація на фронтенд-залежностях. Додано per-stack секцію «Tool Surface у Tauri» в правило tauri (делегація в Rust-крейт/бінарник, два транспорти, схеми через schemars, дозволи плагінів).
+
 ## [10.1.0] - 2026-06-15
 
 ### Changed

package/bin/n-cursor.js

@@ -4,19 +4,18 @@
  * n-cursor — CLI завантаження правил та перевірки проєкту
  *
  * Використання:
- *   `npx \@nitra/cursor`             — завантажити cursor-правила
- *   `npx \@nitra/cursor fix`         — автономний оркестратор: T0-auto + LLM (haiku→sonnet); convergence-loop до чистого стану [--max-iter N] [rules]
- *                                     якщо в корені вже є `.n-cursor.json`, спочатку зчитується конфіг і за потреби дописується `$schema`
- *   `npx \@nitra/cursor fix bun`     — оркестратор лише для вказаних правил; `--json` = check-only (structured output для CI)
+ *   `npx \@nitra/cursor`             — завантажити cursor-правила (синк); якщо в корені вже є `.n-cursor.json`,
+ *                                     спочатку зчитується конфіг і за потреби дописується `$schema`
  *   `npx \@nitra/cursor rename-yaml-extensions` — k8s `*.yml` → `*.yaml`, `.github` `*.yaml` → `*.yml` (опції: `--dry-run`, `--root=…`; див. bin/rename-yaml-extensions.mjs)
  *   `npx \@nitra/cursor post-tool-use-fix` — точка входу PostToolUse hook Claude Code: читає stdin JSON,
  *                                     дістає `tool_input.file_path`, маршрутизує його у відповідні правила
  *                                     (`*.mjs` → `js-lint`, `*.vue` → `js-lint style-lint vue` тощо) і викликає
  *                                     `fix` лише з ними. Прописується автоматично в `.claude/settings.json`.
- *   `npx \@nitra/cursor fix`         — автономний оркестратор (meta.json: orchestrator:true): T0-auto → LLM via pi (haiku→sonnet) → check-gate → loop; [--max-iter N] [rules]
- *   `npx \@nitra/cursor lint`        — оркестратор lint-ланцюжка з кореневого `package.json` з вимірюванням часу
- *                                     кожного `lint-*` / `oxfmt` скрипта (fail-fast); канонічна заміна
- *                                     раніше ручного `lint-ga && lint-js && …` агрегатора.
+ *   `npx \@nitra/cursor lint`        — data-driven оркестратор lint+конформності по `rules/<id>/meta.json` (`lint: per-file|full`):
+ *                                     за замовчуванням fix-by-default по дельті vs origin (лише `per-file` правила); `--full` =
+ *                                     весь репо (`per-file` ∪ `full`); `--read-only` = без мутацій/LLM (CI); позиційні
+ *                                     (не-флаг) аргументи — фільтр правил конформності (мапить колишній `fix <rule>`).
+ *                                     CI = `lint --read-only --full` (весь репо, нуль мутацій/LLM).
  *   `npx \@nitra/cursor lint-ga`     — канонічний lint-ga (ga.mdc): preflight на `shellcheck` →
  *                                     `bunx github-actionlint` → `uvx zizmor --offline --collect=workflows .`
  *   `npx \@nitra/cursor lint-rego`   — канонічний lint-rego (conftest.mdc + rego.mdc):
@@ -27,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
@@ -661,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`, за запитом.',
     ''
   ]
 }
@@ -1507,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))
   }
@@ -1542,12 +1540,6 @@ try {
 
       break
     }
-    case 'lint-ci': {
-      // CI = весь репо в read-only (нуль мутацій, нуль LLM) — еквівалент `lint --read-only --full`.
-      process.exitCode = await runLint({ full: true, readOnly: true })
-
-      break
-    }
     case 'lint-ga': {
       // Канонічний lint-ga з preflight на shellcheck → actionlint → zizmor → check-ga (ga.mdc).
       // Останній крок (check-ga) async — тому await обов'язковий, інакше process.exitCode буде Promise.
@@ -1669,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
     }
@@ -1727,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, lint-ci, 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.1.0",
+  "version": "10.3.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

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

@@ -42,8 +42,17 @@ const IMPORT_AS_RE = /[ \t]{1,8}as[ \t]{1,8}.{0,200}/
 const WRITE_FS_RE = /\b(writeFile|mkdir|rmdir|unlink|appendFile|createWriteStream|rm\()/
 const CATCH_RE = /catch\s*\(/
 const TRY_RE = /\btry\s*\{/
-const FALSY_RETURN_RE = /return\s+(false|null|''|"")/
-const NETWORK_RE = /\bfetch\(|https?\.|axios|got\(/
+// Falsy-return як «fail-safe» — лише коли воно в catch/error-гілці (інакше це
+// звичайний guard `if (!x) return null`, не обробка помилки). Уникає over-claim.
+const FALSY_RETURN_RE = /catch[\s\S]{0,400}?return\s+(false|null|''|"")/
+// Мережа: окрім явного fetch/http, ловимо абстраговані клієнти (graphql/db/rpc/
+// 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()`) — не кеш, а хибна гарантія
 // «Кешує результати» гірша за пропуск (фабрикація > мовчання).
@@ -202,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/js-lint-ci/js-lint-ci.mdc

@@ -1,5 +1,5 @@
 ---
-description: Крос-файловий ci-етап js-lint — jscpd (детектор клонів) і knip (невикористані експорти). Лише у lint-ci, по всьому репо.
+description: Крос-файловий ci-етап js-lint — jscpd (детектор клонів) і knip (невикористані експорти). Лише у `lint --full`, по всьому репо.
 globs: "**/{.oxlintrc.json,eslint.config.js,.jscpd.json,knip.json,package.json},**/*.{js,mjs,cjs,jsx,ts,tsx}"
 alwaysApply: false
 version: '1.0'
@@ -8,7 +8,7 @@ version: '1.0'
 # js-lint-ci — крос-файловий ci-етап
 
 `jscpd` і `knip` аналізують увесь граф проєкту, тож мають сенс лише у повному прогоні
-`npx @nitra/cursor lint-ci` (не у швидкому `lint` по змінених файлах). Per-file режиму нема.
+`npx @nitra/cursor lint --full` (CI: `lint --read-only --full`) — не у швидкому `lint` по змінених файлах. Per-file режиму нема.
 
 Швидкий етап js-lint (oxlint/eslint) — у правилі `js-lint` (`lint: per-file`).
 

package/rules/tauri/tauri.mdc

@@ -2,7 +2,7 @@
 description: Tauri
 globs: "**/src-tauri/**,**/tauri.conf.json"
 alwaysApply: false
-version: '1.4'
+version: '1.5'
 ---
 
 У `.vscode/extensions.json` `recommendations` має містити `tauri-apps.tauri-vscode`:
@@ -66,3 +66,25 @@ exclude_globs = [
   - якщо обидва канонічні ключі (`additional_cargo_test_args`, `exclude_globs`) вже присутні — `manual cargo-mutants config preserved`, нічого не зміниться;
   - якщо якийсь канонічний ключ відсутній — додається окремим блоком у кінці файла, без зміни існуючих значень.
 - Послідовний `fix test` → `fix tauri` створює Tauri-config; повторний `fix tauri` не дублює секцій; повторний `fix test` не перетирає Tauri-tuning.
+
+## Tool Surface у Tauri (реалізація ядра `tool-surface`)
+
+Це per-stack реалізація правила **`tool-surface`** (`n-tool-surface`) для Tauri+Rust. Контракт (каталог → `dispatch` → UI/оркестратор/LLM, інваріант паритету, конверт) — у тому правилі; тут — як він лягає на Tauri.
+
+**Реальна робота живе в Rust, JS-каталог — тонкий call surface.** Handler тула не містить логіки сам — він **делегує** в native. Одна реалізація в Rust-крейті backs два споживачі:
+
+- **Бінарник** (`src-tauri` як CLI, або окремий crate-bin) — headless-вхід для оркестратора;
+- **Tauri-команда** (`#[tauri::command]`) — той самий крейт-fn, обгорнутий для UI.
+
+**Два транспорти одного каталогу** (`src/tool/transports`):
+
+- **UI (in-app):** `invoke(tool.tauri, input)` → Tauri-команда → крейт. Ключі `input` мапляться 1:1 на аргументи команди (camelCase, напр. `tasksDir`); поля вкладених struct лишаються snake_case (Tauri конвертить лише імена top-level аргументів).
+- **Оркестратор (headless):** `bin/<app>.mjs` спавнить зібраний бінарник (`<bin> <verb> …` per-verb, або уніфікований `<bin> exec '<json>'`), парсить JSON stdout.
+
+**Конверт:** Tauri-команда повертає `Result<T, String>`; адаптер мапить у `{ ok, output }` / `{ ok:false, error }`. Бінарник друкує конверт у stdout, exit ≠ 0 на `ok:false`.
+
+**Єдине джерело схем:** надавай перевагу `schemars`-derive на Rust-param-структурах → бінарник віддає маніфест (`<bin> schema`); або тримай схему в JS-каталозі й валідуй до `invoke`. **Не дублюй** контракт між Rust і JS — лише деривація + спільні тест-вектори.
+
+**Дозволи:** будь-який плагін, який смикають тули (`tauri-plugin-dialog`, `tauri-plugin-http` для локальної LLM тощо), має бути в `src-tauri/capabilities/*.json` і зареєстрований у `lib.rs` — інакше виклик тихо падає.
+
+**LLM-раннер in-app:** chat-loop ходить до OpenAI-сумісного ендпоінта через `tauri-plugin-http` fetch (бо webview-fetch обмежений CSP/capability), а тули виконує через спільний `dispatch` (той самий, що й UI).

package/rules/tool-surface/fix.mjs

@@ -0,0 +1,18 @@
+import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
+import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
+
+/**
+ * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
+ * Library mode: викликається CLI orchestration через `import + run(ctx)`.
+ * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function run(ctx) {
+  return runStandardRule(import.meta.dirname, ctx)
+}
+
+if (isRunAsCli(import.meta.url)) {
+  // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
+  // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
+  process.exitCode = await runRuleCli(import.meta.dirname)
+}

package/rules/tool-surface/meta.json

@@ -0,0 +1 @@
+{ "auto": { "predicate": "depInAnyPackageJson", "arg": ["vue", "react", "svelte", "@angular/core", "preact", "solid-js", "@tauri-apps/api", "@capacitor/core"] } }

package/rules/tool-surface/tool-surface.mdc

@@ -0,0 +1,72 @@
+---
+description: Tool Surface — будь-яка дія фронтенду має бути виконуваною без UI (CLI + LLM) через спільний каталог тулів; UI/оркестратор/LLM — рівноправні адаптери
+alwaysApply: true
+version: '1.0'
+---
+
+# Tool Surface — паритет «UI ↔ LLM ↔ оркестратор»
+
+## Принцип
+
+**Будь-яка дія, яку людина виконує через фронтенд, мусить бути виконуваною як `tool` — без UI — бо вона організована як іменований виклик зі схемою, до якого однаково дотягуються UI, скриптовий оркестратор і LLM.**
+
+Ключовий новий споживач — **LLM**, тож одиниця називається `tool`. Фронтенд — лише один з адаптерів, а не єдині двері.
+
+## Це НЕ про «винести логіку на бекенд»
+
+Лінія поділу не «фронт ↔ бек», а:
+
+> виклик, досяжний **лише через UI-взаємодію** → погано
+> виклик, досяжний як **іменований tool зі схемою** → добре
+
+JS-логіка може лишатися на фронті — її лише треба **витягнути** з обробника події в окремий tool (ім'я + параметри + схема), який однаково кличе UI, оркестратор і LLM. Tool Surface — це **call surface**, не обов'язково бекенд.
+
+## Три шари
+
+1. **Tool Catalog** (`src/tool/`) — декларативний каталог. Кожен tool: `name`, `summary`, схема входу/виходу, `handler`. Handler **може бути фронтендовою JS-функцією** (або делегувати в native/HTTP/DB). Це **єдине джерело правди**; з нього генеруються schema-маніфест (для LLM) і типи клієнта.
+2. **Dispatch** — одна функція `dispatch(name, input) → { ok, output } | { ok: false, error }`: валідує вхід за схемою, кличе handler, повертає **уніфікований конверт**. Не прив'язана до UI-рендеру/подій.
+3. **Споживачі** (усі обов'язкові):
+   - **UI** — компонент кличе `dispatch`, без inline-логіки дії.
+   - **Оркестратор** — машинний вхід `<bin> <tool> '<json>'` (+ `schema`/`list`). Кличуть скрипти, не люди — людський CLI з verb-ами не потрібен.
+   - **LLM** — tool-маніфест із каталогу; tool_call маршрутизується в `dispatch`.
+
+## Інваріант паритету (серце правила)
+
+- **Жодної дії, досяжної лише через UI-взаємодію.** Обробник події **делегує** в `dispatch`/каталог, а не містить inline-логіку (мережа, мутація моделі, виклик бекенду).
+- Дозволено: логіка у фронтенд-коді. Заборонено: логіка **зашита** в обробник кліку/сабміту так, що дотягтись можна лише кліком.
+- Кожен tool каталогу має **усіх** споживачів (UI + оркестратор + LLM), інакше це не headless.
+
+## Єдине джерело схем
+
+Схема входу tool-а живе в каталозі (zod / JSON Schema; для Rust — `schemars`). З неї генеруються: tool-маніфест для LLM (формат залежить від провайдера — OpenAI function-calling, Anthropic tools або MCP), CLI-довідка, типи клієнта. Тул-визначення **не повинні розходитися** з каталогом — лише деривація, не дублювання.
+
+## Уніфікований конверт
+
+```jsonc
+{ "ok": true,  "output": { /* результат */ } }
+{ "ok": false, "error": { "code": "validation|not_found|io|…", "message": "…" } }
+```
+
+Оркестратор: `ok:false` → ненульовий exit. UI/LLM: `Result` / tool_result з `is_error`.
+
+## Дворівнева структура (архітектура спільна, реалізація per-stack)
+
+Архітектура **спільна**, реалізація **навмисно розходиться** за стеком. Це правило тримає платформо-незалежне **ядро**; конкретику делегують профільні правила:
+
+| Рівень | Що тут | Де |
+|---|---|---|
+| **Ядро** | принцип, інваріант паритету, контракт каталог/`dispatch`/схема/конверт, 3 споживачі | це правило |
+| **Tauri+Rust** | handler делегує в Rust-крейт/бінарник; машинний bin; `invoke`/spawn | `n-tauri` |
+| **Capacitor / pure-web** | handler — JS напряму; bin = node/bun-скрипт, що імпортує handlers | `n-capacitor` |
+| **UI-адаптер** | компонент делегує в `dispatch`, нуль inline-логіки | `n-vue` |
+
+## Конвенція файлів
+
+```
+src/tool/
+  catalog.(js|ts)     ← каталог тулів (single source): name, summary, input schema, mapping
+  dispatch.(js|ts)    ← dispatch(name, input) + валідація + конверт
+  manifest.(js|ts)    ← каталог → LLM tools ; CLI help
+  transports.(js|ts)  ← UI-транспорт (invoke/fetch) ; CLI-транспорт (spawn/import)
+bin/<app>.mjs         ← машинний вхід: <tool> '<json>' | schema | list
+```

package/schemas/rule-meta.json

@@ -8,8 +8,8 @@
   "properties": {
     "lint": {
       "type": "string",
-      "enum": ["quick", "ci"],
-      "description": "Фаза lint-кроку: quick (по змінених, у lint і lint-ci) або ci (лише lint-ci)."
+      "enum": ["per-file", "full"],
+      "description": "Scope lint-кроку: per-file (декомпозиція по змінених файлах, дельта vs origin) або full (нероздільно крос-файловий, лише `lint --full`)."
     },
     "auto": {
       "description": "Умова автоактивації правила: \"завжди\", масив id правил-залежностей, glob, або іменований предикат.",

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 }
+}