@nitra/cursor 1.9.21 → 1.10.0

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]

package/skills/fix/auto.md

@@ -0,0 +1 @@
+завжди

package/skills/lint/auto.md

@@ -0,0 +1 @@
+завжди

package/skills/llm-patch/auto.md

@@ -0,0 +1 @@
+завжди

package/skills/publish-telegram/auto.md

@@ -0,0 +1 @@
+завжди

package/skills/taze/auto.md

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

package/bin/auto-rules.md

@@ -1,59 +0,0 @@
-# Авто вмикання правил
-
-В цьому файлі описані умови, по яким повинні правила автододаватись в конфіг. Умови автододавання скілів — у `auto-skills.md` (виносить логіку зі словника правил у пару «правило → скіл»).
-
-## Правила, які автоматично додається до .n-cursor.json
-
-Синтаксис `rule - [other]` означає: правило `rule` варто автододати лише якщо всі правила у списку `[other]` вже додані до конфігу (граф залежностей між правилами; умова не дублюється).
-
-abie - якщо в кореневому package.json в секції "repository" присутній текст "<https://github.com/abinbevefes/**/>"
-
-bun - якщо в корені проекту є package.json
-
-capacitor - якщо в проекті є хоч один файл capacitor.config.json
-
-changelog - [bun]
-
-docker - якщо в проекті є хоч один Dockerfile
-
-ga - якщо присутня директорія .github/workflows
-
-graphql - якщо хоч в одному js або vue файлі присутній gql` темплейт літерал
-
-hasura - якщо в директорії присутній config.yaml, який містить рядок `metadata_directory: metadata`
-
-image-compress - [bun]
-
-image-avif - [vue, image-compress]
-
-js-lint - якщо присутній хоч один js файл
-
-js-run - якщо це вкладена директорія з package.json (не в корені) та в devDependencies немає vite
-
-js-mssql - якщо в хоч одному package.json в секції dependencies присутній пакет mssql
-
-js-bun-db - якщо в хоч одному package.json в секції dependencies присутній пакет pg, pg-format або mysql2 або є імпорт sql/SQL з Bun (приклад: import { sql } from "bun")
-
-js-bun-redis - якщо в хоч одному package.json в секції dependencies присутній пакет ioredis або node-redis
-
-k8s - якщо присутня хоч одна директорія k8s
-
-nginx-default-tpl - якщо присутній хоч один файл з переліку - default.conf.template, default.conf, nginx.conf
-
-npm-module - якщо в корені присутня директорія npm
-
-php - якщо в корені є composer.json
-
-rego - якщо в проекті є хоч один rego
-
-style-lint - якщо присутній хоч один vue або css файл
-
-tauri - - якщо в хоч в package.json в секції dependencies присутній пакет @tauri-apps/api
-
-text - завжди
-
-vue - якщо присутній хоч один vue файл
-
-## Виключення
-
-Якщо в .n-cursor.json задано в секції disable-rules правило, то воно автоматично додаватись не повинно.

package/bin/auto-skills.md

@@ -1,25 +0,0 @@
-# Авто вмикання скілів
-
-В цьому файлі описані умови, по яким повинні скіли автододаватись в конфіг.
-
-## Скіли, які автоматично додається до .n-cursor.json
-
-Синтаксис `skill - [rules]` означає: скіл `skill` варто автододати лише якщо всі правила у списку `[rules]` уже додані до конфігу автодетектом (з `auto-rules.md`). Так залежність не дублює вихідну умову правила.
-
-abie-kustomize - [abie]
-
-abie-clean - [abie]
-
-fix - завжди
-
-llm-patch - завжди
-
-lint - завжди
-
-publish-telegram - завжди
-
-taze - [bun]
-
-## Виключення
-
-Якщо в .n-cursor.json задано в секції disable-skills скіл, то він автоматично додаватись не повинен.

package/mdc/adr.mdc

@@ -1,86 +0,0 @@
----
-description: Автоматичний збір ADR/Runbook/Knowledge-чернеток із Stop-хука Claude Code (capture-decisions)
-alwaysApply: true
-version: '1.0'
----
-
-Правило вмикається **вручну** — додай `"adr"` у масив `rules` файлу `.n-cursor.json`. У `auto-rules.md` його немає, бо корисність залежить від робочого процесу команди (не кожен проєкт хоче літати ADR-чернеткам у `docs/`).
-
-Коли правило увімкнене, **`npx @nitra/cursor`** автоматично:
-
-- копіює канонічний bash-скрипт у **`.claude/hooks/capture-decisions.sh`** (executable, повністю керується пакетом — на кожен sync перезаписується);
-- додає managed-групу у **`hooks.Stop`** в **`.claude/settings.json`**, яка викликає цей скрипт асинхронно (`async: true`, `timeout: 180`);
-- ці зміни — додаткові до lint Stop-hook (`@nitra/cursor stop-hook`); обидві групи живуть поряд у `Stop`.
-
-## Що робить механізм
-
-Stop-hook Claude Code зчитує JSONL-транскрипт сесії (через `jq`), витягає текст, `thinking`-блоки та назви `tool_use`-викликів, передає компактний дайджест у LLM CLI з промптом українською і записує результат у **`docs/adr/_inbox/<timestamp>-<session>.md`**, якщо модель повернула блок з шапкою `## ADR|Runbook|Knowledge …`. Якщо модель повернула `NONE` (тривіальна сесія) — нічого не пишеться. Рекурсію з внутрішнього виклику моделі блокує env-var `CAPTURE_DECISIONS_RUNNING=1`.
-
-## LLM CLI: claude → cursor-agent fallback
-
-Скрипт сам обирає доступний CLI (порядок фіксований):
-
-1. **`claude`** (Anthropic Claude Code CLI) — `claude -p --model "$CAPTURE_DECISIONS_CLAUDE_MODEL"` (default `sonnet`).
-2. **`cursor-agent`** (Cursor IDE CLI) — `cursor-agent -p --mode ask --output-format text --model "$CAPTURE_DECISIONS_CURSOR_MODEL"` (default `claude-4.6-sonnet-medium`).
-3. Жодного CLI у `PATH` — скрипт виходить з кодом `0` і нічого не пише.
-
-`--mode ask` для cursor-agent навмисно: режим Q&A read-only, без shell/edit-інструментів — для класифікації сесії інструменти не потрібні. Моделі можна перевизначити через ENV: `CAPTURE_DECISIONS_CLAUDE_MODEL`, `CAPTURE_DECISIONS_CURSOR_MODEL`.
-
-## Структура каталогу
-
-```text
-docs/adr/
-└── _inbox/                         # чернетки, що пишуться Stop-хуком
-    └── YYYYMMDD-HHMMSS-<sid>.md    # session_id (перші 8 символів)
-.claude/hooks/
-├── capture-decisions.sh            # auto-synced з пакета
-└── capture-decisions.log           # лог запусків (НЕ коміти)
-```
-
-`.gitignore` повинен містити рядок **`.claude/hooks/capture-decisions.log`**, щоб лог не потрапляв у git.
-
-`docs/adr/_inbox/` — це робоча скринька; чернетки звідти переносяться у структуровані ADR-файли вручну (під час оглядів) або тримаються як архів сесій. Каталог сам створюється скриптом, тому пустим у git тримати не потрібно.
-
-## Stop-hook у `.claude/settings.json`
-
-Канонічний запис, який вставляє sync (поряд із lint stop-hook):
-
-```json title=".claude/settings.json"
-{
-  "hooks": {
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "npx --no @nitra/cursor stop-hook",
-            "timeout": 60
-          }
-        ]
-      },
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/capture-decisions.sh\"",
-            "async": true,
-            "timeout": 180
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-Обидві групи ідентифікуються пакетом за маркером у `command` (`@nitra/cursor stop-hook` і `.claude/hooks/capture-decisions.sh`) — користувацькі hook-групи поряд не чіпаються. Якщо `adr` прибрати з `rules`, ADR-група автоматично видаляється на наступному `npx @nitra/cursor`.
-
-## Локальні vs project-shared налаштування
-
-Stop-hook ADR живе у **project-shared** `.claude/settings.json` (закомічений), щоб механізм працював у всіх членів команди. Якщо хук колись був у `.claude/settings.local.json` — прибери дубль вручну: project-shared і local-копія створили б два запуски на одну подію.
-
-## Перевірка
-
-`npx @nitra/cursor check adr`

package/policy/adr/settings_json/settings_json.rego

@@ -1,31 +0,0 @@
-# Порт перевірки `.claude/settings.json` з `npm/scripts/check-adr.mjs` (adr.mdc):
-# `hooks.Stop[*]` має містити групу, де хоча б один елемент `hooks[]` має `command`
-# зі substring `.claude/hooks/capture-decisions.sh`.
-#
-# Запуск (локально):
-#   conftest test .claude/settings.json -p npm/policy/adr \
-#     --namespace adr.settings_json
-#
-# Hash-порівняння bash-скрипта з канонічним bundled-варіантом і `.gitignore`-перевірки
-# — у JS (`check-adr.mjs`).
-#
-# Структура каталогу збігається зі шляхом пакету (regal: directory-package-mismatch).
-# Конвенція проєкту — `import rego.v1` + multi-value `deny contains msg if { … }`
-# (.cursor/rules/conftest.mdc). Лінт — `bun run lint-rego` (regal).
-package adr.settings_json
-
-import rego.v1
-
-hook_command_marker := ".claude/hooks/capture-decisions.sh"
-
-deny contains msg if {
-	not has_adr_stop_hook
-	msg := ".claude/settings.json: відсутній Stop-hook для `capture-decisions.sh` у hooks.Stop (adr.mdc)"
-}
-
-# Чи є в `hooks.Stop[*].hooks[*].command` рядок з маркером скрипта.
-has_adr_stop_hook 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)
-}

package/policy/adr/settings_local_json/settings_local_json.rego

@@ -1,28 +0,0 @@
-# Порт перевірки `.claude/settings.local.json` з `npm/scripts/check-adr.mjs`
-# (adr.mdc): після переходу на project-shared `settings.json` цей файл (якщо є)
-# НЕ повинен мати дубля Stop-хука з маркером `.claude/hooks/capture-decisions.sh`,
-# інакше один і той самий скрипт виконається двічі на одну подію.
-#
-# Запуск (локально):
-#   conftest test .claude/settings.local.json -p npm/policy/adr \
-#     --namespace adr.settings_local_json
-#
-# Структура каталогу збігається зі шляхом пакету (regal: directory-package-mismatch).
-# Конвенція проєкту — `import rego.v1` + multi-value `deny contains msg if { … }`
-# (.cursor/rules/conftest.mdc). Лінт — `bun run lint-rego` (regal).
-package adr.settings_local_json
-
-import rego.v1
-
-hook_command_marker := ".claude/hooks/capture-decisions.sh"
-
-duplicate_template := concat(" ", [
-	".claude/settings.local.json: видали дубль Stop-хука для",
-	"`capture-decisions.sh` — він уже у project-shared settings.json (adr.mdc)",
-])
-
-deny contains duplicate_template 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)
-}