@nitra/cursor 1.8.179 → 1.8.184

package/CHANGELOG.md

@@ -4,6 +4,48 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.8.184] - 2026-05-06
+
+### Added
+
+- `check-js-run.mjs`: програмна перевірка нового правила «depcheck у GitHub Actions з path-фільтром». Для кожного backend workspace-пакета сканується `.github/workflows/*.yml`; якщо `on.push.paths` або `on.pull_request.paths` містить glob, що починається з `<rootDir>/`, у job очікується крок `npx depcheck` з `working-directory: <rootDir>` і `--ignores`, що містить мінімум `graphql,bun` (інші значення допустимі). Логіка — у новому `scripts/utils/depcheck-workflow.mjs` (парсинг `--ignores="…"` з підтримкою single/double-quote і unquoted формату; класифікація `missing` / `wrong-cwd` / `missing-ignores`).
+- `check-js-run-fixture.test.mjs`: 9 нових кейсів — нема `.github/workflows/`, глобальні paths без скоупу пакета, scoped-paths без depcheck (fail), depcheck з неправильним `working-directory` (fail), без `--ignores` (fail), `--ignores` без `bun` (fail), валідний з extra-ignores (pass), вкладений `cron-jobs/foo/src/**` як scope (pass).
+- `.github/workflows/npm-publish.yml`: додано власний крок `npx depcheck --ignores="graphql,bun,bun:test,@nitra/cursor"` з `working-directory: npm`, щоб репо `@nitra/cursor` саме відповідало новому правилу js-run (`paths: ['npm/**']` обмежено пакетом `npm`); extra-ignores потрібні для self-reference `@nitra/cursor` у devDependencies та для `bun:test` як bun-built-in.
+
+## [1.8.183] - 2026-05-06
+
+### Changed
+
+- `ga` (mdc v1.6 → v1.7): додано **універсальну** вимогу — кожен workflow у `.github/workflows/*.yml` обов'язково містить блок `concurrency` з `group: ${{ github.ref }}-${{ github.workflow }}` і `cancel-in-progress: true`. Без винятків — scheduled cleanup-воркфлоу, `pull_request: types: [closed]`, publish-воркфлоу теж. Канонічні приклади у правилі (`clean-ga-workflows.yml`, `clean-merged-branch.yml`, `git-ai.yml`) оновлено й тепер містять цей блок.
+- `check-ga.mjs`: нова перевірка `verifyConcurrencyBlock` — запускається на кожному `*.yml` у `.github/workflows/` і структурно перевіряє рівно два поля (`concurrency.group` дорівнює канонічному рядку, `concurrency.cancel-in-progress === true`); відсутність блоку, інший `group` або `cancel-in-progress: false` — fail. Спільний `validateConcurrencyOnRoot` додано в усі канонічні структурні валідатори (clean-ga-workflows, clean-merged-branch, lint-ga, git-ai), щоб ці workflow перевірялися й через шаблонну, і через універсальну логіку.
+
+## [1.8.182] - 2026-05-06
+
+### Changed
+
+- `js-run` (mdc v1.2 → v1.3): додано секцію **«depcheck у GitHub Actions з path-фільтром»** — якщо в `.github/workflows/*.yml` тригер `paths:` обмежено каталогом одного backend-пакета (наприклад `cron-jobs/refund-loyalty-points/**`), у job має бути крок `npx depcheck --ignores="graphql,bun"` з `working-directory`, що вказує на той самий каталог. Список `--ignores` обов'язково містить мінімум `graphql,bun` (peer-залежність GraphQL та рантайм Bun, які depcheck не розпізнає коректно), але може бути розширений значеннями через кому без пробілів. Не застосовується до глобальних workflow без `paths:` або з кореневими `**/*.js` патернами.
+
+## [1.8.181] - 2026-05-06
+
+### Changed
+
+- `scripts/utils/find-package-json-paths.mjs`: винесено спільну `findAllPackageJsonPaths(repoRoot, ignorePaths)` з `check-js-bun-db.mjs` і `check-js-mssql.mjs`, щоб усунути jscpd-дублювання. Самі check-скрипти тепер імпортують її, як інші утиліти з `utils/`.
+- `scripts/utils/walkDir.mjs` / `scripts/utils/load-cursor-config.mjs`: trimming trailing-slash переписано з регулярки `/\\/+$/` на `while (s.endsWith('/'))`, щоб уникнути попередження `sonarjs/slow-regex` (потенційний backtracking) — поведінка не змінилась.
+- `scripts/check-k8s.mjs`: `failIfExplicitPatchTargetsHaveRedundantGroupVersion` рефакторено — логіка одного запису винесена в новий хелпер `describePatchTargetRedundancy`, основна функція тепер просто будує повідомлення з результату (зменшено sonarjs/cognitive-complexity 24→<15, поведінка не змінилась).
+- `scripts/claude-stop-hook.mjs`: `readStdin` і `runStopHookCli` переписані з `new Promise(resolve => …)` на `events.once(stream, 'end' | 'exit')` — підказка `eslint-plugin-promise/avoid-new`, поведінка не змінилась.
+
+### Fixed
+
+- `scripts/utils/bun-sql-scan.mjs`: у JSDoc `findBunSqlUnsafeUseWithoutAllowMarkerInText` прибрано вкладений приклад із backslash-backtick (`sql\\`...\\${value}...\\``), який ламав парсер коментарів oxlint і призводив до false-positive `eslint-plugin-jsdoc(require-param)`/`(require-returns)` на функції з валідним JSDoc — текст переписано без екранованих backtick-ів.
+- Десятки `eslint-plugin-jsdoc` правил у `npm/scripts/**` та `npm/tests/**`: додано відсутні описи `@param` / `@returns` (включно зі спільним `ignorePaths`-аргументом у нових сигнатурах walkDir-обгорток), прибрано неприпустимі дефолтні значення в JSDoc (`[name=...]`) — без зміни поведінки.
+
+## [1.8.180] - 2026-05-05
+
+### Changed
+
+- `js-run` (mdc v1.1 → v1.2): додано секцію **«Область застосування»** — правило явно не застосовується до frontend-пакетів (маркер `vite` у `devDependencies`). У браузерному бандлі немає `node:process`, тому заміна `process.env.X` на `import { env } from 'node:process'` ламає рантайм (`TypeError: Cannot read properties of undefined (reading 'X')`); для frontend замість `process.env.NODE_ENV` — `import.meta.env.MODE` / `import.meta.env.PROD`, інші ENV — лише `import.meta.env.VITE_*`. Передумова — інцидент у abie/b2b `site/`, де LLM-агент за правилом замінив `process.env.NODE_ENV` у `src/main.js` і вибив прод-бандл.
+- `check-js-run.mjs`: workspace-пакети з `vite` у `devDependencies` пропускаються — нова `packageJsonHasViteDevDependency(pkgJson)`, виклик одразу після `loadPackageJsonAndCheckBunyanDeps`. bunyan-залежність у `package.json` все одно перевіряється (бо це робиться до раннього виходу), але скан `process.env`, `#conn/*` і OTEL configmap для frontend-пакета не запускається. Тести: 2 нові кейси у `check-js-run-fixture.test.mjs` (vite-пакет з прямим `process.env` — pass; non-vite пакет з тим же кодом — fail).
+
 ## [1.8.179] - 2026-05-05
 
 ### Changed
@@ -48,9 +90,6 @@
 ### Added
 
 - Нове правило `changelog` (`mdc/changelog.mdc` + `scripts/check-changelog.mjs`): для «звичайних» Bun-монорепо проєктів вимагає, щоб у кожному workspace, який змінився відносно базової гілки `dev`, у поточному PR було підвищено `version` у `<ws>/package.json` і додано запис `## [version] - YYYY-MM-DD` у `<ws>/CHANGELOG.md` (Keep a Changelog 1.1.0). Перевірка PR-scoped: на самій гілці `dev` пропускається; на feature-гілці bump і запис достатньо зробити **один раз — як суму по всьому PR**, без бамп-шуму в проміжних комітах. Воркспейс `npm/` пропускається — його CHANGELOG покриває окреме правило `npm-module`. У `auto-rules.md` / `auto-rules.mjs` `changelog` додано до автодетекту з умовою «у корені є `package.json`» і до `AUTO_RULE_ORDER` між `capacitor` і `docker`.
-
-### Added
-
 - `.n-cursor.json` поле `ignore` (`schemas/n-cursor.json`): тепер не лише сигнал для AI, а й керує обходом усіх `check-*.mjs` / `run-*.mjs` — перелічені каталоги повністю виключаються з `walkDir`, як `node_modules` чи `.git`. Дозволяє безпечно тримати vendored Helm-чарти, генеровані маніфести, legacy-дерева у репо без false-positive’ів від check-скриптів. Розширено опис у схемі (стандартні виключення додавати не треба) і README отримав секцію «Виключення цілих дерев».
 - `scripts/utils/load-cursor-config.mjs`: нова утиліта `loadCursorIgnorePaths(root)` — читає поле `ignore` з `.n-cursor.json` і нормалізує до абсолютних posix-шляхів без trailing-slash; пропускає не-рядки та порожні елементи; повертає `[]`, якщо файлу/поля нема або JSON невалідний.
 - `scripts/utils/walkDir.mjs`: третій аргумент `ignorePaths` (за замовчуванням `[]`) — каталоги, які пропускаються разом з усім вмістом. Збіг — за повним шляхом (точний або з префіксом `/`), а не за basename, тож `postgres-master-test/` не пропускається коли в ignore лише `postgres-master/`. Стандартні пропуски (`node_modules`, `.git`, `dist`, `coverage`, `.turbo`, `.next`) працюють як раніше.
@@ -147,8 +186,8 @@
 
 ### Changed
 
-- `js-bun-db.mdc` (v1.4): `sql.unsafe(...)` тепер заборонено за замовчуванням — допустимо лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL з code-controlled значенням; інакше переробляємо на tagged template `sql\`...${value}...\``. Кожен легітимний виклик має супроводжуватись маркером `// allow-unsafe: <причина>` на тому ж рядку або рядком вище.
-- `check-js-bun-db.mjs`: замість вузької перевірки `sql.unsafe(\`...${expr}...\`)` тепер сканер `findBunSqlUnsafeUseWithoutAllowMarkerInText` падає на будь-якому `<obj>.unsafe(...)` без маркера-коментаря з непорожньою причиною (line- або block-коментар на тому ж рядку чи безпосередньо перед викликом).
+- `js-bun-db.mdc` (v1.4): `sql.unsafe(...)` тепер заборонено за замовчуванням — допустимо лише для підстановки назви таблиці/колонки чи dynamic SQL/DDL з code-controlled значенням; інакше переробляємо на tagged template `sql\`...${value}...\``. Кожен легітимний виклик має супроводжуватись маркером`// allow-unsafe: <причина>` на тому ж рядку або рядком вище.
+- `check-js-bun-db.mjs`: замість вузької перевірки `sql.unsafe` із tagged-template і інтерполяцією тепер сканер `findBunSqlUnsafeUseWithoutAllowMarkerInText` падає на будь-якому `obj.unsafe(...)` без маркера-коментаря з непорожньою причиною (line- або block-коментар на тому ж рядку чи безпосередньо перед викликом).
 - `ast-scan-utils.mjs`: додано `parseProgramAndCommentsOrNull` — окремий вхід для перевірок, яким потрібні коментарі поряд з AST.
 
 ## [1.8.159] - 2026-05-01

package/mdc/ga.mdc

@@ -1,11 +1,21 @@
 ---
 description: Правила форматів для .github/workflows
 alwaysApply: true
-version: '1.6'
+version: '1.7'
 ---
 
 У `.github/workflows/` лише **`.yml`**. Мають бути **`clean-ga-workflows.yml`**, **`clean-merged-branch.yml`**, **`lint-ga.yml`**, **`git-ai.yml`**. Якщо є **`apply-k8s.yml`** / **`apply-nats-consumer.yml`** — paths у тригері як у фрагментах.
 
+**Кожен** workflow у `.github/workflows/*.yml` **обов'язково** містить блок `concurrency` з фіксованим `group` та `cancel-in-progress: true`:
+
+```yaml
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+```
+
+Без винятків — у scheduled cleanup-воркфлоу, у `pull_request: types: [closed]`, у publish-воркфлоу теж. Це уникає паралельних запусків того самого workflow на тій самій ref і скасовує попередні в чергу нових.
+
 Повинен бути файл .github/workflows/clean-ga-workflows.yml, зі змістом:
 
 ```yaml
@@ -18,6 +28,10 @@ on:
   # Allow workflow to be manually run from the GitHub UI
   workflow_dispatch: {}
 
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
 jobs:
   cleanup_old_workflows:
     runs-on: ubuntu-latest
@@ -47,6 +61,10 @@ on:
   # Allow workflow to be manually run from the GitHub UI
   workflow_dispatch: {}
 
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
 jobs:
   cleanup_old_branches:
     runs-on: ubuntu-latest
@@ -119,6 +137,10 @@ on:
   pull_request:
     types: [closed]
 
+concurrency:
+  group: ${{ github.ref }}-${{ github.workflow }}
+  cancel-in-progress: true
+
 jobs:
   git-ai:
     if: github.event.pull_request.merged == true

package/mdc/js-run.mdc

@@ -1,9 +1,21 @@
 ---
 description: Це правила для backend проектів на JavaScript/Node.js, сюди входять і job і WEB сервери.
 alwaysApply: true
-version: '1.1'
+version: '1.3'
 ---
 
+## Область застосування
+
+Правило стосується **виключно backend Node.js workspace-пакетів** (jobs, GraphQL/HTTP-сервери, CLI). **Не застосовується** до frontend-пакетів, які бандляться в браузер: маркер — наявність `vite` у `devDependencies` пакета (`site/`, мобільні Capacitor-пакети, будь-яка Vue/Quasar SPA).
+
+У браузерному середовищі:
+
+- немає `node:process` — імпорт `import { env } from 'node:process'` resolve'иться у `undefined`, і `env.X` падає з `TypeError: Cannot read properties of undefined`;
+- `process.env.X` у джерелах пакета відсутнє в рантаймі — Vite або взагалі не підставляє його, або підставляє лише `process.env.NODE_ENV`;
+- усі змінні оточення для frontend задаються через `VITE_*` і доступні як `import.meta.env.VITE_X` (типобезпечно через `vite-check-env`); режим — `import.meta.env.MODE` / `import.meta.env.PROD`.
+
+Тому **у frontend-пакетах не торкайся `process.env.*`** і **не додавай** `import { env } from 'node:process'`. Якщо натрапив на `process.env.NODE_ENV` у frontend-коді — заміна, якщо взагалі потрібна, лише на `import.meta.env.MODE`.
+
 ## Структура проекту
 
 Рекомендується використовувати таку структуру проекту:
@@ -108,6 +120,8 @@ export const db = new SQL({ url: env.PG_CONN })
 
 Прямий доступ до `process.env.X` у коді заборонений — його треба замінити на `env`:
 
+> Стосується лише backend-пакетів (див. **Область застосування**). У frontend-пакетах (`vite` у `devDependencies`) — **не змінюй** `process.env.*` і **не додавай** імпорт `node:process`.
+
 - **обов'язкова змінна** — `import { checkEnv, env } from '@nitra/check-env'` плюс `checkEnv(['X'])`
   у тому ж файлі (приклад див. вище в розділі **CheckEnv**);
 - **опційна змінна** — `import { env } from 'node:process'`:
@@ -122,6 +136,26 @@ console.log(env.OPTIONAL_ENV_VAR)
 `// @nitra/cursor ignore-next-line checkEnv` безпосередньо перед використанням
 (escape-hatch для legacy-коду, не для нових файлів).
 
+## depcheck у GitHub Actions з path-фільтром
+
+Якщо в `.github/workflows/*.yml` є тригер з `paths:`, який обмежує запуск workflow змінами в каталозі конкретного backend-пакета, в job цього workflow має бути крок `npx depcheck` з `working-directory`, який вказує на той самий каталог пакета. Це гарантує, що декларація залежностей у `package.json` пакета відповідає реальним імпортам — інакше можна випадково зламати білд після видалення «зайвої» залежності, яка насправді використовується через побічний імпорт.
+
+Список `--ignores` **обов'язково** містить як мінімум `graphql,bun` (це ті, які `depcheck` не вміє коректно розпізнавати: `graphql` — peer-залежність, що часто використовується без прямого імпорту в коді; `bun` — рантайм, не npm-пакет). За потреби список можна розширити іншими модулями, специфічними для пакета — список значень розділяється комою без пробілів.
+
+```yaml title="Приклад: workflow для cron-jobs/refund-loyalty-points"
+on:
+  push:
+    paths:
+      - 'cron-jobs/refund-loyalty-points/**'
+
+# …
+
+      - run: npx depcheck --ignores="graphql,bun"
+        working-directory: cron-jobs/refund-loyalty-points
+```
+
+Правило не застосовується до workflow без `paths:` або з `paths:`, який не звужує тригер до одного backend-пакета (наприклад, кореневі `lint-*.yml` з глобальними `**/*.js`).
+
 ## Перевірка
 
 `npx @nitra/cursor check js-run`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.8.179",
+  "version": "1.8.184",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -44,11 +44,11 @@
     "oxc-parser": "^0.128.0",
     "yaml": "^2.8.3"
   },
+  "devDependencies": {
+    "@nitra/cursor": "^1.8.170"
+  },
   "engines": {
     "bun": ">=1.3",
     "node": ">=25"
-  },
-  "devDependencies": {
-    "@nitra/cursor": "^1.8.170"
   }
 }

package/scripts/check-abie.mjs

@@ -384,6 +384,7 @@ export function ignoreBranchesIncludesRequired(ignoreBranches, required) {
 /**
  * Збирає абсолютні шляхи до **.yaml** / **.yml** під деревом, де є сегмент **k8s**.
  * @param {string} root корінь репозиторію
+ * @param {string[]} [ignorePaths] абсолютні шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<string[]>} відсортовані шляхи
  */
 async function findK8sYamlFiles(root, ignorePaths = []) {

package/scripts/check-changelog.mjs

@@ -41,7 +41,7 @@ const NPM_VIEW_TIMEOUT_MS = 10_000
 /**
  * Тихо запускає `git` і повертає stdout або `null` при будь-якій помилці.
  * @param {string[]} args аргументи `git`
- * @returns {Promise<string | null>}
+ * @returns {Promise<string | null>} stdout процесу або `null` при будь-якій помилці виконання
  */
 async function gitOrNull(args) {
   try {
@@ -54,7 +54,7 @@ async function gitOrNull(args) {
 
 /**
  * Чи робочий каталог — git-репозиторій.
- * @returns {Promise<boolean>}
+ * @returns {Promise<boolean>} `true`, якщо `git rev-parse --is-inside-work-tree` повернув `true`
  */
 async function isInsideGitRepo() {
   const out = await gitOrNull(['rev-parse', '--is-inside-work-tree'])
@@ -63,7 +63,7 @@ async function isInsideGitRepo() {
 
 /**
  * Назва поточної гілки (або `HEAD` для detached state).
- * @returns {Promise<string | null>}
+ * @returns {Promise<string | null>} назва гілки чи `'HEAD'`, або `null` (поза git / помилка)
  */
 async function currentBranchName() {
   const out = await gitOrNull(['rev-parse', '--abbrev-ref', 'HEAD'])
@@ -73,7 +73,7 @@ async function currentBranchName() {
 /**
  * Знаходить ref для базової гілки. Перевага локальному `dev`, далі `origin/dev`. Повертає `null`,
  * якщо жоден не існує.
- * @returns {Promise<string | null>}
+ * @returns {Promise<string | null>} назва ref-а (`dev` чи `origin/dev`) або `null`, якщо жоден не знайдено
  */
 async function resolveBaseRef() {
   for (const ref of [BASE_BRANCH, `origin/${BASE_BRANCH}`]) {
@@ -88,8 +88,8 @@ async function resolveBaseRef() {
 /**
  * Точка розгалуження поточної гілки від `baseRef`. На feature-гілці = коли вона відгалузилась;
  * на `main` після merge `dev → main` = поточний `dev`. Повертає `null`, якщо merge-base нема.
- * @param {string} baseRef
- * @returns {Promise<string | null>}
+ * @param {string} baseRef SHA або ref-name бази (зазвичай `dev` / `origin/dev`)
+ * @returns {Promise<string | null>} SHA точки розгалуження або `null`, якщо merge-base нема
  */
 async function resolveMergeBase(baseRef) {
   const out = await gitOrNull(['merge-base', baseRef, 'HEAD'])
@@ -104,9 +104,9 @@ async function resolveMergeBase(baseRef) {
  * Для кореня `.` — це точка плюс magic-виключення кожного підворкспейсу через `:(exclude)<sub>/`,
  * щоб зміни всередині sub-workspace не вважалися змінами кореня.
  * Для звичайного воркспейсу — просто `<ws>/`.
- * @param {string} ws
- * @param {string[]} subWorkspaces
- * @returns {string[]}
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня, інакше — відносний шлях, як у `workspaces`)
+ * @param {string[]} subWorkspaces усі під-воркспейси (зокрема для `'.'` потрібно виключити їх)
+ * @returns {string[]} pathspec для git: масив, що передається після `--`
  */
 function pathspecForWorkspace(ws, subWorkspaces) {
   if (ws !== '.') return [`${ws}/`]
@@ -119,9 +119,9 @@ function pathspecForWorkspace(ws, subWorkspaces) {
  * `git diff --quiet <baseRef> -- <pathspec>` ловить committed-зміни на цій гілці й незбережені
  * правки tracked-файлів. Untracked-файли — `git ls-files --others --exclude-standard`.
  * @param {string} baseRef SHA або ref-name (зокрема merge-base)
- * @param {string} ws
- * @param {string[]} subWorkspaces
- * @returns {Promise<boolean>}
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @param {string[]} subWorkspaces усі під-воркспейси для коректного формування pathspec кореня
+ * @returns {Promise<boolean>} `true`, якщо в межах воркспейсу є будь-які зміни (committed або untracked)
  */
 async function workspaceHasChangesAgainstBase(baseRef, ws, subWorkspaces) {
   const pathspec = pathspecForWorkspace(ws, subWorkspaces)
@@ -129,8 +129,7 @@ async function workspaceHasChangesAgainstBase(baseRef, ws, subWorkspaces) {
     await execFileAsync('git', ['diff', '--quiet', baseRef, '--', ...pathspec])
   } catch (error) {
     const code = /** @type {{ code?: number }} */ (error).code
-    if (code === 1) return true
-    return false
+    return code === 1
   }
   const untracked = await gitOrNull(['ls-files', '--others', '--exclude-standard', '--', ...pathspec])
   return typeof untracked === 'string' && untracked.trim().length > 0
@@ -138,9 +137,9 @@ async function workspaceHasChangesAgainstBase(baseRef, ws, subWorkspaces) {
 
 /**
  * Версія з `<ws>/package.json` на `baseRef` або `null`.
- * @param {string} baseRef
- * @param {string} ws
- * @returns {Promise<string | null>}
+ * @param {string} baseRef SHA або ref-name (зазвичай merge-base) для `git show`
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @returns {Promise<string | null>} значення поля `version` або `null`, якщо файла нема / JSON некоректний
  */
 async function readBaseVersion(baseRef, ws) {
   const wsPath = ws === '.' ? 'package.json' : `${ws}/package.json`
@@ -156,9 +155,9 @@ async function readBaseVersion(baseRef, ws) {
 
 /**
  * Чи містить текст `CHANGELOG.md` запис `## [version]` (з опційним `- YYYY-MM-DD`).
- * @param {string} text
- * @param {string} version
- * @returns {boolean}
+ * @param {string} text вміст CHANGELOG.md
+ * @param {string} version версія, яку шукаємо у форматі Keep a Changelog
+ * @returns {boolean} `true`, якщо запис для `version` знайдено
  */
 function changelogHasVersionEntry(text, version) {
   const escaped = version.replaceAll(/[.+*?^$()[\]{}|\\]/g, String.raw`\$&`)
@@ -168,8 +167,8 @@ function changelogHasVersionEntry(text, version) {
 
 /**
  * Зчитує `<ws>/package.json`. `null`, якщо файл відсутній або JSON некоректний.
- * @param {string} ws
- * @returns {Promise<Record<string, unknown> | null>}
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @returns {Promise<Record<string, unknown> | null>} розпарсений `package.json` або `null`
  */
 async function readPackageJsonOrNull(ws) {
   const path = join(ws, 'package.json')
@@ -186,8 +185,8 @@ async function readPackageJsonOrNull(ws) {
 
 /**
  * Воркспейс публікується в npm: має непорожній `name`, не `private: true`, і має масив `files`.
- * @param {Record<string, unknown> | null} pkg
- * @returns {boolean}
+ * @param {Record<string, unknown> | null} pkg розпарсений `package.json` (або `null`)
+ * @returns {boolean} `true`, якщо пакет придатний для публікації в npm
  */
 function isNpmPublishable(pkg) {
   if (!pkg) return false
@@ -199,8 +198,8 @@ function isNpmPublishable(pkg) {
 /**
  * Опублікована версія пакета в npm-реєстрі. `null` — пакет не знайдено / нема мережі / помилка.
  * Дефолтна імплементація — `npm view <name> version` із таймаутом, щоб не блокуватись офлайн.
- * @param {string} name
- * @returns {Promise<string | null>}
+ * @param {string} name повна назва пакета (включно зі скоупом)
+ * @returns {Promise<string | null>} опублікована версія або `null` (нема пакета / офлайн)
  */
 async function defaultGetPublishedVersion(name) {
   try {
@@ -214,10 +213,10 @@ async function defaultGetPublishedVersion(name) {
 
 /**
  * Перевіряє масив `files` у `<ws>/package.json`: якщо оголошено — має містити `"CHANGELOG.md"`.
- * @param {Record<string, unknown> | null} pkg
- * @param {string} ws
- * @param {(msg: string) => void} pass
- * @param {(msg: string) => void} fail
+ * @param {Record<string, unknown> | null} pkg розпарсений `package.json` воркспейсу
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
  */
 function checkFilesArrayContainsChangelog(pkg, ws, pass, fail) {
   if (!pkg || !Array.isArray(pkg.files)) return
@@ -231,10 +230,10 @@ function checkFilesArrayContainsChangelog(pkg, ws, pass, fail) {
 
 /**
  * Перевіряє наявність запису у `<ws>/CHANGELOG.md` для версії `version`.
- * @param {string} ws
- * @param {string} version
- * @param {(msg: string) => void} pass
- * @param {(msg: string) => void} fail
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @param {string} version версія, для якої очікується запис
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
  * @returns {Promise<boolean>} `false`, якщо файл відсутній або немає запису
  */
 async function verifyChangelogEntry(ws, version, pass, fail) {
@@ -257,11 +256,11 @@ async function verifyChangelogEntry(ws, version, pass, fail) {
  * npm-published режим: порівнює локальну `version` з опублікованою в реєстрі. Якщо вони
  * відрізняються — вимагає запис у CHANGELOG і `"CHANGELOG.md"` у `files`. Якщо реєстр недосяжний,
  * правило fail-safe пасує (щоб офлайн-розробка не блокувалась).
- * @param {string} ws
- * @param {Record<string, unknown>} pkg
- * @param {(name: string) => Promise<string | null>} getPublishedVersion
- * @param {(msg: string) => void} pass
- * @param {(msg: string) => void} fail
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @param {Record<string, unknown>} pkg розпарсений `package.json` воркспейсу
+ * @param {(name: string) => Promise<string | null>} getPublishedVersion стаб/реальна функція отримання опублікованої версії
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
  */
 async function checkPublishedWorkspace(ws, pkg, getPublishedVersion, pass, fail) {
   const label = ws === '.' ? '<root>' : ws
@@ -289,10 +288,10 @@ async function checkPublishedWorkspace(ws, pkg, getPublishedVersion, pass, fail)
  * local-only режим: PR-scoped перевірка проти `dev` через `git merge-base`. Викликається лише
  * для воркспейсів, де є реальні зміни щодо merge-base.
  * @param {string} mergeBase SHA точки розгалуження
- * @param {string} ws
- * @param {Record<string, unknown> | null} pkg
- * @param {(msg: string) => void} pass
- * @param {(msg: string) => void} fail
+ * @param {string} ws шлях воркспейсу (`'.'` для кореня)
+ * @param {Record<string, unknown> | null} pkg розпарсений `package.json` воркспейсу (або `null`)
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
  */
 async function checkLocalOnlyChangedWorkspace(mergeBase, ws, pkg, pass, fail) {
   const label = ws === '.' ? '<root>' : ws
@@ -315,12 +314,12 @@ async function checkLocalOnlyChangedWorkspace(mergeBase, ws, pkg, pass, fail) {
 
 /**
  * Виконує local-only перевірку для всіх workspace-ів, у яких немає npm-published режиму.
- * @param {string[]} localOnlyWorkspaces
- * @param {Map<string, Record<string, unknown> | null>} pkgByWs
- * @param {string[]} subWorkspaces
- * @param {(msg: string) => void} pass
- * @param {(msg: string) => void} fail
- * @returns {Promise<void>}
+ * @param {string[]} localOnlyWorkspaces список шляхів local-only воркспейсів
+ * @param {Map<string, Record<string, unknown> | null>} pkgByWs мапа: шлях воркспейсу → розпарсений `package.json` (або `null`)
+ * @param {string[]} subWorkspaces усі під-воркспейси (для коректного pathspec кореня)
+ * @param {(msg: string) => void} pass callback при успішній перевірці
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<void>} резолвиться по завершенню перевірок усіх local-only воркспейсів
  */
 async function runLocalOnlyChecks(localOnlyWorkspaces, pkgByWs, subWorkspaces, pass, fail) {
   if (localOnlyWorkspaces.length === 0) return
@@ -358,7 +357,7 @@ async function runLocalOnlyChecks(localOnlyWorkspaces, pkgByWs, subWorkspaces, p
 
 /**
  * Перевіряє відповідність проєкту правилу changelog.mdc.
- * @param {object} [opts]
+ * @param {object} [opts] опції перевірки
  * @param {(name: string) => Promise<string | null>} [opts.getPublishedVersion] перевизначення для тестів
  * @returns {Promise<number>} 0 — все OK, 1 — є проблеми
  */

package/scripts/check-docker.mjs

@@ -66,7 +66,7 @@ export function isDockerfileName(name) {
 /**
  * Збирає абсолютні шляхи до Dockerfile / Containerfile від кореня cwd.
  * @param {string} root корінь репозиторію
- * @param {string[]} [ignorePaths=[]] шляхи каталогів, повністю виключених з обходу
+ * @param {string[]} [ignorePaths] шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<string[]>} відсортовані абсолютні шляхи
  */
 export async function findDockerfilePaths(root, ignorePaths = []) {

package/scripts/check-ga.mjs

@@ -43,6 +43,8 @@ const MEGALINTER_USE_PATTERNS = [/oxsecurity\/megalinter-action/i, /megalinter\/
 /** Типові конфіги MegaLinter у корені репо */
 const MEGALINTER_CONFIG_NAMES = ['.mega-linter.yml', '.megalinter.yaml', '.mega-linter.yaml']
 
+const N_CURSOR_LINT_GA_RE = /\bn-cursor\s+lint-ga\b/
+
 /** Локальні composite setup-bun-deps (ga.mdc). */
 const SETUP_BUN_PATTERNS = ['./.github/actions/setup-bun-deps', './npm/github-actions/setup-bun-deps']
 
@@ -56,6 +58,9 @@ const FORBIDDEN_BUN_PATTERNS = [
 /** Обовʼязкові workflow-файли (ga.mdc). */
 const REQUIRED_WORKFLOWS = ['clean-ga-workflows.yml', 'clean-merged-branch.yml', 'lint-ga.yml', 'git-ai.yml']
 
+/** Канонічне значення `concurrency.group` (ga.mdc). Збирається з фрагментів, щоб не плодити expression-токени в коді. */
+const EXPECTED_CONCURRENCY_GROUP = ['$', '{{ github.ref }}-$', '{{ github.workflow }}'].join('')
+
 /**
  * Повертає true, якщо glob у GitHub Actions `on.*.paths` матчитсья хоча б на один tracked файл у репозиторії.
  *
@@ -229,6 +234,8 @@ function validateCleanGaWorkflows(root, passFn, failFn) {
     passFn('clean-ga-workflows.yml: workflow_dispatch OK')
   }
 
+  validateConcurrencyOnRoot('clean-ga-workflows.yml', root, passFn, failFn)
+
   const jobs = getObjKey(root, 'jobs')
   const job = getObjKey(jobs, 'cleanup_old_workflows')
   if (!job) {
@@ -342,6 +349,8 @@ function validateCleanMergedBranch(root, passFn, failFn) {
     failFn('clean-merged-branch.yml: має бути workflow_dispatch: {} (ga.mdc)')
   }
 
+  validateConcurrencyOnRoot('clean-merged-branch.yml', root, passFn, failFn)
+
   const jobs = getObjKey(root, 'jobs')
   const job = getObjKey(jobs, 'cleanup_old_branches')
   if (!job) {
@@ -419,10 +428,7 @@ function validateLintGaWorkflowStructure(root, passFn, failFn) {
 
   validateLintGaOnTriggers(root.on, failFn)
 
-  const conc = getObjKey(root, 'concurrency')
-  if (getObjKey(conc, 'cancel-in-progress') !== true) {
-    failFn('lint-ga.yml: concurrency.cancel-in-progress має бути true (ga.mdc)')
-  }
+  validateConcurrencyOnRoot('lint-ga.yml', root, passFn, failFn)
 
   const jobs = getObjKey(root, 'jobs')
   const job = getObjKey(jobs, 'lint-ga')
@@ -488,6 +494,8 @@ function validateGitAiWorkflowStructure(root, passFn, failFn) {
     failFn('git-ai.yml: on.pull_request.types має містити closed (ga.mdc)')
   }
 
+  validateConcurrencyOnRoot('git-ai.yml', root, passFn, failFn)
+
   const jobs = getObjKey(root, 'jobs')
   const job = getObjKey(jobs, 'git-ai')
   if (!job) {
@@ -516,6 +524,60 @@ function validateGitAiWorkflowStructure(root, passFn, failFn) {
   }
 }
 
+/**
+ * Перевіряє блок `concurrency` на вже розпарсеному корені workflow (ga.mdc).
+ *
+ * Використовується в канонічних структурних валідаторах (clean-ga-workflows, clean-merged-branch,
+ * lint-ga, git-ai), де root уже отримано через `parseWorkflowYaml`. Логіка ідентична
+ * `verifyConcurrencyBlock`, але без повторного парсингу.
+ * @param {string} relPath шлях для повідомлень
+ * @param {Record<string, unknown>} root parsed YAML workflow
+ * @param {(msg: string) => void} passFn pass
+ * @param {(msg: string) => void} failFn fail
+ * @returns {void}
+ */
+function validateConcurrencyOnRoot(relPath, root, passFn, failFn) {
+  const conc = getObjKey(root, 'concurrency')
+  if (!conc || typeof conc !== 'object') {
+    failFn(
+      `${relPath}: відсутня секція concurrency — додай concurrency.group: ${EXPECTED_CONCURRENCY_GROUP} і cancel-in-progress: true (ga.mdc)`
+    )
+    return
+  }
+  const group = getObjKey(conc, 'group')
+  const cancel = getObjKey(conc, 'cancel-in-progress')
+  if (group !== EXPECTED_CONCURRENCY_GROUP) {
+    failFn(`${relPath}: concurrency.group має бути ${EXPECTED_CONCURRENCY_GROUP} (ga.mdc)`)
+    return
+  }
+  if (cancel !== true) {
+    failFn(`${relPath}: concurrency.cancel-in-progress має бути true (ga.mdc)`)
+    return
+  }
+  passFn(`${relPath}: concurrency блок OK`)
+}
+
+/**
+ * Перевіряє, що workflow містить блок `concurrency` з канонічними `group` і `cancel-in-progress: true` (ga.mdc).
+ *
+ * Без винятків — застосовується до всіх workflow у `.github/workflows/*.yml`, включно з scheduled cleanup,
+ * `pull_request: types: [closed]` та publish-воркфлоу. Делегує логіку `validateConcurrencyOnRoot`,
+ * додаючи лише крок парсингу YAML; якщо парсинг провалився — мовчки виходить (синтаксичні проблеми
+ * ловлять інші перевірки).
+ * @param {string} relPath шлях для повідомлень
+ * @param {string} content вміст YAML
+ * @param {(msg: string) => void} failFn реєструє порушення (exit 1)
+ * @param {(msg: string) => void} passFn реєструє успішну перевірку
+ * @returns {void}
+ */
+function verifyConcurrencyBlock(relPath, content, failFn, passFn) {
+  const root = parseWorkflowYaml(content)
+  if (!root) {
+    return
+  }
+  validateConcurrencyOnRoot(relPath, root, passFn, failFn)
+}
+
 /**
  * Якщо workflow викликає локальний setup-bun-deps, раніше у файлі має бути `actions/checkout@v…` (ga.mdc).
  * Fallback: сирий текст, якщо YAML не вдається розібрати.
@@ -743,12 +805,10 @@ async function checkLintGaScript(passFn, failFn) {
   // на shellcheck + послідовно `bunx github-actionlint` і `uvx zizmor --offline --collect=workflows .`.
   // Виклик через bin-ім’я `n-cursor`, а не `npx --no @nitra/cursor`, бо `bun run` транслює `npx` у `bun x`,
   // а `bun x @nitra/cursor` для скоупованого пакету з одним bin-ім’ям повертає 0 без виконання.
-  if (/\bn-cursor\s+lint-ga\b/.test(lg)) {
+  if (N_CURSOR_LINT_GA_RE.test(lg)) {
     passFn('lint-ga делегує CLI n-cursor lint-ga (preflight shellcheck + actionlint + zizmor)')
   } else {
-    failFn(
-      'lint-ga має бути "n-cursor lint-ga" — CLI робить preflight shellcheck перед actionlint/zizmor (ga.mdc)'
-    )
+    failFn('lint-ga має бути "n-cursor lint-ga" — CLI робить preflight shellcheck перед actionlint/zizmor (ga.mdc)')
   }
 }
 
@@ -994,6 +1054,7 @@ export async function check() {
     verifyCheckoutBeforeLocalSetupBunDeps(`${wfDir}/${f}`, content, fail, pass)
     verifyNoDirectBunOrCache(`${wfDir}/${f}`, content, fail, pass)
     verifyNoRunShellLineContinuationBackslash(`${wfDir}/${f}`, content, fail, pass)
+    verifyConcurrencyBlock(`${wfDir}/${f}`, content, fail, pass)
     const parsed = parseWorkflowYaml(content)
     if (parsed) {
       verifyWorkflowEventPathsGlobsExist(`${wfDir}/${f}`, parsed, pass, fail)

package/scripts/check-graphql.mjs

@@ -32,6 +32,7 @@ export const REQUIRED_DUMP_SCHEMA_SCRIPT =
 /**
  * Збирає абсолютні шляхи source-файлів, які підлягають скануванню на gql templates.
  * @param {string} root абсолютний шлях кореня
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<string[]>} список кандидатів
  */
 async function collectScanCandidates(root, ignorePaths) {

package/scripts/check-hasura.mjs

@@ -102,6 +102,7 @@ export function isEnvFile(relPath) {
 /**
  * Збирає всі `*.env` файли в дереві, окрім службових каталогів.
  * @param {string} root абсолютний шлях кореня
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<string[]>} відсортовані posix-шляхи відносно кореня
  */
 async function collectEnvFiles(root, ignorePaths) {