@nitra/cursor 1.9.21 → 1.10.0

package/bin/n-cursor.js

@@ -21,7 +21,7 @@
  *
  * Якщо у корені репозиторію немає .n-cursor.json, спочатку перейменовується за наявності nitra-cursor.json;
  * у `.cursor/rules` файли `nitra-*.mdc` перейменовуються на `n-*.mdc`; інакше конфіг створюється автоматично
- * з усіма правилами з каталогу mdc пакету (їх можна відредагувати після створення). У файлі завжди має бути
+ * з усіма правилами з каталогу rules/ пакету (їх можна відредагувати після створення). У файлі завжди має бути
  * поле `$schema` з посиланням на JSON Schema пакету (публічний URL для IDE); при зчитуванні конфігу воно додається або виправляється на диску, якщо відсутнє або некоректне.
  * Масиви `rules`, `skills`, `disable-rules` і `disable-skills` при записі сортуються за алфавітом.
  *
@@ -36,7 +36,7 @@
  * `github-actions/` пакету при кожному успішному синку (workflows з правил ga / js-lint / text).
  *
  * Skills копіюються з npm/skills пакету лише для id з масиву «skills» у .n-cursor.json
- * (у JSON — без префікса, як імена файлів у mdc/ без n-). У пакеті джерело — каталоги
+ * (у JSON — без префікса, як імена каталогів у rules/ без n-). У пакеті джерело — каталоги
  * skills/<id>/ (без префікса); у проєкті — .cursor/skills/n-<id>/ (префікс n-, як n-*.mdc).
  * Якщо ключа skills немає, за замовчуванням підтягуються всі підкаталоги skills/ (лише імена без префікса n-).
  * Зайві каталоги n-* у .cursor/skills, яких немає у списку, видаляються.
@@ -67,7 +67,7 @@ import {
 import { detectAutoSkills } from '../scripts/auto-skills.mjs'
 import { runStopHookCli } from '../scripts/claude-stop-hook.mjs'
 import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
-import { runLintGaCli } from '../scripts/lint-ga.mjs'
+import { runLintGaCli } from '../rules/ga/js/lint.mjs'
 import { syncClaudeConfig } from '../scripts/sync-claude-config.mjs'
 import { upgradeNitraCursorToLatestAndBunInstall } from '../scripts/upgrade-nitra-cursor-and-install.mjs'
 import { runRenameYamlExtensionsCli } from './rename-yaml-extensions.mjs'
@@ -85,11 +85,11 @@ const COMMANDS_DIR = '.claude/commands'
 const RULE_PREFIX = 'n-'
 
 const binDir = dirname(fileURLToPath(import.meta.url))
-const BUNDLED_MDC_DIR = join(binDir, '..', 'mdc')
+const BUNDLED_RULES_DIR = join(binDir, '..', 'rules')
 const BUNDLED_SCRIPTS_DIR = join(binDir, '..', 'scripts')
 const BUNDLED_SKILLS_DIR = join(binDir, '..', 'skills')
 const BUNDLED_AGENTS_TEMPLATE_PATH = join(binDir, '..', AGENTS_TEMPLATE_FILE)
-/** Корінь установленого пакету (каталог з `mdc/`, `github-actions/`, …) */
+/** Корінь установленого пакету (каталог з `rules/`, `github-actions/`, …) */
 const BUNDLED_PACKAGE_ROOT = join(binDir, '..')
 
 const YAML_FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/
@@ -116,25 +116,27 @@ function sortConfigIdArrays(config) {
 }
 
 /**
- * Імена правил (без .mdc) з каталогу mdc поточної інсталяції пакету
- * @param {string} [bundledMdcDir] каталог `mdc/` у корені пакету (за замовчуванням — з поточного процесу)
- * @returns {Promise<string[]>} відсортовані імена файлів правил без суфікса .mdc
+ * Імена правил з каталогу `rules/` поточної інсталяції пакету. Кожне правило — окремий
+ * підкаталог `rules/<id>/`, у якому має бути `<id>.mdc`.
+ * @param {string} [bundledRulesDir] каталог `rules/` у корені пакету
+ * @returns {Promise<string[]>} відсортовані id правил (імена підкаталогів)
  */
-async function discoverBundledRuleNames(bundledMdcDir = BUNDLED_MDC_DIR) {
-  if (!existsSync(bundledMdcDir)) {
+async function discoverBundledRuleNames(bundledRulesDir = BUNDLED_RULES_DIR) {
+  if (!existsSync(bundledRulesDir)) {
     throw new Error(
       `Не знайдено каталог правил пакету.\n` +
-        `Очікуваний шлях: ${bundledMdcDir}\n` +
+        `Очікуваний шлях: ${bundledRulesDir}\n` +
         `Перевстановіть ${PACKAGE_NAME} або створіть ${CONFIG_FILE} вручну.`
     )
   }
-  const names = await readdir(bundledMdcDir)
-  const rules = names
-    .filter(n => n.endsWith('.mdc'))
-    .map(n => n.slice(0, -'.mdc'.length))
+  const entries = await readdir(bundledRulesDir, { withFileTypes: true })
+  const rules = entries
+    .filter(e => e.isDirectory() && !e.name.startsWith('.'))
+    .filter(e => existsSync(join(bundledRulesDir, e.name, `${e.name}.mdc`)))
+    .map(e => e.name)
     .toSorted((a, b) => a.localeCompare(b))
   if (rules.length === 0) {
-    throw new Error(`У каталозі mdc пакету немає файлів .mdc. Створіть ${CONFIG_FILE} вручну.`)
+    throw new Error(`У каталозі rules/ пакету немає підкаталогів з <id>.mdc. Створіть ${CONFIG_FILE} вручну.`)
   }
   return rules
 }
@@ -203,15 +205,15 @@ async function migrateLegacyConfigIfNeeded() {
 
 /**
  * Зчитує конфіг .n-cursor.json з поточної директорії
- * @param {{ bundledMdcDir?: string, bundledSkillsDir?: string }} [paths] каталоги з пакету-джерела (після `bun i` — зазвичай `node_modules/@nitra/cursor`)
+ * @param {{ bundledRulesDir?: string, bundledSkillsDir?: string }} [paths] каталоги з пакету-джерела (після `bun i` — зазвичай `node_modules/@nitra/cursor`)
  * @returns {Promise<{ $schema: string, rules: string[], skills: string[], version?: string } & Record<string, unknown>>} rules, skills (id без префікса n-); поле version у файлі за наявності ігнорується при синхронізації правил
  */
 async function readConfig(paths = {}) {
-  const bundledMdcDir = paths.bundledMdcDir ?? BUNDLED_MDC_DIR
+  const bundledRulesDir = paths.bundledRulesDir ?? BUNDLED_RULES_DIR
   const bundledSkillsDir = paths.bundledSkillsDir ?? BUNDLED_SKILLS_DIR
   await migrateLegacyConfigIfNeeded()
   const configPath = join(cwd(), CONFIG_FILE)
-  const availableRules = await discoverBundledRuleNames(bundledMdcDir)
+  const availableRules = await discoverBundledRuleNames(bundledRulesDir)
   const availableSkills = await discoverBundledSkillNames(bundledSkillsDir)
 
   /**
@@ -231,7 +233,7 @@ async function readConfig(paths = {}) {
   }
 
   /**
-   * Автодописує правила/skills за `auto-rules.md` і синхронізує `$schema`.
+   * Автодописує правила/skills за `rules/<rule>/auto.md` і синхронізує `$schema`.
    * @param {Record<string, unknown>} parsedConfig сирий обʼєкт конфігу
    * @returns {Promise<Record<string, unknown>>} нормалізований конфіг
    */
@@ -350,29 +352,31 @@ function logRuleMigrationsIfAny(parsedConfig) {
 }
 
 /**
- * Витягує чисте ім'я файлу правила (без шляху, але зберігає .mdc)
- * "npm/mdc/text.mdc" → "text.mdc"
- * "text"             → "text.mdc"
+ * Витягує чистий id правила без шляху і без .mdc.
+ * "npm/rules/text/text.mdc" → "text"
+ * "text.mdc"                → "text"
+ * "text"                    → "text"
  * @param {string} ruleName шлях або базове ім'я, з суфіксом .mdc або без
- * @returns {string} лише ім'я файлу з суфіксом .mdc
+ * @returns {string} id правила (без .mdc, без шляху)
  */
 function normalizeRuleName(ruleName) {
-  const name = ruleName.endsWith('.mdc') ? ruleName : `${ruleName}.mdc`
-  return basename(name)
+  const name = basename(String(ruleName).trim())
+  return name.endsWith('.mdc') ? name.slice(0, -'.mdc'.length) : name
 }
 
 /**
- * Читає вміст правила з каталогу `mdc/` установленого пакету (наприклад `node_modules/@nitra/cursor/mdc` або кеш npx).
+ * Читає вміст правила з каталогу `rules/<id>/<id>.mdc` установленого пакету
+ * (наприклад `node_modules/@nitra/cursor/rules/<id>/<id>.mdc` або кеш npx).
  * @param {string} rule елемент масиву rules з `.n-cursor.json`
- * @param {string} [bundledMdcDir] каталог `mdc/` у корені пакету-джерела
+ * @param {string} [bundledRulesDir] каталог `rules/` у корені пакету-джерела
  * @returns {Promise<string>} текст правила для запису в `.cursor/rules/n-*.mdc`
  */
-function readBundledRuleContent(rule, bundledMdcDir = BUNDLED_MDC_DIR) {
-  const bundledName = normalizeRuleName(rule)
-  const bundledPath = join(bundledMdcDir, bundledName)
+function readBundledRuleContent(rule, bundledRulesDir = BUNDLED_RULES_DIR) {
+  const id = normalizeRuleName(rule)
+  const bundledPath = join(bundledRulesDir, id, `${id}.mdc`)
   if (!existsSync(bundledPath)) {
     throw new Error(
-      `Немає файлу ${bundledName} у ${bundledMdcDir}. Оновіть ${PACKAGE_NAME} або приберіть "${rule}" з rules у ${CONFIG_FILE}.`
+      `Немає файлу ${id}/${id}.mdc у ${bundledRulesDir}. Оновіть ${PACKAGE_NAME} або приберіть "${rule}" з rules у ${CONFIG_FILE}.`
     )
   }
   return readFile(bundledPath, 'utf8')
@@ -515,7 +519,7 @@ async function listProjectRulesMdcFiles() {
  * @returns {Set<string>} множина очікуваних імен файлів (наприклад n-bun.mdc)
  */
 function expectedManagedRuleBasenames(configRules) {
-  return new Set(configRules.map(rule => `${RULE_PREFIX}${normalizeRuleName(rule)}`))
+  return new Set(configRules.map(rule => `${RULE_PREFIX}${normalizeRuleName(rule)}.mdc`))
 }
 
 /**
@@ -939,19 +943,19 @@ async function runSyncStep(prefix, action) {
 /**
  * Копіює керовані `.mdc` файли з пакету до `.cursor/rules`.
  * @param {string[]} rules список rules з конфігу
- * @param {string} bundledMdcDir каталог `mdc` пакету-джерела
+ * @param {string} bundledRulesDir каталог `mdc` пакету-джерела
  * @param {string} rulesDir абсолютний шлях до `.cursor/rules`
  * @returns {Promise<{ successCount: number, failCount: number }>} статистика копіювання
  */
-async function syncManagedRuleFiles(rules, bundledMdcDir, rulesDir) {
+async function syncManagedRuleFiles(rules, bundledRulesDir, rulesDir) {
   let successCount = 0
   let failCount = 0
   for (const rule of rules) {
-    const fileName = `${RULE_PREFIX}${normalizeRuleName(rule)}`
+    const fileName = `${RULE_PREFIX}${normalizeRuleName(rule)}.mdc`
     const destPath = join(rulesDir, fileName)
     try {
       process.stdout.write(`  ⬇  ${rule} → ${RULES_DIR}/${fileName} ... `)
-      const content = await readBundledRuleContent(rule, bundledMdcDir)
+      const content = await readBundledRuleContent(rule, bundledRulesDir)
       await writeFile(destPath, content, 'utf8')
       console.log(`✅`)
       successCount++
@@ -982,15 +986,17 @@ function logRemovedManagedItems(title, basePath, names) {
 }
 
 /**
- * Знаходить доступні check-скрипти у каталозі scripts пакету
- * @returns {Promise<string[]>} відсортовані імена правил (наприклад ['bun', 'ga', 'js-lint'])
+ * Знаходить доступні check-скрипти. Кожне правило з check-скриптом тримає його у
+ * `rules/<id>/js/check.mjs` (rule-centric layout).
+ * @returns {Promise<string[]>} відсортовані id правил, для яких є check.mjs
  */
 async function discoverCheckScripts() {
-  if (!existsSync(BUNDLED_SCRIPTS_DIR)) return []
-  const names = await readdir(BUNDLED_SCRIPTS_DIR)
-  return names
-    .filter(n => n.startsWith('check-') && n.endsWith('.mjs'))
-    .map(n => n.slice('check-'.length, -'.mjs'.length))
+  if (!existsSync(BUNDLED_RULES_DIR)) return []
+  const entries = await readdir(BUNDLED_RULES_DIR, { withFileTypes: true })
+  return entries
+    .filter(e => e.isDirectory() && !e.name.startsWith('.'))
+    .filter(e => existsSync(join(BUNDLED_RULES_DIR, e.name, 'js', 'check.mjs')))
+    .map(e => e.name)
     .toSorted((a, b) => a.localeCompare(b))
 }
 
@@ -1090,10 +1096,10 @@ async function runChecks(requestedRules) {
   let totalFailed = 0
 
   for (const rule of rulesToCheck) {
-    const scriptPath = join(BUNDLED_SCRIPTS_DIR, `check-${rule}.mjs`)
+    const scriptPath = join(BUNDLED_RULES_DIR, rule, 'js', 'check.mjs')
     console.log(`📋 ${rule}:`)
     try {
-      // eslint-disable-next-line no-unsanitized/method -- rule валідовано проти available, scriptPath будується з фіксованої BUNDLED_SCRIPTS_DIR
+      // eslint-disable-next-line no-unsanitized/method -- rule валідовано проти available, scriptPath будується з фіксованої BUNDLED_RULES_DIR
       const { check } = await import(scriptPath)
       const code = await check()
       if (code !== 0) totalFailed++
@@ -1201,11 +1207,11 @@ async function runSync() {
 
   await reexecIfPackageVersionChanged(effectivePackageRoot)
 
-  const bundledMdcDir = join(effectivePackageRoot, 'mdc')
+  const bundledRulesDir = join(effectivePackageRoot, 'mdc')
   const bundledSkillsDir = join(effectivePackageRoot, 'skills')
   const bundledAgentsTemplatePath = join(effectivePackageRoot, AGENTS_TEMPLATE_FILE)
 
-  const config = await runSyncStep('❌ ', () => readConfig({ bundledMdcDir, bundledSkillsDir }))
+  const config = await runSyncStep('❌ ', () => readConfig({ bundledRulesDir, bundledSkillsDir }))
 
   const { rules, skills, version, ignore } = config
   const claudeConfigEnabled = config['claude-config'] !== false
@@ -1230,7 +1236,7 @@ async function runSync() {
 
   const rulesDir = join(cwd(), RULES_DIR)
   await mkdir(rulesDir, { recursive: true })
-  const { successCount, failCount } = await syncManagedRuleFiles(rules, bundledMdcDir, rulesDir)
+  const { successCount, failCount } = await syncManagedRuleFiles(rules, bundledRulesDir, rulesDir)
 
   await runSyncStep(`❌ Не вдалося прибрати зайві файли в ${RULES_DIR}: `, async () => {
     const removed = await removeOrphanManagedRuleFiles(rulesDir, rules)
@@ -1288,6 +1294,7 @@ async function runSync() {
     if (result.npmClaudeMd) parts.push('npm/CLAUDE.md')
     if (result.commands.length > 0) parts.push(`${result.commands.length} slash-commands`)
     if (result.adrHook) parts.push('.claude/hooks/capture-decisions.sh')
+    if (result.adrNormalizeHook) parts.push('.claude/hooks/normalize-decisions.sh')
     if (parts.length > 0) {
       console.log(`🤖 Claude-конфіг: ${parts.join(', ')}`)
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.9.21",
+  "version": "1.10.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -24,21 +24,23 @@
   },
   "files": [
     "types",
-    "mdc",
+    "rules",
     "bin",
     "github-actions",
-    "policy",
     "schemas",
     "scripts",
     "skills",
     ".claude-template",
     "AGENTS.template.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "!**/*.test.mjs",
+    "!**/test-helpers.mjs",
+    "!**/fixtures/**"
   ],
   "type": "module",
   "types": "./types/bin/n-cursor.d.ts",
   "scripts": {
-    "test": "bun test tests",
+    "test": "bun test",
     "rename-yaml-extensions": "bun ./bin/n-cursor.js rename-yaml-extensions"
   },
   "dependencies": {
@@ -48,5 +50,8 @@
   "engines": {
     "bun": ">=1.3",
     "node": ">=25"
+  },
+  "devDependencies": {
+    "@nitra/cursor": "^1.9.22"
   }
 }

package/rules/abie/auto.md

@@ -0,0 +1 @@
+якщо в кореневому package.json в секції "repository" присутній текст "<https://github.com/abinbevefes/**/>"

package/{scripts/check-abie.mjs → rules/abie/js/check.mjs}

@@ -45,11 +45,11 @@ import { basename, dirname, join, relative } from 'node:path'
 
 import { parseAllDocuments } from 'yaml'
 
-import { pathHasK8sSegment } from './check-k8s.mjs'
-import { createCheckReporter } from './utils/check-reporter.mjs'
-import { loadCursorIgnorePaths } from './utils/load-cursor-config.mjs'
-import { runConftestBatch } from './utils/run-conftest-batch.mjs'
-import { walkDir } from './utils/walkDir.mjs'
+import { pathHasK8sSegment } from '../../k8s/js/check.mjs'
+import { createCheckReporter } from '../../../scripts/utils/check-reporter.mjs'
+import { loadCursorIgnorePaths } from '../../../scripts/utils/load-cursor-config.mjs'
+import { runConftestBatch } from '../../../scripts/utils/run-conftest-batch.mjs'
+import { walkDir } from '../../../scripts/utils/walkDir.mjs'
 
 const CONFIG_FILE = '.n-cursor.json'
 

package/rules/adr/adr.mdc

@@ -0,0 +1,150 @@
+---
+description: Автоматичний збір ADR/Runbook/Knowledge-чернеток і батч-нормалізація у `docs/adr/` через Stop-хук Claude Code
+alwaysApply: true
+version: '2.0'
+---
+
+Правило вмикається **вручну** — додай `"adr"` у масив `rules` файлу `.n-cursor.json`. У `auto-rules.md` його немає, бо корисність залежить від робочого процесу команди (не кожен проєкт хоче літати ADR-чернеткам у `docs/`).
+
+Коли правило увімкнене, **`npx @nitra/cursor`** автоматично:
+
+- копіює канонічний bash-скрипт у **`.claude/hooks/capture-decisions.sh`** (executable, повністю керується пакетом — на кожен sync перезаписується);
+- копіює канонічний 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`.
+
+## Дві фази, один каталог
+
+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 (порядок фіксований):
+
+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-інструментів — для класифікації / нормалізації інструменти не потрібні.
+
+## Структура каталогу
+
+```text
+docs/adr/
+├── YYYYMMDD-HHMMSS-<sid>.md   # drafts (frontmatter session:/captured:/transcript:)
+└── <slug>.md                  # clean ADR-и (без frontmatter)
+.claude/hooks/
+├── 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/*.log`** і службові файли normalize (`.claude/hooks/.normalize-*`).
+
+> Якщо в репозиторії лишився старий каталог **`docs/adr/_inbox/`** з попередньої версії правила — `normalize-decisions.sh` бачить його рекурсивно й поступово розчистить. Можна також одразу `git mv docs/adr/_inbox/*.md docs/adr/` і прибрати порожній каталог.
+
+## Stop-hook у `.claude/settings.json`
+
+Канонічний запис, який вставляє sync (поряд із lint stop-hook):
+
+```json title=".claude/settings.json"
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx --no @nitra/cursor stop-hook",
+            "timeout": 60
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/capture-decisions.sh\"",
+            "async": true,
+            "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`, `.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-копія створили б два запуски на одну подію.
+
+## Перевірка
+
+`npx @nitra/cursor check adr`