@nitra/cursor 1.8.185 → 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,48 @@
 
 Формат — [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
+
+- `vue` (mdc v1.6 → v1.7): для Volar/асетів канонічно лише **`jsconfig.json`** у корені пакета — прибрано альтернативу з `tsconfig.json`. `check-vue.mjs`: перевіряється лише наявність `jsconfig.json`.
+
+## [1.8.187] - 2026-05-07
+
+### Added
+
+- `check-vue.mjs`: перевірка `src/vite-env.d.ts` з `/// <reference types="vite/client" />` та наявності `jsconfig.json` або `tsconfig.json` у корені кожного Vue-пакета (типи для імпортів асетів у `.vue`).
+
+### Changed
+
+- `vue` (mdc v1.5 → v1.6): секція **«Vite client types (Volar, імпорти асетів)»** — обов’язкові `vite-env.d.ts`, jsconfig/tsconfig; застереження щодо вузького `compilerOptions.types`. Оновлено блок **«Перевірка»**.
+
+## [1.8.186] - 2026-05-07
+
+### Added
+
+- `check-js-run.mjs` + `scripts/utils/promise-settimeout-scan.mjs`: програмна перевірка нової секції js-run «Паузи через setTimeout». AST-сканер на `oxc-parser` ловить `new Promise(resolve => setTimeout(resolve, ms))` (з `await` чи без, arrow та function expression, concise та block body, тривіально загорнутий callback `() => resolve()`). Паттерни з передачею значення (`r => setTimeout(() => r(value), ms)`), іншим callback-ом замість resolve, або з додатковими стейтментами в блоці — поза правилом (це не «чиста» пауза).
+- `tests/promise-settimeout-scan.test.mjs`: 13 модульних тестів (await/без, block-body, function expression, обгорнутий callback, false-positive guards, multiline номер рядка, кілька входжень, фільтр розширень).
+- `tests/check-js-run-fixture.test.mjs`: 2 інтеграційні кейси на `check()` — fail при `await new Promise(r => setTimeout(r, ms))` у workspace-пакеті, pass при `await setTimeout(ms)` з `node:timers/promises`.
+
+### Changed
+
+- `js-run` (mdc v1.3 → v1.4): додано секцію **«Паузи через setTimeout»** — заборонено `await new Promise(resolve => setTimeout(resolve, ms))`, замість цього треба `await setTimeout(ms)` з `node:timers/promises`. Зауваження про затінення глобального `setTimeout` у тому ж файлі (за потреби callback-варіант імпортувати під іншим іменем, наприклад `setTimeoutCb` з `node:timers`).
+
 ## [1.8.185] - 2026-05-06
 
 ### 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/mdc/js-run.mdc

@@ -1,7 +1,7 @@
 ---
 description: Це правила для backend проектів на JavaScript/Node.js, сюди входять і job і WEB сервери.
 alwaysApply: true
-version: '1.3'
+version: '1.4'
 ---
 
 ## Область застосування
@@ -136,6 +136,18 @@ console.log(env.OPTIONAL_ENV_VAR)
 `// @nitra/cursor ignore-next-line checkEnv` безпосередньо перед використанням
 (escape-hatch для legacy-коду, не для нових файлів).
 
+## Паузи через setTimeout
+
+Заборонено робити паузи через `await new Promise(resolve => setTimeout(resolve, ms))` — таку обгортку треба замінити на promise-варіант `setTimeout` з `node:timers/promises`:
+
+```javascript title="Замість new Promise + setTimeout"
+import { setTimeout } from 'node:timers/promises'
+
+await setTimeout(500)
+```
+
+Імпорт `setTimeout` з `node:timers/promises` затіняє глобальний таймер у файлі — якщо в тому ж файлі потрібен callback-варіант, імпортуй його під іншим іменем (наприклад, `import { setTimeout as setTimeoutCb } from 'node:timers'`).
+
 ## depcheck у GitHub Actions з path-фільтром
 
 Якщо в `.github/workflows/*.yml` є тригер з `paths:`, який обмежує запуск workflow змінами в каталозі конкретного backend-пакета, в job цього workflow має бути крок `npx depcheck` з `working-directory`, який вказує на той самий каталог пакета. Це гарантує, що декларація залежностей у `package.json` пакета відповідає реальним імпортам — інакше можна випадково зламати білд після видалення «зайвої» залежності, яка насправді використовується через побічний імпорт.

package/mdc/vue.mdc

@@ -1,7 +1,7 @@
 ---
 description: Vue
 alwaysApply: true
-version: '1.5'
+version: '1.7'
 ---
 
 # Vue 3 Composition API — правила для .cursorrules
@@ -208,6 +208,45 @@ export default defineConfig({
 })
 ```
 
+## Vite client types (Volar, імпорти асетів)
+
+Без типів **Vite** редактор (Volar / TypeScript) не знає, що імпорт статичного файлу (`import url from './hero.avif'`, `*.png`, `*.svg` тощо) відповідає модулю з `string` URL. Тоді у `.vue` з’являється помилка на кшталт **Cannot find module '…' or its corresponding type declarations**.
+
+У **кожному** workspace-пакеті з **Vue + Vite** обов’язково:
+
+1. **`src/vite-env.d.ts`** — рівно з посиланням на клієнтські типи Vite (одного рядка достатньо):
+
+```ts title="src/vite-env.d.ts"
+/// <reference types="vite/client" />
+```
+
+Так підтягуються декларації з `vite/client.d.ts` (`declare module '*.avif'`, `*.png`, …).
+
+2. **Корінь пакета:** **`jsconfig.json`** із **`include`**, що охоплює `src` (наприклад `"include": ["src/**/*"]`), щоб мова служби бачила `vite-env.d.ts` і SFC.
+
+Мінімальний приклад для JS-пакета:
+
+```json title="jsconfig.json"
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "jsx": "preserve",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "allowJs": true
+  },
+  "include": ["src/**/*"]
+}
+```
+
+**Не** звужуй без потреби **`compilerOptions.types`** до `["vite/client"]`: це може відрізати інші пакети з `@types` і зламати інші підказки. Достатньо `/// <reference types="vite/client" />` у `vite-env.d.ts` і коректного `include`.
+
 ## Тести
 
 Проекту повинен бути покритий тестами E2E за допомогою Playwright.
@@ -287,4 +326,4 @@ import path from 'node:path'
 
 ## Перевірка
 
-`npx @nitra/cursor check vue` — перевіряє залежності, `vite.config`, а також обходить джерела Vue-пакета (`.vue`, `.ts`, `.js` тощо) на заборонені value-імпорти з модуля `vue` (дозволені лише type-only та side-effect `import 'vue'`) і додатково сканує `.vue` SFC на імпорти Node-нативних модулів (`node:*` префікс або bare-ім’я вбудованого модуля Node — `fs`, `path`, `timers/promises` тощо). Імпорти аналізуються через **oxc-parser** (`module.staticImports`); для `.vue` вміст `<script>` витягується з SFC, далі той самий парсер (логіка в `npm/scripts/utils/vue-forbidden-imports.mjs`).
+`npx @nitra/cursor check vue` — перевіряє залежності, `vite.config`, наявність **`src/vite-env.d.ts`** з `/// <reference types="vite/client" />` та **`jsconfig.json`** у корені Vue-пакета; обходить джерела Vue-пакета (`.vue`, `.ts`, `.js` тощо) на заборонені value-імпорти з модуля `vue` (дозволені лише type-only та side-effect `import 'vue'`) і додатково сканує `.vue` SFC на імпорти Node-нативних модулів (`node:*` префікс або bare-ім’я вбудованого модуля Node — `fs`, `path`, `timers/promises` тощо). Імпорти аналізуються через **oxc-parser** (`module.staticImports`); для `.vue` вміст `<script>` витягується з SFC, далі той самий парсер (логіка в `npm/scripts/utils/vue-forbidden-imports.mjs`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.185",
+  "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/check-js-run.mjs

@@ -21,7 +21,10 @@
  *  - «depcheck у GitHub Actions з path-фільтром»: для кожного workflow з `paths:`,
  *    обмеженим каталогом цього пакета (`<rootDir>/...`), має бути крок
  *    `npx depcheck --ignores="graphql,bun"` (плюс інші, за потреби) з
- *    `working-directory: <rootDir>` (див. `utils/depcheck-workflow.mjs`).
+ *    `working-directory: <rootDir>` (див. `utils/depcheck-workflow.mjs`);
+ *  - «Паузи через setTimeout»: `new Promise(resolve => setTimeout(resolve, ms))` (з/без `await`)
+ *    треба замінити на `await setTimeout(ms)` з `node:timers/promises`
+ *    (див. `utils/promise-settimeout-scan.mjs`).
  */
 import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
@@ -42,6 +45,10 @@ import {
   resolveConnDirFromPackageJson
 } from './utils/conn-imports-scan.mjs'
 import { loadCursorIgnorePaths } from './utils/load-cursor-config.mjs'
+import {
+  findPromiseSetTimeoutInText,
+  isPromiseSetTimeoutScanSourceFile
+} from './utils/promise-settimeout-scan.mjs'
 import { walkDir } from './utils/walkDir.mjs'
 import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
 
@@ -162,6 +169,30 @@ async function checkProcessEnvUsage(absPackageRoot, sourcePaths, label, fail) {
   return violations
 }
 
+/**
+ * Сканує джерела пакета на паттерн `new Promise(resolve => setTimeout(resolve, ms))`.
+ * @param {string} absPackageRoot абсолютний корінь пакета
+ * @param {string[]} sourcePaths абсолютні шляхи до файлів
+ * @param {string} label префікс повідомлення `[<pkg>] `
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<number>} кількість порушень
+ */
+async function checkPromiseSetTimeoutPause(absPackageRoot, sourcePaths, label, fail) {
+  let violations = 0
+  for (const absPath of sourcePaths) {
+    const rel = relPosix(absPackageRoot, absPath)
+    if (!isPromiseSetTimeoutScanSourceFile(rel)) continue
+    const content = await readFile(absPath, 'utf8')
+    for (const v of findPromiseSetTimeoutInText(content, rel)) {
+      violations++
+      fail(
+        `${label}${rel}:${v.line} — заміни 'new Promise(r => setTimeout(r, ms))' на 'await setTimeout(ms)' з 'node:timers/promises': ${v.snippet}`
+      )
+    }
+  }
+  return violations
+}
+
 /**
  * Перевіряє відповідність правилам js-run.mdc для одного workspace-пакета.
  * @param {string} rootDir відносний шлях workspace (не `'.'`)
@@ -205,6 +236,11 @@ async function checkWorkspacePackage(rootDir, ignorePaths, workflows, fail, pass
     )
   }
 
+  const pauseViolations = await checkPromiseSetTimeoutPause(absPackageRoot, sourcePaths, label, fail)
+  if (pauseViolations === 0) {
+    passFn(`${label}немає 'new Promise(r => setTimeout(r, ms))' — паузи через 'node:timers/promises'`)
+  }
+
   await checkOtelConfigmap(rootDir, label, fail, passFn)
 
   checkDepcheckInWorkflows(rootDir, workflows, label, fail, passFn)

package/scripts/check-vue.mjs

@@ -4,6 +4,9 @@
  * Версії Vite та плагінів, vue-macros, auto-import, layouts, вміст `vite.config`;
  * у репозиторії — рекомендацію розширення Vue.volar.
  *
+ * У кожному Vue+Vite-пакеті очікується `src/vite-env.d.ts` з `/// <reference types="vite/client" />`
+ * та `jsconfig.json` у корені пакета (типи для імпортів асетів у `.vue`).
+ *
  * У `vite.config.*` заборонено використовувати `process.env.npm_lifecycle_event` (Bun не підставляє його як npm),
  * натомість використовуй `mode` з `defineConfig(({ mode }) => ...)`.
  *
@@ -32,6 +35,9 @@ import { getMonorepoPackageRootDirs } from './utils/workspaces.mjs'
 const MAJOR_VERSION_RE = /(\d+)/
 const ESBUILD_RE = /\besbuild\b/
 
+/** Регулярний вираз для triple-slash `reference types="vite/client"` у `src/vite-env.d.ts`. */
+const VITE_CLIENT_REFERENCE_RE = /\/\/\/\s*<reference\s+types\s*=\s*["']vite\/client["']\s*\/>/
+
 /**
  * Визначає, чи можна сканувати файл як текст на згадки `esbuild`.
  * @param {string} relPosix відносний шлях у posix-форматі
@@ -202,6 +208,43 @@ function checkRequiredDep(deps, name, prefix, passFn, fail, hint = `${name} ві
  * @param {(msg: string) => void} passFn callback при успішній перевірці
  * @param {(msg: string) => void} fail callback при помилці
  */
+/**
+ * Перевіряє `src/vite-env.d.ts` і наявність `jsconfig.json` для підтягування типів асетів Vite у IDE.
+ * @param {string} rootDir відносний шлях до кореня пакета
+ * @param {string} prefix префікс повідомлень
+ * @param {(msg: string) => void} passFn успіх
+ * @param {(msg: string) => void} fail помилка
+ * @returns {Promise<void>}
+ */
+async function checkViteClientEnvAndEditorConfig(rootDir, prefix, passFn, fail) {
+  const envRel = join(rootDir, 'src/vite-env.d.ts')
+  if (!existsSync(envRel)) {
+    fail(
+      `${prefix}немає src/vite-env.d.ts — додай файл з рядком /// <reference types="vite/client" /> ` +
+        `(інакше TS/Volar не бачать типів для імпортів асетів: png, avif, css як URL).`
+    )
+    return
+  }
+  const envContent = await readFile(envRel, 'utf8')
+  if (!VITE_CLIENT_REFERENCE_RE.test(envContent)) {
+    fail(
+      `${prefix}src/vite-env.d.ts має містити /// <reference types="vite/client" /> ` +
+        `(без цього імпорти статичних файлів у .vue дають «Cannot find module … type declarations»).`
+    )
+    return
+  }
+  passFn(`${prefix}src/vite-env.d.ts посилається на vite/client`)
+
+  if (!existsSync(join(rootDir, 'jsconfig.json'))) {
+    fail(
+      `${prefix}немає jsconfig.json у корені пакета — додай файл з "include": ["src/**/*"] тощо, ` +
+        `щоб IDE підхопила vite-env.d.ts і .vue.`
+    )
+    return
+  }
+  passFn(`${prefix}jsconfig.json присутній`)
+}
+
 function checkViteVersion(devDeps, prefix, passFn, fail) {
   const v = devDeps.vite
   if (!v) {
@@ -442,6 +485,8 @@ async function checkVuePackage(rootDir, ignorePaths, fail, passFn) {
     'vite-plugin-vue-layouts-next відсутній — bun add -d vite-plugin-vue-layouts-next'
   )
 
+  await checkViteClientEnvAndEditorConfig(rootDir, prefix, passFn, fail)
+
   const { hasVueAutoImport } = await checkViteConfig(rootDir, prefix, passFn, fail)
   await checkVueImportViolations(
     rootDir,

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

package/scripts/utils/promise-settimeout-scan.mjs

@@ -0,0 +1,129 @@
+/**
+ * Знаходить паттерн `new Promise(resolve => setTimeout(resolve, ms))` (з `await` чи без)
+ * у джерелах — таку обгортку треба замінити на `setTimeout` з `node:timers/promises`
+ * згідно з js-run.mdc, секція «Паузи через setTimeout».
+ *
+ * Семантика — структурна (без regex по тілу): `NewExpression` з ідентифікатор-callee `Promise`
+ * і єдиним аргументом-функцією, тіло якої — виклик `setTimeout(<resolve>, ms)`. Перший
+ * аргумент `setTimeout` має передавати `resolve` напряму або тривіально загорнутим у
+ * безпараметричну функцію `() => resolve()` / `function () { resolve() }` без жодних
+ * аргументів — інакше це не «чиста пауза», і паттерн не вмикається.
+ *
+ * Сканер не вимагає, щоб файл компілювався: при синтаксичних помилках повертається
+ * порожній результат (як інші сканери — спочатку треба полагодити синтаксис).
+ */
+import { normalizeSnippet, offsetToLine, parseProgramOrNull } from './ast-scan-utils.mjs'
+
+const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/
+
+/**
+ * Чи аргумент, який передають у `setTimeout`, — це «голий» виклик `resolve`
+ * (тобто сам ідентифікатор або `() => resolve()` без аргументів).
+ * @param {Record<string, unknown> | null | undefined} arg AST-вузол першого аргументу `setTimeout`
+ * @param {string} paramName ім'я параметра-resolve у тіла-функції Promise
+ * @returns {boolean} `true`, якщо це чиста передача resolve без значення
+ */
+function isBareResolveCallback(arg, paramName) {
+  if (!arg || typeof arg !== 'object') return false
+  if (arg.type === 'Identifier' && arg.name === paramName) return true
+  if (arg.type !== 'ArrowFunctionExpression' && arg.type !== 'FunctionExpression') return false
+  if ((arg.params?.length ?? 0) !== 0) return false
+  const callExpr = extractSingleCallExpression(arg.body)
+  if (!callExpr) return false
+  if (callExpr.callee?.type !== 'Identifier' || callExpr.callee.name !== paramName) return false
+  return !Array.isArray(callExpr.arguments) || callExpr.arguments.length === 0
+}
+
+/**
+ * Якщо тіло функції — рівно один `CallExpression` (концизне `() => foo()` або
+ * `{ foo() }` без інших стейтментів), повертає його. Інакше — `null`.
+ * @param {unknown} body тіло функції з AST
+ * @returns {Record<string, unknown> | null} AST-вузол `CallExpression` або `null`
+ */
+function extractSingleCallExpression(body) {
+  if (!body || typeof body !== 'object') return null
+  if (body.type === 'CallExpression') return body
+  if (body.type !== 'BlockStatement') return null
+  if (!Array.isArray(body.body) || body.body.length !== 1) return null
+  const stmt = body.body[0]
+  if (!stmt || stmt.type !== 'ExpressionStatement') return null
+  const expr = stmt.expression
+  return expr?.type === 'CallExpression' ? expr : null
+}
+
+/**
+ * Чи це `NewExpression` виду `new Promise(<resolve> => setTimeout(<resolve>, ms))`.
+ * Параметр-resolve має бути простим Identifier; setTimeout — глобальним викликом
+ * за іменем (з будь-якого джерела — node:timers, global, тощо: значення для нас має
+ * лише структурний паттерн).
+ * @param {Record<string, unknown> | null | undefined} node AST-вузол
+ * @returns {boolean} `true`, якщо це проблемний паттерн «обгортки таймера у Promise»
+ */
+function isPromiseSetTimeoutDelay(node) {
+  if (!node || node.type !== 'NewExpression') return false
+  if (node.callee?.type !== 'Identifier' || node.callee.name !== 'Promise') return false
+  if (!Array.isArray(node.arguments) || node.arguments.length !== 1) return false
+  const fn = node.arguments[0]
+  if (!fn || (fn.type !== 'ArrowFunctionExpression' && fn.type !== 'FunctionExpression')) return false
+  if (!Array.isArray(fn.params) || fn.params.length === 0) return false
+  const firstParam = fn.params[0]
+  if (!firstParam || firstParam.type !== 'Identifier') return false
+  const setTimeoutCall = extractSingleCallExpression(fn.body)
+  if (!setTimeoutCall) return false
+  if (setTimeoutCall.callee?.type !== 'Identifier' || setTimeoutCall.callee.name !== 'setTimeout') return false
+  if (!Array.isArray(setTimeoutCall.arguments) || setTimeoutCall.arguments.length < 1) return false
+  return isBareResolveCallback(setTimeoutCall.arguments[0], firstParam.name)
+}
+
+/**
+ * Простий рекурсивний обхід AST: заходимо в усі об'єкти/масиви, щоб знайти `NewExpression`.
+ * @param {unknown} node корінь або під-вузол AST
+ * @param {(n: Record<string, unknown>) => void} visit виклик для кожного об'єкта-вузла з `type`
+ * @returns {void}
+ */
+function walkAst(node, visit) {
+  if (!node || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (const item of node) walkAst(item, visit)
+    return
+  }
+  if (typeof node.type === 'string') {
+    visit(node)
+  }
+  for (const key of Object.keys(node)) {
+    if (key === 'parent') continue
+    const v = node[key]
+    if (v && typeof v === 'object') walkAst(v, visit)
+  }
+}
+
+/**
+ * Знаходить усі `new Promise(resolve => setTimeout(resolve, ms))` у тексті.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang` (наприклад `pkg/src/foo.ts`)
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findPromiseSetTimeoutInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  walkAst(program, node => {
+    if (!isPromiseSetTimeoutDelay(node)) return
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, node.end))
+    })
+  })
+  return out
+}
+
+/**
+ * Чи сканувати цей файл за розширенням (JS/TS-сім'я, виключно з `.d.ts`).
+ * @param {string} relativePath відносний шлях до файлу
+ * @returns {boolean} `true`, якщо розширення підходить для сканування
+ */
+export function isPromiseSetTimeoutScanSourceFile(relativePath) {
+  if (!SOURCE_FILE_RE.test(relativePath)) return false
+  return !relativePath.endsWith('.d.ts')
+}