@nitra/cursor 1.13.65 → 1.13.67

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

@@ -334,7 +334,19 @@ jq -c '.operations[]' "$RESPONSE_CLEAN_FILE" | while IFS= read -r op_json; do
           continue
           ;;
       esac
-      DEST_PATH=$(resolve_unique_slug_path "$SLUG")
+      # Keep the draft's `YYYYMMDD-HHMMSS-` prefix on the clean file: the name
+      # stays anchored to capture time, only the slug part changes between draft
+      # and clean, and docs/adr/ keeps sorting chronologically. Drafts without a
+      # timestamp prefix fall back to a bare `<slug>.md`.
+      case "$FILE" in
+        [0-9][0-9][0-9][0-9][0-9][0-9][0-9][0-9]-[0-9][0-9][0-9][0-9][0-9][0-9]-*)
+          DEST_SLUG="$(printf '%s' "$FILE" | cut -c1-15)-$SLUG"
+          ;;
+        *)
+          DEST_SLUG="$SLUG"
+          ;;
+      esac
+      DEST_PATH=$(resolve_unique_slug_path "$DEST_SLUG")
       printf '%s\n' "$CONTENT" > "$DEST_PATH"
       rm -- "$SRC_PATH"
       log "rewrite: $FILE → $(basename "$DEST_PATH")"

package/CHANGELOG.md

@@ -4,6 +4,23 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.13.67] - 2026-05-21
+
+### Changed
+
+- Правило **`changelog`**: перевірка `changelog/consistency` більше не вимагає version-bump і запису в `CHANGELOG.md` за зміни синхронізованого з `@nitra/cursor` інструментарію. Інверсію шляхів розширено: до `docs/` / `doc/` додано префікси `.cursor/` (канонічні правила та скіли) і `.claude/` (ADR-хуки). Причина: синк tooling-пакета — це дзеркало `@nitra/cursor`, а не зміна логіки воркспейсу, тож раніше кожен `npx @nitra/cursor` тягнув за собою зайвий bump і секцію CHANGELOG, де описувалося лише оновлення інструментарію. Кореневі `AGENTS.md` / `CLAUDE.md` окремого запису в інверсії не потребують — їх покриває пропуск кореня монорепо (нижче). Джерело правил у самому репо `@nitra/cursor` лежить під `npm/`, тож на нього інверсія не поширюється — реальні зміни правил і далі вимагають bump. Зачеплено: [check.mjs](rules/changelog/fix/consistency/check.mjs) (`CHANGELOG_IGNORE_PATH_PREFIXES`), [changelog.mdc](rules/changelog/changelog.mdc) (секція «Інверсія», bump `2.5` → `2.6`).
+- Правило **`changelog`**: корінь монорепо (воркспейс `.` за наявності підпакетів) більше не перевіряється на bump/CHANGELOG. Причина: кореневий `package.json` монорепо — це glue/конфіг/tooling (`private`, `workspaces`), власного продуктового CHANGELOG він не веде, а помітні зміни документують підпакети. Раніше будь-яка правка в корені (конфіги, синк правил, bump `@nitra/cursor` у `devDependencies`) хибно вимагала bump кореневої `version`. Одно-пакетні репозиторії (корінь = єдиний воркспейс) перевіряються як і раніше. Зачеплено: [check.mjs](rules/changelog/fix/consistency/check.mjs) (`isMonorepoRoot` у `check()`), [changelog.mdc](rules/changelog/changelog.mdc).
+
+### Fixed
+
+- Правило **`changelog`**: перевірка `changelog/consistency` коректно опрацьовує файли з не-ASCII іменами (кирилиця тощо). `git diff` / `git ls-files` без `-z` застосовують `core.quotePath` і повертають такі шляхи у C-quoted формі `"docs/\320\262..."` — рядок не збігався з префіксами інверсії, тож, наприклад, чернетка ADR з кириличною назвою під `docs/` хибно вважалася зміною, що потребує bump, і валила перевірку. Усі переліки шляхів тепер читаються через `-z` (`NUL`-розділення, без quoting). Зачеплено: [check.mjs](rules/changelog/fix/consistency/check.mjs) (`splitNulPaths`, `listChangedPathsAgainstBase`), [check.test.mjs](rules/changelog/fix/consistency/check.test.mjs) (тести quotePath, синку tooling і пропуску кореня монорепо).
+
+## [1.13.66] - 2026-05-20
+
+### Changed
+
+- `adr`: `normalize-decisions.sh` тепер зберігає `YYYYMMDD-HHMMSS-`-префікс чернетки в імені clean-файлу — операція `rewrite` пише результат у `<timestamp>-<slug>.md` замість bare `<slug>.md`. Причина: під час нормалізації LLM генерує `slug` заново, тож раніше чернетка `20260518-092807-foo.md` ставала clean-файлом з абсолютно іншим іменем `bar.md` — назва «стрибала» цілком. Тепер timestamp-префікс лишається стабільним якорем: між draft і clean змінюється лише slug-частина, а `docs/adr/` сортується хронологічно (capture-час). Чернетки без `YYYYMMDD-HHMMSS-`-префікса лишаються на fallback bare `<slug>.md`. Колізії resolve'яться як і раніше — детермінований суфікс `-2`, `-3`, тепер на повному імені `<timestamp>-<slug>-N.md`. Зачеплено: [normalize-decisions.sh](.claude-template/hooks/normalize-decisions.sh) (нова `case`-гілка у rewrite-операції обчислює `DEST_SLUG` з timestamp-префіксом перед `resolve_unique_slug_path`), [adr.mdc](rules/adr/adr.mdc) (опис clean-формату, рядок таблиці `rewrite`, дерево каталогу `docs/adr/` й абзац про `slug`), [SKILL.md](skills/adr-normalize/SKILL.md) (опис rewrite-результату й дублів імен). Bump `adr.mdc` `2.0` → `2.1`.
+
 ## [1.13.65] - 2026-05-20
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.13.65",
+  "version": "1.13.67",
   "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.0'
+version: '2.1'
 ---
 
 ## MADR v4 і дві фази
@@ -19,7 +19,7 @@ ADR живуть у єдиному каталозі **`docs/adr/`**. Clean 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` або людина руками.
+- **Clean** — файл без frontmatter, з kebab-case-іменем. `normalize-decisions.sh` зберігає timestamp-префікс чернетки → `YYYYMMDD-HHMMSS-<slug>.md` (наприклад `20260518-092807-ланцюжок-запуску-abie.md`); створений руками clean-файл може мати просто `<slug>.md`.
 
 `normalize-decisions.sh` ніколи не чіпає clean-файли — крім випадку `merge-into`, коли дописує `## Update YYYY-MM-DD` в кінець наявного clean-файлу.
 
@@ -44,10 +44,10 @@ LLM повертає масив операцій:
 | `op` | Семантика | Поля |
 | --- | --- | --- |
 | `delete` | Чернетка тривіальна / повністю покрита іншим clean-ADR-ом. | `file`, `reason` |
-| `rewrite` | Чернетка стає окремим clean-файлом MADR v4 minimal: frontmatter знімається, ім'я → `<slug>.md`, додаються `**Status:** Accepted`, `**Date:**` з `captured` і canonical MADR headings. | `file`, `slug`, `content` |
+| `rewrite` | Чернетка стає окремим clean-файлом MADR v4 minimal: frontmatter знімається, ім'я → `<timestamp>-<slug>.md` (timestamp-префікс чернетки збережено), додаються `**Status:** Accepted`, `**Date:**` з `captured` і canonical MADR headings. | `file`, `slug`, `content` |
 | `merge-into` | Чернетка повторює тему вже існуючого clean-файлу; дописуємо `## Update YYYY-MM-DD` у кінець `target`. | `file`, `target`, `additions` |
 
-`slug` — kebab-case українською (`ланцюжок-запуску-abie`, `npm-publish-flow`); англійські технічні терміни лишаються англійською без транслітерації. Колізія slug-ів обробляється детермінованим суфіксом `-2`, `-3`.
+`slug` — kebab-case українською (`ланцюжок-запуску-abie`, `npm-publish-flow`); англійські технічні терміни лишаються англійською без транслітерації. До імені clean-файлу скрипт додає `YYYYMMDD-HHMMSS-` чернетки, тож запис лишається прив'язаним до часу capture, а `docs/adr/` сортується хронологічно. Колізія імен обробляється детермінованим суфіксом `-2`, `-3`.
 
 ### Жодних git-операцій
 
@@ -82,8 +82,8 @@ LLM повертає масив операцій:
 
 ```text
 docs/adr/
-├── YYYYMMDD-HHMMSS-<sid>.md   # drafts (frontmatter session:/captured:/transcript:)
-└── <slug>.md                  # clean ADR-и (без frontmatter)
+├── YYYYMMDD-HHMMSS-<sid>.md     # drafts (frontmatter session:/captured:/transcript:)
+└── YYYYMMDD-HHMMSS-<slug>.md    # clean ADR-и (без frontmatter, timestamp-префікс чернетки збережено)
 .claude/hooks/
 ├── capture-decisions.sh       # auto-synced з пакета
 ├── normalize-decisions.sh     # auto-synced з пакета

package/rules/changelog/changelog.mdc

@@ -1,6 +1,6 @@
 ---
 description: CHANGELOG.md в кожному workspace, з двома моделями бази порівняння (npm і Python)
-version: '2.5'
+version: '2.6'
 alwaysApply: true
 ---
 
@@ -14,7 +14,7 @@ alwaysApply: true
 
 **Тригер шляхів (приклади):** `npm/**`, `packages/foo/**`, будь-який каталог з власним `package.json` / `pyproject.toml`, куди потрапили правки.
 
-**Інверсія (bump не потрібен):** лише `docs/` / `doc/`; лише `.gitignore`; лише сам релізний крок (`CHANGELOG.md` + `version`).
+**Інверсія (bump не потрібен):** лише `docs/` / `doc/`; синхронізований із `@nitra/cursor` інструментарій (`.cursor/`, `.claude/`); лише `.gitignore`; лише сам релізний крок (`CHANGELOG.md` + `version`). **Корінь монорепо** (воркспейс `.` за наявності підпакетів) не перевіряється взагалі — отже й кореневі `AGENTS.md` / `CLAUDE.md` та bump `@nitra/cursor` у `devDependencies`.
 
 **Pre-commit (людина):** `hk` у цьому репо також запускає `check changelog` при змінах під `npm/**` — агент не покладайся лише на commit hook; виконай кроки 1–3 **до** фінальної відповіді.
 
@@ -36,10 +36,12 @@ alwaysApply: true
 **Інверсія (за замовчуванням не вимагають bump/CHANGELOG):**
 
 - зміни **лише** під `docs/` або `doc/`;
+- синхронізований із `@nitra/cursor` інструментарій під `.cursor/` (канонічні правила та скіли) і `.claude/` (ADR-хуки) — це дзеркало tooling-пакета, а не логіка воркспейсу;
+- будь-які зміни в **корені монорепо** (воркспейс `.` за наявності підпакетів) — корінь веде glue/конфіг/tooling, власного CHANGELOG не має; помітні зміни документують підпакети. Сюди потрапляють і кореневі `AGENTS.md` / `CLAUDE.md`, і bump `@nitra/cursor` у `devDependencies`;
 - файли під **`.gitignore`**;
 - правки **лише** `CHANGELOG.md` або поля `version` у маніфесті як сам релізний крок.
 
-**Вимагають bump + нову секцію CHANGELOG** — усі інші зміни в каталозі workspace (код, rego, правила, скіли, конфіги, тести тощо).
+**Вимагають bump + нову секцію CHANGELOG** — усі інші зміни в каталозі workspace (код, rego, правила, скіли, конфіги, тести тощо). Виняток `.cursor/` / `.claude/` **не** поширюється на джерело правил у репо `@nitra/cursor` — воно лежить під `npm/`, тож зміни в ньому далі вимагають bump.
 
 Перевірка програмна (`changelog/fix/consistency/check.mjs`).
 

package/rules/changelog/fix/consistency/check.mjs

@@ -38,11 +38,14 @@ const FEATURE_BASE_BRANCH_CANDIDATES = Object.freeze(['dev', 'main'])
 /** Гілка `dev`: local-only не активний (крім незакомічених registry-published). */
 const LOCAL_ONLY_SKIP_BRANCH = 'dev'
 
-/** Префікси шляхів (posix), які не вважаються релізними змінами — інверсія glob (n-changelog.mdc). */
-const CHANGELOG_IGNORE_PATH_PREFIXES = Object.freeze(['docs/', 'doc/'])
-
-/** Точні шляхи каталогів документації (posix), без bump. */
-const CHANGELOG_IGNORE_PATH_EXACT = Object.freeze(['docs', 'doc'])
+/**
+ * Префікси шляхів (posix), які не вважаються релізними змінами — інверсія glob (n-changelog.mdc):
+ * документація (`docs/`, `doc/`) та синхронізований із `@nitra/cursor` інструментарій
+ * (`.cursor/` — канонічні правила й скіли, `.claude/` — ADR-хуки). Останнє — дзеркало tooling-пакета,
+ * не логіка самого воркспейсу, тож bump CHANGELOG не потрібен. Джерело правил у репо `@nitra/cursor`
+ * лежить під `npm/`, тож на нього ця інверсія не поширюється.
+ */
+const CHANGELOG_IGNORE_PATH_PREFIXES = Object.freeze(['docs/', 'doc/', '.cursor/', '.claude/'])
 
 /** Таймаут на `npm view` / PyPI (мс) */
 const REGISTRY_TIMEOUT_MS = 10_000
@@ -117,9 +120,6 @@ async function resolveBranchRef(branchName) {
  */
 function isChangelogIgnoredPath(relPath) {
   const p = relPath.replaceAll('\\', '/').replace(LEADING_DOTSLASH_RE, '')
-  if (CHANGELOG_IGNORE_PATH_EXACT.includes(p)) {
-    return true
-  }
   return CHANGELOG_IGNORE_PATH_PREFIXES.some(prefix => p.startsWith(prefix))
 }
 
@@ -196,29 +196,31 @@ function pathspecForWorkspace(ws, subWorkspaces) {
   return ['.', ...subWorkspaces.filter(s => s !== '.').map(s => `:(exclude)${s}/`)]
 }
 
+/**
+ * Шляхи з `NUL`-розділеного виводу git (прапорець `-z`).
+ *
+ * `-z` критичний: без нього git застосовує `core.quotePath` і повертає не-ASCII імена файлів
+ * (кирилиця тощо) у C-quoted формі `"docs/\320\262..."`. Такий рядок не збігається з
+ * префіксами інверсії (`docs/`, `.cursor/`, ...), тож файл хибно вважався б зміною, що потребує bump.
+ * @param {string | null} nulSeparated сирий вивід git або `null`
+ * @returns {string[]} шляхи без обгортки/escape
+ */
+function splitNulPaths(nulSeparated) {
+  if (typeof nulSeparated !== 'string') {
+    return []
+  }
+  return nulSeparated.split('\0').filter(p => p.length > 0)
+}
+
 /**
  * @param {string} baseRef параметр
  * @param {string[]} pathspec параметр
  * @returns {Promise<string[]>} результат
  */
 async function listChangedPathsAgainstBase(baseRef, pathspec) {
-  /**
-  @type {string[]}
-   */
-  const out = []
-  const diffArgs =
-    baseRef === 'HEAD'
-      ? ['diff', '--name-only', 'HEAD', '--', ...pathspec]
-      : ['diff', '--name-only', baseRef, '--', ...pathspec]
-  const diffOut = await gitOrNull(diffArgs)
-  if (typeof diffOut === 'string' && diffOut.trim().length > 0) {
-    out.push(...diffOut.trim().split('\n'))
-  }
-  const untrackedOut = await gitOrNull(['ls-files', '--others', '--exclude-standard', '--', ...pathspec])
-  if (typeof untrackedOut === 'string' && untrackedOut.trim().length > 0) {
-    out.push(...untrackedOut.trim().split('\n'))
-  }
-  return [...new Set(out)]
+  const diffOut = await gitOrNull(['diff', '--name-only', '-z', baseRef, '--', ...pathspec])
+  const untrackedOut = await gitOrNull(['ls-files', '--others', '--exclude-standard', '-z', '--', ...pathspec])
+  return [...new Set([...splitNulPaths(diffOut), ...splitNulPaths(untrackedOut)])]
 }
 
 /**
@@ -551,6 +553,9 @@ export async function check(opts = {}) {
 
   const workspaces = await getMonorepoProjectRootDirs(process.cwd())
   const subWorkspaces = workspaces.filter(w => w !== '.')
+  // Корінь монорепо (`.` за наявності підпакетів) — це glue/конфіг/tooling, а не логіка
+  // продукту: власного CHANGELOG він не веде, помітні зміни документують підпакети.
+  const isMonorepoRoot = subWorkspaces.length > 0
 
   /**
   @type {import('../../../../scripts/utils/package-manifest.mjs').PackageManifest[]}
@@ -562,6 +567,12 @@ export async function check(opts = {}) {
   const localOnly = []
 
   for (const ws of workspaces) {
+    if (ws === '.' && isMonorepoRoot) {
+      pass(
+        '<root>: корінь монорепо (glue/конфіг/tooling) — перевірку CHANGELOG пропущено; помітні зміни документують підпакети'
+      )
+      continue
+    }
     const manifest = await readPackageManifest(ws)
     if (!manifest) {
       continue

package/skills/adr-normalize/SKILL.md

@@ -48,7 +48,7 @@ description: >-
    git diff docs/adr/
    ```
 
-   Видалені файли — `delete`-операція. Нові файли `<slug>.md` — `rewrite`. Модифіковані clean-файли — `merge-into`.
+   Видалені файли — `delete`-операція. Нові файли `<timestamp>-<slug>.md` (timestamp-префікс чернетки збережено) — `rewrite`. Модифіковані clean-файли — `merge-into`.
 
 4. **Прийняти / відкотити:**
    - Прийняти все: `git add docs/adr/ && git commit -m "adr: normalize batch"`.
@@ -67,4 +67,4 @@ description: >-
 
 - LLM повернув криву JSON → у логу буде `invalid JSON response (first 200 chars): …`. Запусти ще раз — нерідко це разовий збій.
 - Скрипт виходить миттєво без логу → перевір `ADR_NORMALIZE_RUNNING` у env (recursion guard) і чи репо не у стані merge/rebase.
-- Перейменування зробило слаги-дублі (`<slug>-2.md`) → це нормально, скрипт детермінований; під час review можна обʼєднати руками й видалити `-2`.
+- Перейменування зробило дублі імен (`<timestamp>-<slug>-2.md`) → це нормально, скрипт детермінований; під час review можна обʼєднати руками й видалити `-2`.