@nitra/cursor 1.9.23 → 1.11.0

package/scripts/sync-claude-config.mjs

@@ -10,10 +10,12 @@
  * - `npm/CLAUDE.md` — **fully owned**: завжди перезаписується; пропускається,
  *   якщо в проєкті немає каталогу `npm/`.
  * - `.claude/commands/n-check.md` — fully owned slash-команда.
- * - `.claude/hooks/capture-decisions.sh` — fully owned bash-скрипт ADR Stop-hook;
+ * - `.claude/hooks/capture-decisions.sh` — fully owned bash-скрипт ADR capture Stop-hook;
  *   копіюється з `.claude-template/hooks/`, лише коли в `.n-cursor.json` `rules`
  *   присутнє `adr` (правило вмикається вручну). Якщо правила немає, керована
  *   ADR-група в hooks так само автоматично прибирається з settings.json.
+ * - `.claude/hooks/normalize-decisions.sh` — fully owned bash-скрипт ADR normalize
+ *   Stop-hook (батч-нормалізація чернеток); умови — ті самі, що для `capture`.
  *
  * Опт-аут — `claude-config: false` у `.n-cursor.json`.
  */
@@ -23,20 +25,27 @@ import { join } from 'node:path'
 
 /** Маркер lint Stop-hook'а (`npx --no \@nitra/cursor stop-hook`). */
 export const MANAGED_HOOK_COMMAND_MARKER = '@nitra/cursor stop-hook'
-/** Маркер ADR Stop-hook'а — підрядок шляху до bash-скрипта. */
+/** Маркер ADR Stop-hook'а — підрядок шляху до bash-скрипта capture-decisions. */
 export const ADR_HOOK_COMMAND_MARKER = '.claude/hooks/capture-decisions.sh'
+/** Маркер ADR Stop-hook'а — підрядок шляху до bash-скрипта normalize-decisions. */
+export const ADR_NORMALIZE_HOOK_COMMAND_MARKER = '.claude/hooks/normalize-decisions.sh'
 /** Усі маркери managed-hook'ів пакета — за ними відрізняємо свої записи від користувацьких. */
-export const MANAGED_HOOK_COMMAND_MARKERS = Object.freeze([MANAGED_HOOK_COMMAND_MARKER, ADR_HOOK_COMMAND_MARKER])
+export const MANAGED_HOOK_COMMAND_MARKERS = Object.freeze([
+  MANAGED_HOOK_COMMAND_MARKER,
+  ADR_HOOK_COMMAND_MARKER,
+  ADR_NORMALIZE_HOOK_COMMAND_MARKER
+])
 
 const CLAUDE_DIR = '.claude'
 const CLAUDE_SETTINGS_FILE = `${CLAUDE_DIR}/settings.json`
 const CLAUDE_COMMANDS_DIR = `${CLAUDE_DIR}/commands`
 const CLAUDE_HOOKS_DIR = `${CLAUDE_DIR}/hooks`
 const ADR_HOOK_SCRIPT_NAME = 'capture-decisions.sh'
+const ADR_NORMALIZE_HOOK_SCRIPT_NAME = 'normalize-decisions.sh'
 const NPM_CLAUDE_MD_FILE = 'npm/CLAUDE.md'
 const TEMPLATE_DIR_NAME = '.claude-template'
 
-/** Канонічна група hooks для ADR Stop-hook'а — додається в settings, коли `adr` у `rules`. */
+/** Канонічна група hooks для ADR capture Stop-hook'а — додається в settings, коли `adr` у `rules`. */
 const ADR_STOP_HOOK_GROUP = Object.freeze({
   matcher: '',
   hooks: Object.freeze([
@@ -49,6 +58,19 @@ const ADR_STOP_HOOK_GROUP = Object.freeze({
   ])
 })
 
+/** Канонічна група hooks для ADR normalize Stop-hook'а — батч-нормалізація чернеток у `docs/adr/`. */
+const ADR_NORMALIZE_STOP_HOOK_GROUP = Object.freeze({
+  matcher: '',
+  hooks: Object.freeze([
+    Object.freeze({
+      type: 'command',
+      command: `bash "$CLAUDE_PROJECT_DIR/${ADR_NORMALIZE_HOOK_COMMAND_MARKER}"`,
+      async: true,
+      timeout: 600
+    })
+  ])
+})
+
 /**
  * @typedef {object} HookEntry
  * @property {string} type тип hook'а у форматі Claude Code (зазвичай `'command'`)
@@ -140,7 +162,11 @@ function templateWithAdrHook(template) {
   for (const [event, groups] of Object.entries(template.hooks ?? {})) {
     hooks[event] = Array.isArray(groups) ? [...groups] : []
   }
-  hooks.Stop = [...(hooks.Stop ?? []), /** @type {HookGroup} */ (ADR_STOP_HOOK_GROUP)]
+  hooks.Stop = [
+    ...(hooks.Stop ?? []),
+    /** @type {HookGroup} */ (ADR_STOP_HOOK_GROUP),
+    /** @type {HookGroup} */ (ADR_NORMALIZE_STOP_HOOK_GROUP)
+  ]
   return { ...template, hooks }
 }
 
@@ -209,24 +235,45 @@ export async function syncClaudeSettings(projectRoot, templateDir, options = {})
 }
 
 /**
- * Копіює канонічний `.claude/hooks/capture-decisions.sh` з темплейту пакета.
+ * Копіює один канонічний bash-скрипт hook'а з темплейту пакета у `.claude/hooks/`.
  * Файл повністю керується пакетом — на кожен sync перезаписується (як setup-bun-deps).
  * @param {string} projectRoot корінь проєкту, куди писати
  * @param {string} templateDir каталог `.claude-template/` усередині пакету
+ * @param {string} scriptName базове ім'я скрипта (наприклад `capture-decisions.sh`)
  * @returns {Promise<{ written: boolean, path: string }>} результат: чи писали файл, та його відносний шлях
  */
-export async function syncAdrHookScript(projectRoot, templateDir) {
-  const templatePath = join(templateDir, 'hooks', ADR_HOOK_SCRIPT_NAME)
+async function syncHookScript(projectRoot, templateDir, scriptName) {
+  const templatePath = join(templateDir, 'hooks', scriptName)
   if (!existsSync(templatePath)) {
     return { written: false, path: '' }
   }
   const content = await readFile(templatePath, 'utf8')
   const hooksDir = join(projectRoot, CLAUDE_HOOKS_DIR)
   await mkdir(hooksDir, { recursive: true })
-  const destPath = join(hooksDir, ADR_HOOK_SCRIPT_NAME)
+  const destPath = join(hooksDir, scriptName)
   await writeFile(destPath, content, 'utf8')
   await chmod(destPath, 0o755)
-  return { written: true, path: `${CLAUDE_HOOKS_DIR}/${ADR_HOOK_SCRIPT_NAME}` }
+  return { written: true, path: `${CLAUDE_HOOKS_DIR}/${scriptName}` }
+}
+
+/**
+ * Копіює канонічний `.claude/hooks/capture-decisions.sh` з темплейту пакета.
+ * @param {string} projectRoot корінь проєкту, куди писати
+ * @param {string} templateDir каталог `.claude-template/` усередині пакету
+ * @returns {Promise<{ written: boolean, path: string }>} результат: чи писали файл, та його відносний шлях
+ */
+export function syncAdrHookScript(projectRoot, templateDir) {
+  return syncHookScript(projectRoot, templateDir, ADR_HOOK_SCRIPT_NAME)
+}
+
+/**
+ * Копіює канонічний `.claude/hooks/normalize-decisions.sh` з темплейту пакета.
+ * @param {string} projectRoot корінь проєкту, куди писати
+ * @param {string} templateDir каталог `.claude-template/` усередині пакету
+ * @returns {Promise<{ written: boolean, path: string }>} результат: чи писали файл, та його відносний шлях
+ */
+export function syncAdrNormalizeHookScript(projectRoot, templateDir) {
+  return syncHookScript(projectRoot, templateDir, ADR_NORMALIZE_HOOK_SCRIPT_NAME)
 }
 
 /**
@@ -283,20 +330,29 @@ export async function syncClaudeCommands(projectRoot, templateDir) {
  * @param {string} options.bundledPackageRoot корінь установленого `@nitra/cursor`
  * @param {boolean} options.enabled чи увімкнено sync (з `.n-cursor.json` `claude-config`)
  * @param {string[]} [options.rules] список увімкнених правил із `.n-cursor.json` — впливає на ADR Stop-hook (`adr`)
- * @returns {Promise<{ settings: boolean, npmClaudeMd: boolean, commands: string[], adrHook: boolean }>} прапорці записів settings/CLAUDE.md/ADR-hook та список записаних slash-команд
+ * @returns {Promise<{ settings: boolean, npmClaudeMd: boolean, commands: string[], adrHook: boolean, adrNormalizeHook: boolean }>} прапорці записів settings/CLAUDE.md/ADR-hook(s) та список записаних slash-команд
  */
 export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enabled, rules = [] }) {
   if (!enabled) {
-    return { settings: false, npmClaudeMd: false, commands: [], adrHook: false }
+    return { settings: false, npmClaudeMd: false, commands: [], adrHook: false, adrNormalizeHook: false }
   }
   const templateDir = join(bundledPackageRoot, TEMPLATE_DIR_NAME)
   if (!existsSync(templateDir)) {
-    return { settings: false, npmClaudeMd: false, commands: [], adrHook: false }
+    return { settings: false, npmClaudeMd: false, commands: [], adrHook: false, adrNormalizeHook: false }
   }
   const includeAdrHook = Array.isArray(rules) && rules.includes('adr')
   const adrHook = includeAdrHook ? await syncAdrHookScript(projectRoot, templateDir) : { written: false, path: '' }
+  const adrNormalizeHook = includeAdrHook
+    ? await syncAdrNormalizeHookScript(projectRoot, templateDir)
+    : { written: false, path: '' }
   const settings = await syncClaudeSettings(projectRoot, templateDir, { includeAdrHook })
   const npmClaudeMd = await syncNpmClaudeMd(projectRoot, templateDir)
   const commands = await syncClaudeCommands(projectRoot, templateDir)
-  return { settings: settings.written, npmClaudeMd: npmClaudeMd.written, commands, adrHook: adrHook.written }
+  return {
+    settings: settings.written,
+    npmClaudeMd: npmClaudeMd.written,
+    commands,
+    adrHook: adrHook.written,
+    adrNormalizeHook: adrNormalizeHook.written
+  }
 }

package/scripts/utils/discover-checkable-rules.mjs

@@ -0,0 +1,123 @@
+/**
+ * Discovery rules для CLI `check`. Шукає правила, для яких є щось «прогонне»:
+ *   - JS concerns:   `rules/<id>/js/<concern>/<check.mjs | check-*.mjs>` — кожен concern окремий вузол.
+ *   - Policy concerns: `rules/<id>/policy/<concern>/target.json` — пара з `<concern>.rego`.
+ *   - Legacy JS (на час міграції): `rules/<id>/js/check.mjs` (плаский) — мапиться у concern `legacy`,
+ *     щоб не ламати ще не мігровані правила.
+ *
+ * Каталог `utils/` всередині `js/` свідомо пропускається — це хелпери, не концерни.
+ * Файли `*.test.mjs` фільтруються regex (`^check(?:-.+)?\.mjs$`).
+ *
+ * Намеренно НЕ парсимо `target.json` тут (це робить runner). Discovery — швидкий скан структури:
+ * шляхи + назви, без I/O вмісту.
+ */
+import { existsSync } from 'node:fs'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+const CHECK_FILENAME_RE = /^check(?:-.+)?\.mjs$/u
+const TEST_SUFFIX = '.test.mjs'
+
+/**
+ * @typedef {object} JsConcern
+ * @property {string} name імʼя концерну (`<name>` у `js/<name>/`); для legacy — `'legacy'`
+ * @property {string[]} files імена `check*.mjs` у концерні (відсортовані алфавітно)
+ * @property {boolean} legacy чи це fallback на плаский `js/check.mjs`
+ */
+
+/**
+ * @typedef {object} PolicyConcern
+ * @property {string} name імʼя концерну (`<name>` у `policy/<name>/`)
+ */
+
+/**
+ * @typedef {object} CheckableRule
+ * @property {string} id ідентифікатор правила (імʼя каталогу `rules/<id>/`)
+ * @property {JsConcern[]} jsConcerns
+ * @property {PolicyConcern[]} policyConcerns
+ */
+
+/**
+ * Перелічує JS-концерни одного правила: підкаталоги `js/<name>/` з принаймні одним `check*.mjs`,
+ * плюс legacy-fallback на плаский `js/check.mjs` (без підкаталогу).
+ *
+ * `js/utils/` свідомо пропускається — це хелпери, а не концерни.
+ * @param {string} jsDir абсолютний шлях `rules/<id>/js/`
+ * @returns {Promise<JsConcern[]>} концерни в алфавітному порядку
+ */
+async function listJsConcerns(jsDir) {
+  if (!existsSync(jsDir)) return []
+  const topLevel = await readdir(jsDir, { withFileTypes: true })
+
+  // Перевага — нова concern-структура (`js/<concern>/check*.mjs`).
+  /** @type {JsConcern[]} */
+  const concerns = []
+  for (const entry of topLevel) {
+    if (!entry.isDirectory() || entry.name === 'utils' || entry.name.startsWith('.')) continue
+    const concernDir = join(jsDir, entry.name)
+    const files = (await readdir(concernDir))
+      .filter(n => CHECK_FILENAME_RE.test(n) && !n.endsWith(TEST_SUFFIX))
+      .toSorted((a, b) => a.localeCompare(b))
+    if (files.length > 0) {
+      concerns.push({ name: entry.name, files, legacy: false })
+    }
+  }
+
+  // Legacy fallback — лише якщо subdir-концернів немає взагалі. Гібридні правила
+  // (одночасно legacy check.mjs + нові концерни) трактуються як уже мігровані:
+  // CLI запускає тільки субдиректорні концерни, flat-файл лишається для backward-compat
+  // тестів, які імпортують `check` напряму.
+  if (concerns.length === 0) {
+    const flatChecks = topLevel
+      .filter(e => e.isFile() && CHECK_FILENAME_RE.test(e.name) && !e.name.endsWith(TEST_SUFFIX))
+      .map(e => e.name)
+      .toSorted((a, b) => a.localeCompare(b))
+    if (flatChecks.length > 0) {
+      concerns.push({ name: 'legacy', files: flatChecks, legacy: true })
+    }
+  }
+
+  return concerns.toSorted((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * Перелічує policy-концерни: підкаталоги `policy/<name>/` з наявним `target.json`.
+ * @param {string} policyDir абсолютний шлях `rules/<id>/policy/`
+ * @returns {Promise<PolicyConcern[]>} концерни в алфавітному порядку
+ */
+async function listPolicyConcerns(policyDir) {
+  if (!existsSync(policyDir)) return []
+  const entries = await readdir(policyDir, { withFileTypes: true })
+  /** @type {PolicyConcern[]} */
+  const out = []
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    if (existsSync(join(policyDir, entry.name, 'target.json'))) {
+      out.push({ name: entry.name })
+    }
+  }
+  return out.toSorted((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * Сканує `rules/` і повертає правила, для яких є JS-концерни або policy-концерни.
+ * Правила без жодної прогонної частини (тільки `.mdc` + `auto.md`) фільтруються.
+ * @param {string} bundledRulesDir абсолютний шлях до `npm/rules/`
+ * @returns {Promise<CheckableRule[]>} відсортовані за id
+ */
+export async function discoverCheckableRules(bundledRulesDir) {
+  if (!existsSync(bundledRulesDir)) return []
+  const entries = await readdir(bundledRulesDir, { withFileTypes: true })
+  /** @type {CheckableRule[]} */
+  const out = []
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    const ruleDir = join(bundledRulesDir, entry.name)
+    const jsConcerns = await listJsConcerns(join(ruleDir, 'js'))
+    const policyConcerns = await listPolicyConcerns(join(ruleDir, 'policy'))
+    if (jsConcerns.length > 0 || policyConcerns.length > 0) {
+      out.push({ id: entry.name, jsConcerns, policyConcerns })
+    }
+  }
+  return out.toSorted((a, b) => a.id.localeCompare(b.id))
+}

package/scripts/utils/resolve-target-files.mjs

@@ -0,0 +1,109 @@
+/**
+ * Резолвер списку файлів для одного `policy/<name>/target.json` у новій структурі правил.
+ *
+ * Дві форми у `target.json:files`:
+ *   - `{ "single": "<rel>" }` — конкретний відносний шлях. Якщо `existsSync(root/single)` → `[single]`;
+ *     інакше `[]` (caller сам вирішує fail vs silent skip за `required`).
+ *   - `{ "walkGlob": <glob | glob[]> }` — picomatch проти posix-відносних шляхів, отриманих обходом
+ *     `walkDir` від `root` із загальними skip-ами та `.n-cursor.json:ignore`. Обхід кешований у
+ *     `walkCache` (Map ключ — підпис ignorePaths) — повторні таргети з тим самим набором ignore
+ *     перевикористовують список без нового readdir.
+ *
+ * Path-traversal у `single` — кидаємо помилку при resolve. Реалізує інваріант контракту: полісі
+ * читають лише файли в репо.
+ */
+import { existsSync } from 'node:fs'
+import { isAbsolute, join, normalize, relative, sep } from 'node:path'
+
+import picomatch from 'picomatch'
+
+import { loadCursorIgnorePaths } from './load-cursor-config.mjs'
+import { walkDir } from './walkDir.mjs'
+
+/** Узгоджений regex для path-traversal: `..` як сегмент або абсолютний шлях. */
+const PARENT_SEGMENT_RE = /(^|[\\/])\.\.([\\/]|$)/u
+
+/**
+ * Перевіряє, що `single`-шлях у `target.json:files` лежить у межах репозиторію.
+ * Кидає помилку, якщо шлях абсолютний або містить сегмент `..`.
+ * @param {string} singlePath значення `files.single`
+ * @returns {void}
+ */
+function assertSafeSinglePath(singlePath) {
+  if (isAbsolute(singlePath)) {
+    throw new Error(`target.json: files.single має бути відносним шляхом (отримано: ${singlePath})`)
+  }
+  if (PARENT_SEGMENT_RE.test(singlePath)) {
+    throw new Error(`target.json: files.single не може містити '..' (отримано: ${singlePath})`)
+  }
+}
+
+/**
+ * Збирає всі файли (posix-відносні шляхи від `root`) одним обходом дерева.
+ * Скіпи: загальні з `walkDir` + `.n-cursor.json:ignore`.
+ * @param {string} root абсолютний корінь репозиторію
+ * @param {string[]} ignorePaths абсолютні posix-шляхи виключених каталогів
+ * @returns {Promise<string[]>} відсортовані posix-відносні шляхи
+ */
+async function walkAllRelative(root, ignorePaths) {
+  /** @type {string[]} */
+  const out = []
+  await walkDir(
+    root,
+    abs => {
+      const rel = relative(root, abs).split(sep).join('/')
+      if (rel.length > 0) out.push(rel)
+    },
+    ignorePaths
+  )
+  return out.toSorted((a, b) => a.localeCompare(b))
+}
+
+/**
+ * Витягує (або обчислює і кешує) список усіх файлів у дереві для заданого набору ignore-шляхів.
+ * Кеш — мapа `signature → Promise<string[]>`, тож паралельні виклики одного й того ж набору
+ * чекають один обхід.
+ * @param {string} root абсолютний корінь репозиторію
+ * @param {string[]} ignorePaths абсолютні posix-шляхи виключених каталогів
+ * @param {Map<string, Promise<string[]>>} walkCache мутабельний кеш від caller-а
+ * @returns {Promise<string[]>} відсортовані posix-відносні шляхи
+ */
+function getAllFilesCached(root, ignorePaths, walkCache) {
+  const signature = `${root}|${ignorePaths.join('|')}`
+  let p = walkCache.get(signature)
+  if (!p) {
+    p = walkAllRelative(root, ignorePaths)
+    walkCache.set(signature, p)
+  }
+  return p
+}
+
+/**
+ * Резолвить список файлів для одного `target.json:files`.
+ * @param {object} filesSpec поле `files` з `target.json` (вже після schema-валідації)
+ * @param {string} root абсолютний корінь репозиторію
+ * @param {Map<string, Promise<string[]>>} walkCache кеш обходів дерева (cross-target у межах одного check-прогону)
+ * @returns {Promise<string[]>} абсолютні шляхи знайдених файлів (порожній — нічого не знайдено)
+ */
+export async function resolveTargetFiles(filesSpec, root, walkCache) {
+  if (typeof filesSpec?.single === 'string') {
+    assertSafeSinglePath(filesSpec.single)
+    const normalized = normalize(filesSpec.single).split(sep).join('/')
+    const abs = join(root, normalized)
+    return existsSync(abs) ? [abs] : []
+  }
+  if (filesSpec?.walkGlob !== undefined) {
+    const ignorePaths = await loadCursorIgnorePaths(root)
+    const all = await getAllFilesCached(root, ignorePaths, walkCache)
+    const globs = Array.isArray(filesSpec.walkGlob) ? filesSpec.walkGlob : [filesSpec.walkGlob]
+    // picomatch у масиві трактує `!neg` як ОКРЕМИЙ позитивний матчер «не-neg» (some-OR логіка),
+    // тож наївне `picomatch(['pos','!neg'])` повертає true майже на всьому. Розділяємо вручну:
+    // позитиви join-имо через picomatch(...), негативні фільтруємо окремим isExcluded.
+    const positives = globs.filter(g => !g.startsWith('!'))
+    const negatives = globs.filter(g => g.startsWith('!')).map(g => g.slice(1))
+    const isMatch = positives.length > 0 ? picomatch(positives, { dot: false }) : () => false
+    const isExcluded = negatives.length > 0 ? picomatch(negatives, { dot: false }) : () => false
+    return all.filter(rel => isMatch(rel) && !isExcluded(rel)).map(rel => join(root, rel))
+  }
+  throw new Error(`target.json: files має містити single або walkGlob (отримано: ${JSON.stringify(filesSpec)})`)
+}

package/scripts/utils/run-rule.mjs

@@ -0,0 +1,131 @@
+/**
+ * Оркестратор одного правила під CLI `check`.
+ *
+ * Послідовність (concerns у межах правила — алфавітно):
+ *   1. **applies-гейт** з `js/applies/check.mjs`. Якщо модуль експортує `applies()` і вона повертає
+ *      false — друкуємо `✅ правило не застосовне` і завершуємо без подальших викликів.
+ *   2. **JS-концерни** — кожен `check*.mjs` у `js/<concern>/`. Concern `applies` теж може мати
+ *      `check()` для друку контексту (його `applies()` уже відпрацював на кроці 1, він не повторюється).
+ *      Legacy-fallback: плаский `js/check.mjs` лежить як concern `legacy` — імпортується з кореня `js/`,
+ *      а не з підкаталога.
+ *   3. **Policy-концерни** — кожен `policy/<concern>/target.json` через `runConftestBatch`.
+ *      Реcолвер `resolveTargetFiles` ділить cache (`walkCache`) між концернами.
+ *
+ * Кожен concern має власний `createCheckReporter` — їхні exit-коди OR-яться в один на рівні правила.
+ * Це дає той самий 0/1 контракт, що й попередня модель «один check.mjs на правило».
+ */
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import { createCheckReporter } from './check-reporter.mjs'
+import { resolveTargetFiles } from './resolve-target-files.mjs'
+import { runConftestBatch } from './run-conftest-batch.mjs'
+
+const APPLIES_CONCERN_NAME = 'applies'
+
+/**
+ * Обчислює абсолютний шлях до файла-check у JS-концерні.
+ * @param {string} bundledRulesDir абсолютний `rules/`
+ * @param {string} ruleId id правила
+ * @param {import('./discover-checkable-rules.mjs').JsConcern} concern опис концерну
+ * @param {string} fileName імʼя файла з `concern.files`
+ * @returns {string} абсолютний шлях
+ */
+function resolveJsCheckPath(bundledRulesDir, ruleId, concern, fileName) {
+  return concern.legacy
+    ? join(bundledRulesDir, ruleId, 'js', fileName)
+    : join(bundledRulesDir, ruleId, 'js', concern.name, fileName)
+}
+
+/**
+ * Спробувати викликати applies() гейт з `js/applies/check.mjs` правила.
+ * Гейт активний лише за наявності концерну з імʼям `applies` і експортом-функцією `applies` у його
+ * першому check-файлі (алфавіт).
+ * @param {string} bundledRulesDir абсолютний `rules/`
+ * @param {import('./discover-checkable-rules.mjs').CheckableRule} rule опис правила
+ * @returns {Promise<boolean>} `true` — правило застосовне (або гейту немає); `false` — пропустити
+ */
+async function evaluateAppliesGate(bundledRulesDir, rule) {
+  const concern = rule.jsConcerns.find(c => c.name === APPLIES_CONCERN_NAME)
+  if (!concern || concern.files.length === 0) return true
+  const path = resolveJsCheckPath(bundledRulesDir, rule.id, concern, concern.files[0])
+  const mod = await import(path)
+  if (typeof mod.applies !== 'function') return true
+  return Boolean(await mod.applies())
+}
+
+/**
+ * Запускає одну policy-полісі через `runConftestBatch`. Створює локальний репортер,
+ * читає `target.json`, резолвить файли, фіксує fail/pass — і повертає exit-код.
+ * @param {string} bundledRulesDir абсолютний `rules/`
+ * @param {string} ruleId id правила
+ * @param {string} concernName імʼя полісі (= підкаталог у `policy/`)
+ * @param {Map<string, Promise<string[]>>} walkCache shared cache між концернами одного check-прогону
+ * @returns {Promise<number>} 0 — OK, 1 — є порушення
+ */
+async function runPolicyConcern(bundledRulesDir, ruleId, concernName, walkCache) {
+  const reporter = createCheckReporter()
+  const targetPath = join(bundledRulesDir, ruleId, 'policy', concernName, 'target.json')
+  /** @type {{ files: { single?: string, walkGlob?: string|string[], required?: boolean }, missingMessage?: string }} */
+  const target = JSON.parse(await readFile(targetPath, 'utf8'))
+  const files = await resolveTargetFiles(target.files, process.cwd(), walkCache)
+  if (files.length === 0) {
+    if (target.files.required && target.files.single) {
+      const msg =
+        target.missingMessage ?? `${target.files.single} не існує — створи згідно ${ruleId}.mdc (${ruleId}.${concernName})`
+      reporter.fail(msg)
+    }
+    return reporter.getExitCode()
+  }
+  // Rego не дозволяє '-' в імені пакета, тому kebab-id у `.n-cursor.json:rules`
+  // мапиться на snake у namespace. Файлова структура `rules/<id>/policy/` лишається kebab.
+  const regoNamespace = `${ruleId.replaceAll('-', '_')}.${concernName}`
+  const violations = runConftestBatch({
+    policyDirRel: `${ruleId}/${concernName}`,
+    namespace: regoNamespace,
+    files
+  })
+  if (violations.length === 0) {
+    reporter.pass(`${concernName}: ${files.length} файл(ів) OK (rego)`)
+  } else {
+    for (const v of violations) reporter.fail(v.message)
+  }
+  return reporter.getExitCode()
+}
+
+/**
+ * Запускає одне правило: applies-гейт → JS-концерни → policy-концерни.
+ * @param {import('./discover-checkable-rules.mjs').CheckableRule} rule
+ * @param {string} bundledRulesDir абсолютний шлях до `rules/`
+ * @param {Map<string, Promise<string[]>>} walkCache shared cache (один на check-прогон)
+ * @returns {Promise<number>} 0 — OK, 1 — є порушення в одному чи більше концернів
+ */
+export async function runRule(rule, bundledRulesDir, walkCache) {
+  console.log(`📋 ${rule.id}:`)
+
+  if (!(await evaluateAppliesGate(bundledRulesDir, rule))) {
+    console.log(`  ✅ Правило ${rule.id} не застосовне до цього репо — пропущено`)
+    return 0
+  }
+
+  let totalCode = 0
+
+  for (const concern of rule.jsConcerns) {
+    for (const fileName of concern.files) {
+      const path = resolveJsCheckPath(bundledRulesDir, rule.id, concern, fileName)
+      // eslint-disable-next-line no-unsanitized/method -- path будується з discovered concern/file, які пройшли regex CHECK_FILENAME_RE
+      const mod = await import(path)
+      if (typeof mod.check === 'function') {
+        const code = await mod.check()
+        if (code !== 0) totalCode = 1
+      }
+    }
+  }
+
+  for (const policyConcern of rule.policyConcerns) {
+    const code = await runPolicyConcern(bundledRulesDir, rule.id, policyConcern.name, walkCache)
+    if (code !== 0) totalCode = 1
+  }
+
+  return totalCode
+}

package/skills/adr-normalize/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: n-adr-normalize
+description: >-
+  Ручний запуск ADR-нормалізації — обхід порогу й min-interval, прогон одного
+  батчу чернеток через LLM, перегляд результату через git diff
+---
+
+# n-adr-normalize — ручна нормалізація ADR-чернеток
+
+Скіл запускає `.claude/hooks/normalize-decisions.sh` поза звичайним Stop-hook-тригером. Корисно, коли:
+
+- Поріг `ADR_NORMALIZE_THRESHOLD` ще не досягнуто, але хочеш почистити inbox.
+- Минулого разу LLM відмовився, тепер минув ще не весь `ADR_NORMALIZE_MIN_INTERVAL_HOURS` — хочеш повторити одразу.
+- Спочатку треба побачити, що саме LLM зробить (`ADR_NORMALIZE_DRY=1`).
+
+## Передумови
+
+- Правило `adr` увімкнене у `.n-cursor.json` (`"adr"` у `rules`).
+- `.claude/hooks/normalize-decisions.sh` існує (`npx @nitra/cursor` поклав його сюди).
+- У `PATH` доступний `claude` або `cursor-agent` (інакше скрипт мовчки вийде).
+- У `docs/adr/` є чернетки — файли з `session: …` у YAML frontmatter.
+
+## Кроки
+
+1. **Dry-run** (не міняє файли, лише пише план у `.claude/hooks/normalize-decisions.log`):
+
+   ```bash
+   ADR_NORMALIZE_THRESHOLD=0 \
+   ADR_NORMALIZE_MIN_INTERVAL_HOURS=0 \
+   ADR_NORMALIZE_DRY=1 \
+     bash .claude/hooks/normalize-decisions.sh
+   ```
+
+   Потім переглянь план: `tail -100 .claude/hooks/normalize-decisions.log`.
+
+2. **Реальний прогон одного батчу** (за замовчуванням до 30 чернеток):
+
+   ```bash
+   ADR_NORMALIZE_THRESHOLD=0 \
+   ADR_NORMALIZE_MIN_INTERVAL_HOURS=0 \
+     bash .claude/hooks/normalize-decisions.sh
+   ```
+
+3. **Перегляд результату** — скрипт нічого не комітить:
+
+   ```bash
+   git status docs/adr/
+   git diff docs/adr/
+   ```
+
+   Видалені файли — `delete`-операція. Нові файли `<slug>.md` — `rewrite`. Модифіковані clean-файли — `merge-into`.
+
+4. **Прийняти / відкотити:**
+
+   - Прийняти все: `git add docs/adr/ && git commit -m "adr: normalize batch"`.
+   - Відкотити конкретний файл: `git checkout -- docs/adr/<file>` (для `rewrite` цього мало — треба ще `git restore --staged` і `rm` нового).
+   - Відкотити весь батч: `git checkout -- docs/adr/ && git clean -f docs/adr/` (видалить і untracked rewrite-результати).
+
+5. **Повторити для наступного батчу**, якщо чернеток ще багато. Кожен запуск обробляє до `ADR_NORMALIZE_BATCH` файлів (default 30, найстарші за часовою позначкою у назві).
+
+## Tuning через ENV
+
+- `ADR_NORMALIZE_BATCH=10` — менший батч (менше токенів, частіші коміти).
+- `ADR_NORMALIZE_MODEL=opus` — інша модель `claude -p`.
+- `ADR_NORMALIZE_CURSOR_MODEL=…` — інша модель для cursor-agent fallback.
+
+## Якщо щось пішло не так
+
+- LLM повернув криву JSON → у логу буде `invalid JSON response (first 200 chars): …`. Запусти ще раз — нерідко це разовий збій.
+- Скрипт виходить миттєво без логу → перевір `ADR_NORMALIZE_RUNNING` у env (recursion guard) і чи репо не у стані merge/rebase.
+- Перейменування зробило слаги-дублі (`<slug>-2.md`) → це нормально, скрипт детермінований; під час review можна обʼєднати руками й видалити `-2`.

package/skills/adr-normalize/auto.md

@@ -0,0 +1 @@
+[adr]