@nitra/cursor 1.17.4 → 1.18.1

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,35 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.18.1] - 2026-05-25
+
+### Fixed
+
+- **`scripts/cli-entry.mjs::isRunAsCli`** + **`scripts/lib/run-rule-cli.mjs::isRunAsCli`** — функція приймала `()` без аргументів і всередині дивилася на власний `import.meta.url`, а не на caller'а. Через те, що `import.meta` лексично прив'язаний до файлу, де записаний, helper-функція ВСІГДА бачила свій файл — `cli-entry.mjs` / `run-rule-cli.mjs` — і ніколи не дорівнювала `process.argv[1]`. Результат: усі ~40 `if (isRunAsCli())` у `rules/<id>/fix.mjs` / `lint/*.mjs` / `bin/rename-yaml-extensions.mjs` ВСІГДА йшли в else-гілку, і `bun rules/<id>/fix.mjs` мовчки виходив `0` без жодного output'у. `npx @nitra/cursor fix <rule>` → `runFixCommand` → `spawnSync('bun', [fix.mjs])` → exit 0 без жодного reporter-звіту.
+- **Fix:** функція тепер приймає `metaUrl` параметром: `isRunAsCli(import.meta.url)`. Реалізація через `realpathSync(fileURLToPath(metaUrl)) === realpathSync(resolve(process.argv[1]))` — `realpath` знімає різницю «symlink vs canonical» (macOS `/tmp` ↔ `/private/tmp`, pnpm content-addressable links, `node_modules/.bin/*` shim).
+- **Консолідація:** `run-rule-cli.mjs::isRunAsCli` тепер `export { isRunAsCli } from '../cli-entry.mjs'` — одне джерело правди. Existing import paths у callers лишилися без змін.
+- **Callsites:** всі ~40 викликів `isRunAsCli()` оновлено на `isRunAsCli(import.meta.url)`.
+- **Tests:** додано три нові кейси у `scripts/tests/cli-entry.test.mjs` (entry-detection через spawn-fixture, symlink-нормалізація через `/tmp` → `/private/tmp`, no-arg fallback). Fixture — `scripts/tests/fixtures/cli-entry-as-cli.mjs`.
+
+## [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

package/bin/rename-yaml-extensions.mjs

@@ -34,7 +34,7 @@ export async function runRenameYamlExtensionsCli(argv) {
   return errors.length > 0 ? 1 : 0
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   const code = await runRenameYamlExtensionsCli(process.argv.slice(2))
   if (code !== 0) {
     process.exitCode = 1

package/package.json

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

package/rules/abie/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

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/adr/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/bun/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/capacitor/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/changelog/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/ci4/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/docker/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/docker/lint/lint.mjs

@@ -90,6 +90,6 @@ async function runLintDockerSteps() {
  */
 export const runLintDocker = () => runStandardLint(import.meta.dirname, runLintDockerSteps)
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   process.exitCode = await runLintDocker()
 }

package/rules/efes/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/feedback/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/ga/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/graphql/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/hasura/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/image-avif/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/image-compress/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/js-bun-db/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/js-bun-redis/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/js-lint/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/js-mssql/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/js-run/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/k8s/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/k8s/lint/lint.mjs

@@ -354,6 +354,6 @@ async function runLintK8sSteps() {
  */
 export const runLintK8s = () => runStandardLint(import.meta.dirname, runLintK8sSteps)
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   process.exitCode = await runLintK8s()
 }

package/rules/nginx-default-tpl/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/npm-module/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/php/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/php/lint/lint.mjs

@@ -120,6 +120,6 @@ export function run() {
   return reporter.getExitCode()
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   process.exitCode = run()
 }

package/rules/rego/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/rego/lint/lint.mjs

@@ -143,6 +143,6 @@ export function runLintRegoSteps(cwd = process.cwd()) {
  */
 export const runLintRego = () => runStandardLint(import.meta.dirname, () => runLintRegoSteps())
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   process.exitCode = await runLintRego()
 }

package/rules/rust/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/security/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/style-lint/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/tauri/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/test/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/text/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/rules/text/lint/run-dotenv-linter.mjs

@@ -90,6 +90,6 @@ export function runDotenvLinter(cwd = process.cwd()) {
   return 1
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   process.exitCode = runDotenvLinter()
 }

package/rules/text/lint/run-shellcheck.mjs

@@ -215,6 +215,6 @@ function runFinalShellcheck(shellcheck, files, root) {
   return 1
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   process.exitCode = runShellcheckText()
 }

package/rules/text/lint/run-v8r.mjs

@@ -76,7 +76,7 @@ export function runV8rWithGlobs(globs = DEFAULT_V8R_GLOBS) {
   return 0
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   const globs = process.argv.length > 2 ? process.argv.slice(2) : DEFAULT_V8R_GLOBS
   process.exitCode = runV8rWithGlobs(globs)
 }

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/rules/vue/fix.mjs

@@ -11,7 +11,7 @@ export function run(ctx) {
   return runStandardRule(import.meta.dirname, ctx)
 }
 
-if (isRunAsCli()) {
+if (isRunAsCli(import.meta.url)) {
   // Standalone: bun rules/<id>/fix.mjs — повний еквівалент `npx @nitra/cursor fix <id>`
   // (config-loading + whitelist + summary). Дві ролі fix.mjs: library (run) + standalone (main).
   // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE

package/scripts/cli-entry.mjs

@@ -1,23 +1,33 @@
 /**
  * Визначення, чи виконується поточний ESM-модуль як точка входу CLI, а не як import у тестах чи інших модулях.
  *
- * Порівняння `import.meta.url` з `process.argv[1]` після `resolve`, щоб `bun path/to/script.mjs`
- * і `node path/to/script.mjs` коректно вважалися прямим запуском.
+ * Прийом: модуль, що хоче знати свій статус, передає `import.meta.url` —
+ * `import.meta` лексично прив'язаний до файлу, де він записаний, тому helper-функція
+ * без аргументу неминуче дивилася б на свій файл, а не на caller. `realpathSync` на обох
+ * сторонах знімає різницю «symlink vs canonical» (macOS `/tmp` ↔ `/private/tmp`,
+ * `node_modules/.bin/*` shim, pnpm-style content-addressable links).
  */
+import { realpathSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 /**
  * Чи виконується модуль як точка входу CLI (прямий запуск), а не через import.
- * @returns {boolean} `true`, якщо файл запущено напряму; інакше `false`.
+ * @param {string | URL} [metaUrl] `import.meta.url` модуля-caller'а. Без нього — завжди `false`.
+ * @returns {boolean} `true`, якщо файл, з якого передано `metaUrl`, є `process.argv[1]`.
  */
-export function isRunAsCli() {
+export function isRunAsCli(metaUrl) {
+  if (!metaUrl) {
+    return false
+  }
+  const entry = process.argv[1]
+  if (!entry) {
+    return false
+  }
   try {
-    const entry = process.argv[1]
-    if (!entry) {
-      return false
-    }
-    return fileURLToPath(import.meta.url) === resolve(entry)
+    const callerPath = realpathSync(fileURLToPath(metaUrl))
+    const entryPath = realpathSync(resolve(entry))
+    return callerPath === entryPath
   } catch {
     return false
   }

package/scripts/lib/run-rule-cli.mjs

@@ -7,23 +7,17 @@
  * Library-mode виклик з CLI orchestration — інше: див. `runStandardRule` + `fix.mjs::run(ctx)`.
  */
 import { basename } from 'node:path'
-import { pathToFileURL } from 'node:url'
 
 import { isRuleEnabled, readNCursorConfigLite } from './read-n-cursor-config-lite.mjs'
 import { runStandardRule } from './run-standard-rule.mjs'
 import { getOrCreateWalkCache } from '../utils/walk-cache.mjs'
 
-const PACKAGE_NAME = '@nitra/cursor'
+// Re-export для зворотної сумісності: уся `rules/<id>/fix.mjs` уже імпортує `isRunAsCli`
+// саме звідси. Канонічна реалізація — у `scripts/cli-entry.mjs`. Caller передає
+// `import.meta.url`: `if (isRunAsCli(import.meta.url)) …`.
+export { isRunAsCli } from '../cli-entry.mjs'
 
-/**
- * Чи поточний модуль запущено як CLI entry-point (`bun rules/<id>/fix.mjs`).
- * @returns {boolean} true, коли `import.meta.url` збігається з `process.argv[1]`
- */
-export function isRunAsCli() {
-  const entry = process.argv[1]
-  if (!entry) return false
-  return import.meta.url === pathToFileURL(entry).href
-}
+const PACKAGE_NAME = '@nitra/cursor'
 
 /**
  * @param {string} ruleDir абсолютний шлях до `rules/<id>/`

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`.