@nitra/cursor 1.9.23 → 1.11.0

package/rules/abie/utils/k8s-tree.mjs

@@ -0,0 +1,102 @@
+/**
+ * Обхід k8s-дерева abie з кешуванням на час одного прогону:
+ *   - `findK8sYamlFiles(root, ignorePaths)` — yaml/yml файли під сегментом `k8s/`.
+ *   - `collectDeploymentDirs(root, yamlAbs)` — каталоги, де знайдено `kind: Deployment`.
+ *
+ * Кеш — module-level singleton, ключований за `(root, ignorePaths)`. Перший виклик
+ * платить за обхід; наступні концерни в межах того ж прогону отримують готове.
+ * Для тестів — `resetAbieK8sTreeCache()` (інакше withTmpCwd-фікстури злипатимуться).
+ */
+import { dirname, relative } from 'node:path'
+
+import { pathHasK8sSegment } from '../../k8s/js/check.mjs'
+import { walkDir } from '../../../scripts/utils/walkDir.mjs'
+import { isDeploymentDoc, readAndParseYamlDocs } from './yaml.mjs'
+
+const YAML_EXTENSION_RE = /\.ya?ml$/iu
+
+/** @type {Map<string, Promise<string[]>>} */
+const yamlCache = new Map()
+/** @type {Map<string, Promise<Set<string>>>} */
+const deploymentCache = new Map()
+
+/**
+ * Скидає кеш — тести мусять викликати між фікстурами.
+ * @returns {void}
+ */
+export function resetAbieK8sTreeCache() {
+  yamlCache.clear()
+  deploymentCache.clear()
+}
+
+/**
+ * Стабільний ключ кешу за (root, ignorePaths).
+ * @param {string} root
+ * @param {string[]} ignorePaths
+ * @returns {string}
+ */
+function cacheKey(root, ignorePaths) {
+  return `${root}|${[...ignorePaths].toSorted((a, b) => a.localeCompare(b)).join(':')}`
+}
+
+/**
+ * Збирає абсолютні шляхи до `.yaml`/`.yml` під деревом, де є сегмент `k8s/`.
+ * Каталог `.github/` свідомо пропускається (належить `ga.mdc`).
+ * @param {string} root корінь репозиторію
+ * @param {string[]} [ignorePaths] абсолютні шляхи каталогів-виключень
+ * @returns {Promise<string[]>}
+ */
+export function findK8sYamlFiles(root, ignorePaths = []) {
+  const key = cacheKey(root, ignorePaths)
+  const cached = yamlCache.get(key)
+  if (cached) return cached
+  const promise = (async () => {
+    /** @type {string[]} */
+    const out = []
+    await walkDir(
+      root,
+      p => {
+        const rel = relative(root, p).replaceAll('\\', '/')
+        if (rel.startsWith('.github/')) return
+        if (!pathHasK8sSegment(p, root)) return
+        if (!YAML_EXTENSION_RE.test(p)) return
+        out.push(p)
+      },
+      ignorePaths
+    )
+    return [...out].toSorted((a, b) => a.localeCompare(b))
+  })()
+  yamlCache.set(key, promise)
+  return promise
+}
+
+/**
+ * Каталоги, де є хоча б один `kind: Deployment` у YAML під `k8s/`.
+ * @param {string} root корінь репозиторію
+ * @param {string[]} yamlAbs абсолютні шляхи `.yaml`/`.yml` під `k8s/` (як з `findK8sYamlFiles`)
+ * @param {(msg: string) => void} [fail] репортер помилок парсингу (опц.)
+ * @returns {Promise<Set<string>>} абсолютні шляхи директорій
+ */
+export function collectDeploymentDirs(root, yamlAbs, fail = () => {}) {
+  const key = `${root}|${[...yamlAbs].toSorted((a, b) => a.localeCompare(b)).join(':')}`
+  const cached = deploymentCache.get(key)
+  if (cached) return cached
+  const promise = (async () => {
+    /** @type {Set<string>} */
+    const dirs = new Set()
+    for (const abs of yamlAbs) {
+      const rel = relative(root, abs).replaceAll('\\', '/') || abs
+      const docs = await readAndParseYamlDocs(abs, rel, fail)
+      if (docs) {
+        for (const doc of docs) {
+          if (doc.errors.length === 0 && isDeploymentDoc(doc.toJSON())) {
+            dirs.add(dirname(abs))
+          }
+        }
+      }
+    }
+    return dirs
+  })()
+  deploymentCache.set(key, promise)
+  return promise
+}

package/rules/abie/utils/kustomization-patches.mjs

@@ -0,0 +1,224 @@
+/**
+ * Парсинг inline JSON6902-патчів у abie ua-kustomization:
+ *   - **nodeSelector** patch на `Deployment` (preem: false);
+ *   - **HTTPRoute** patch (hostnames, parentRefs namespace, backendRefs namespace).
+ *
+ * Regex використовуються, бо `patch:` — це YAML-string з вкладеним JSON6902, який ми не парсимо
+ * вдруге; підрядки на кшталт `path: /spec/hostnames` і `value: ua` достатньо інформативні.
+ */
+import { parseAllDocuments } from 'yaml'
+
+import { LINE_SPLIT_RE, MODELINE_RE, stripBom } from './yaml.mjs'
+
+const PATCH_NODE_SELECTOR_PATH_RE = /path:\s*\/spec\/template\/spec\/nodeSelector\b/u
+const PATCH_PREEM_FALSE_RE = /\bpreem:\s*['"]?false['"]?\b/u
+const PATCH_HOSTNAMES_PATH_RE = /path:\s*\/spec\/hostnames\b/mu
+// Overlay namespaces: дозволено `ua` і `ua-*` (наприклад `ua-b2b`).
+const PATCH_PARENT_REF_NS_UA_RE =
+  /path:\s*\/spec\/parentRefs\/0\/namespace\b[\s\S]{0,200}?value:\s*['"]?ua(?:-[a-z0-9][a-z0-9-]*)?['"]?(?:\s|$)/imu
+
+/** Домени `hostnames` для overlay `ua` (підрядки у JSON6902-тексті patch). */
+const ABIE_UA_HTTPROUTE_HOST_MARKERS = ['abie.app', 'vybeerai.com.ua', '*.abie.app', '*.vybeerai.com.ua']
+
+// ── nodeSelector (ua) ─────────────────────────────────────────────────────
+
+/**
+ * Чи patch-рядок містить очікуваний ua nodeSelector (preem: false).
+ * @param {string} patchText
+ * @returns {boolean}
+ */
+function jsonPatchTextHasUaDeploymentNodeSelector(patchText) {
+  if (typeof patchText !== 'string' || patchText.trim() === '') return false
+  if (!PATCH_NODE_SELECTOR_PATH_RE.test(patchText)) return false
+  if (!PATCH_PREEM_FALSE_RE.test(patchText)) return false
+  return true
+}
+
+/**
+ * Чи один елемент `patches` відповідає abie nodeSelector для `mode`.
+ * @param {unknown} p
+ * @param {'ua'} mode
+ * @returns {boolean}
+ */
+function inlineKustomizationPatchMatchesAbieMode(p, mode) {
+  if (p === null || typeof p !== 'object' || Array.isArray(p)) return false
+  const pr = /** @type {Record<string, unknown>} */ (p)
+  const target = pr.target
+  if (target === null || typeof target !== 'object' || Array.isArray(target)) return false
+  const tg = /** @type {Record<string, unknown>} */ (target)
+  if (tg.kind !== 'Deployment') return false
+  const patchStr = pr.patch
+  if (typeof patchStr !== 'string') return false
+  if (mode === 'ua' && jsonPatchTextHasUaDeploymentNodeSelector(patchStr)) return true
+  return false
+}
+
+/**
+ * Чи документ Kustomization містить відповідний inline patch на Deployment.
+ * @param {import('yaml').Document} doc
+ * @param {'ua'} mode
+ * @returns {boolean}
+ */
+function kustomizationDocumentHasAbieDeploymentNodeSelectorPatch(doc, mode) {
+  if (doc.errors.length > 0) return false
+  const root = doc.toJSON()
+  if (root === null || typeof root !== 'object' || Array.isArray(root)) return false
+  const rec = /** @type {Record<string, unknown>} */ (root)
+  if (rec.kind !== 'Kustomization') return false
+  const patches = rec.patches
+  if (!Array.isArray(patches)) return false
+  for (const p of patches) {
+    if (inlineKustomizationPatchMatchesAbieMode(p, mode)) return true
+  }
+  return false
+}
+
+/**
+ * Чи `kustomization.yaml` містить валідні inline patch для Deployment nodeSelector (ua).
+ * @param {string} raw повний текст файла
+ * @param {'ua'} mode
+ * @returns {boolean}
+ */
+export function kustomizationHasAbieDeploymentNodeSelectorPatch(raw, mode) {
+  const body = stripBom(raw)
+  const lines = body.split(LINE_SPLIT_RE)
+  const first = lines[0] ?? ''
+  const rest = MODELINE_RE.test(first.trim()) ? lines.slice(1).join('\n') : body
+  /** @type {import('yaml').Document[]} */
+  let docs
+  try {
+    docs = parseAllDocuments(rest)
+  } catch {
+    return false
+  }
+  for (const doc of docs) {
+    if (kustomizationDocumentHasAbieDeploymentNodeSelectorPatch(doc, mode)) return true
+  }
+  return false
+}
+
+// ── HTTPRoute (ua) ────────────────────────────────────────────────────────
+
+/**
+ * @param {unknown} p
+ * @returns {string | null}
+ */
+function extractHttpRoutePatchString(p) {
+  if (p === null || typeof p !== 'object' || Array.isArray(p)) return null
+  const pr = /** @type {Record<string, unknown>} */ (p)
+  const target = pr.target
+  if (target === null || typeof target !== 'object' || Array.isArray(target)) return null
+  const tg = /** @type {Record<string, unknown>} */ (target)
+  if (tg.kind !== 'HTTPRoute' || typeof tg.name !== 'string' || tg.name.trim() === '') return null
+  const patchStr = pr.patch
+  return typeof patchStr === 'string' && patchStr.trim() !== '' ? patchStr : null
+}
+
+/**
+ * Збирає inline `patch`-рядки для HTTPRoute (непорожній `target.name`) з одного Kustomization-документа.
+ * @param {import('yaml').Document} doc
+ * @returns {string[]}
+ */
+function collectAbieHttpRoutePatchStringsFromKustomizationDoc(doc) {
+  if (doc.errors.length > 0) return []
+  const root = doc.toJSON()
+  if (root === null || typeof root !== 'object' || Array.isArray(root)) return []
+  const rec = /** @type {Record<string, unknown>} */ (root)
+  if (rec.kind !== 'Kustomization' || !Array.isArray(rec.patches)) return []
+  /** @type {string[]} */
+  const out = []
+  for (const p of rec.patches) {
+    const s = extractHttpRoutePatchString(p)
+    if (s !== null) out.push(s)
+  }
+  return out
+}
+
+/**
+ * Збирає всі inline JSON6902-фрагменти HTTPRoute (непорожній `target.name`) у kustomization.yaml.
+ * @param {string} raw повний текст файла
+ * @returns {string}
+ */
+export function getCombinedNginxRunPatchTextFromKustomization(raw) {
+  const body = stripBom(raw)
+  const lines = body.split(LINE_SPLIT_RE)
+  const first = lines[0] ?? ''
+  const rest = MODELINE_RE.test(first.trim()) ? lines.slice(1).join('\n') : body
+  /** @type {import('yaml').Document[]} */
+  let docs
+  try {
+    docs = parseAllDocuments(rest)
+  } catch {
+    return ''
+  }
+  /** @type {string[]} */
+  const chunks = []
+  for (const doc of docs) {
+    chunks.push(...collectAbieHttpRoutePatchStringsFromKustomizationDoc(doc))
+  }
+  return chunks.join('\n')
+}
+
+/**
+ * Рахує операції JSON6902 з `path: /spec/rules/.../backendRefs/.../namespace` і `value: ua[-…]`.
+ * @param {string} combined сукупний текст patch
+ * @param {'ua'} mode
+ * @returns {number}
+ */
+function countAbieHttpRouteBackendRefNamespacePatchesInCombined(combined, mode) {
+  if (mode !== 'ua') return 0
+  const re =
+    /path:\s*\/spec\/rules\/\d+\/backendRefs\/\d+\/namespace\b[\s\S]{0,200}?value:\s*['"]?ua(?:-[a-z0-9][a-z0-9-]*)?['"]?(?:\s|$)/gimu
+  return [...combined.matchAll(re)].length
+}
+
+/**
+ * Перевіряє сукупний текст patch(ів) HTTPRoute на відповідність abie.mdc.
+ * @param {string} combined сукупний текст patch
+ * @param {'ua'} mode
+ * @param {string} [_fullKustomizationRaw] зберігається для API-сумісності, не використовується
+ * @param {number} [sharedCrossNsBackendRefCount] кількість `auth-run-hl`/`file-link-hl` у base HTTPRoute
+ * @returns {string | null} повідомлення про помилку або null
+ */
+export function validateAbieNginxRunHttpRoutePatches(
+  combined,
+  mode,
+  _fullKustomizationRaw,
+  sharedCrossNsBackendRefCount = 0
+) {
+  if (typeof combined !== 'string' || combined.trim() === '') {
+    return `очікується patch target kind HTTPRoute з непорожнім target.name (hostnames, parentRefs namespace ${mode}) — abie.mdc`
+  }
+  if (!PATCH_HOSTNAMES_PATH_RE.test(combined)) {
+    return 'HTTPRoute: потрібен path /spec/hostnames у patch (abie.mdc)'
+  }
+  const markers = ABIE_UA_HTTPROUTE_HOST_MARKERS
+  if (!markers.some(m => combined.includes(m))) {
+    return `HTTPRoute: у value для /spec/hostnames має бути один із доменів abie (${markers.join(', ')}) — abie.mdc`
+  }
+  if (!PATCH_PARENT_REF_NS_UA_RE.test(combined)) {
+    return `HTTPRoute: потрібен path /spec/parentRefs/0/namespace з value ${mode} (abie.mdc)`
+  }
+  const sharedCount =
+    typeof sharedCrossNsBackendRefCount === 'number' && Number.isFinite(sharedCrossNsBackendRefCount)
+      ? Math.max(0, Math.floor(sharedCrossNsBackendRefCount))
+      : 0
+  if (sharedCount > 0) {
+    const patchHits = countAbieHttpRouteBackendRefNamespacePatchesInCombined(combined, mode)
+    if (patchHits < sharedCount) {
+      return `HTTPRoute: для backendRefs до спільних сервісів auth-run-hl, file-link-hl очікується ${sharedCount} JSON6902 patch(ів) з path /spec/rules/…/backendRefs/…/namespace та value ${mode} (зараз ${patchHits}) — abie.mdc`
+    }
+  }
+  return null
+}
+
+/**
+ * Чи kustomization містить валідні patch для HTTPRoute (ua).
+ * @param {string} raw повний текст kustomization.yaml
+ * @param {'ua'} mode
+ * @returns {boolean}
+ */
+export function kustomizationHasAbieNginxRunHttpRoutePatch(raw, mode) {
+  const combined = getCombinedNginxRunPatchTextFromKustomization(raw)
+  return validateAbieNginxRunHttpRoutePatches(combined, mode, raw) === null
+}

package/rules/abie/utils/overlay-paths.mjs

@@ -0,0 +1,97 @@
+/**
+ * Path-хелпери для overlay-перевірок abie:
+ *   - класифікація шляхів (`isUaKustomizationPath`, `isAbieK8sBaseYamlPath`),
+ *   - вилучення каталогу пакета з overlay-шляху (`abiePackageDirFromK8sOverlay`),
+ *   - умовний gate для HTTPRoute через наявність `vite.config.*` (`abieOverlayRequiresHttpRouteByVite`),
+ *   - перевірка наявності `Deployment` у дереві пакета (`abieOverlayK8sTreeHasDeployment`),
+ *   - чи yaml належить base-шару пакета (`isK8sYamlInAbiePackageExcludingUaOverlay`).
+ */
+import { existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
+
+const UA_KUSTOMIZATION_PATH_RE = /(^|\/)ua\/kustomization\.yaml$/u
+const OVERLAY_PACKAGE_DIR_RE = /^(.+)\/k8s\/ua\/kustomization\.yaml$/u
+const BASE_SEGMENT_RE = /(^|\/)base\//u
+const TRAILING_SLASH_RE = /\/$/u
+
+/**
+ * Чи `rel` — це `…/ua/kustomization.yaml` (abie overlay).
+ * @param {string} rel посі від кореня репозиторію
+ * @returns {boolean}
+ */
+export function isUaKustomizationPath(rel) {
+  const norm = rel.replaceAll('\\', '/')
+  return UA_KUSTOMIZATION_PATH_RE.test(norm)
+}
+
+/**
+ * Каталог пакета (батько `k8s/`) для overlay `…/k8s/ua/kustomization.yaml`.
+ * @param {string} root корінь репозиторію
+ * @param {string} kustomizationAbs абсолютний шлях до ua kustomization
+ * @returns {string | null}
+ */
+export function abiePackageDirFromK8sOverlay(root, kustomizationAbs) {
+  const rel = relative(root, kustomizationAbs).replaceAll('\\', '/') || kustomizationAbs
+  const m = rel.match(OVERLAY_PACKAGE_DIR_RE)
+  return m ? join(root, m[1]) : null
+}
+
+/**
+ * Чи у каталозі пакета (батько `k8s/`) є `vite.config.{js,mjs,ts}` — HTTPRoute-вимога abie
+ * застосовується лише до Vite-пакетів.
+ * @param {string} root корінь репозиторію
+ * @param {string} kustomizationAbs абсолютний шлях до ua kustomization
+ * @returns {boolean}
+ */
+export function abieOverlayRequiresHttpRouteByVite(root, kustomizationAbs) {
+  const pkg = abiePackageDirFromK8sOverlay(root, kustomizationAbs)
+  if (!pkg) return false
+  return (
+    existsSync(join(pkg, 'vite.config.js')) ||
+    existsSync(join(pkg, 'vite.config.mjs')) ||
+    existsSync(join(pkg, 'vite.config.ts'))
+  )
+}
+
+/**
+ * Чи у дереві `k8s/` пакета є `Deployment` (за каталогами з `collectDeploymentDirs`).
+ * @param {Set<string>} deploymentDirs абсолютні каталоги з Deployment
+ * @param {string} root корінь репозиторію
+ * @param {string} kustomizationAbs абсолютний шлях до ua kustomization
+ * @returns {boolean}
+ */
+export function abieOverlayK8sTreeHasDeployment(deploymentDirs, root, kustomizationAbs) {
+  const pkg = abiePackageDirFromK8sOverlay(root, kustomizationAbs)
+  if (!pkg) return false
+  const k8sRoot = join(pkg, 'k8s').replaceAll('\\', '/')
+  for (const dir of deploymentDirs) {
+    const norm = dir.replaceAll('\\', '/')
+    if (norm === k8sRoot || norm.startsWith(`${k8sRoot}/`)) return true
+  }
+  return false
+}
+
+/**
+ * Чи rel-шлях `…/k8s/base/…` (base-шар abie, не overlay).
+ * @param {string} rel
+ * @returns {boolean}
+ */
+export function isAbieK8sBaseYamlPath(rel) {
+  const norm = rel.replaceAll('\\', '/')
+  return BASE_SEGMENT_RE.test(norm)
+}
+
+/**
+ * Чи yaml належить до `<pkgRel>/k8s/**` поза `ua/` піддеревом (base-шар abie).
+ * @param {string} relFromRoot шлях від кореня
+ * @param {string} pkgRelFromRoot каталог пакета від кореня
+ * @returns {boolean}
+ */
+export function isK8sYamlInAbiePackageExcludingUaOverlay(relFromRoot, pkgRelFromRoot) {
+  const normRel = relFromRoot.replaceAll('\\', '/')
+  const pkg = pkgRelFromRoot.replaceAll('\\', '/').replace(TRAILING_SLASH_RE, '')
+  const prefix = `${pkg}/k8s/`
+  if (!normRel.startsWith(prefix)) return false
+  const after = normRel.slice(prefix.length)
+  return !after.startsWith('ua/')
+}

package/rules/abie/utils/yaml.mjs

@@ -0,0 +1,72 @@
+/**
+ * Спільні YAML-хелпери для abie-перевірок: парсинг документів з опційним modeline,
+ * BOM-strip, regex для `# yaml-language-server: $schema=` і поділу на рядки.
+ */
+import { readFile } from 'node:fs/promises'
+
+import { parseAllDocuments } from 'yaml'
+
+export const MODELINE_RE = /^#\s*yaml-language-server:\s*\$schema=(\S+)\s*$/
+export const LINE_SPLIT_RE = /\r?\n/u
+
+/**
+ * Прибирає BOM на початку файлу.
+ * @param {string} s вміст
+ * @returns {string}
+ */
+export function stripBom(s) {
+  return s.startsWith('') ? s.slice(1) : s
+}
+
+/**
+ * Чи YAML-документ — це `kind: Deployment`.
+ * @param {unknown} obj корінь YAML-документа
+ * @returns {boolean}
+ */
+export function isDeploymentDoc(obj) {
+  return (
+    obj !== null &&
+    typeof obj === 'object' &&
+    !Array.isArray(obj) &&
+    /** @type {Record<string, unknown>} */ (obj).kind === 'Deployment'
+  )
+}
+
+/**
+ * No-op fail-handler для функцій, що мовчки повертають null/[] при помилці парсингу.
+ * @param {string} _msg ігнорується
+ */
+export const silentFail = _msg => {
+  /* silent — пошкоджені файли ловить check-k8s */
+}
+
+/**
+ * Зчитує і парсить YAML-документи з файлу. BOM і modeline (перший рядок `$schema`)
+ * автоматично прибираються перед `parseAllDocuments`. При помилці читання/парсингу
+ * викликає `failFn` і повертає `null`.
+ * @param {string} abs абсолютний шлях
+ * @param {string} rel відносний (для повідомлень)
+ * @param {(msg: string) => void} failFn
+ * @returns {Promise<import('yaml').Document[] | null>}
+ */
+export async function readAndParseYamlDocs(abs, rel, failFn) {
+  let raw
+  try {
+    raw = await readFile(abs, 'utf8')
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    failFn(`${rel}: не вдалося прочитати (${msg})`)
+    return null
+  }
+  const body = stripBom(raw)
+  const lines = body.split(LINE_SPLIT_RE)
+  const first = lines[0] ?? ''
+  const rest = MODELINE_RE.test(first.trim()) ? lines.slice(1).join('\n') : body
+  try {
+    return parseAllDocuments(rest)
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    failFn(`${rel}: YAML (${msg})`)
+    return null
+  }
+}

package/rules/adr/adr.mdc

@@ -1,7 +1,7 @@
 ---
-description: Автоматичний збір ADR/Runbook/Knowledge-чернеток із Stop-хука Claude Code (capture-decisions)
+description: Автоматичний збір ADR/Runbook/Knowledge-чернеток і батч-нормалізація у `docs/adr/` через Stop-хук Claude Code
 alwaysApply: true
-version: '1.0'
+version: '2.0'
 ---
 
 Правило вмикається **вручну** — додай `"adr"` у масив `rules` файлу `.n-cursor.json`. У `auto-rules.md` його немає, бо корисність залежить від робочого процесу команди (не кожен проєкт хоче літати ADR-чернеткам у `docs/`).
@@ -9,37 +9,90 @@ version: '1.0'
 Коли правило увімкнене, **`npx @nitra/cursor`** автоматично:
 
 - копіює канонічний bash-скрипт у **`.claude/hooks/capture-decisions.sh`** (executable, повністю керується пакетом — на кожен sync перезаписується);
-- додає managed-групу у **`hooks.Stop`** в **`.claude/settings.json`**, яка викликає цей скрипт асинхронно (`async: true`, `timeout: 180`);
-- ці зміни — додаткові до lint Stop-hook (`@nitra/cursor stop-hook`); обидві групи живуть поряд у `Stop`.
+- копіює канонічний bash-скрипт у **`.claude/hooks/normalize-decisions.sh`** (батч-нормалізація чернеток через LLM);
+- додає у **`hooks.Stop`** в **`.claude/settings.json`** дві managed-групи: capture (`async: true`, `timeout: 180`) і normalize (`async: true`, `timeout: 600`);
+- ці зміни — додаткові до lint Stop-hook (`@nitra/cursor stop-hook`); усі три групи живуть поряд у `Stop`.
 
-## Що робить механізм
+## Дві фази, один каталог
 
-Stop-hook Claude Code зчитує JSONL-транскрипт сесії (через `jq`), витягає текст, `thinking`-блоки та назви `tool_use`-викликів, передає компактний дайджест у LLM CLI з промптом українською і записує результат у **`docs/adr/_inbox/<timestamp>-<session>.md`**, якщо модель повернула блок з шапкою `## ADR|Runbook|Knowledge …`. Якщо модель повернула `NONE` (тривіальна сесія) — нічого не пишеться. Рекурсію з внутрішнього виклику моделі блокує env-var `CAPTURE_DECISIONS_RUNNING=1`.
+ADR живуть у єдиному каталозі **`docs/adr/`**. Є два стани файлу, які відрізняються YAML frontmatter:
+
+- **Draft** — файл з frontmatter `session: …`, `captured: …`, `transcript: …` та timestamp-іменем `YYYYMMDD-HHMMSS-<sid>.md`. Пише `capture-decisions.sh` після кожної сесії.
+- **Clean** — файл без frontmatter, з kebab-case-іменем `<slug>.md` (наприклад `ланцюжок-запуску-abie.md`). Створює `normalize-decisions.sh` або людина руками.
+
+`normalize-decisions.sh` ніколи не чіпає clean-файли — крім випадку `merge-into`, коли дописує `## Update YYYY-MM-DD` в кінець наявного clean-файлу.
+
+### Фаза 1 — Capture
+
+Stop-hook `capture-decisions.sh` зчитує JSONL-транскрипт сесії (через `jq`), витягає текст, `thinking`-блоки та назви `tool_use`-викликів, передає компактний дайджест у LLM CLI з промптом українською і записує результат у **`docs/adr/<timestamp>-<session>.md`**, якщо модель повернула блок з шапкою `## ADR|Runbook|Knowledge …`. Якщо модель повернула `NONE` (тривіальна сесія) — нічого не пишеться. Рекурсію з внутрішнього виклику моделі блокує env-var `CAPTURE_DECISIONS_RUNNING=1`.
+
+### Фаза 2 — Normalize
+
+Stop-hook `normalize-decisions.sh` спрацьовує на тому самому `Stop`-евенті, але:
+
+- Виходить миттєво, якщо чернеток (`session:` у frontmatter) менше ніж **`ADR_NORMALIZE_THRESHOLD`** (default 30).
+- Виходить миттєво, якщо від попередньої спроби пройшло менше **`ADR_NORMALIZE_MIN_INTERVAL_HOURS`** годин (default 6) — щоб не крутитися щоразу, коли поріг постійний.
+- Бере не більше **`ADR_NORMALIZE_BATCH`** чернеток (default 30, найстарші за іменем-timestamp), формує один промпт LLM і чекає JSON-відповідь зі списком операцій.
+- Виходить миттєво, якщо репозиторій у стані `MERGE_HEAD` / `rebase-*` — небезпечно правити файли посеред конфлікту.
+- Виходить миттєво, якщо інший normalize-запуск тримає `flock` на `.claude/hooks/.normalize.lock` (тільки де `flock` доступний).
+
+LLM повертає масив операцій:
+
+| `op` | Семантика | Поля |
+|---|---|---|
+| `delete` | Чернетка тривіальна / повністю покрита іншим clean-ADR-ом. | `file`, `reason` |
+| `rewrite` | Чернетка стає окремим clean-файлом: frontmatter знімається, ім'я → `<slug>.md`, додаються `**Status: Accepted**` і `**Date:**` з `captured`. | `file`, `slug`, `content` |
+| `merge-into` | Чернетка повторює тему вже існуючого clean-файлу; дописуємо `## Update YYYY-MM-DD` у кінець `target`. | `file`, `target`, `additions` |
+
+`slug` — kebab-case українською (`ланцюжок-запуску-abie`, `npm-publish-flow`); англійські технічні терміни лишаються англійською без транслітерації. Колізія slug-ів обробляється детермінованим суфіксом `-2`, `-3`.
+
+### Жодних git-операцій
+
+`normalize-decisions.sh` **не комітить, не `git add`, нічого з git**. Усі зміни — у робочому дереві. Розробник у зручний момент дивиться `git status` / `git diff` і вирішує: `git add` + commit, `git checkout -- <file>` для відкату, або правки руками. Це і є review-вікно.
+
+### Recursion guard і ENV-керування
+
+Інший LLM CLI, який запустить normalize, успадковує `ADR_NORMALIZE_RUNNING=1` — внутрішній Stop-hook вийде відразу. Доступні ENV:
+
+| Змінна | Default | Призначення |
+|---|---|---|
+| `ADR_NORMALIZE_THRESHOLD` | `30` | Поріг чернеток для запуску фази. |
+| `ADR_NORMALIZE_BATCH` | `30` | Максимум чернеток у одному виклику LLM. |
+| `ADR_NORMALIZE_MIN_INTERVAL_HOURS` | `6` | Мінімум між спробами (навіть якщо поріг). |
+| `ADR_NORMALIZE_DRY` | `0` | `1` — лише лог запланованих операцій, без змін на диску. |
+| `ADR_NORMALIZE_MODEL` | `sonnet` | Модель для `claude -p`. |
+| `ADR_NORMALIZE_CURSOR_MODEL` | `claude-4.6-sonnet-medium` | Модель для `cursor-agent -p`. |
+
+Для ручного запуску (поза порогом і поза Stop-хуком) є **`/n-adr-normalize`** — slash-команда тимчасово виставляє `ADR_NORMALIZE_THRESHOLD=0` і `ADR_NORMALIZE_MIN_INTERVAL_HOURS=0` та викликає скрипт напряму.
 
 ## LLM CLI: claude → cursor-agent fallback
 
-Скрипт сам обирає доступний CLI (порядок фіксований):
+Обидва скрипти обирають доступний CLI (порядок фіксований):
 
-1. **`claude`** (Anthropic Claude Code CLI) — `claude -p --model "$CAPTURE_DECISIONS_CLAUDE_MODEL"` (default `sonnet`).
-2. **`cursor-agent`** (Cursor IDE CLI) — `cursor-agent -p --mode ask --output-format text --model "$CAPTURE_DECISIONS_CURSOR_MODEL"` (default `claude-4.6-sonnet-medium`).
+1. **`claude`** (Anthropic Claude Code CLI) — `claude -p --model "<model>"`.
+2. **`cursor-agent`** (Cursor IDE CLI) — `cursor-agent -p --mode ask --output-format text --model "<model>"`.
 3. Жодного CLI у `PATH` — скрипт виходить з кодом `0` і нічого не пише.
 
-`--mode ask` для cursor-agent навмисно: режим Q&A read-only, без shell/edit-інструментів — для класифікації сесії інструменти не потрібні. Моделі можна перевизначити через ENV: `CAPTURE_DECISIONS_CLAUDE_MODEL`, `CAPTURE_DECISIONS_CURSOR_MODEL`.
+`--mode ask` для cursor-agent навмисно: режим Q&A read-only, без shell/edit-інструментів — для класифікації / нормалізації інструменти не потрібні.
 
 ## Структура каталогу
 
 ```text
 docs/adr/
-└── _inbox/                         # чернетки, що пишуться Stop-хуком
-    └── YYYYMMDD-HHMMSS-<sid>.md    # session_id (перші 8 символів)
+├── YYYYMMDD-HHMMSS-<sid>.md   # drafts (frontmatter session:/captured:/transcript:)
+└── <slug>.md                  # clean ADR-и (без frontmatter)
 .claude/hooks/
-├── capture-decisions.sh            # auto-synced з пакета
-└── capture-decisions.log           # лог запусків (НЕ коміти)
+├── capture-decisions.sh       # auto-synced з пакета
+├── normalize-decisions.sh     # auto-synced з пакета
+├── capture-decisions.log      # лог запусків capture (НЕ коміти)
+├── normalize-decisions.log    # лог запусків normalize (НЕ коміти)
+├── .normalize-state           # timestamp останнього normalize-запуску (НЕ коміти)
+└── .normalize.lock            # lock-файл (НЕ коміти)
 ```
 
-`.gitignore` повинен містити рядок **`.claude/hooks/capture-decisions.log`**, щоб лог не потрапляв у git.
+`.gitignore` повинен містити рядки, що покривають **`.claude/hooks/*.log`** і службові файли normalize (`.claude/hooks/.normalize-*`).
 
-`docs/adr/_inbox/` — це робоча скринька; чернетки звідти переносяться у структуровані ADR-файли вручну (під час оглядів) або тримаються як архів сесій. Каталог сам створюється скриптом, тому пустим у git тримати не потрібно.
+> Якщо в репозиторії лишився старий каталог **`docs/adr/_inbox/`** з попередньої версії правила — `normalize-decisions.sh` бачить його рекурсивно й поступово розчистить. Можна також одразу `git mv docs/adr/_inbox/*.md docs/adr/` і прибрати порожній каталог.
 
 ## Stop-hook у `.claude/settings.json`
 
@@ -69,17 +122,28 @@ docs/adr/
             "timeout": 180
           }
         ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/normalize-decisions.sh\"",
+            "async": true,
+            "timeout": 600
+          }
+        ]
       }
     ]
   }
 }
 ```
 
-Обидві групи ідентифікуються пакетом за маркером у `command` (`@nitra/cursor stop-hook` і `.claude/hooks/capture-decisions.sh`) — користувацькі hook-групи поряд не чіпаються. Якщо `adr` прибрати з `rules`, ADR-група автоматично видаляється на наступному `npx @nitra/cursor`.
+Усі три групи ідентифікуються пакетом за маркером у `command` (`@nitra/cursor stop-hook`, `.claude/hooks/capture-decisions.sh`, `.claude/hooks/normalize-decisions.sh`) — користувацькі hook-групи поряд не чіпаються. Якщо `adr` прибрати з `rules`, обидві ADR-групи автоматично видаляються на наступному `npx @nitra/cursor`.
 
 ## Локальні vs project-shared налаштування
 
-Stop-hook ADR живе у **project-shared** `.claude/settings.json` (закомічений), щоб механізм працював у всіх членів команди. Якщо хук колись був у `.claude/settings.local.json` — прибери дубль вручну: project-shared і local-копія створили б два запуски на одну подію.
+Обидва Stop-hook'и ADR живуть у **project-shared** `.claude/settings.json` (закомічений), щоб механізм працював у всіх членів команди. Якщо хук колись був у `.claude/settings.local.json` — прибери дубль вручну: project-shared і local-копія створили б два запуски на одну подію.
 
 ## Перевірка