@nitra/cursor 1.13.62 → 1.13.64

package/CHANGELOG.md

@@ -4,6 +4,30 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.13.64] - 2026-05-20
+
+### Added
+
+- **`sync-claude-config`**: при увімкненому правилі `adr` `npx @nitra/cursor` дописує в кореневий `.gitignore` канонічний фрагмент `rules/adr/fix/hooks/template/.gitignore.snippet` (`.claude/hooks/*.log`, `.normalize-state`, `.normalize.lock`) — логи ADR Stop-hook більше не потрапляють у git status.
+
+### Changed
+
+- Правило **`adr`**: посилання на канон `.gitignore.snippet` і згадка автоматичного дописування під час sync.
+- **`.gitignore.snippet`**: додано базові рядки `node_modules/`, `dist/`, `*.secret` (як у кореневому `.gitignore` пакета).
+
+## [1.13.63] - 2026-05-20
+
+### Fixed
+
+- **`check changelog`**: новий local-only воркспейс (маніфест відсутній на merge-base з `dev`/`main`, напр. `demo/` на `main`) більше не вимагає штучного bump — достатньо початкової `version` і запису в `CHANGELOG.md` (раніше `Vbase === ∅` помилково трактувалось як «version не підвищено»).
+- **`check changelog`**: на гілці **`main`** база порівняння — **`origin/main`** (або `HEAD~1` без remote), не `dev`; коли `origin/main` збігається з `HEAD`, diff порожній (не fallback на `HEAD~1`); feature-гілки — `merge-base` з `dev`, інакше з `main` (репо без `dev`).
+
+### Changed
+
+- Правило **`changelog`** ([changelog.mdc](rules/changelog/changelog.mdc) `2.5`): блок **STOP** перенесено на початок (тригер шляхів, інверсія, три кроки до завершення відповіді) — щоб агент не пропускав bump після правок у `npm/skills/` тощо, коли чеклист губився внизу довгого alwaysApply-правила.
+- **`.cursor/rules/scripts.mdc`**: секція «Завершення задачі після правок у пакетному workspace» — cross-STOP з **n-changelog** (останні кроки сесії перед відповіддю).
+- **`hk.pkl`**: pre-commit крок **`npm-changelog`** (`glob: npm/**`, `bun ./npm/bin/n-cursor.js check changelog`) — програмний стоп-кран при commit, якщо агент забув bump.
+
 ## [1.13.62] - 2026-05-20
 
 ### Changed

package/bin/n-cursor.js

@@ -1274,6 +1274,7 @@ async function runSync() {
     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 (result.gitignoreAdr) parts.push('.gitignore (adr fragment)')
     if (parts.length > 0) {
       console.log(`🤖 Claude-конфіг: ${parts.join(', ')}`)
     }

package/package.json

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

package/rules/adr/adr.mdc

@@ -95,7 +95,7 @@ docs/adr/
 └── hooks.json                 # Cursor Agent stop-hooks для тих самих скриптів
 ```
 
-`.gitignore` повинен містити рядки, що покривають **`.claude/hooks/*.log`** і службові файли normalize (`.claude/hooks/.normalize-*`).
+`.gitignore` у корені проєкту повинен містити базові рядки (`node_modules/`, `dist/`, `*.secret`) і патерни для ADR Stop-hook (**`.claude/hooks/*.log`**, `.claude/hooks/.normalize-state`, `.claude/hooks/.normalize.lock`). Канонічний фрагмент (дописується `npx @nitra/cursor`, коли правило `adr` увімкнене): [.gitignore.snippet](./fix/hooks/template/.gitignore.snippet).
 
 ## Stop-hook у `.claude/settings.json`
 

package/rules/adr/fix/hooks/template/.gitignore.snippet

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+*.secret
+
+# @nitra/cursor (adr) — локальні артефакти Stop-hook, не коміти
+.claude/hooks/*.log
+.claude/hooks/.normalize-state
+.claude/hooks/.normalize.lock

package/rules/changelog/changelog.mdc

@@ -1,9 +1,25 @@
 ---
 description: CHANGELOG.md в кожному workspace, з двома моделями бази порівняння (npm і Python)
-version: '2.4'
+version: '2.5'
 alwaysApply: true
 ---
 
+## STOP — перед завершенням відповіді агента
+
+> **Якщо в цій сесії ти змінив(ла) файли в пакетному workspace** (код, rego, правила, скіли, скрипти, конфіги, тести — **не** лише `docs/` / `doc/`) — **не завершуй задачу**, поки не виконаєш **усі три** кроки нижче в **тому ж** наборі змін. Це не «опційно після синку» — це частина PR.
+
+1. **`version`** у `<ws>/package.json` (або `[project].version` у `pyproject.toml`) → **patch +1** відносно `git show HEAD:<ws>/package.json`, якщо ще не піднято.
+2. **`CHANGELOG.md`** того workspace → **нова** секція `## [версія] - YYYY-MM-DD` **зверху** (не bullet-и в стару версію).
+3. **`npx @nitra/cursor check changelog`** (у репо `@nitra/cursor`: `bun ./npm/bin/n-cursor.js check changelog`) → exit **`0`**.
+
+**Тригер шляхів (приклади):** `npm/**`, `packages/foo/**`, будь-який каталог з власним `package.json` / `pyproject.toml`, куди потрапили правки.
+
+**Інверсія (bump не потрібен):** лише `docs/` / `doc/`; лише `.gitignore`; лише сам релізний крок (`CHANGELOG.md` + `version`).
+
+**Pre-commit (людина):** `hk` у цьому репо також запускає `check changelog` при змінах під `npm/**` — агент не покладайся лише на commit hook; виконай кроки 1–3 **до** фінальної відповіді.
+
+---
+
 У кожному **пакетному** workspace (каталог із `package.json` або `pyproject.toml`) має бути власний **`CHANGELOG.md`**. Спільного на репозиторій змісту змін **не існує** — кожен пакет веде свій.
 
 **Маніфест версії:**
@@ -13,7 +29,9 @@ alwaysApply: true
 
 Каталоги лише з `pyproject.toml` (без `package.json`) теж враховуються; `node_modules/`, `.venv/`, `venv/` при пошуку ігноруються.
 
-## Чеклист агента (будь-який репозиторій з цим правилом)
+## Чеклист агента (деталі)
+
+Повний алгоритм — у блоці **STOP** вище; тут лише уточнення.
 
 **Інверсія (за замовчуванням не вимагають bump/CHANGELOG):**
 
@@ -21,13 +39,7 @@ alwaysApply: true
 - файли під **`.gitignore`**;
 - правки **лише** `CHANGELOG.md` або поля `version` у маніфесті як сам релізний крок.
 
-**Вимагають bump + нову секцію CHANGELOG** — усі інші зміни в каталозі workspace (код, rego, правила, конфіги, тести тощо).
-
-Перед завершенням задачі:
-
-1. **`version`** у `<ws>/package.json` або `[project].version` у `<ws>/pyproject.toml` підвищено (build/patch +1 на PR), якщо зміни входять у реліз.
-2. **`CHANGELOG.md`** — **нова** секція `## [версія] - YYYY-MM-DD` зверху (не дописуй bullet-и в стару версію).
-3. **`npx @nitra/cursor check changelog`** — exit `0`.
+**Вимагають bump + нову секцію CHANGELOG** — усі інші зміни в каталозі workspace (код, rego, правила, скіли, конфіги, тести тощо).
 
 Перевірка програмна (`changelog/fix/consistency/check.mjs`).
 
@@ -48,14 +60,14 @@ alwaysApply: true
 
 ### local-only
 
-**npm:** `private: true` або без `files`. **Python:** без пари name+version для реєстру. База = **`dev` або `main`** (перша наявна), `git merge-base`:
+**npm:** `private: true` або без `files`. **Python:** без пари name+version для реєстру. База залежить від гілки:
 
 1. На **`dev`** local-only не активний (крім незакомічених registry-published).
-2. На feature-гілці — bump + CHANGELOG **раз на PR**.
-3. Після merge на інтеграційну гілку diff порожній → pass.
-4. Direct-commit на `main` ловиться так само.
+2. На **`main`** — diff від **`origin/main`** (попередній опублікований `main`); без remote — від `HEAD~1`. **`dev` не використовується** як база на `main`.
+3. На **feature-гілці** — `merge-base` з **`dev`**, якщо є; інакше з **`main`** (репо без `dev`).
+4. Bump + CHANGELOG **раз на PR** / direct-commit на `main`.
 
-Якщо немає git або немає `dev`/`main` — local-only пропускається.
+Якщо немає git або немає `dev`/`main`/`origin/main` — local-only пропускається.
 
 ## Формат CHANGELOG.md
 

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

@@ -10,8 +10,9 @@
  *    Якщо локальна версія відрізняється — потрібен CHANGELOG; для npm також `"CHANGELOG.md"`
  *    у `files`. Якщо версії збігаються, але в git є релевантні зміни без bump — fail.
  *
- * 2) **local-only** (приватні npm, без `files`, Python без імені/версії для реєстру): PR-scoped
- *    перевірка проти `dev` / `main` через `git merge-base`.
+ * 2) **local-only** (приватні npm, без `files`, Python без імені/версії для реєстру):
+ *    feature-гілка — `merge-base` з `dev`, інакше з `main`; на `main` — diff від
+ *    `origin/main` (попередній опублікований main) або `HEAD~1` без remote.
  *
  * Усі `git` і зовнішні виклики — через `execFile` / `fetch`, без shell-інтерполяції.
  */
@@ -31,11 +32,11 @@ import {
 
 const execFileAsync = promisify(execFile)
 
-/** Кандидати інтеграційної гілки (перша наявна в репо; див. n-changelog.mdc) */
-const BASE_BRANCH_CANDIDATES = Object.freeze(['dev', 'main'])
+/** Кандидати інтеграційної гілки для feature-гілок (перша наявна; див. n-changelog.mdc). */
+const FEATURE_BASE_BRANCH_CANDIDATES = Object.freeze(['dev', 'main'])
 
-/** Гілки, на яких local-only перевірку пропускаємо (крім незакомічених registry-published). */
-const INTEGRATION_BRANCHES = 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/'])
@@ -78,14 +79,6 @@ async function currentBranchName() {
   return typeof out === 'string' ? out.trim() : null
 }
 
-/**
- * @param {string | null} branch параметр
- * @returns {boolean} результат
- */
-function isIntegrationBranch(branch) {
-  return branch !== null && INTEGRATION_BRANCHES.includes(branch)
-}
-
 /**
  * @param {string} ref параметр
  * @returns {string} результат
@@ -94,6 +87,30 @@ function baseRefLabel(ref) {
   return ref.startsWith('origin/') ? ref.slice('origin/'.length) : ref
 }
 
+/**
+ * @param {string} ancestor предок
+ * @param {string} descendant нащадок
+ * @returns {Promise<boolean>} результат
+ */
+async function isGitAncestor(ancestor, descendant) {
+  const out = await gitOrNull(['merge-base', '--is-ancestor', ancestor, descendant])
+  return typeof out === 'string' && out.trim() === 'true'
+}
+
+/**
+ * @param {string} branchName локальна або remote-tracking гілка
+ * @returns {Promise<string | null>} ref для git або null
+ */
+async function resolveBranchRef(branchName) {
+  for (const ref of [branchName, `origin/${branchName}`]) {
+    const out = await gitOrNull(['rev-parse', '--verify', '--quiet', ref])
+    if (typeof out === 'string' && out.trim().length > 0) {
+      return ref
+    }
+  }
+  return null
+}
+
 /**
  * @param {string} relPath параметр
  * @returns {boolean} результат
@@ -119,21 +136,6 @@ async function isPathGitIgnored(relPath) {
   }
 }
 
-/**
- * @returns {Promise<string | null>} результат
- */
-async function resolveBaseRef() {
-  for (const name of BASE_BRANCH_CANDIDATES) {
-    for (const ref of [name, `origin/${name}`]) {
-      const out = await gitOrNull(['rev-parse', '--verify', '--quiet', ref])
-      if (typeof out === 'string' && out.trim().length > 0) {
-        return ref
-      }
-    }
-  }
-  return null
-}
-
 /**
  * @param {string} baseRef параметр
  * @returns {Promise<string | null>} результат
@@ -145,6 +147,45 @@ async function resolveMergeBase(baseRef) {
   return sha.length > 0 ? sha : null
 }
 
+/**
+ * Точка порівняння git для changelog (ref або SHA для `git diff` / `git show`).
+ * @param {string | null} branch поточна гілка
+ * @returns {Promise<{ ref: string, label: string } | null>} результат
+ */
+async function resolveChangelogComparisonPoint(branch) {
+  if (branch === LOCAL_ONLY_SKIP_BRANCH) {
+    return null
+  }
+
+  if (branch === 'main') {
+    const originMainRaw = await gitOrNull(['rev-parse', '--verify', '--quiet', 'origin/main'])
+    const originMainSha = originMainRaw?.trim()
+    const headRaw = await gitOrNull(['rev-parse', 'HEAD'])
+    const headSha = headRaw?.trim()
+    if (originMainSha && headSha && (originMainSha === headSha || (await isGitAncestor('origin/main', 'HEAD')))) {
+      return { ref: 'origin/main', label: 'main' }
+    }
+    const parent = await gitOrNull(['rev-parse', '--verify', '--quiet', 'HEAD~1'])
+    if (typeof parent === 'string' && parent.trim().length > 0) {
+      return { ref: parent.trim(), label: 'main~1' }
+    }
+    return null
+  }
+
+  for (const name of FEATURE_BASE_BRANCH_CANDIDATES) {
+    const baseRef = await resolveBranchRef(name)
+    if (!baseRef) {
+      continue
+    }
+    const mergeBase = await resolveMergeBase(baseRef)
+    if (!mergeBase) {
+      continue
+    }
+    return { ref: mergeBase, label: baseRefLabel(baseRef) }
+  }
+  return null
+}
+
 /**
  * @param {string} ws параметр
  * @param {string[]} subWorkspaces параметр
@@ -355,7 +396,8 @@ async function checkPublishedWorkspacePendingGitChanges(manifest, Vcurrent, subW
   }
 
   const branch = await currentBranchName()
-  if (isIntegrationBranch(branch)) {
+
+  if (branch === LOCAL_ONLY_SKIP_BRANCH) {
     if (await workspaceHasRelevantChangesAgainstBase('HEAD', manifest.ws, subWorkspaces)) {
       fail(
         `${label}: у registry-published пакеті є незакомічені зміни при version ${Vcurrent}, що вже в реєстрі. ` +
@@ -365,28 +407,32 @@ async function checkPublishedWorkspacePendingGitChanges(manifest, Vcurrent, subW
     return
   }
 
-  const baseRef = await resolveBaseRef()
-  if (!baseRef) {
-    return
-  }
-  const mergeBase = await resolveMergeBase(baseRef)
-  if (!mergeBase) {
-    return
-  }
-  if (!(await workspaceHasRelevantChangesAgainstBase(mergeBase, manifest.ws, subWorkspaces))) {
-    return
+  const comparison = await resolveChangelogComparisonPoint(branch)
+  if (comparison && (await workspaceHasRelevantChangesAgainstBase(comparison.ref, manifest.ws, subWorkspaces))) {
+    const Vbase = await readBaseVersion(comparison.ref, manifest)
+    const baseLabel = comparison.label
+    if (Vbase === null) {
+      pass(
+        `${label}: новий registry-published воркспейс (на ${baseLabel} відсутній ${mf}) — перевіряємо CHANGELOG для ${Vcurrent}`
+      )
+      await verifyChangelogEntry(manifest.ws, Vcurrent, pass, fail)
+      checkNpmFilesArrayContainsChangelog(manifest, pass, fail)
+    } else if (Vbase === Vcurrent) {
+      fail(
+        `${label}: у цій гілці є зміни в registry-published пакеті, але version у ${mf} ` +
+          `не підвищено (на ${baseLabel} — ${Vbase}). Bump + запис у CHANGELOG.md обов'язкові (n-changelog.mdc)`
+      )
+    } else {
+      pass(`${label}: version змінено (${Vbase} → ${Vcurrent}) — очікується запис CHANGELOG після bump`)
+    }
   }
 
-  const Vbase = await readBaseVersion(mergeBase, manifest)
-  const baseLabel = baseRefLabel(baseRef)
-  if (Vbase === null || Vbase === Vcurrent) {
+  if (branch === 'main' && (await workspaceHasRelevantChangesAgainstBase('HEAD', manifest.ws, subWorkspaces))) {
     fail(
-      `${label}: у цій гілці є зміни в registry-published пакеті, але version у ${mf} ` +
-        `не підвищено (на ${baseLabel} — ${Vbase ?? '∅'}). Bump + запис у CHANGELOG.md обов'язкові на PR (n-changelog.mdc)`
+      `${label}: у registry-published пакеті є незакомічені зміни при version ${Vcurrent}, що вже в реєстрі. ` +
+        `Підвищ version у ${mf} і додай запис у CHANGELOG.md (n-changelog.mdc)`
     )
-    return
   }
-  pass(`${label}: version змінено (${Vbase} → ${Vcurrent}) — очікується запис CHANGELOG після bump`)
 }
 
 /**
@@ -426,13 +472,13 @@ async function checkPublishedWorkspace(manifest, subWorkspaces, getPublishedVers
 }
 
 /**
- * @param {string} mergeBase параметр
+ * @param {string} comparisonRef ref/SHA для `git diff` / `git show`
  * @param {import('../../../../scripts/utils/package-manifest.mjs').PackageManifest} manifest параметр
  * @param {string} baseLabel параметр
  * @param {(msg: string) => void} pass параметр
  * @param {(msg: string) => void} fail параметр
  */
-async function checkLocalOnlyChangedWorkspace(mergeBase, manifest, baseLabel, pass, fail) {
+async function checkLocalOnlyChangedWorkspace(comparisonRef, manifest, baseLabel, pass, fail) {
   const label = workspaceLabel(manifest)
   const mf = manifestFilePath(manifest.ws, manifest)
   const Vcurrent = manifest.version
@@ -440,10 +486,16 @@ async function checkLocalOnlyChangedWorkspace(mergeBase, manifest, baseLabel, pa
     fail(`${label}: у ${mf} відсутнє поле version (потрібне для запису в CHANGELOG)`)
     return
   }
-  const Vbase = await readBaseVersion(mergeBase, manifest)
-  if (Vbase === null || Vbase === Vcurrent) {
+  const Vbase = await readBaseVersion(comparisonRef, manifest)
+  if (Vbase === null) {
+    pass(`${label}: новий воркспейс (на ${baseLabel} відсутній ${mf}) — перевіряємо CHANGELOG для ${Vcurrent}`)
+    if (!(await verifyChangelogEntry(manifest.ws, Vcurrent, pass, fail))) return
+    checkNpmFilesArrayContainsChangelog(manifest, pass, fail)
+    return
+  }
+  if (Vbase === Vcurrent) {
     fail(
-      `${label}: у цій гілці є зміни, але version у ${mf} не підвищено (на ${baseLabel} — ${Vbase ?? '∅'}). Bump + запис у CHANGELOG.md обов'язкові на PR`
+      `${label}: у цій гілці є зміни, але version у ${mf} не підвищено (на ${baseLabel} — ${Vbase}). Bump + запис у CHANGELOG.md обов'язкові на PR`
     )
     return
   }
@@ -466,30 +518,24 @@ async function runLocalOnlyChecks(localOnly, subWorkspaces, pass, fail) {
     return
   }
   const branch = await currentBranchName()
-  if (branch === 'dev') {
+  if (branch === LOCAL_ONLY_SKIP_BRANCH) {
     pass('changelog: поточна гілка = dev — local-only перевірку пропущено')
     return
   }
-  const baseRef = await resolveBaseRef()
-  if (!baseRef) {
+  const comparison = await resolveChangelogComparisonPoint(branch)
+  if (!comparison) {
     pass('changelog: ref dev/main (та origin/*) не знайдено — local-only перевірку пропущено')
     return
   }
-  const mergeBase = await resolveMergeBase(baseRef)
-  if (!mergeBase) {
-    pass(`changelog: merge-base з ${baseRef} не знайдено — local-only перевірку пропущено`)
-    return
-  }
 
-  const baseLabel = baseRefLabel(baseRef)
   let checkedAny = false
   for (const manifest of localOnly) {
-    if (!(await workspaceHasRelevantChangesAgainstBase(mergeBase, manifest.ws, subWorkspaces))) continue
+    if (!(await workspaceHasRelevantChangesAgainstBase(comparison.ref, manifest.ws, subWorkspaces))) continue
     checkedAny = true
-    await checkLocalOnlyChangedWorkspace(mergeBase, manifest, baseLabel, pass, fail)
+    await checkLocalOnlyChangedWorkspace(comparison.ref, manifest, comparison.label, pass, fail)
   }
   if (!checkedAny) {
-    pass(`changelog: local-only воркспейси без змін відносно merge-base(${baseRef})`)
+    pass(`changelog: local-only воркспейси без змін відносно ${comparison.label}`)
   }
 }
 

package/scripts/sync-claude-config.mjs

@@ -18,6 +18,10 @@
  *   Stop-hook (батч-нормалізація чернеток); умови — ті самі, що для `capture`.
  * - `.cursor/hooks.json` — **merge**: користувацькі hooks зберігаються; ADR stop
  *   entries додаються, коли правило `adr` увімкнене, і видаляються, коли вимкнене.
+ * - `.gitignore` — **merge** (лише з `adr`): дописує відсутні рядки з канонічного
+ *   фрагмента `rules/adr/fix/hooks/template/.gitignore.snippet` (`node_modules/`, `dist/`,
+ *   `*.secret`, логи capture/normalize, `.normalize-state`, `.normalize.lock`); існуючі
+ *   рядки не перезаписуються.
  *
  * Опт-аут — `claude-config: false` у `.n-cursor.json`.
  */
@@ -51,6 +55,10 @@ const CURSOR_HOOKS_FILE = `${CURSOR_DIR}/hooks.json`
 const ADR_HOOK_SCRIPT_NAME = 'capture-decisions.sh'
 const ADR_NORMALIZE_HOOK_SCRIPT_NAME = 'normalize-decisions.sh'
 const TEMPLATE_DIR_NAME = '.claude-template'
+/** Відносний шлях до канонічного фрагмента `.gitignore` для ADR Stop-hook'ів у tarball пакета. */
+export const ADR_GITIGNORE_SNIPPET_REL = 'rules/adr/fix/hooks/template/.gitignore.snippet'
+const GITIGNORE_FILE = '.gitignore'
+const EOL_RE = /\r?\n/u
 
 /** Канонічна група hooks для ADR capture Stop-hook'а — додається в settings, коли `adr` у `rules`. */
 const ADR_STOP_HOOK_GROUP = Object.freeze({
@@ -387,6 +395,60 @@ export function syncAdrNormalizeHookScript(projectRoot, templateDir) {
   return syncHookScript(projectRoot, templateDir, ADR_NORMALIZE_HOOK_SCRIPT_NAME)
 }
 
+/**
+ * Повертає змістовні (не коментар, не порожній) рядки з text-фрагмента `.gitignore`.
+ * @param {string} raw вміст snippet-файлу
+ * @returns {string[]} нормалізовані рядки патернів
+ */
+function parseGitignoreFragmentLines(raw) {
+  return raw
+    .split(EOL_RE)
+    .map(l => l.trim())
+    .filter(l => l !== '' && !l.startsWith('#'))
+}
+
+/**
+ * Дописує в кореневий `.gitignore` проєкту відсутні рядки з канонічного ADR-фрагмента.
+ * @param {string} projectRoot корінь проєкту-споживача
+ * @param {string} bundledPackageRoot корінь установленого `@nitra/cursor`
+ * @returns {Promise<{ written: boolean, path: string }>} чи змінено файл і відносний шлях
+ */
+export async function syncGitignoreAdrFragment(projectRoot, bundledPackageRoot) {
+  const snippetPath = join(bundledPackageRoot, ADR_GITIGNORE_SNIPPET_REL)
+  if (!existsSync(snippetPath)) {
+    return { written: false, path: '' }
+  }
+  const fragment = await readFile(snippetPath, 'utf8')
+  const required = parseGitignoreFragmentLines(fragment)
+  if (required.length === 0) {
+    return { written: false, path: '' }
+  }
+
+  const destPath = join(projectRoot, GITIGNORE_FILE)
+  const existing = existsSync(destPath) ? await readFile(destPath, 'utf8') : ''
+  const existingLines = new Set(
+    existing
+      .split(EOL_RE)
+      .map(l => l.trim())
+      .filter(l => l !== '' && !l.startsWith('#'))
+  )
+  const missing = required.filter(l => !existingLines.has(l))
+  if (missing.length === 0) {
+    return { written: false, path: GITIGNORE_FILE }
+  }
+
+  const sectionHeader = '# @nitra/cursor (adr) — локальні артефакти Stop-hook, не коміти'
+  const hasHeader = existing.split(EOL_RE).some(l => l.trim() === sectionHeader)
+  const block = hasHeader ? missing.join('\n') : [sectionHeader, ...missing].join('\n')
+  let prefix = ''
+  if (existing.length > 0) {
+    prefix = existing.endsWith('\n') ? existing : `${existing}\n`
+  }
+  const next = `${prefix}${block}\n`
+  await writeFile(destPath, next, 'utf8')
+  return { written: true, path: GITIGNORE_FILE }
+}
+
 /**
  * Копіює всі slash-команди з `templateDir/commands/` у `.claude/commands/`.
  * Команди ідентифікуються тим, що вони лежать у темплейті — не перетинаються
@@ -422,7 +484,7 @@ 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, cursorHooks: boolean, commands: string[], adrHook: boolean, adrNormalizeHook: boolean }>} прапорці записів settings/Cursor hooks/ADR-hook(s) та список записаних slash-команд
+ * @returns {Promise<{ settings: boolean, cursorHooks: boolean, commands: string[], adrHook: boolean, adrNormalizeHook: boolean, gitignoreAdr: boolean }>} прапорці записів settings/Cursor hooks/ADR-hook(s)/`.gitignore` та список slash-команд
  */
 export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enabled, rules = [] }) {
   if (!enabled) {
@@ -431,7 +493,8 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
       cursorHooks: false,
       commands: [],
       adrHook: false,
-      adrNormalizeHook: false
+      adrNormalizeHook: false,
+      gitignoreAdr: false
     }
   }
   const templateDir = join(bundledPackageRoot, TEMPLATE_DIR_NAME)
@@ -441,7 +504,8 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
       cursorHooks: false,
       commands: [],
       adrHook: false,
-      adrNormalizeHook: false
+      adrNormalizeHook: false,
+      gitignoreAdr: false
     }
   }
   const includeAdrHook = Array.isArray(rules) && rules.includes('adr')
@@ -449,6 +513,9 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
   const adrNormalizeHook = includeAdrHook
     ? await syncAdrNormalizeHookScript(projectRoot, templateDir)
     : { written: false, path: '' }
+  const gitignoreAdr = includeAdrHook
+    ? await syncGitignoreAdrFragment(projectRoot, bundledPackageRoot)
+    : { written: false, path: '' }
   const settings = await syncClaudeSettings(projectRoot, templateDir, { includeAdrHook })
   const cursorHooks = await syncCursorHooksConfig(projectRoot, { includeAdrHook })
   const commands = await syncClaudeCommands(projectRoot, templateDir)
@@ -457,6 +524,7 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
     cursorHooks: cursorHooks.written,
     commands,
     adrHook: adrHook.written,
-    adrNormalizeHook: adrNormalizeHook.written
+    adrNormalizeHook: adrNormalizeHook.written,
+    gitignoreAdr: gitignoreAdr.written
   }
 }

package/skills/lint/SKILL.md

@@ -44,13 +44,13 @@ bun run lint
 
 **Конфіги і коментарі, які потребують зупинки** (неповний список — будь-який аналог):
 
-| Інструмент | Типові файли / зміни |
-| --- | --- |
-| **jscpd** | `.jscpd.json` → `ignore`, `minLines` |
-| **cspell** | `.cspell.json` → `words`, `ignorePaths`; `.cspellignore` |
-| **knip** | `knip.json` → `ignore`, `ignoreDependencies`, `ignoreBinaries`, `entry` |
+| Інструмент          | Типові файли / зміни                                                                                            |
+| ------------------- | --------------------------------------------------------------------------------------------------------------- |
+| **jscpd**           | `.jscpd.json` → `ignore`, `minLines`                                                                            |
+| **cspell**          | `.cspell.json` → `words`, `ignorePaths`; `.cspellignore`                                                        |
+| **knip**            | `knip.json` → `ignore`, `ignoreDependencies`, `ignoreBinaries`, `entry`                                         |
 | **oxlint / ESLint** | `.oxlintrc.json` → `ignorePatterns`; `eslint.config.js` → `ignores`; `eslint-disable` / `oxlint-disable` у коді |
-| **інше** | `.v8rignore`, `.stylelintignore`, `.trufflehog-exclude`, розширення `ignores` у workflow-конфігах |
+| **інше**            | `.v8rignore`, `.stylelintignore`, `.trufflehog-exclude`, розширення `ignores` у workflow-конфігах               |
 
 Політика узгоджена з **`.cursor/rules/`** (зокрема **n-js-lint**, **n-text**): виняток допустимий лише з **обґрунтованою** причиною, не як заміна рефакторингу для справжніх клонів / дублікатів.
 
@@ -64,12 +64,12 @@ bun run lint
 
 **Варіанти відповіді** (мінімум такі; `allow_multiple: false`):
 
-| id | label (українською) | Дія агента |
-| --- | --- | --- |
-| `refactor` | **Рефакторинг коду** — усунути дублікат / помилку в коді (рекомендовано за замовчуванням) | Рефакторинг; конфіг **не** чіпати |
-| `ignore-once` | **Точковий виняток у конфігу** — додати ignore/words/minLines з обґрунтуванням у коментарі PR/відповіді | Після вибору — мінімальна зміна конфігу + 1 речення **чому** це не рефакторинг |
-| `skip` | **Залишити як є** — не чіпати ні код, ні конфіг зараз | Не змінювати; у фінальному резюме — що лишилось червоним |
-| `explain` | **Потрібні деталі** — поясни варіанти глибше | Розгорнути порівняння refactor vs ignore; **знову** запитати той самий набір варіантів |
+| id            | label (українською)                                                                                     | Дія агента                                                                             |
+| ------------- | ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `refactor`    | **Рефакторинг коду** — усунути дублікат / помилку в коді (рекомендовано за замовчуванням)               | Рефакторинг; конфіг **не** чіпати                                                      |
+| `ignore-once` | **Точковий виняток у конфігу** — додати ignore/words/minLines з обґрунтуванням у коментарі PR/відповіді | Після вибору — мінімальна зміна конфігу + 1 речення **чому** це не рефакторинг         |
+| `skip`        | **Залишити як є** — не чіпати ні код, ні конфіг зараз                                                   | Не змінювати; у фінальному резюме — що лишилось червоним                               |
+| `explain`     | **Потрібні деталі** — поясни варіанти глибше                                                            | Розгорнути порівняння refactor vs ignore; **знову** запитати той самий набір варіантів |
 
 Якщо користувач обрав **`ignore-once`** — у відповіді після зміни зафіксуй: який ключ конфігу змінено, який glob/слово додано, чому рефакторинг був недоречний (генерований код, формальний шаблон, легітимний термін без перекладу тощо).