@nitra/cursor 1.9.23 → 1.10.0

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

@@ -22,10 +22,10 @@ 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"
+ADR_DIR="$PROJECT_ROOT/docs/adr"
 LOG_DIR="$PROJECT_ROOT/.claude/hooks"
 LOG="$LOG_DIR/capture-decisions.log"
-mkdir -p "$INBOX" "$LOG_DIR"
+mkdir -p "$ADR_DIR" "$LOG_DIR"
 
 log() { printf '%s %s\n' "$(date -Iseconds)" "$*" >> "$LOG"; }
 
@@ -145,7 +145,7 @@ if ! printf '%s' "$RESPONSE_TRIMMED" | grep -q '^## '; then
 fi
 
 TS=$(date +%Y%m%d-%H%M%S)
-OUT="$INBOX/$TS-${SESSION_ID:0:8}.md"
+OUT="$ADR_DIR/$TS-${SESSION_ID:0:8}.md"
 {
   printf -- '---\nsession: %s\ncaptured: %s\ntranscript: %s\n---\n\n' \
     "$SESSION_ID" "$(date -Iseconds)" "$TRANSCRIPT_PATH"

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

@@ -0,0 +1,370 @@
+#!/usr/bin/env bash
+# Stop hook: normalize ADR drafts in docs/adr/ via LLM.
+#
+# Triggers when number of draft files (with `session:` in YAML frontmatter)
+# reaches ADR_NORMALIZE_THRESHOLD (default 30). Asks LLM to return a JSON list
+# of operations (rewrite / delete / merge-into) and applies them to the working
+# tree. Never invokes git — developer reviews via `git status` / `git diff`.
+#
+# LLM CLI selection (first available wins):
+#   1. claude        — `claude -p --model "$ADR_NORMALIZE_MODEL"` (default: sonnet)
+#   2. cursor-agent  — `cursor-agent -p --mode ask --output-format text --model …`
+#                      (default: claude-4.6-sonnet-medium)
+#   neither          — exit 0 silently
+#
+# Portable bash 3.2 (macOS /bin/bash): no `mapfile`, no associative arrays.
+#
+# Bundled with @nitra/cursor; project copy is auto-synced by the `adr` rule.
+set -eu
+set -o pipefail
+
+if [ -n "${ADR_NORMALIZE_RUNNING:-}" ]; then
+  exit 0
+fi
+export ADR_NORMALIZE_RUNNING=1
+
+PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+ADR_DIR="$PROJECT_ROOT/docs/adr"
+LOG_DIR="$PROJECT_ROOT/.claude/hooks"
+LOG="$LOG_DIR/normalize-decisions.log"
+STATE_FILE="$LOG_DIR/.normalize-state"
+LOCK_FILE="$LOG_DIR/.normalize.lock"
+mkdir -p "$LOG_DIR"
+
+log() { printf '%s %s\n' "$(date -Iseconds)" "$*" >> "$LOG"; }
+
+# Skip if repo is mid-rebase / mid-merge — editing files now would tangle the user.
+if [ -d "$PROJECT_ROOT/.git" ]; then
+  for marker in MERGE_HEAD CHERRY_PICK_HEAD REVERT_HEAD rebase-apply rebase-merge; do
+    if [ -e "$PROJECT_ROOT/.git/$marker" ]; then
+      log "skip: git is mid-$marker"
+      exit 0
+    fi
+  done
+fi
+
+if [ ! -d "$ADR_DIR" ]; then
+  exit 0
+fi
+
+# Acquire lock if `flock` is available (Linux). macOS lacks flock by default —
+# treat absence as "no concurrent runs expected" and skip locking.
+if command -v flock >/dev/null 2>&1; then
+  exec 9>"$LOCK_FILE"
+  if ! flock -n 9; then
+    log "skip: another normalize run holds the lock"
+    exit 0
+  fi
+fi
+
+# Min interval between attempts — when LLM returns nothing for the batch, do not
+# spin on every Stop event. Default 6 hours.
+MIN_INTERVAL_HOURS="${ADR_NORMALIZE_MIN_INTERVAL_HOURS:-6}"
+if [ -f "$STATE_FILE" ]; then
+  LAST_ATTEMPT=$(cat "$STATE_FILE" 2>/dev/null || printf '0')
+  NOW=$(date +%s)
+  ELAPSED=$(( NOW - LAST_ATTEMPT ))
+  MIN_SECS=$(( MIN_INTERVAL_HOURS * 3600 ))
+  if [ "$ELAPSED" -lt "$MIN_SECS" ]; then
+    log "skip: only $ELAPSED s since last attempt (min ${MIN_SECS}s)"
+    exit 0
+  fi
+fi
+
+THRESHOLD="${ADR_NORMALIZE_THRESHOLD:-30}"
+BATCH_SIZE="${ADR_NORMALIZE_BATCH:-30}"
+DRY_RUN="${ADR_NORMALIZE_DRY:-0}"
+
+# Detects whether a markdown file is a draft: has YAML frontmatter with `session:` field.
+is_draft() {
+  awk '
+    NR==1 && /^---$/ { fm=1; next }
+    fm && /^---$/    { exit }
+    fm && /^session: / { found=1 }
+    END              { exit !found }
+  ' "$1" 2>/dev/null
+}
+
+TMP_DIR=$(mktemp -d "${TMPDIR:-/tmp}/adr-normalize.XXXXXX")
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+DRAFTS_LIST="$TMP_DIR/drafts.txt"
+CLEAN_LIST="$TMP_DIR/clean.txt"
+BATCH_LIST="$TMP_DIR/batch.txt"
+CLAIMED_SLUGS="$TMP_DIR/claimed.txt"
+: > "$DRAFTS_LIST"
+: > "$CLEAN_LIST"
+: > "$CLAIMED_SLUGS"
+
+# Find all draft files (recursive) under docs/adr/.
+find "$ADR_DIR" -type f -name '*.md' 2>/dev/null | while IFS= read -r f; do
+  if is_draft "$f"; then
+    printf '%s\n' "$f"
+  fi
+done | sort > "$DRAFTS_LIST"
+
+DRAFT_COUNT=$(wc -l < "$DRAFTS_LIST" | tr -d ' ')
+log "drafts found: $DRAFT_COUNT (threshold: $THRESHOLD)"
+
+if [ "$DRAFT_COUNT" -lt "$THRESHOLD" ]; then
+  exit 0
+fi
+
+head -n "$BATCH_SIZE" "$DRAFTS_LIST" > "$BATCH_LIST"
+BATCH_COUNT=$(wc -l < "$BATCH_LIST" | tr -d ' ')
+log "batch size: $BATCH_COUNT"
+
+# Find clean ADR files at root of docs/adr/ (no `session:`).
+find "$ADR_DIR" -maxdepth 1 -type f -name '*.md' 2>/dev/null | while IFS= read -r f; do
+  if ! is_draft "$f"; then
+    basename "$f"
+  fi
+done | sort > "$CLEAN_LIST"
+
+# Build prompt input section.
+INPUT_FILE="$TMP_DIR/input.md"
+{
+  i=0
+  while IFS= read -r f; do
+    i=$(( i + 1 ))
+    idx=$(printf '%03d' "$i")
+    rel="${f#"$ADR_DIR/"}"
+    printf '\n[DRAFT-%s] %s\n' "$idx" "$rel"
+    cat "$f"
+    printf '\n[END DRAFT-%s]\n' "$idx"
+  done < "$BATCH_LIST"
+} > "$INPUT_FILE"
+
+CLEAN_SECTION_FILE="$TMP_DIR/clean-section.md"
+: > "$CLEAN_SECTION_FILE"
+if [ -s "$CLEAN_LIST" ]; then
+  {
+    printf '\nClean ADR files already in docs/adr/ (potential merge-into targets):\n'
+    while IFS= read -r c; do
+      printf '%s\n' "- $c"
+    done < "$CLEAN_LIST"
+  } > "$CLEAN_SECTION_FILE"
+fi
+
+PROMPT_HEADER=$(cat <<'EOF'
+Ти нормалізуєш чернетки ADR/Runbook/Knowledge у `docs/adr/` репозиторію. Для кожного драфта обери одну з трьох операцій і поверни ЛИШЕ JSON-обʼєкт без markdown-обгортки, без передмови.
+
+Схема відповіді:
+
+{
+  "operations": [
+    { "op": "delete",     "file": "<basename>.md", "reason": "..." },
+    { "op": "rewrite",    "file": "<basename>.md", "slug": "<kebab-case-ukrainian>", "content": "<повний markdown файлу>" },
+    { "op": "merge-into", "file": "<basename>.md", "target": "<slug>.md", "additions": "<markdown для дописування>" }
+  ]
+}
+
+Правила:
+
+1. `delete` — драфт тривіальний / повністю покритий іншим існуючим clean-ADR-ом / порожній. Поясни короткою причиною українською.
+
+2. `rewrite` — драфт має самостійну цінність. Повертай у `content` повний фінальний вміст файлу:
+   - Без YAML frontmatter (жодного `session:`, `captured:`, `transcript:`).
+   - Заголовок `# <Title>` українською.
+   - Один рядок `**Status:** Accepted` і один рядок `**Date:** YYYY-MM-DD` — дату беремо з поля `captured:` оригінальної чернетки (перші 10 символів ISO-дати).
+   - Далі розділи **Контекст**, **Рішення/Процедура/Факт**, **Обґрунтування**, **Розглянуті альтернативи**, **Зачіпає** — як у драфті, але причесані: цілісні речення, без скорочень, без слідів автогенерованого тегу типу `## Knowledge`.
+   - `slug` — kebab-case українською (наприклад `ланцюжок-запуску-abie`, `npm-publish-flow`). Без розширення `.md`. Літери малі, дозволено цифри, дефіс, кирилиця. Якщо тема технічна англійською (назва пакету, ключове слово) — лиши англійською без транслітерації.
+
+3. `merge-into` — драфт повторює тему вже існуючого clean-файлу зі списку нижче. `target` — точна назва файлу зі списку (з `.md`). `additions` — лише новий зміст, який варто дописати в кінець target-файлу під підзаголовком `## Update YYYY-MM-DD` (date з `captured` драфта). Якщо нічого нового додати — використовуй `delete`.
+
+Жорсткі обмеження:
+
+- Поверни валідний JSON, нічого крім нього. Жодних code-fence, жодних коментарів.
+- Кожен файл з вхідного списку має зʼявитися у `operations` рівно один раз.
+- Слаги не повторювати між операціями того самого батча. Якщо дві чернетки про одну тему — одна `rewrite`, інша `merge-into target: <slug>.md` з тим самим slug-ом.
+- Не вигадуй target, якого нема у списку clean-файлів.
+
+Вхідні драфти і clean-список — нижче.
+EOF
+)
+
+FULL_PROMPT_FILE="$TMP_DIR/prompt.md"
+{
+  printf '%s\n' "$PROMPT_HEADER"
+  cat "$CLEAN_SECTION_FILE"
+  printf '\n=== DRAFTS ===\n'
+  cat "$INPUT_FILE"
+} > "$FULL_PROMPT_FILE"
+
+# Update state BEFORE calling LLM — even if LLM fails, we honor min-interval.
+date +%s > "$STATE_FILE"
+
+CLAUDE_MODEL="${ADR_NORMALIZE_MODEL:-sonnet}"
+CURSOR_MODEL="${ADR_NORMALIZE_CURSOR_MODEL:-claude-4.6-sonnet-medium}"
+
+RESPONSE_FILE="$TMP_DIR/response.txt"
+
+if command -v claude >/dev/null 2>&1; then
+  log "using claude CLI (model: $CLAUDE_MODEL)"
+  claude -p --model "$CLAUDE_MODEL" < "$FULL_PROMPT_FILE" > "$RESPONSE_FILE" 2>>"$LOG" || true
+elif command -v cursor-agent >/dev/null 2>&1; then
+  log "using cursor-agent CLI (model: $CURSOR_MODEL)"
+  FULL_PROMPT=$(cat "$FULL_PROMPT_FILE")
+  cursor-agent -p --mode ask --output-format text --model "$CURSOR_MODEL" -- "$FULL_PROMPT" > "$RESPONSE_FILE" 2>>"$LOG" || true
+else
+  log "no LLM CLI found, skipping"
+  exit 0
+fi
+
+if [ ! -s "$RESPONSE_FILE" ]; then
+  log "empty LLM response"
+  exit 0
+fi
+
+# Strip markdown code-fence lines and surrounding blank lines.
+# Use awk to avoid backtick/end-anchor lint false positives in sed regex.
+RESPONSE_CLEAN_FILE="$TMP_DIR/response-clean.json"
+awk '
+  /^[[:space:]]*```/ { next }
+  started || /[^[:space:]]/ { started = 1; print }
+' "$RESPONSE_FILE" > "$RESPONSE_CLEAN_FILE"
+
+# Validate JSON.
+if ! jq -e '.operations | type == "array"' "$RESPONSE_CLEAN_FILE" >/dev/null 2>&1; then
+  HEAD200=$(head -c 200 "$RESPONSE_CLEAN_FILE" | tr '\n' ' ')
+  log "invalid JSON response (first 200 chars): $HEAD200"
+  exit 0
+fi
+
+OP_COUNT=$(jq '.operations | length' "$RESPONSE_CLEAN_FILE")
+log "operations parsed: $OP_COUNT"
+
+if [ "$DRY_RUN" = "1" ]; then
+  log "DRY RUN — would apply $OP_COUNT operations:"
+  jq -r '.operations[] | "  " + .op + " " + .file + (if .slug then " → " + .slug else "" end) + (if .target then " → " + .target else "" end)' \
+    "$RESPONSE_CLEAN_FILE" >> "$LOG"
+  exit 0
+fi
+
+# Resolve unique target path for slug — appends -2, -3 on collision.
+# Tracks claims via CLAIMED_SLUGS file (one slug per line).
+resolve_unique_slug_path() {
+  slug="$1"
+  base="$ADR_DIR/${slug}.md"
+  if [ ! -e "$base" ] && ! grep -Fxq "$slug" "$CLAIMED_SLUGS" 2>/dev/null; then
+    printf '%s\n' "$slug" >> "$CLAIMED_SLUGS"
+    printf '%s\n' "$base"
+    return
+  fi
+  n=2
+  while :; do
+    cand="$ADR_DIR/${slug}-${n}.md"
+    key="${slug}-${n}"
+    if [ ! -e "$cand" ] && ! grep -Fxq "$key" "$CLAIMED_SLUGS" 2>/dev/null; then
+      printf '%s\n' "$key" >> "$CLAIMED_SLUGS"
+      printf '%s\n' "$cand"
+      return
+    fi
+    n=$(( n + 1 ))
+  done
+}
+
+APPLIED=0
+SKIPPED=0
+
+jq -c '.operations[]' "$RESPONSE_CLEAN_FILE" | while IFS= read -r op_json; do
+  OP=$(printf '%s' "$op_json" | jq -r '.op // empty')
+  FILE=$(printf '%s' "$op_json" | jq -r '.file // empty')
+  SRC_PATH="$ADR_DIR/$FILE"
+
+  if [ -z "$OP" ] || [ -z "$FILE" ]; then
+    log "skip: malformed op (missing op/file)"
+    SKIPPED=$(( SKIPPED + 1 ))
+    continue
+  fi
+  case "$FILE" in
+    */*|.*)
+      log "skip: refusing path-like file '$FILE'"
+      SKIPPED=$(( SKIPPED + 1 ))
+      continue
+      ;;
+  esac
+
+  # Resolve nested batch files by basename if not at docs/adr/ root.
+  if [ ! -f "$SRC_PATH" ]; then
+    while IFS= read -r bf; do
+      bn=$(basename "$bf")
+      if [ "$bn" = "$FILE" ]; then
+        SRC_PATH="$bf"
+        break
+      fi
+    done < "$BATCH_LIST"
+  fi
+  if [ ! -f "$SRC_PATH" ]; then
+    log "skip: source missing '$FILE'"
+    SKIPPED=$(( SKIPPED + 1 ))
+    continue
+  fi
+
+  case "$OP" in
+    delete)
+      REASON=$(printf '%s' "$op_json" | jq -r '.reason // ""')
+      rm -- "$SRC_PATH"
+      log "delete: $FILE — $REASON"
+      APPLIED=$(( APPLIED + 1 ))
+      ;;
+    rewrite)
+      SLUG=$(printf '%s' "$op_json" | jq -r '.slug // empty')
+      CONTENT=$(printf '%s' "$op_json" | jq -r '.content // empty')
+      if [ -z "$SLUG" ] || [ -z "$CONTENT" ]; then
+        log "skip rewrite: missing slug or content for '$FILE'"
+        SKIPPED=$(( SKIPPED + 1 ))
+        continue
+      fi
+      case "$SLUG" in
+        */*|.*)
+          log "skip rewrite: refusing path-like slug '$SLUG'"
+          SKIPPED=$(( SKIPPED + 1 ))
+          continue
+          ;;
+      esac
+      DEST_PATH=$(resolve_unique_slug_path "$SLUG")
+      printf '%s\n' "$CONTENT" > "$DEST_PATH"
+      rm -- "$SRC_PATH"
+      log "rewrite: $FILE → $(basename "$DEST_PATH")"
+      APPLIED=$(( APPLIED + 1 ))
+      ;;
+    merge-into)
+      TARGET=$(printf '%s' "$op_json" | jq -r '.target // empty')
+      ADDITIONS=$(printf '%s' "$op_json" | jq -r '.additions // empty')
+      if [ -z "$TARGET" ] || [ -z "$ADDITIONS" ]; then
+        log "skip merge-into: missing target or additions for '$FILE'"
+        SKIPPED=$(( SKIPPED + 1 ))
+        continue
+      fi
+      case "$TARGET" in
+        */*|.*)
+          log "skip merge-into: refusing path-like target '$TARGET'"
+          SKIPPED=$(( SKIPPED + 1 ))
+          continue
+          ;;
+      esac
+      TARGET_PATH="$ADR_DIR/$TARGET"
+      if [ ! -f "$TARGET_PATH" ]; then
+        log "skip merge-into: target '$TARGET' missing"
+        SKIPPED=$(( SKIPPED + 1 ))
+        continue
+      fi
+      if is_draft "$TARGET_PATH"; then
+        log "skip merge-into: target '$TARGET' is itself a draft"
+        SKIPPED=$(( SKIPPED + 1 ))
+        continue
+      fi
+      printf '\n%s\n' "$ADDITIONS" >> "$TARGET_PATH"
+      rm -- "$SRC_PATH"
+      log "merge-into: $FILE → $TARGET"
+      APPLIED=$(( APPLIED + 1 ))
+      ;;
+    *)
+      log "skip: unknown op '$OP' for '$FILE'"
+      SKIPPED=$(( SKIPPED + 1 ))
+      ;;
+  esac
+done
+
+log "done"

package/CHANGELOG.md

@@ -4,6 +4,25 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.10.0] - 2026-05-15
+
+### Added
+
+- **Правило `adr` — фаза 2 (Normalize).** Новий Stop-hook `.claude/hooks/normalize-decisions.sh` батчево нормалізує ADR-чернетки через LLM: коли кількість файлів з `session:` у frontmatter досягає `ADR_NORMALIZE_THRESHOLD` (default 30), бере до `ADR_NORMALIZE_BATCH` найстарших, отримує JSON-операції (`rewrite` / `delete` / `merge-into`) і застосовує їх до робочого дерева. **Жодних git-операцій** — розробник дивиться `git status`/`git diff` і вирішує сам. Recursion guard `ADR_NORMALIZE_RUNNING=1`, мінімальний інтервал між спробами `ADR_NORMALIZE_MIN_INTERVAL_HOURS=6`, lock-файл, skip при mid-rebase/mid-merge, `ADR_NORMALIZE_DRY=1` для dry-run. Slug-стиль — kebab-case українською; дата у фінальному ADR береться з `captured` чернетки.
+- **Skill `adr-normalize`** (slash-команда `/n-adr-normalize`) — ручний запуск normalize поза порогом і поза Stop-hook (виставляє `ADR_NORMALIZE_THRESHOLD=0` і `ADR_NORMALIZE_MIN_INTERVAL_HOURS=0`, корисно для dry-run або разової чистки). Авто-додається при `adr` у `rules`.
+- **`sync-claude-config`**: експортовано `ADR_NORMALIZE_HOOK_COMMAND_MARKER` і функцію `syncAdrNormalizeHookScript`; managed-група normalize додається до `hooks.Stop` поряд з capture-групою (`async: true`, `timeout: 600`) при `"adr"` у `rules`. Маркер `.claude/hooks/normalize-decisions.sh` додано в `MANAGED_HOOK_COMMAND_MARKERS`.
+- **Rego-перевірка `adr.settings_json`** тепер вимагає Stop-hook групу і для capture, і для normalize; **`adr.settings_local_json`** забороняє дублі обох хуків.
+
+### Changed
+
+- **`capture-decisions.sh` тепер пише чернетки напряму в `docs/adr/<timestamp>-<sid>.md`** (раніше — у `docs/adr/_inbox/`). Сам каталог `_inbox/` більше не створюється, але `normalize-decisions.sh` бачить його рекурсивно — старі чернетки з `_inbox/` поступово розчищаються нормалізацією. Можна також одноразово `git mv docs/adr/_inbox/*.md docs/adr/` і прибрати порожній каталог.
+- **Правило `adr` (`npm/rules/adr/adr.mdc`)**: повне переписування під дві фази (capture + normalize). Видалено згадки `_inbox/`. Версія `version: '2.0'`.
+- **`npm/rules/adr/js/check.mjs`**: перевірка обох hook-скриптів (canonicity), обох log-файлів у `.gitignore`.
+
+### Fixed
+
+- `npm/rules/adr/js/check.{mjs,test.mjs}`: виправлено `BUNDLED_HOOKS_DIR` (після phase 3 co-location шлях `'..'` указував у `npm/rules/adr/.claude-template/`, потрібно `'../../..'` — до `npm/.claude-template/`).
+
 ## [1.9.23] - 2026-05-14
 
 ### Fixed

package/bin/n-cursor.js

@@ -1294,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.23",
+  "version": "1.10.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",

package/rules/adr/adr.mdc

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

package/rules/adr/js/check.mjs

@@ -1,14 +1,17 @@
 /**
- * Перевіряє вимоги правила adr.mdc: ADR Stop-hook capture-decisions.sh у Claude Code.
+ * Перевіряє вимоги правила adr.mdc: ADR Stop-hook'и `capture-decisions.sh` і
+ * `normalize-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`.
+ * - `.claude/hooks/capture-decisions.sh` та `.claude/hooks/normalize-decisions.sh`
+ *   існують і байт-у-байт збігаються з канонічними `.claude-template/hooks/*`
+ *   пакета (sync керує файлами повністю).
+ * - `.claude/settings.json` (project-shared) має managed-групи у `hooks.Stop` для
+ *   обох скриптів (маркери у `command` — самі шляхи до скриптів).
+ * - `.claude/settings.local.json` (якщо існує) НЕ має дублів цих managed-груп —
+ *   після переходу на project-shared такі записи створили б два запуски на одну подію.
+ * - `.gitignore` у корені містить шаблон, який покриває
+ *   `.claude/hooks/capture-decisions.log` і `.claude/hooks/normalize-decisions.log`.
  *
  * LLM CLI (`claude` або `cursor-agent`) у `PATH` — інформативна перевірка: якщо жодного
  * немає, скрипт працює, але мовчки виходить, тому це warning, а не fail.
@@ -21,26 +24,48 @@ import { fileURLToPath } from 'node:url'
 
 import { createCheckReporter } from '../../../scripts/utils/check-reporter.mjs'
 
-const PROJECT_HOOK_PATH = '.claude/hooks/capture-decisions.sh'
+/** Один hook-артефакт: bash-скрипт + його лог-файл, які перевіряємо однотипно. */
+const HOOK_ARTIFACTS = /** @type {const} */ ([
+  { scriptName: 'capture-decisions.sh', logName: 'capture-decisions.log' },
+  { scriptName: 'normalize-decisions.sh', logName: 'normalize-decisions.log' }
+])
+
 const PROJECT_SETTINGS_PATH = '.claude/settings.json'
-const PROJECT_LOG_PATH = '.claude/hooks/capture-decisions.log'
 const EOL_RE = /\r?\n/u
 
 const here = dirname(fileURLToPath(import.meta.url))
-/** Канонічний bundled-скрипт у пакеті — джерело правди для звірки з проєктним. */
-const BUNDLED_HOOK_PATH = join(here, '..', '.claude-template', 'hooks', 'capture-decisions.sh')
+const BUNDLED_HOOKS_DIR = join(here, '..', '..', '..', '.claude-template', 'hooks')
+
+/**
+ * Відносний шлях до managed hook-скрипта у проєкті.
+ * @param {string} scriptName базове ім'я скрипта (наприклад `capture-decisions.sh`)
+ * @returns {string} `.claude/hooks/<scriptName>`
+ */
+function projectHookPath(scriptName) {
+  return `.claude/hooks/${scriptName}`
+}
+
+/**
+ * Відносний шлях до лог-файлу managed hook'а у проєкті.
+ * @param {string} logName базове ім'я лог-файлу (наприклад `capture-decisions.log`)
+ * @returns {string} `.claude/hooks/<logName>`
+ */
+function projectLogPath(logName) {
+  return `.claude/hooks/${logName}`
+}
 
 /**
- * Чи містить рядок `.gitignore` шаблон, який покриває `.claude/hooks/capture-decisions.log`.
+ * Чи містить рядок `.gitignore` шаблон, який покриває цей конкретний лог-файл хука.
  * Враховує точний шлях, glob `.claude/hooks/*.log` та широкий glob `**\/*.log`.
  * @param {string} line одна нормалізована (trim) лінія `.gitignore`
- * @returns {boolean} `true`, якщо лінія матчить лог-файл хука
+ * @param {string} logPath шлях `.claude/hooks/<name>.log`, який треба покрити
+ * @returns {boolean} `true`, якщо лінія матчить цей лог-файл
  */
-function gitignoreLineCoversHookLog(line) {
+function gitignoreLineCoversHookLog(line, logPath) {
   if (!line || line.startsWith('#')) {
     return false
   }
-  if (line === PROJECT_LOG_PATH) {
+  if (line === logPath) {
     return true
   }
   if (line === '.claude/hooks/*.log' || line === '.claude/hooks/**/*.log') {
@@ -53,28 +78,28 @@ function gitignoreLineCoversHookLog(line) {
 }
 
 /**
- * Перевіряє наявність і канонічність `.claude/hooks/capture-decisions.sh` у проєкті.
+ * Перевіряє наявність і канонічність одного hook-скрипта.
  * @param {import('./utils/check-reporter.mjs').CheckReporter} reporter репортер для збору результатів
+ * @param {string} scriptName базове ім'я скрипта (наприклад `capture-decisions.sh`)
  * @returns {Promise<void>}
  */
-async function checkHookScript(reporter) {
+async function checkHookScript(reporter, scriptName) {
   const { pass, fail } = reporter
-  if (!existsSync(PROJECT_HOOK_PATH)) {
-    fail(`${PROJECT_HOOK_PATH} не існує — запусти \`npx @nitra/cursor\` (правило adr копіює канонічний скрипт)`)
+  const projectPath = projectHookPath(scriptName)
+  const bundledPath = join(BUNDLED_HOOKS_DIR, scriptName)
+  if (!existsSync(projectPath)) {
+    fail(`${projectPath} не існує — запусти \`npx @nitra/cursor\` (правило adr копіює канонічний скрипт)`)
     return
   }
-  if (!existsSync(BUNDLED_HOOK_PATH)) {
-    fail(`канонічний скрипт у пакеті не знайдено: ${BUNDLED_HOOK_PATH} — перевстанови @nitra/cursor`)
+  if (!existsSync(bundledPath)) {
+    fail(`канонічний скрипт у пакеті не знайдено: ${bundledPath} — перевстанови @nitra/cursor`)
     return
   }
-  const [project, bundled] = await Promise.all([
-    readFile(PROJECT_HOOK_PATH, 'utf8'),
-    readFile(BUNDLED_HOOK_PATH, 'utf8')
-  ])
+  const [project, bundled] = await Promise.all([readFile(projectPath, 'utf8'), readFile(bundledPath, 'utf8')])
   if (project === bundled) {
-    pass(`${PROJECT_HOOK_PATH} збігається з канонічним`)
+    pass(`${projectPath} збігається з канонічним`)
   } else {
-    fail(`${PROJECT_HOOK_PATH} відрізняється від канонічного — запусти \`npx @nitra/cursor\` для повторного синку`)
+    fail(`${projectPath} відрізняється від канонічного — запусти \`npx @nitra/cursor\` для повторного синку`)
   }
 }
 
@@ -95,25 +120,42 @@ function checkProjectSettings(reporter) {
 }
 
 /**
- * Перевіряє `.gitignore` на ігнорування лог-файлу хука.
+ * Перевіряє `.gitignore` на ігнорування лог-файлу одного хука.
+ * @param {import('./utils/check-reporter.mjs').CheckReporter} reporter репортер для збору результатів
+ * @param {string} logName базове ім'я лог-файлу (наприклад `capture-decisions.log`)
+ * @param {string} gitignoreContent попередньо прочитаний вміст `.gitignore`
+ * @returns {void}
+ */
+function checkGitignoreForLog(reporter, logName, gitignoreContent) {
+  const { pass, fail } = reporter
+  const logPath = projectLogPath(logName)
+  const covers = gitignoreContent
+    .split(EOL_RE)
+    .map(l => l.trim())
+    .some(line => gitignoreLineCoversHookLog(line, logPath))
+  if (covers) {
+    pass(`.gitignore покриває ${logPath}`)
+  } else {
+    fail(`.gitignore не ігнорує \`${logPath}\` — додай цей рядок`)
+  }
+}
+
+/**
+ * Перевіряє `.gitignore` для всіх hook-логів одним проходом.
  * @param {import('./utils/check-reporter.mjs').CheckReporter} reporter репортер для збору результатів
  * @returns {Promise<void>}
  */
 async function checkGitignore(reporter) {
-  const { pass, fail } = reporter
+  const { fail } = reporter
   if (!existsSync('.gitignore')) {
-    fail(`.gitignore не існує — додай рядок \`${PROJECT_LOG_PATH}\``)
+    for (const { logName } of HOOK_ARTIFACTS) {
+      fail(`.gitignore не існує — додай рядок \`${projectLogPath(logName)}\``)
+    }
     return
   }
   const content = await readFile('.gitignore', 'utf8')
-  const covers = content
-    .split(EOL_RE)
-    .map(l => l.trim())
-    .some(line => gitignoreLineCoversHookLog(line))
-  if (covers) {
-    pass(`.gitignore покриває ${PROJECT_LOG_PATH}`)
-  } else {
-    fail(`.gitignore не ігнорує \`${PROJECT_LOG_PATH}\` — додай цей рядок`)
+  for (const { logName } of HOOK_ARTIFACTS) {
+    checkGitignoreForLog(reporter, logName, content)
   }
 }
 
@@ -166,7 +208,9 @@ function checkLlmCliAvailable(reporter) {
  */
 export async function check() {
   const reporter = createCheckReporter()
-  await checkHookScript(reporter)
+  for (const { scriptName } of HOOK_ARTIFACTS) {
+    await checkHookScript(reporter, scriptName)
+  }
   checkProjectSettings(reporter)
   await checkGitignore(reporter)
   checkLlmCliAvailable(reporter)

package/rules/adr/policy/settings_json/settings_json.rego

@@ -1,13 +1,13 @@
-# Порт перевірки `.claude/settings.json` з `npm/scripts/check-adr.mjs` (adr.mdc):
-# `hooks.Stop[*]` має містити групу, де хоча б один елемент `hooks[]` має `command`
-# зі substring `.claude/hooks/capture-decisions.sh`.
+# Перевірка `.claude/settings.json` для правила adr.mdc:
+# `hooks.Stop[*]` має містити дві managed-групи — capture і normalize — у
+# кожній хоча б один елемент `hooks[]` з відповідним маркером у `command`.
 #
 # Запуск (локально):
-#   conftest test .claude/settings.json -p npm/policy/adr \
+#   conftest test .claude/settings.json -p npm/rules/adr/policy \
 #     --namespace adr.settings_json
 #
-# Hash-порівняння bash-скрипта з канонічним bundled-варіантом і `.gitignore`-перевірки
-# — у JS (`check-adr.mjs`).
+# Hash-порівняння bash-скриптів з канонічними bundled-варіантами і `.gitignore`-перевірки
+# — у JS (`js/check.mjs`).
 #
 # Структура каталогу збігається зі шляхом пакету (regal: directory-package-mismatch).
 # Конвенція проєкту — `import rego.v1` + multi-value `deny contains msg if { … }`
@@ -16,16 +16,22 @@ package adr.settings_json
 
 import rego.v1
 
-hook_command_marker := ".claude/hooks/capture-decisions.sh"
+capture_marker := ".claude/hooks/capture-decisions.sh"
+normalize_marker := ".claude/hooks/normalize-decisions.sh"
 
 deny contains msg if {
-	not has_adr_stop_hook
+	not has_stop_hook_with_marker(capture_marker)
 	msg := ".claude/settings.json: відсутній Stop-hook для `capture-decisions.sh` у hooks.Stop (adr.mdc)"
 }
 
-# Чи є в `hooks.Stop[*].hooks[*].command` рядок з маркером скрипта.
-has_adr_stop_hook if {
+deny contains msg if {
+	not has_stop_hook_with_marker(normalize_marker)
+	msg := ".claude/settings.json: відсутній Stop-hook для `normalize-decisions.sh` у hooks.Stop (adr.mdc)"
+}
+
+# Чи є в `hooks.Stop[*].hooks[*].command` рядок з заданим маркером.
+has_stop_hook_with_marker(marker) if {
 	some group in object.get(object.get(input, "hooks", {}), "Stop", [])
 	some hook in object.get(group, "hooks", [])
-	contains(object.get(hook, "command", ""), hook_command_marker)
+	contains(object.get(hook, "command", ""), marker)
 }

package/rules/adr/policy/settings_local_json/settings_local_json.rego

@@ -1,10 +1,10 @@
-# Порт перевірки `.claude/settings.local.json` з `npm/scripts/check-adr.mjs`
-# (adr.mdc): після переходу на project-shared `settings.json` цей файл (якщо є)
-# НЕ повинен мати дубля Stop-хука з маркером `.claude/hooks/capture-decisions.sh`,
-# інакше один і той самий скрипт виконається двічі на одну подію.
+# Перевірка `.claude/settings.local.json` для правила adr.mdc: після переходу на
+# project-shared `settings.json` цей файл (якщо є) НЕ повинен мати дубля жодного
+# з керованих Stop-хуків (`capture-decisions.sh` або `normalize-decisions.sh`),
+# інакше відповідний скрипт виконається двічі на одну подію.
 #
 # Запуск (локально):
-#   conftest test .claude/settings.local.json -p npm/policy/adr \
+#   conftest test .claude/settings.local.json -p npm/rules/adr/policy \
 #     --namespace adr.settings_local_json
 #
 # Структура каталогу збігається зі шляхом пакету (regal: directory-package-mismatch).
@@ -14,15 +14,27 @@ package adr.settings_local_json
 
 import rego.v1
 
-hook_command_marker := ".claude/hooks/capture-decisions.sh"
+capture_marker := ".claude/hooks/capture-decisions.sh"
+normalize_marker := ".claude/hooks/normalize-decisions.sh"
 
-duplicate_template := concat(" ", [
-	".claude/settings.local.json: видали дубль Stop-хука для",
-	"`capture-decisions.sh` — він уже у project-shared settings.json (adr.mdc)",
-])
+deny contains msg if {
+	has_stop_hook_with_marker(capture_marker)
+	msg := concat(" ", [
+		".claude/settings.local.json: видали дубль Stop-хука для",
+		"`capture-decisions.sh` — він уже у project-shared settings.json (adr.mdc)",
+	])
+}
+
+deny contains msg if {
+	has_stop_hook_with_marker(normalize_marker)
+	msg := concat(" ", [
+		".claude/settings.local.json: видали дубль Stop-хука для",
+		"`normalize-decisions.sh` — він уже у project-shared settings.json (adr.mdc)",
+	])
+}
 
-deny contains duplicate_template if {
+has_stop_hook_with_marker(marker) if {
 	some group in object.get(object.get(input, "hooks", {}), "Stop", [])
 	some hook in object.get(group, "hooks", [])
-	contains(object.get(hook, "command", ""), hook_command_marker)
+	contains(object.get(hook, "command", ""), marker)
 }

package/scripts/auto-skills.mjs

@@ -14,6 +14,7 @@
 /** Порядок автододавання skills відповідно до `skills/<skill>/auto.md`. */
 export const AUTO_SKILL_ORDER = Object.freeze([
   'abie-kustomize',
+  'adr-normalize',
   'fix',
   'lint',
   'llm-patch',
@@ -28,6 +29,7 @@ export const AUTO_SKILL_ORDER = Object.freeze([
 export const AUTO_SKILL_RULE_DEPENDENCIES = Object.freeze(
   /** @type {Record<string, readonly string[]>} */ ({
     'abie-kustomize': Object.freeze(['abie']),
+    'adr-normalize': Object.freeze(['adr']),
     taze: Object.freeze(['bun'])
   })
 )

package/scripts/sync-claude-config.mjs

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

package/skills/adr-normalize/SKILL.md

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

package/skills/adr-normalize/auto.md

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