@nitra/cursor 1.17.3 → 1.18.0

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

@@ -34,6 +34,62 @@ mkdir -p "$ADR_DIR" "$LOG_DIR"
 
 log() { printf '%s %s\n' "$(date -Iseconds)" "$*" >> "$LOG"; }
 
+# Структурний скіп ADR-генерації для "tooling-only" сесій.
+# Вхід: рядки-шляхи у stdin (один шлях на лінію), відносні до $PROJECT_ROOT
+# або абсолютні з префіксом $PROJECT_ROOT (нормалізуємо тут).
+# Вихід: 0 — усі шляхи в allowlist; 1 — є хоч один змістовний шлях.
+# Bash 3.2: без mapfile/асоц. масивів.
+is_tooling_only_change() {
+  local proj="$1"
+  local had_file=0
+  local f rel
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    had_file=1
+    case "$f" in
+      "$proj"/*) rel="${f#"$proj"/}" ;;
+      /*) return 1 ;;
+      *)  rel="$f" ;;
+    esac
+    case "$rel" in
+      .cspell.json) ;;
+      docs/adr/*.md) ;;
+      AGENTS.md|CLAUDE.md) ;;
+      CHANGELOG.md) ;;
+      */CHANGELOG.md) ;;
+      package.json|*/package.json)
+        if ! git_diff_only_version_field "$proj" "$rel"; then
+          return 1
+        fi
+        ;;
+      *) return 1 ;;
+    esac
+  done
+  [ "$had_file" = "1" ] && return 0
+  return 1
+}
+
+# Допоміжна: чи git-diff для файлу торкається ЛИШЕ рядків з `"version":`.
+# Поза git-репо або при помилці — вертаємо 1 (не tooling).
+git_diff_only_version_field() {
+  local proj="$1" path="$2"
+  [ -d "$proj/.git" ] || return 1
+  local diff
+  diff=$(cd "$proj" && git diff HEAD --unified=0 -- "$path" 2>/dev/null) || return 1
+  [ -z "$diff" ] && return 1
+  local line
+  while IFS= read -r line; do
+    case "$line" in
+      '+++ '*|'--- '*|'@@ '*|'') continue ;;
+      [+-]*'"version":'*) continue ;;
+      [+-]*) return 1 ;;
+    esac
+  done <<EOF
+$diff
+EOF
+  return 0
+}
+
 log "fired: $SESSION_ID"
 
 if [[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]]; then
@@ -86,6 +142,29 @@ if [[ -z "$TRANSCRIPT" ]]; then
   exit 0
 fi
 
+# Structural skip: якщо в сесії змінювалися лише tooling-файли — не викликаємо LLM.
+# ENV `ADR_NORMALIZE_SKIP_TOOLING_ONLY=0` вимикає скіп.
+if [[ "${ADR_NORMALIZE_SKIP_TOOLING_ONLY:-1}" = "1" ]]; then
+  CHANGED_FILES=$(jq -r '
+    select(.type == "assistant" or .role == "assistant")
+    | .message as $m
+    | ($m.content // [])
+    | if type == "array" then
+        map(select(.type == "tool_use" and (.name == "Edit" or .name == "Write" or .name == "MultiEdit"))
+            | .input.file_path // empty)
+        | .[]
+      else empty end
+  ' "$TRANSCRIPT_PATH" 2>/dev/null | sort -u || true)
+
+  if [[ -n "$CHANGED_FILES" ]]; then
+    if printf '%s\n' "$CHANGED_FILES" | is_tooling_only_change "$PROJECT_ROOT"; then
+      log "  → skipping ADR capture: tooling-only session"
+      log "    files: $(printf '%s' "$CHANGED_FILES" | tr '\n' ' ')"
+      exit 0
+    fi
+  fi
+fi
+
 PROMPT=$(cat <<'EOF'
 You analyze an AI coding session transcript and produce durable decision documentation.
 

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

@@ -39,6 +39,65 @@ mkdir -p "$LOG_DIR"
 
 log() { printf '%s %s\n' "$(date -Iseconds)" "$*" >> "$LOG"; }
 
+# Структурний скіп ADR-нормалізації для "tooling-only" сесій.
+# Дублікат із capture-decisions.sh: `.claude-template/hooks/` копіюється плоско,
+# спільний helper-файл туди не вписується.
+is_tooling_only_change() {
+  proj="$1"
+  had_file=0
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    had_file=1
+    case "$f" in
+      "$proj"/*) rel="${f#"$proj"/}" ;;
+      /*) return 1 ;;
+      *)  rel="$f" ;;
+    esac
+    case "$rel" in
+      .cspell.json) ;;
+      docs/adr/*.md) ;;
+      AGENTS.md|CLAUDE.md) ;;
+      CHANGELOG.md) ;;
+      */CHANGELOG.md) ;;
+      package.json|*/package.json)
+        if ! git_diff_only_version_field "$proj" "$rel"; then
+          return 1
+        fi
+        ;;
+      *) return 1 ;;
+    esac
+  done
+  [ "$had_file" = "1" ] && return 0
+  return 1
+}
+
+# Допоміжна: чи git-diff для файлу торкається ЛИШЕ рядків з `"version":`.
+git_diff_only_version_field() {
+  proj="$1"; path="$2"
+  [ -d "$proj/.git" ] || return 1
+  diff=$(cd "$proj" && git diff HEAD --unified=0 -- "$path" 2>/dev/null) || return 1
+  [ -z "$diff" ] && return 1
+  while IFS= read -r line; do
+    case "$line" in
+      '+++ '*|'--- '*|'@@ '*|'') continue ;;
+      [+-]*'"version":'*) continue ;;
+      [+-]*) return 1 ;;
+    esac
+  done <<EOF
+$diff
+EOF
+  return 0
+}
+
+# Витягає поле `transcript:` з YAML frontmatter ADR-чернетки.
+draft_transcript_path() {
+  awk '
+    NR==1 && /^---$/ { fm=1; next }
+    fm && /^---$/    { exit }
+    fm && /^transcript: / { sub(/^transcript: /, ""); print; exit }
+  ' "$1" 2>/dev/null
+}
+
 # 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
@@ -120,6 +179,45 @@ head -n "$BATCH_SIZE" "$DRAFTS_LIST" > "$BATCH_LIST"
 BATCH_COUNT=$(wc -l < "$BATCH_LIST" | tr -d ' ')
 log "batch size: $BATCH_COUNT"
 
+# Structural skip: чернетки з tooling-only сесій видаляємо без виклику LLM.
+if [ "${ADR_NORMALIZE_SKIP_TOOLING_ONLY:-1}" = "1" ]; then
+  FILTERED_LIST="$TMP_DIR/batch-filtered.txt"
+  : > "$FILTERED_LIST"
+  TOOLING_REMOVED=0
+  while IFS= read -r draft; do
+    [ -f "$draft" ] || continue
+    tpath=$(draft_transcript_path "$draft")
+    if [ -n "$tpath" ] && [ -f "$tpath" ]; then
+      changed=$(jq -r '
+        select(.type == "assistant" or .role == "assistant")
+        | .message as $m
+        | ($m.content // [])
+        | if type == "array" then
+            map(select(.type == "tool_use" and (.name == "Edit" or .name == "Write" or .name == "MultiEdit"))
+                | .input.file_path // empty)
+            | .[]
+          else empty end
+      ' "$tpath" 2>/dev/null | sort -u || true)
+      if [ -n "$changed" ] && printf '%s\n' "$changed" | is_tooling_only_change "$PROJECT_ROOT"; then
+        rm -f -- "$draft"
+        log "tooling-only delete: $(basename "$draft") (files: $(printf '%s' "$changed" | tr '\n' ' '))"
+        TOOLING_REMOVED=$(( TOOLING_REMOVED + 1 ))
+        continue
+      fi
+    fi
+    printf '%s\n' "$draft" >> "$FILTERED_LIST"
+  done < "$BATCH_LIST"
+  mv "$FILTERED_LIST" "$BATCH_LIST"
+  BATCH_COUNT=$(wc -l < "$BATCH_LIST" | tr -d ' ')
+  if [ "$TOOLING_REMOVED" -gt 0 ]; then
+    log "after tooling-only filter: $BATCH_COUNT drafts remain (removed $TOOLING_REMOVED)"
+  fi
+  if [ "$BATCH_COUNT" -eq 0 ]; then
+    log "batch is empty after tooling-only filter — exit"
+    exit 0
+  fi
+fi
+
 # 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

package/CHANGELOG.md

@@ -4,6 +4,32 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.18.0] - 2026-05-25
+
+### Added
+
+- `text`: `docs/adr/**` у канонічному `ignorePaths` правила `.cspell.json` (`policy/cspell/template/.cspell.json.snippet.json`). Машинно-генеровані ADR-документи більше не валідуються cspell-ом — це розриває петлю «правка `.cspell.json` → новий ADR-draft → знову `cspell` ламається на ньому». Локальні розширення `ignorePaths` лишаються дозволені (rego subset-of).
+- `adr`: ENV `ADR_NORMALIZE_SKIP_TOOLING_ONLY` (default `1`) — вимикає structural skip у capture-/normalize-хуках. Документація в `adr.mdc` (таблиця ENV) і `skills/adr-normalize/SKILL.md`.
+
+### Changed
+
+- `adr`: `.claude-template/hooks/capture-decisions.sh` — перед LLM-викликом перевіряє список `tool_use`-правок із transcript'у. Якщо всі правки у вузькому allowlist (`.cspell.json`, `docs/adr/*.md`, кореневі `AGENTS.md`/`CLAUDE.md`, `CHANGELOG.md`, `*/package.json` із diff виключно по ключу `version`) — `exit 0` із записом `skipping ADR capture: tooling-only session` у лог. Inline-функція `is_tooling_only_change` + `git_diff_only_version_field`, bash 3.2-сумісно.
+- `adr`: `.claude-template/hooks/normalize-decisions.sh` — після формування батча для кожної чернетки читає `transcript:` із frontmatter і та сама перевірка allowlist'у. Tooling-only чернетки видаляються без виклику LLM; якщо батч порожній — `exit 0`.
+- `text.mdc` 1.29 → 1.30: документація `docs/adr/**` у `ignorePaths`; приклади `.cspell.json` оновлено.
+- `adr.mdc` 2.1 → 2.2: нова секція «Tooling-only skip» у Фазі 1, bullet у Фазі 2, рядок у таблиці ENV.
+
+### Notes
+
+- Існуючі ENV (`ADR_NORMALIZE_THRESHOLD`, `…_MIN_INTERVAL_HOURS`, `…_BATCH`, `…_DRY`, recursion-guard `CAPTURE_DECISIONS_RUNNING` / `ADR_NORMALIZE_RUNNING`) поведінку не змінюють.
+- `cspell.rego` subset-of-перевірку зберігає — нічого не зламано для проєктів, де користувач уже руками додав `docs/adr/**` у свій `.cspell.json`.
+
+## [1.17.4] - 2026-05-24
+
+### Changed
+
+- Концерн `stryker_config`: gitignore-патерн `**/reports/stryker/.tmp/` + `**/reports/stryker/mutation.json` замінено на один broader `**/reports/stryker/` — увесь каталог Stryker-output-у. Покриває не лише `.tmp/` + `mutation.json`, а й HTML/dashboard-репорти якщо користувач додасть інші reporter-и. Існуючі дрібніші патерни в `.gitignore` користувача не видаляються (idempotent helper лише дописує), але стають надлишковими — користувач може почистити вручну за бажанням.
+- `test.mdc` 2.1 → 2.2: оновлено опис gitignore-керування під новий broader patern.
+
 ## [1.17.3] - 2026-05-24
 
 ### Added

package/package.json

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

package/rules/adr/adr.mdc

@@ -1,7 +1,7 @@
 ---
 description: Автоматичний збір ADR/Runbook/Knowledge-чернеток і батч-нормалізація у `docs/adr/` через Stop-хуки Claude Code та Cursor Agent
 alwaysApply: true
-version: '2.1'
+version: '2.2'
 ---
 
 ## MADR v4 і дві фази
@@ -29,6 +29,8 @@ Stop-hook `capture-decisions.sh` зчитує JSONL-транскрипт сес
 
 Для Cursor payload скрипт бере `transcript_path`, `conversation_id` / `generation_id` і `workspace_roots[0]`; для Claude Code — `transcript_path`, `session_id` і `CLAUDE_PROJECT_DIR`.
 
+**Tooling-only skip:** перед викликом LLM `capture-decisions.sh` дивиться у transcript на `tool_use`-правки (`Edit`/`Write`/`MultiEdit`). Якщо всі змінені файли потрапляють у вузький allowlist — `.cspell.json`, `docs/adr/*.md`, `CHANGELOG.md`, кореневі `AGENTS.md`/`CLAUDE.md`, або `package.json` з diff виключно по ключу `version` — хук виходить з `exit 0` без LLM-виклику. Це розриває петлю «`/n-lint` править `.cspell.json` → з'являється новий ADR-draft → наступний `/n-lint` знов псує правопис у цьому draft». Поведінку вимикає `ADR_NORMALIZE_SKIP_TOOLING_ONLY=0`.
+
 ### Фаза 2 — Normalize
 
 Stop-hook `normalize-decisions.sh` спрацьовує на тому самому `Stop`-евенті, але:
@@ -38,6 +40,7 @@ Stop-hook `normalize-decisions.sh` спрацьовує на тому самом
 - Бере не більше **`ADR_NORMALIZE_BATCH`** чернеток (default 10, найстарші за іменем-timestamp), формує один промпт LLM і чекає JSON-відповідь зі списком операцій.
 - Виходить миттєво, якщо репозиторій у стані `MERGE_HEAD` / `rebase-*` — небезпечно правити файли посеред конфлікту.
 - Виходить миттєво, якщо інший normalize-запуск тримає `flock` на `.claude/hooks/.normalize.lock` (тільки де `flock` доступний).
+- Перед викликом LLM для кожної чернетки batch'а читає `transcript:` із frontmatter і той самий tool_use-список. Чернетки tooling-only — видаляє без виклику LLM. Якщо після фільтра batch порожній — `exit 0`.
 
 LLM повертає масив операцій:
 
@@ -65,6 +68,7 @@ LLM повертає масив операцій:
 | `ADR_NORMALIZE_DRY` | `0` | `1` — лише лог запланованих операцій, без змін на диску. |
 | `ADR_NORMALIZE_MODEL` | `sonnet` | Модель для `claude -p`. |
 | `ADR_NORMALIZE_CURSOR_MODEL` | `claude-4.6-sonnet-medium` | Модель для `cursor-agent -p`. |
+| `ADR_NORMALIZE_SKIP_TOOLING_ONLY` | `1` | `0` — вимкнути structural skip tooling-only сесій (старий behavior). |
 
 Для ручного запуску (поза порогом і поза Stop-хуком) є **`/n-adr-normalize`** — slash-команда тимчасово виставляє `ADR_NORMALIZE_THRESHOLD=0` і `ADR_NORMALIZE_MIN_INTERVAL_HOURS=0` та викликає скрипт напряму.
 

package/rules/test/js/stryker_config.mjs

@@ -23,11 +23,11 @@ import { resolveAllJsRoots } from '../../../scripts/utils/resolve-js-root.mjs'
 const HERE = dirname(fileURLToPath(import.meta.url))
 const BASELINE_PATH = join(HERE, 'data', 'stryker_config', 'stryker.config.baseline.mjs')
 
-// Stryker-output патерни для .gitignore: temp-каталог з backup-файлами
-// (`tempDirName: 'reports/stryker/.tmp'` у baseline) і JSON-репорт мутацій.
-// Канон in-place mode у baseline лишає backup'и у `reports/stryker/.tmp/backup-XXX/`,
-// які НЕ можна комітити. Подвійний-зірочка-префікс покриває всі workspaces.
-const STRYKER_GITIGNORE_ENTRIES = ['**/reports/stryker/.tmp/', '**/reports/stryker/mutation.json']
+// Stryker-output патерн для .gitignore: увесь каталог reports/stryker/ — це
+// build-артефакти (`tempDirName` backup'и, mutation.json, HTML/dashboard-репорти
+// якщо користувач додасть інші reporter-и). Покриваємо одним патерном замість
+// перелічування під-патернів. Подвійний-зірочка-префікс — для monorepo workspaces.
+const STRYKER_GITIGNORE_ENTRIES = ['**/reports/stryker/']
 
 /**
  * @returns {Promise<number>} 0 — OK або silently skipped, 1 — порушення

package/rules/test/test.mdc

@@ -1,6 +1,6 @@
 ---
 description: JS-тести (*.test.mjs) живуть у tests/. Правило `test` керує stryker.config.mjs (якщо js-lint enabled) і .cargo/mutants.toml (якщо rust enabled).
-version: '2.1'
+version: '2.2'
 globs: "**/{.n-cursor.json,package.json,Cargo.toml,stryker.config.mjs,.cargo/mutants.toml},**/*.test.mjs"
 alwaysApply: false
 ---
@@ -82,4 +82,4 @@ Recursive globs ловлять файли всередині `tests/` так с
 
 Customization (mutate patterns, exclude rules, timeout) — відповідальність проєкту-споживача; концерни лише забезпечують наявність файлу як стартового baseline в кожному з виявлених workspace-каталогів.
 
-Додатково: коли `js-lint` enabled, концерн `stryker_config` ідемпотентно додає у кореневий `.gitignore` патерни Stryker-output-у — `**/reports/stryker/.tmp/` (in-place backup-каталог з baseline-у) і `**/reports/stryker/mutation.json` (JSON-репорт). Це запобігає випадковому коміту backup-копій вихідного коду та мутаційного звіту як build-артефактів.
+Додатково: коли `js-lint` enabled, концерн `stryker_config` ідемпотентно додає у кореневий `.gitignore` патерн `**/reports/stryker/` — увесь каталог Stryker-output-у (backup'и `tempDirName`, `mutation.json`, HTML/dashboard-репорти якщо додасте інші reporter-и). Це запобігає випадковому коміту build-артефактів.

package/rules/text/policy/cspell/template/.cspell.json.snippet.json

@@ -7,6 +7,7 @@
     ".vscode",
     "report",
     "*.svg",
-    "**/k8s/**/*.yaml"
+    "**/k8s/**/*.yaml",
+    "docs/adr/**"
   ]
 }

package/rules/text/text.mdc

@@ -1,7 +1,7 @@
 ---
 description: Обробка та перевірка текстових файлів, oxfmt, cspell, shellcheck (sh), dotenv-linter (.env*), markdownlint-cli2, v8r, CI
 alwaysApply: true
-version: '1.29'
+version: '1.30'
 ---
 
 **oxfmt** (`.oxfmtrc.json`, редактор), **cspell**, **shellcheck** (tracked `*.sh` у `lint-text`), **[dotenv-linter](https://dotenv-linter.github.io/)** (`.env*` у `lint-text`), **markdownlint-cli2**, **[v8r](https://chris48s.github.io/v8r/)** ([Schema Store](https://www.schemastore.org/)), розширення **DavidAnson.vscode-markdownlint** / **timonwong.shellcheck**, workflow **`lint-text`**.
@@ -186,7 +186,7 @@ version: '1.29'
 {
   "version": "0.2",
   "language": "nitra",
-  "ignorePaths": ["**/node_modules/**", "**/vscode-extension/**", "**/.git/**", ".vscode", "report", "*.svg", "**/k8s/**/*.yaml"],
+  "ignorePaths": ["**/node_modules/**", "**/vscode-extension/**", "**/.git/**", ".vscode", "report", "*.svg", "**/k8s/**/*.yaml", "docs/adr/**"],
   "import": ["@nitra/cspell-dict/cspell-ext.json"],
   "words": []
 }
@@ -194,6 +194,8 @@ version: '1.29'
 
 Канон базових ключів `.cspell.json` (`version`, `ignorePaths`): [.cspell.json.snippet.json](./policy/cspell/template/.cspell.json.snippet.json). Обовʼязковий запис у `import`: [.cspell.json.contains.json](./policy/cspell/template/.cspell.json.contains.json). Заборонено імпортувати окремі `@cspell/dict-*` у `.cspell.json`: [.cspell.json.deny.json](./policy/cspell/template/.cspell.json.deny.json).
 
+`docs/adr/**` у канонічному `ignorePaths` — машинно-генеровані MADR-документи (драфти `capture-decisions.sh` + clean-ADR-и після `normalize-decisions.sh`). cspell-перевірка там безглузда: чернетка стирається наступним прогоном хук-ланцюжка, а будь-яка ручна правка правопису перезаписується. Локальні розширення `ignorePaths` дозволені — це лише мінімум.
+
 ```json title="package.json"
 {
   "scripts": {
@@ -230,7 +232,7 @@ version: '1.29'
 {
   "version": "0.2",
   "language": "en,uk,ru-ru,nitra",
-  "ignorePaths": ["**/node_modules/**", "**/vscode-extension/**", "**/.git/**", ".vscode", "report", "*.svg", "**/k8s/**/*.yaml"],
+  "ignorePaths": ["**/node_modules/**", "**/vscode-extension/**", "**/.git/**", ".vscode", "report", "*.svg", "**/k8s/**/*.yaml", "docs/adr/**"],
   "import": ["@nitra/cspell-dict/cspell-ext.json"],
   "words": []
 }

package/skills/adr-normalize/SKILL.md

@@ -62,9 +62,11 @@ description: >-
 - `ADR_NORMALIZE_BATCH=30` — більший батч (менше викликів LLM, більше токенів за раз).
 - `ADR_NORMALIZE_MODEL=opus` — інша модель `claude -p`.
 - `ADR_NORMALIZE_CURSOR_MODEL=…` — інша модель для cursor-agent fallback.
+- `ADR_NORMALIZE_SKIP_TOOLING_ONLY=0` — вимкнути structural skip для tooling-only сесій (default `1`). Корисно лише якщо хочеш зберегти чернетки навіть для правок у `.cspell.json` / `CHANGELOG.md` / `version`-bump-ів.
 
 ## Якщо щось пішло не так
 
 - LLM повернув криву JSON → у логу буде `invalid JSON response (first 200 chars): …`. Запусти ще раз — нерідко це разовий збій.
 - Скрипт виходить миттєво без логу → перевір `ADR_NORMALIZE_RUNNING` у env (recursion guard) і чи репо не у стані merge/rebase.
 - Перейменування зробило дублі імен (`<timestamp>-<slug>-2.md`) → це нормально, скрипт детермінований; під час review можна обʼєднати руками й видалити `-2`.
+- ADR-чернетки видаляються мовчки → це structural tooling-only skip. Перевір лог: `tail .claude/hooks/normalize-decisions.log | grep tooling-only`. Для діагностики на capture-стороні: `tail .claude/hooks/capture-decisions.log | grep tooling-only`. Аби тимчасово вимкнути — `ADR_NORMALIZE_SKIP_TOOLING_ONLY=0 bash .claude/hooks/normalize-decisions.sh`.