@nitra/cursor 1.8.188 → 1.8.189

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

@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+# Stop hook: extract ADR/Runbook/Knowledge drafts from session transcript.
+# Runs async. Recursion guard: env var prevents the inner LLM CLI from
+# re-triggering this hook (the inner session inherits CAPTURE_DECISIONS_RUNNING=1).
+#
+# LLM CLI selection (first available wins):
+#   1. claude        — use `claude -p --model "$CAPTURE_DECISIONS_CLAUDE_MODEL"` (default: sonnet)
+#   2. cursor-agent  — use `cursor-agent -p --mode ask --model "$CAPTURE_DECISIONS_CURSOR_MODEL"`
+#                       (default: claude-4.6-sonnet-medium)
+#   neither          — exit 0 silently
+#
+# Bundled with @nitra/cursor; project copy is auto-synced by the `adr` rule.
+set -euo pipefail
+
+if [[ -n "${CAPTURE_DECISIONS_RUNNING:-}" ]]; then
+  exit 0
+fi
+export CAPTURE_DECISIONS_RUNNING=1
+
+INPUT=$(cat)
+TRANSCRIPT_PATH=$(printf '%s' "$INPUT" | jq -r '.transcript_path // empty')
+SESSION_ID=$(printf '%s' "$INPUT" | jq -r '.session_id // "unknown"')
+
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+INBOX="$PROJECT_ROOT/docs/adr/_inbox"
+LOG_DIR="$PROJECT_ROOT/.claude/hooks"
+LOG="$LOG_DIR/capture-decisions.log"
+mkdir -p "$INBOX" "$LOG_DIR"
+
+log() { printf '%s %s\n' "$(date -Iseconds)" "$*" >> "$LOG"; }
+
+log "fired: $SESSION_ID"
+
+if [[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]]; then
+  log "  → no transcript path"
+  exit 0
+fi
+
+# Extract role + text + thinking + tool_use names from JSONL transcript.
+# We keep reasoning/decisions visible to the analyzer but drop large tool outputs.
+TRANSCRIPT=$(jq -r '
+  select(.type == "user" or .type == "assistant")
+  | .message as $m
+  | ($m.role // .type) as $role
+  | ($m.content
+      | if type == "string" then .
+        else (
+          map(
+            if .type == "text" then .text
+            elif .type == "thinking" then "[thinking]\n" + (.thinking // "")
+            elif .type == "tool_use" then
+              "[tool: " + .name + "]" +
+              (if .input then
+                " " + (.input | tostring | .[0:300])
+              else "" end)
+            elif .type == "tool_result" then
+              "[tool_result] " + (
+                (.content
+                  | if type == "string" then . else (map(select(.type=="text") | .text) | join(" ")) end
+                ) // "" | .[0:300]
+              )
+            else "" end
+          ) | map(select(length > 0)) | join("\n")
+        )
+        end) as $body
+  | select($body | length > 0)
+  | "[" + $role + "]\n" + $body
+' "$TRANSCRIPT_PATH" 2>/dev/null || true)
+
+# Cap input size to keep latency/cost predictable.
+MAX_CHARS=120000
+if (( ${#TRANSCRIPT} > MAX_CHARS )); then
+  TRANSCRIPT="${TRANSCRIPT: -$MAX_CHARS}"
+fi
+
+if [[ -z "$TRANSCRIPT" ]]; then
+  exit 0
+fi
+
+PROMPT=$(cat <<'EOF'
+You analyze a Claude Code session transcript and produce a durable knowledge artifact (ADR, Runbook, or Knowledge note) capturing what was done and why.
+
+LANGUAGE: Write the ENTIRE output in Ukrainian. This applies to the title, all section content, prose, and rationale. Keep code identifiers, file paths, commands, and tool or library names in their original form (do not translate `walkDir`, `package.json`, `npm`, etc.) — only translate the natural-language prose around them. Section labels themselves stay in Ukrainian per the template below.
+
+IMPORTANT: by "decision" we mean the design choice expressed in the session — even if the user pre-specified it in their brief. The user dictating the approach IS the decision; capture it, including the rationale they gave or that became apparent during implementation. Do NOT return NONE just because the user gave detailed instructions upfront.
+
+OUTPUT RULES:
+- Emit one or more markdown blocks in this exact shape (no preamble, no trailing prose):
+
+## [ADR|Runbook|Knowledge] <короткий заголовок українською>
+**Контекст:** <яка проблема / ситуація це спричинила — 1-2 речення>
+**Рішення/Процедура/Факт:** <що було зроблено — конкретно: змінені файли, введена семантика, кроки>
+**Обґрунтування:** <чому саме такий підхід — з ТЗ користувача або міркувань асистента>
+**Розглянуті альтернативи:** <перелік явно обговорених, або «не обговорювалися»>
+**Зачіпає:** <файли, модулі, публічні API, конфіги>
+
+WHEN TO PICK EACH TYPE:
+- ADR: a design choice (library, schema, pattern, semantics of a field/API). Most substantive code work qualifies.
+- Runbook: a procedure to operate, fix, deploy, or reproduce something.
+- Knowledge: a non-obvious constraint, gotcha, or invariant uncovered (without a corresponding code change).
+
+OUTPUT NONE ONLY IF the session is genuinely trivial:
+- A single typo fix, comment edit, or lint cleanup with no design content
+- A pure question/answer with no code change and no surprising fact
+- An aborted/empty session
+
+When in doubt, emit a block. Capturing too much is acceptable; missing real work is not.
+
+TRANSCRIPT FOLLOWS:
+---
+EOF
+)
+
+PROMPT_FULL=$(printf '%s\n%s\n' "$PROMPT" "$TRANSCRIPT")
+
+CLAUDE_MODEL="${CAPTURE_DECISIONS_CLAUDE_MODEL:-sonnet}"
+CURSOR_MODEL="${CAPTURE_DECISIONS_CURSOR_MODEL:-claude-4.6-sonnet-medium}"
+
+if command -v claude >/dev/null 2>&1; then
+  log "  → using claude CLI (model: $CLAUDE_MODEL)"
+  RESPONSE=$(printf '%s' "$PROMPT_FULL" | claude -p --model "$CLAUDE_MODEL" 2>>"$LOG" || true)
+elif command -v cursor-agent >/dev/null 2>&1; then
+  log "  → using cursor-agent CLI (model: $CURSOR_MODEL)"
+  RESPONSE=$(cursor-agent -p --mode ask --output-format text --model "$CURSOR_MODEL" -- "$PROMPT_FULL" 2>>"$LOG" || true)
+else
+  log "  → no LLM CLI found (claude/cursor-agent), skipping"
+  exit 0
+fi
+
+RESPONSE_TRIMMED=$(printf '%s' "$RESPONSE" | sed 's/^[[:space:]]*//; s/[[:space:]]*$//')
+
+log "  → response length: ${#RESPONSE_TRIMMED}, first 200: ${RESPONSE_TRIMMED:0:200}"
+
+if [[ -z "$RESPONSE_TRIMMED" ]]; then
+  log "  → empty response from LLM CLI"
+  exit 0
+fi
+if [[ "$RESPONSE_TRIMMED" == "NONE" ]]; then
+  log "  → NONE"
+  exit 0
+fi
+if ! printf '%s' "$RESPONSE_TRIMMED" | grep -q '^## '; then
+  log "  → response missing '## ' header"
+  exit 0
+fi
+
+TS=$(date +%Y%m%d-%H%M%S)
+OUT="$INBOX/$TS-${SESSION_ID:0:8}.md"
+{
+  printf -- '---\nsession: %s\ncaptured: %s\ntranscript: %s\n---\n\n' \
+    "$SESSION_ID" "$(date -Iseconds)" "$TRANSCRIPT_PATH"
+  printf '%s\n' "$RESPONSE_TRIMMED"
+} > "$OUT"
+log "wrote: $OUT"

package/CHANGELOG.md

@@ -4,6 +4,20 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.189] - 2026-05-07
+
+### Added
+
+- Нове правило `adr` (вмикається **вручну** через `.n-cursor.json` `rules`): автоматичне копіювання канонічного `.claude/hooks/capture-decisions.sh` з пакета та керована Stop-група у `.claude/settings.json`, яка викликає скрипт асинхронно (`async: true`, timeout `180`s). Скрипт зчитує JSONL-транскрипт сесії, передає дайджест у LLM CLI і пише чернетки ADR/Runbook/Knowledge у `docs/adr/_inbox/`.
+- `capture-decisions.sh`: fallback `claude` → `cursor-agent` (LLM CLI). Якщо `claude` відсутній, береться `cursor-agent -p --mode ask --output-format text`. Моделі задаються через ENV `CAPTURE_DECISIONS_CLAUDE_MODEL` (default `sonnet`) і `CAPTURE_DECISIONS_CURSOR_MODEL` (default `claude-4.6-sonnet-medium`).
+- `check-adr.mjs`: програмна перевірка наявності та канонічності `.claude/hooks/capture-decisions.sh`, ADR-групи у `.claude/settings.json`, відсутності дубля у `.claude/settings.local.json`, ігнорування `.claude/hooks/capture-decisions.log` у `.gitignore`, інформативно — наявність бодай одного LLM CLI (`claude`/`cursor-agent`) у `PATH`.
+- `tests/check-adr.test.mjs` (7 кейсів) і нові кейси у `tests/sync-claude-config.test.mjs`: copy + Stop-merge + ідемпотентність + автоматичне видалення managed-групи при видаленні `adr` з `rules`.
+
+### Changed
+
+- `sync-claude-config.mjs`: `MANAGED_HOOK_COMMAND_MARKERS` (масив) замість одиничного маркера; `mergeSettings(existing, template, { includeAdrHook })`; `syncClaudeConfig` приймає `rules` і умовно копіює ADR Stop-hook script + додає managed-групу до Stop. `syncClaudeConfig` повертає додатковий прапорець `adrHook`.
+- `bin/n-cursor.js`: передає `rules` у `syncClaudeConfig` і логує `.claude/hooks/capture-decisions.sh` у підсумку Claude-конфіга.
+
 ## [1.8.188] - 2026-05-07
 
 ### Changed

package/bin/n-cursor.js

@@ -1177,7 +1177,8 @@ async function runSync() {
     const result = await syncClaudeConfig({
       projectRoot: cwd(),
       bundledPackageRoot: effectivePackageRoot,
-      enabled: claudeConfigEnabled
+      enabled: claudeConfigEnabled,
+      rules
     })
     if (!claudeConfigEnabled) {
       console.log('🤖 Claude-конфіг: пропущено (claude-config: false у .n-cursor.json)')
@@ -1187,6 +1188,7 @@ async function runSync() {
     if (result.settings) parts.push('.claude/settings.json')
     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 (parts.length > 0) {
       console.log(`🤖 Claude-конфіг: ${parts.join(', ')}`)
     }

package/mdc/adr.mdc

@@ -0,0 +1,86 @@
+---
+description: Автоматичний збір ADR/Runbook/Knowledge-чернеток із Stop-хука Claude Code (capture-decisions)
+alwaysApply: true
+version: '1.0'
+---
+
+Правило вмикається **вручну** — додай `"adr"` у масив `rules` файлу `.n-cursor.json`. У `auto-rules.md` його немає, бо корисність залежить від робочого процесу команди (не кожен проєкт хоче літати ADR-чернеткам у `docs/`).
+
+Коли правило увімкнене, **`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`.
+
+## Що робить механізм
+
+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`.
+
+## LLM CLI: claude → cursor-agent fallback
+
+Скрипт сам обирає доступний 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`).
+3. Жодного CLI у `PATH` — скрипт виходить з кодом `0` і нічого не пише.
+
+`--mode ask` для cursor-agent навмисно: режим Q&A read-only, без shell/edit-інструментів — для класифікації сесії інструменти не потрібні. Моделі можна перевизначити через ENV: `CAPTURE_DECISIONS_CLAUDE_MODEL`, `CAPTURE_DECISIONS_CURSOR_MODEL`.
+
+## Структура каталогу
+
+```text
+docs/adr/
+└── _inbox/                         # чернетки, що пишуться Stop-хуком
+    └── YYYYMMDD-HHMMSS-<sid>.md    # session_id (перші 8 символів)
+.claude/hooks/
+├── capture-decisions.sh            # auto-synced з пакета
+└── capture-decisions.log           # лог запусків (НЕ коміти)
+```
+
+`.gitignore` повинен містити рядок **`.claude/hooks/capture-decisions.log`**, щоб лог не потрапляв у git.
+
+`docs/adr/_inbox/` — це робоча скринька; чернетки звідти переносяться у структуровані ADR-файли вручну (під час оглядів) або тримаються як архів сесій. Каталог сам створюється скриптом, тому пустим у git тримати не потрібно.
+
+## 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
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Обидві групи ідентифікуються пакетом за маркером у `command` (`@nitra/cursor stop-hook` і `.claude/hooks/capture-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`

package/package.json

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

package/scripts/check-adr.mjs

@@ -0,0 +1,248 @@
+/**
+ * Перевіряє вимоги правила adr.mdc: ADR Stop-hook capture-decisions.sh у Claude Code.
+ *
+ * Очікування:
+ * - `.claude/hooks/capture-decisions.sh` існує і байт-у-байт збігається з канонічним
+ *   `.claude-template/hooks/capture-decisions.sh` пакета (sync керує файлом повністю).
+ * - `.claude/settings.json` (project-shared) має managed-групу у `hooks.Stop`, яка
+ *   викликає цей bash-скрипт; маркер у `command` — `.claude/hooks/capture-decisions.sh`.
+ * - `.claude/settings.local.json` (якщо існує) НЕ має дубля цієї managed-групи —
+ *   після переходу на project-shared такий запис створив би два запуски на одну подію.
+ * - `.gitignore` у корені містить шаблон, який покриває `.claude/hooks/capture-decisions.log`.
+ *
+ * LLM CLI (`claude` або `cursor-agent`) у `PATH` — інформативна перевірка: якщо жодного
+ * немає, скрипт працює, але мовчки виходить, тому це warning, а не fail.
+ */
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { delimiter, dirname, join } from 'node:path'
+import { env } from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+import { createCheckReporter } from './utils/check-reporter.mjs'
+
+const PROJECT_HOOK_PATH = '.claude/hooks/capture-decisions.sh'
+const PROJECT_SETTINGS_PATH = '.claude/settings.json'
+const PROJECT_LOCAL_SETTINGS_PATH = '.claude/settings.local.json'
+const PROJECT_LOG_PATH = '.claude/hooks/capture-decisions.log'
+const HOOK_COMMAND_MARKER = '.claude/hooks/capture-decisions.sh'
+
+const here = dirname(fileURLToPath(import.meta.url))
+/** Канонічний bundled-скрипт у пакеті — джерело правди для звірки з проєктним. */
+const BUNDLED_HOOK_PATH = join(here, '..', '.claude-template', 'hooks', 'capture-decisions.sh')
+
+/**
+ * Чи містить рядок `.gitignore` шаблон, який покриває `.claude/hooks/capture-decisions.log`.
+ * Враховує точний шлях, glob `.claude/hooks/*.log` та широкий glob `**\/*.log`.
+ * @param {string} line одна нормалізована (trim) лінія `.gitignore`
+ * @returns {boolean} `true`, якщо лінія матчить лог-файл хука
+ */
+function gitignoreLineCoversHookLog(line) {
+  if (!line || line.startsWith('#')) {
+    return false
+  }
+  if (line === PROJECT_LOG_PATH) {
+    return true
+  }
+  if (line === '.claude/hooks/*.log' || line === '.claude/hooks/**/*.log') {
+    return true
+  }
+  if (line === '*.log' || line === '**/*.log') {
+    return true
+  }
+  return false
+}
+
+/**
+ * Перевіряє наявність і канонічність `.claude/hooks/capture-decisions.sh` у проєкті.
+ * @param {import('./utils/check-reporter.mjs').CheckReporter} reporter репортер для збору результатів
+ * @returns {Promise<void>}
+ */
+async function checkHookScript(reporter) {
+  const { pass, fail } = reporter
+  if (!existsSync(PROJECT_HOOK_PATH)) {
+    fail(`${PROJECT_HOOK_PATH} не існує — запусти \`npx @nitra/cursor\` (правило adr копіює канонічний скрипт)`)
+    return
+  }
+  if (!existsSync(BUNDLED_HOOK_PATH)) {
+    fail(`канонічний скрипт у пакеті не знайдено: ${BUNDLED_HOOK_PATH} — перевстанови @nitra/cursor`)
+    return
+  }
+  const [project, bundled] = await Promise.all([readFile(PROJECT_HOOK_PATH, 'utf8'), readFile(BUNDLED_HOOK_PATH, 'utf8')])
+  if (project === bundled) {
+    pass(`${PROJECT_HOOK_PATH} збігається з канонічним`)
+  } else {
+    fail(`${PROJECT_HOOK_PATH} відрізняється від канонічного — запусти \`npx @nitra/cursor\` для повторного синку`)
+  }
+}
+
+/**
+ * Знаходить у `hooks.Stop` групу, де `command` будь-якого hook-а містить маркер.
+ * @param {unknown} settings розпарсений `.claude/settings.json`
+ * @returns {boolean} `true`, якщо знайдено хоч одну групу з маркером
+ */
+function settingsHaveAdrHookGroup(settings) {
+  if (!settings || typeof settings !== 'object') {
+    return false
+  }
+  const hooks = /** @type {Record<string, unknown>} */ (settings).hooks
+  if (!hooks || typeof hooks !== 'object') {
+    return false
+  }
+  const stopGroups = /** @type {Record<string, unknown>} */ (hooks).Stop
+  if (!Array.isArray(stopGroups)) {
+    return false
+  }
+  return stopGroups.some(group => {
+    const inner = group && typeof group === 'object' ? /** @type {Record<string, unknown>} */ (group).hooks : null
+    if (!Array.isArray(inner)) {
+      return false
+    }
+    return inner.some(h => {
+      const cmd = h && typeof h === 'object' ? /** @type {Record<string, unknown>} */ (h).command : null
+      return typeof cmd === 'string' && cmd.includes(HOOK_COMMAND_MARKER)
+    })
+  })
+}
+
+/**
+ * Зчитує JSON-файл або повертає `undefined`, якщо файл відсутній чи невалідний.
+ * @param {string} path відносний шлях до JSON-файлу
+ * @returns {Promise<unknown | undefined>} розпарсений вміст або `undefined`
+ */
+async function readJsonOrUndefined(path) {
+  if (!existsSync(path)) {
+    return
+  }
+  try {
+    return JSON.parse(await readFile(path, 'utf8'))
+  } catch {
+    return
+  }
+}
+
+/**
+ * Перевіряє project-shared `.claude/settings.json` на наявність ADR Stop-hook'а.
+ * @param {import('./utils/check-reporter.mjs').CheckReporter} reporter репортер для збору результатів
+ * @returns {Promise<void>}
+ */
+async function checkProjectSettings(reporter) {
+  const { pass, fail } = reporter
+  const settings = await readJsonOrUndefined(PROJECT_SETTINGS_PATH)
+  if (settings === undefined) {
+    fail(`${PROJECT_SETTINGS_PATH} не існує або невалідний — запусти \`npx @nitra/cursor\``)
+    return
+  }
+  if (settingsHaveAdrHookGroup(settings)) {
+    pass(`${PROJECT_SETTINGS_PATH} містить ADR Stop-hook (capture-decisions.sh)`)
+  } else {
+    fail(
+      `${PROJECT_SETTINGS_PATH}: у hooks.Stop немає групи з \`${HOOK_COMMAND_MARKER}\` — переконайся, що "adr" у rules і запусти \`npx @nitra/cursor\``
+    )
+  }
+}
+
+/**
+ * Перевіряє, що `.claude/settings.local.json` не дублює ADR Stop-hook (project-shared — джерело правди).
+ * @param {import('./utils/check-reporter.mjs').CheckReporter} reporter репортер для збору результатів
+ * @returns {Promise<void>}
+ */
+async function checkLocalSettingsNoDuplicate(reporter) {
+  const { pass, fail } = reporter
+  if (!existsSync(PROJECT_LOCAL_SETTINGS_PATH)) {
+    pass(`${PROJECT_LOCAL_SETTINGS_PATH} відсутній — дубля немає`)
+    return
+  }
+  const local = await readJsonOrUndefined(PROJECT_LOCAL_SETTINGS_PATH)
+  if (local === undefined) {
+    pass(`${PROJECT_LOCAL_SETTINGS_PATH} нечитабельний — дубля немає`)
+    return
+  }
+  if (settingsHaveAdrHookGroup(local)) {
+    fail(
+      `${PROJECT_LOCAL_SETTINGS_PATH} містить дубль ADR Stop-hook (capture-decisions.sh) — прибери, бо project-shared settings.json уже керує цим`
+    )
+  } else {
+    pass(`${PROJECT_LOCAL_SETTINGS_PATH} не дублює ADR Stop-hook`)
+  }
+}
+
+/**
+ * Перевіряє `.gitignore` на ігнорування лог-файлу хука.
+ * @param {import('./utils/check-reporter.mjs').CheckReporter} reporter репортер для збору результатів
+ * @returns {Promise<void>}
+ */
+async function checkGitignore(reporter) {
+  const { pass, fail } = reporter
+  if (!existsSync('.gitignore')) {
+    fail(`.gitignore не існує — додай рядок \`${PROJECT_LOG_PATH}\``)
+    return
+  }
+  const content = await readFile('.gitignore', 'utf8')
+  const covers = content
+    .split(/\r?\n/u)
+    .map(l => l.trim())
+    .some(gitignoreLineCoversHookLog)
+  if (covers) {
+    pass(`.gitignore покриває ${PROJECT_LOG_PATH}`)
+  } else {
+    fail(`.gitignore не ігнорує \`${PROJECT_LOG_PATH}\` — додай цей рядок`)
+  }
+}
+
+/**
+ * Чи виконуваний бінарник з іменем `name` доступний у `PATH` поточного процесу.
+ * Перевірка без spawn — просто шукаємо файл у каталогах PATH (як `which`).
+ * @param {string} name ім'я бінарника без розширення
+ * @returns {boolean} `true`, якщо знайдено в одному з каталогів `PATH`
+ */
+function isBinaryInPath(name) {
+  const path = env.PATH ?? ''
+  if (!path) {
+    return false
+  }
+  for (const dir of path.split(delimiter)) {
+    if (!dir) continue
+    if (existsSync(join(dir, name))) {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ * Інформативна перевірка: чи доступний бодай один LLM CLI (`claude` або `cursor-agent`).
+ * Якщо жодного немає — це warning (`pass` з підказкою), бо хук просто мовчки no-op'ає.
+ * @param {import('./utils/check-reporter.mjs').CheckReporter} reporter репортер для збору результатів
+ * @returns {void}
+ */
+function checkLlmCliAvailable(reporter) {
+  const { pass } = reporter
+  const hasClaude = isBinaryInPath('claude')
+  const hasCursor = isBinaryInPath('cursor-agent')
+  if (hasClaude && hasCursor) {
+    pass('LLM CLI: знайдено `claude` і `cursor-agent`')
+  } else if (hasClaude) {
+    pass('LLM CLI: знайдено `claude` (cursor-agent відсутній — fallback не використовується)')
+  } else if (hasCursor) {
+    pass('LLM CLI: знайдено `cursor-agent` (claude відсутній — буде використано fallback)')
+  } else {
+    pass(
+      'LLM CLI: жодного з `claude`/`cursor-agent` не знайдено у PATH — Stop-hook буде мовчки no-op до встановлення CLI'
+    )
+  }
+}
+
+/**
+ * Перевіряє відповідність проєкту правилам adr.mdc.
+ * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
+ */
+export async function check() {
+  const reporter = createCheckReporter()
+  await checkHookScript(reporter)
+  await checkProjectSettings(reporter)
+  await checkLocalSettingsNoDuplicate(reporter)
+  await checkGitignore(reporter)
+  checkLlmCliAvailable(reporter)
+  return reporter.getExitCode()
+}

package/scripts/sync-claude-config.mjs

@@ -1,31 +1,54 @@
 /**
  * Синхронізує конфігурацію Claude Code (`.claude/settings.json`, `npm/CLAUDE.md`,
- * slash-команди для checks) у поточний проєкт із темплейтів пакету
+ * slash-команди для checks, ADR Stop-hook) у поточний проєкт із темплейтів пакету
  * `npm/.claude-template/`.
  *
  * Архітектура:
  * - `settings.json` — **merge**: користувацькі поля зберігаються; наші hooks
- *   ідентифікуються командою-маркером (`MANAGED_HOOK_COMMAND_MARKER`) і
+ *   ідентифікуються командою-маркером (`MANAGED_HOOK_COMMAND_MARKERS`) і
  *   перезаписуються; permissions.allow зливається через union (із дедублікацією).
  * - `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-template/hooks/`, лише коли в `.n-cursor.json` `rules`
+ *   присутнє `adr` (правило вмикається вручну). Якщо правила немає, керована
+ *   ADR-група в hooks так само автоматично прибирається з settings.json.
  *
  * Опт-аут — `claude-config: false` у `.n-cursor.json`.
  */
 import { existsSync } from 'node:fs'
-import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import { chmod, mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
-/** Маркер у command нашого managed-hook'а — за ним відрізняємо свої записи від користувацьких */
+/** Маркер lint Stop-hook'а (`npx --no @nitra/cursor stop-hook`). */
 export const MANAGED_HOOK_COMMAND_MARKER = '@nitra/cursor stop-hook'
+/** Маркер ADR Stop-hook'а — підрядок шляху до bash-скрипта. */
+export const ADR_HOOK_COMMAND_MARKER = '.claude/hooks/capture-decisions.sh'
+/** Усі маркери managed-hook'ів пакета — за ними відрізняємо свої записи від користувацьких. */
+export const MANAGED_HOOK_COMMAND_MARKERS = Object.freeze([MANAGED_HOOK_COMMAND_MARKER, ADR_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 NPM_CLAUDE_MD_FILE = 'npm/CLAUDE.md'
 const TEMPLATE_DIR_NAME = '.claude-template'
 
+/** Канонічна група hooks для ADR Stop-hook'а — додається в settings, коли `adr` у `rules`. */
+const ADR_STOP_HOOK_GROUP = Object.freeze({
+  matcher: '',
+  hooks: Object.freeze([
+    Object.freeze({
+      type: 'command',
+      command: `bash "$CLAUDE_PROJECT_DIR/${ADR_HOOK_COMMAND_MARKER}"`,
+      async: true,
+      timeout: 180
+    })
+  ])
+})
+
 /**
  * @typedef {object} HookEntry
  * @property {string} type тип hook'а у форматі Claude Code (зазвичай `'command'`)
@@ -46,15 +69,17 @@ const TEMPLATE_DIR_NAME = '.claude-template'
  */
 
 /**
- * Чи hook-група містить лише наші managed-команди (за маркером).
+ * Чи hook-група містить лише наші managed-команди (за будь-яким із маркерів пакета).
  * @param {HookGroup} group hook-група з .claude/settings.json
- * @returns {boolean} `true`, якщо всі hooks мають маркер `MANAGED_HOOK_COMMAND_MARKER`
+ * @returns {boolean} `true`, якщо всі hooks мають маркер з `MANAGED_HOOK_COMMAND_MARKERS`
  */
 function isManagedHookGroup(group) {
   if (!group?.hooks?.length) {
     return false
   }
-  return group.hooks.every(h => typeof h?.command === 'string' && h.command.includes(MANAGED_HOOK_COMMAND_MARKER))
+  return group.hooks.every(
+    h => typeof h?.command === 'string' && MANAGED_HOOK_COMMAND_MARKERS.some(marker => h.command.includes(marker))
+  )
 }
 
 /**
@@ -103,20 +128,39 @@ export function mergeHooks(existing, fromTemplate) {
   return out
 }
 
+/**
+ * Будує копію темплейту із додатковою ADR Stop hook-групою у `Stop`.
+ * Темплейт залишається незмінним; повертається новий об'єкт з доданою групою.
+ * @param {ClaudeSettings} template вихідний темплейт із `.claude-template/settings.template.json`
+ * @returns {ClaudeSettings} копія з доданою ADR-групою у `hooks.Stop`
+ */
+function templateWithAdrHook(template) {
+  /** @type {Record<string, HookGroup[]>} */
+  const hooks = {}
+  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)]
+  return { ...template, hooks }
+}
+
 /**
  * Повертає об'єднаний об'єкт settings.json.
  * @param {ClaudeSettings | undefined} existing існуючий вміст `.claude/settings.json` користувача (або undefined, якщо файла нема)
  * @param {ClaudeSettings} template settings із темплейту пакета `@nitra/cursor`
+ * @param {object} [options] опції merge-у
+ * @param {boolean} [options.includeAdrHook] чи додати ADR Stop-hook групу до managed-hooks (коли в `.n-cursor.json` `rules` присутнє `adr`)
  * @returns {ClaudeSettings} результат merge-у (користувацькі поля збережено, наші перевизначено)
  */
-export function mergeSettings(existing, template) {
+export function mergeSettings(existing, template, options = {}) {
+  const effectiveTemplate = options.includeAdrHook ? templateWithAdrHook(template) : template
   /** @type {ClaudeSettings} */
   const merged = { ...existing }
-  const mergedAllow = mergeAllowList(existing?.permissions?.allow, template.permissions?.allow)
+  const mergedAllow = mergeAllowList(existing?.permissions?.allow, effectiveTemplate.permissions?.allow)
   if (mergedAllow.length > 0) {
     merged.permissions = { ...existing?.permissions, allow: mergedAllow }
   }
-  const mergedHooks = mergeHooks(existing?.hooks, template.hooks)
+  const mergedHooks = mergeHooks(existing?.hooks, effectiveTemplate.hooks)
   if (Object.keys(mergedHooks).length > 0) {
     merged.hooks = mergedHooks
   } else {
@@ -146,9 +190,11 @@ async function readJsonOrUndefined(path) {
  * користувацьких полів.
  * @param {string} projectRoot корінь проєкту, куди писати
  * @param {string} templateDir каталог `.claude-template/` усередині пакету
+ * @param {object} [options] опції merge-у
+ * @param {boolean} [options.includeAdrHook] чи додавати ADR Stop-hook (правило `adr` увімкнене у `rules`)
  * @returns {Promise<{ written: boolean, path: string }>} результат: чи писали файл, та його відносний шлях
  */
-export async function syncClaudeSettings(projectRoot, templateDir) {
+export async function syncClaudeSettings(projectRoot, templateDir, options = {}) {
   const templatePath = join(templateDir, 'settings.template.json')
   if (!existsSync(templatePath)) {
     return { written: false, path: '' }
@@ -156,12 +202,33 @@ export async function syncClaudeSettings(projectRoot, templateDir) {
   const template = /** @type {ClaudeSettings} */ (JSON.parse(await readFile(templatePath, 'utf8')))
   const settingsPath = join(projectRoot, CLAUDE_SETTINGS_FILE)
   const existing = await readJsonOrUndefined(settingsPath)
-  const merged = mergeSettings(existing, template)
+  const merged = mergeSettings(existing, template, options)
   await mkdir(join(projectRoot, CLAUDE_DIR), { recursive: true })
   await writeFile(settingsPath, `${JSON.stringify(merged, null, 2)}\n`, 'utf8')
   return { written: true, path: CLAUDE_SETTINGS_FILE }
 }
 
+/**
+ * Копіює канонічний `.claude/hooks/capture-decisions.sh` з темплейту пакета.
+ * Файл повністю керується пакетом — на кожен sync перезаписується (як setup-bun-deps).
+ * @param {string} projectRoot корінь проєкту, куди писати
+ * @param {string} templateDir каталог `.claude-template/` усередині пакету
+ * @returns {Promise<{ written: boolean, path: string }>} результат: чи писали файл, та його відносний шлях
+ */
+export async function syncAdrHookScript(projectRoot, templateDir) {
+  const templatePath = join(templateDir, 'hooks', ADR_HOOK_SCRIPT_NAME)
+  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)
+  await writeFile(destPath, content, 'utf8')
+  await chmod(destPath, 0o755)
+  return { written: true, path: `${CLAUDE_HOOKS_DIR}/${ADR_HOOK_SCRIPT_NAME}` }
+}
+
 /**
  * Копіює `npm/CLAUDE.md` з темплейту, якщо в проєкті є каталог `npm/`.
  * @param {string} projectRoot корінь проєкту, куди писати
@@ -215,18 +282,21 @@ export async function syncClaudeCommands(projectRoot, templateDir) {
  * @param {string} options.projectRoot корінь проєкту-споживача
  * @param {string} options.bundledPackageRoot корінь установленого `@nitra/cursor`
  * @param {boolean} options.enabled чи увімкнено sync (з `.n-cursor.json` `claude-config`)
- * @returns {Promise<{ settings: boolean, npmClaudeMd: boolean, commands: string[] }>} прапорці записів settings/CLAUDE.md та список записаних slash-команд
+ * @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-команд
  */
-export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enabled }) {
+export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enabled, rules = [] }) {
   if (!enabled) {
-    return { settings: false, npmClaudeMd: false, commands: [] }
+    return { settings: false, npmClaudeMd: false, commands: [], adrHook: false }
   }
   const templateDir = join(bundledPackageRoot, TEMPLATE_DIR_NAME)
   if (!existsSync(templateDir)) {
-    return { settings: false, npmClaudeMd: false, commands: [] }
+    return { settings: false, npmClaudeMd: false, commands: [], adrHook: false }
   }
-  const settings = await syncClaudeSettings(projectRoot, templateDir)
+  const includeAdrHook = Array.isArray(rules) && rules.includes('adr')
+  const adrHook = includeAdrHook ? await syncAdrHookScript(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 }
+  return { settings: settings.written, npmClaudeMd: npmClaudeMd.written, commands, adrHook: adrHook.written }
 }