@nitra/cursor 3.19.0 → 3.21.0

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

@@ -199,7 +199,7 @@ if ! printf '%s' "$RESPONSE_TRIMMED" | grep -q '^## '; then
   exit 0
 fi
 
-TS=$(date +%Y%m%d-%H%M%S)
+TS=$(date +%y%m%d-%H%M)
 
 # Slug із першого `## [ADR|Runbook|Knowledge] <heading>`-рядка відповіді.
 # Логіка локальна (без додаткового LLM-виклику): використовуємо вже згенерований heading.

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

@@ -407,11 +407,15 @@ while IFS= read -r op_json; do
           continue
           ;;
       esac
-      # Keep the draft's `YYYYMMDD-HHMMSS-` prefix on the clean file: the name
+      # Keep the draft's timestamp 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`.
+      # and clean, and docs/adr/ keeps sorting chronologically. New drafts use
+      # `YYMMDD-HHMM-`; older `YYYYMMDD-HHMMSS-` drafts are still supported.
+      # 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]-*)
+          DEST_SLUG="$(printf '%s' "$FILE" | cut -c1-11)-$SLUG"
+          ;;
         [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"
           ;;
@@ -444,7 +448,7 @@ while IFS= read -r op_json; do
           ;;
       esac
       # Resolve the target clean file. The LLM gives a bare `<slug>.md`, but the
-      # real file usually carries a `YYYYMMDD-HHMMSS-` prefix. Try, in order:
+      # real file usually carries a timestamp prefix. Try, in order:
       #   1. exact name in docs/adr/,
       #   2. a rewrite of this batch that produced that slug (SLUG_MAP),
       #   3. a unique existing clean file whose name ends with `-<slug>.md`.

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## [3.21.0] - 2026-06-04
+
+### Added
+
+- Root-guard для всіх деструктивних точок: CLI-команди fix/lint/coverage/change/release + дефолтний sync хардом перевіряють cwd===git-toplevel (assertCwdIsProjectRoot); worktree-preflight підсилено root-assert (pwd vs toplevel); новий meta.json-флаг requireRoot + injectRootNotice для in-place root-only скілів (n-start-check); skillRequiresRoot як явна похідна ознака захисту; валідація requireRoot у npm-module
+- sync .gitignore: ігнорувати .claude/scheduled_tasks.lock (runtime-lock планувальника)
+
+### Changed
+
+- Скорочено timestamp-префікси ADR і change-файлів до YYMMDD-HHMM; додано атомарний suffix для локальних колізій та заборону Temporal у Bun runtime.
+
+### Fixed
+
+- n-changelog: directional version-drift — лише version ВПЕРЕД (> опублікованої/git-бази) валить як ручний bump; version ПОЗАДУ (локаль відстала від CI-релізу, ще не git pull) більше не блокує коміт (compareSemverCore/versionIsAhead)
+
+## [3.20.0] - 2026-06-03
+
+### Added
+
+- ensure-tool: авто-встановлення зовнішніх CLI-залежностей (hk, conftest, shellcheck, actionlint, dotenv-linter) — brew/scoop/GitHub Release per-platform; hk install після fix; conftest авто-встановлюється перед fix та lint-ga
+- ensureTool: розширено на opa/regal/hadolint/kubeconform/kubescape (brew/scoop/GitHub Release per-platform) + підтримка сирих бінарників (archive:false → download+chmod, без tar). Мігровано call-sites rego-lint (opa/regal), docker (hadolint з docker-fallback), k8s-lint (kubeconform/kubescape). withBinRemovedFromPath виставляє N_CURSOR_NO_AUTO_INSTALL=1.
+- Guard: дефолтний sync (`npx @nitra/cursor` без підкоманди) забороняє запуск із піддиректорії git-репо — STOP до мутацій, замість скаффолда .cursor/.claude/CLAUDE.md/.n-cursor.json не в той каталог
+
+### Changed
+
+- worktree-only скіли: bootstrap-виклик npx @nitra/cursor у новоствореному worktree тепер ретраїться при транзитних помилках реєстру/CDN (ETARGET/notarget, ENOTFOUND, ETIMEDOUT, EAI_AGAIN, ECONNRESET, 5xx) кожні 30с до 5 хв (env N_CURSOR_NPX_RETRY_MAX_MIN, ceiling 10 хв); реальний nonzero CLI віддається одразу. worktree-notice додає bun install у дереві (локальна копія усуває гонку з CDN) і shell-обгортку n_cursor_npx; fix-скіл кроки 1/6 використовують її
+- npm-module: npm_publish_yml тепер звіряє ВЕСЬ канонічний сніпет напряму (target.json "check":"template", generic deep-subset) замість bespoke subset-of rego — редагування сніпета одразу змінює enforce, без правок rego й міграторів; масиви (steps) матчаться структурним subset-ом за наявністю (order/key-insensitive, зайві кроки дозволені); legacy publish-only workflow тепер падає check (вимагає release-publish job). Новий режим check:template перевикористовний для будь-якого whole-file концерну зі сніпетом.
+- docker hadolint: прибрано docker-run fallback — hadolint тепер лише нативний бінарник через ensureTool (brew/scoop/GitHub Release). Видалено HADOLINT_IMAGE; оновлено docker.mdc і тести.
+
+### Fixed
+
+- nginx-default-tpl: error_log off → error_log /dev/null crit; (error_log off — НЕ валідний nginx, падає під readOnlyRootFilesystem); авто-заміна в шаблонах + оновлено канон .mdc/фікстуру
+
 ## [3.19.0] - 2026-06-03
 
 ### Changed

package/bin/n-cursor.js

@@ -92,10 +92,12 @@ import {
 import { detectAutoSkills } from '../scripts/auto-skills.mjs'
 import { readSkillMetaRaw } from '../scripts/lib/skill-meta.mjs'
 import { injectWorktreeNotice } from '../scripts/lib/worktree-notice.mjs'
+import { injectRootNotice } from '../scripts/lib/root-notice.mjs'
 import { runPostToolUseFixCli } from '../scripts/post-tool-use-fix.mjs'
 import { discoverCheckRulesFromCursorRules } from '../scripts/lib/discover-check-rules-from-cursor.mjs'
 import { listRuleIds } from '../scripts/lib/list-rule-ids.mjs'
 import { ensureNitraCursorInRootDevDependencies } from '../scripts/ensure-nitra-cursor-dev-dependencies.mjs'
+import { assertCwdIsProjectRoot } from '../scripts/lib/assert-project-root.mjs'
 import { runLintDocker } from '../rules/docker/lint/lint.mjs'
 import { runLintGaCli } from '../rules/ga/lint/lint.mjs'
 import { runLintK8s } from '../rules/k8s/lint/lint.mjs'
@@ -110,6 +112,7 @@ import { runWorktreeCli } from '../scripts/worktree-cli.mjs'
 import { syncSetupBunDepsAction } from '../scripts/sync-setup-bun-deps-action.mjs'
 import { runLint } from '../scripts/lint-cli.mjs'
 import { formatTimingSummary } from '../scripts/lib/timing-summary.mjs'
+import { ensureHkInstall, ensureTool } from '../scripts/lib/ensure-tool.mjs'
 
 const PACKAGE_NAME = '@nitra/cursor'
 const CONFIG_FILE = '.n-cursor.json'
@@ -785,6 +788,9 @@ async function syncSkills(configSkills, bundledSkillsDir = BUNDLED_SKILLS_DIR) {
         await mkdir(destDir, { recursive: true })
         const meta = readSkillMetaRaw(srcDir)
         const worktree = meta?.worktree === true
+        // root-guard для in-place скілів (мутують CWD без worktree-ізоляції).
+        // Worktree-скіли root-assert уже мають у worktree-блоці, тож тут лише !worktree.
+        const rootOnly = !worktree && meta?.requireRoot === true
         const entries = await readdir(srcDir, { withFileTypes: true })
         for (const entry of entries) {
           // Лише top-level файли скіла. `meta.json` — метадані (не для споживача);
@@ -794,6 +800,7 @@ async function syncSkills(configSkills, bundledSkillsDir = BUNDLED_SKILLS_DIR) {
           let content = await readFile(join(srcDir, entry.name), 'utf8')
           if (entry.name === 'SKILL.md') {
             content = injectWorktreeNotice(content, worktree)
+            content = injectRootNotice(content, rootOnly)
           }
           await writeFile(join(destDir, entry.name), content, 'utf8')
         }
@@ -1184,6 +1191,10 @@ function logRemovedManagedItems(title, basePath, names) {
  * @returns {Promise<void>}
  */
 async function runFixCommand(requestedRules) {
+  const hkBin = ensureTool('hk')
+  ensureHkInstall(hkBin)
+  ensureTool('conftest')
+
   const available = await listRuleIds(BUNDLED_RULES_DIR)
   if (available.length === 0) {
     console.error('❌ Не знайдено жодного правила у пакеті')
@@ -1453,10 +1464,52 @@ async function runSync() {
   }
 }
 
+/**
+ * Команди, що мутують проєкт у CWD і вимагають кореня репо. `undefined`/`''` —
+ * дефолтний sync; `check` — deprecated-alias `fix`. Решта (read-only `trace`/
+ * `graph`, `--root`-команди `docgen`/`rename-yaml-extensions`, `worktree`,
+ * sub-лінтери) гард не зачіпає.
+ */
+const ROOT_GUARDED_COMMANDS = new Set([undefined, '', 'fix', 'check', 'lint', 'coverage', 'change', 'release'])
+
+/**
+ * Короткий опис дії для тексту root-guard помилки за іменем команди.
+ * @param {string | undefined} cmd підкоманда CLI (або undefined для дефолтного sync)
+ * @returns {string} фраза «що саме мутує CWD»
+ */
+function describeRootGuardedAction(cmd) {
+  switch (cmd) {
+    case undefined:
+    case '':
+      return 'Дефолтна синхронізація скаффолдить .cursor/, .claude/, CLAUDE.md, .n-cursor.json і робить bun install у поточному каталозі'
+    case 'fix':
+    case 'check':
+      return '`fix` запускає programmatic-перевірки правил, що переписують конфіги в поточному каталозі'
+    case 'lint':
+      return '`lint` запускає авто-fix лінтерів (oxfmt/eslint --fix/stylelint --fix) у поточному каталозі'
+    case 'coverage':
+      return '`coverage` генерує COVERAGE.md і Stryker-артефакти в поточному каталозі'
+    case 'change':
+      return '`change` пише change-файл у .changes/ поточного каталогу'
+    case 'release':
+      return '`release` бампає version і переписує CHANGELOG у поточному каталозі'
+    default:
+      return 'Команда @nitra/cursor мутує проєкт у поточному каталозі'
+  }
+}
+
 // CLI: маршрутизація команд
 const [command, ...args] = process.argv.slice(2)
 
 try {
+  // Root-guard до перших мутацій: дефолтний sync скаффолдить .cursor/.claude/CLAUDE.md/
+  // .n-cursor.json + bun install, а fix/lint/coverage/change/release переписують файли в CWD —
+  // усе це ключиться на cwd(). Запуск із піддиректорії git-репо (типово прямий
+  // `bun npm/bin/n-cursor.js` не з кореня) зачепив би не той каталог → STOP. Read-only та
+  // `--root`-команди (trace, graph, docgen, rename-yaml-extensions) не зачіпаємо.
+  if (ROOT_GUARDED_COMMANDS.has(command)) {
+    assertCwdIsProjectRoot(cwd(), describeRootGuardedAction(command))
+  }
   await ensureNitraCursorInRootDevDependencies(cwd())
   switch (command) {
     case 'fix': {

package/package.json

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

package/rules/adr/adr.mdc

@@ -18,8 +18,8 @@ ADR живуть у єдиному каталозі **`docs/adr/`**. Clean ADR-
 
 Є два стани файлу, які відрізняються YAML frontmatter:
 
-- **Draft** — файл з frontmatter `session: …`, `captured: …`, `transcript: …` та timestamp-іменем `YYYYMMDD-HHMMSS-<sid>.md`. Пише `capture-decisions.sh` після кожної сесії.
-- **Clean** — файл без frontmatter, з kebab-case-іменем. `normalize-decisions.sh` зберігає timestamp-префікс чернетки → `YYYYMMDD-HHMMSS-<slug>.md` (наприклад `20260518-092807-ланцюжок-запуску-abie.md`); створений руками clean-файл може мати просто `<slug>.md`.
+- **Draft** — файл з frontmatter `session: …`, `captured: …`, `transcript: …` та timestamp-іменем `YYMMDD-HHMM-<sid>.md`. Пише `capture-decisions.sh` після кожної сесії.
+- **Clean** — файл без frontmatter, з kebab-case-іменем. `normalize-decisions.sh` зберігає timestamp-префікс чернетки → `YYMMDD-HHMM-<slug>.md` (наприклад `260518-0928-ланцюжок-запуску-abie.md`); створений руками clean-файл може мати просто `<slug>.md`.
 
 `normalize-decisions.sh` ніколи не чіпає clean-файли — крім випадку `merge-into`, коли дописує `## Update YYYY-MM-DD` в кінець наявного clean-файлу.
 
@@ -50,7 +50,7 @@ LLM повертає масив операцій:
 | `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`); англійські технічні терміни лишаються англійською без транслітерації. До імені clean-файлу скрипт додає `YYYYMMDD-HHMMSS-` чернетки, тож запис лишається прив'язаним до часу capture, а `docs/adr/` сортується хронологічно. Колізія імен обробляється детермінованим суфіксом `-2`, `-3`.
+`slug` — kebab-case українською (`ланцюжок-запуску-abie`, `npm-publish-flow`); англійські технічні терміни лишаються англійською без транслітерації. До імені clean-файлу скрипт додає `YYMMDD-HHMM-` чернетки, тож запис лишається прив'язаним до часу capture, а `docs/adr/` сортується хронологічно. Колізія імен обробляється детермінованим суфіксом `-2`, `-3`. Старі чернетки з `YYYYMMDD-HHMMSS-` prefix нормалізатор також розпізнає, щоб не ламати наявний inbox.
 
 ### Жодних git-операцій
 
@@ -86,8 +86,8 @@ LLM повертає масив операцій:
 
 ```text
 docs/adr/
-├── YYYYMMDD-HHMMSS-<sid>.md     # drafts (frontmatter session:/captured:/transcript:)
-└── YYYYMMDD-HHMMSS-<slug>.md    # clean ADR-и (без frontmatter, timestamp-префікс чернетки збережено)
+├── YYMMDD-HHMM-<sid>.md       # drafts (frontmatter session:/captured:/transcript:)
+└── YYMMDD-HHMM-<slug>.md      # clean ADR-и (без frontmatter, timestamp-префікс чернетки збережено)
 .claude/hooks/
 ├── capture-decisions.sh       # auto-synced з пакета
 ├── normalize-decisions.sh     # auto-synced з пакета

package/rules/adr/js/templates/hooks/.gitignore.snippet

@@ -6,3 +6,4 @@ dist/
 .claude/hooks/*.log
 .claude/hooks/.normalize-state
 .claude/hooks/.normalize.lock
+.claude/scheduled_tasks.lock

package/rules/changelog/changelog.mdc

@@ -8,7 +8,7 @@ alwaysApply: true
 
 > **Якщо в цій сесії ти змінив(ла) файли в пакетному workspace** (код, rego, правила, скіли, скрипти, конфіги, тести — **не** лише `docs/` / `doc/`) — **не завершуй задачу**, поки не виконаєш **усі три** кроки нижче в **тому ж** наборі змін. Це не «опційно після синку» — це частина PR.
 
-1. **Поклади change-файл** `<ws>/.changes/<timestamp>-<rand>.md` з frontmatter `bump:` (`major|minor|patch`) + `section:` (`Added|Changed|Fixed|Removed`) і текстом опису. Команда: `npx @nitra/cursor change --bump <…> --section <…> --message "<…>" [--ws <шлях>]`.
+1. **Поклади change-файл** `<ws>/.changes/YYMMDD-HHMM.md` з frontmatter `bump:` (`major|minor|patch`) + `section:` (`Added|Changed|Fixed|Removed`) і текстом опису. Команда: `npx @nitra/cursor change --bump <…> --section <…> --message "<…>" [--ws <шлях>]`. Якщо файл за ту саму хвилину вже існує, CLI атомарно створює `YYMMDD-HHMM-2.md`, потім `-3` тощо.
 2. **Ніколи** не редагуй `version` і `CHANGELOG.md` вручну — навіть для hotfix. Єдиний артефакт зміни — change-файл; `version`/CHANGELOG формує `n-cursor release` у CI на `main` (агрегує change-файли, ставить git-тег `<name>@<version>`). Будь-яка зміна `version` поза CI (drift від бази чи опублікованої) завалює `check changelog` — навіть якщо поряд є change-файл.
 3. **`npx @nitra/cursor fix changelog`** → exit **`0`** (достатньо наявності change-файлу; `version` лишається незмінним).
 

package/rules/changelog/js/consistency.mjs

@@ -3,10 +3,12 @@
  * change-файл `<ws>/.changes/*.md` — єдиний дозволений артефакт зміни. Bump `version`
  * і генерацію `CHANGELOG.md` робить виключно `n-cursor release` у CI на `main`.
  *
- * Інваріант (на будь-якій гілці): `version` не має відхилятися від бази. Будь-який drift
- * `version` (vs опублікована в реєстрі або vs git-база) — ручний bump поза CI — завалює
- * перевірку, навіть якщо присутній change-файл. Pass лише коли є change-файл, а version
- * не зрушено; зміни без change-файлу — fail.
+ * Інваріант (на будь-якій гілці): `version` у дереві не має **випереджати** базу. Лише
+ * drift **уперед** (`version` > опублікованої в реєстрі / > git-бази) — ручний bump поза
+ * CI — завалює перевірку, навіть із change-файлом. Version **позаду** бази (локаль відстала
+ * від уже опублікованого CI-релізу, ще не зроблено `git pull`) — НЕ порушення: це не ручний
+ * bump, а git і так не дасть запушити non-fast-forward. Pass лише коли є change-файл, а
+ * version не випереджає базу; зміни без change-файлу — fail.
  *
  * Дві моделі бази — на рівні воркспейсу (див. n-changelog.mdc):
  *
@@ -318,6 +320,48 @@ function resolvePublishedVersion(manifest, getPublishedVersion) {
   return getPublishedVersion(manifest.name, manifest.kind)
 }
 
+/** Числове ядро semver (`x.y.z`); хвіст (prerelease/build) ігнорується. */
+const SEMVER_CORE_RE = /^(\d+)\.(\d+)\.(\d+)/
+
+/**
+ * Парсить числове ядро semver-рядка.
+ * @param {unknown} v версія
+ * @returns {{ major: number, minor: number, patch: number } | null} ядро або null
+ */
+function parseSemverCore(v) {
+  const m = typeof v === 'string' ? v.match(SEMVER_CORE_RE) : null
+  if (!m) return null
+  return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) }
+}
+
+/**
+ * Порівнює semver-ядра двох версій.
+ * @param {unknown} a перша версія
+ * @param {unknown} b друга версія
+ * @returns {-1 | 0 | 1 | null} a<b → -1, a==b → 0, a>b → 1; null — нерозпізнано
+ */
+function compareSemverCore(a, b) {
+  const pa = parseSemverCore(a)
+  const pb = parseSemverCore(b)
+  if (!pa || !pb) return null
+  if (pa.major !== pb.major) return pa.major > pb.major ? 1 : -1
+  if (pa.minor !== pb.minor) return pa.minor > pb.minor ? 1 : -1
+  if (pa.patch !== pb.patch) return pa.patch > pb.patch ? 1 : -1
+  return 0
+}
+
+/**
+ * Чи `current` випереджає `base` (ручний bump поза CI). Якщо semver нерозпізнаний
+ * (null) — fail-closed на будь-яку нерівність (консервативно, як до directional-фікса).
+ * @param {unknown} current версія в дереві
+ * @param {unknown} base база (опублікована / git-база)
+ * @returns {boolean} true — current попереду base (або нерозпізнано й не рівні)
+ */
+function versionIsAhead(current, base) {
+  const cmp = compareSemverCore(current, base)
+  return cmp === null ? current !== base : cmp > 0
+}
+
 /**
  * @param {string} name пакет
  * @param {import('../lib/package-manifest.mjs').PackageKind} [kind] тип пакета
@@ -454,16 +498,28 @@ async function checkPublishedWorkspace(manifest, subWorkspaces, getPublishedVers
     pass(`${label}: ${name} — опублікована версія недоступна (мережа/реєстр), перевірку пропущено`)
     return
   }
-  // Drift від опублікованої версії має пріоритет над change-файлом: ручний bump
-  // заборонено навіть із change-файлом (симетрично з local-only-шляхом).
-  if (Vpublished !== Vcurrent) {
+  // Лише drift УПЕРЕД (version > опублікованої) — ручний bump поза CI; має пріоритет
+  // над change-файлом (симетрично з local-only-шляхом). Версія ПОЗАДУ реєстру — локаль
+  // відстала від уже опублікованого релізу, не порушення (нижче).
+  if (versionIsAhead(Vcurrent, Vpublished)) {
     fail(
-      `${label}: version у ${mf} (${Vcurrent}) розходиться з опублікованою (${Vpublished}) — ` +
-        `ручний bump заборонено. Відкоти version і поклади change-файл ` +
+      `${label}: version у ${mf} (${Vcurrent}) випереджає опубліковану (${Vpublished}) — ` +
+        `ручний bump поза CI заборонено. Відкоти version і поклади change-файл ` +
         `(npx @nitra/cursor change …); bump зробить CI на main (n-changelog.mdc)`
     )
     return
   }
+  if (compareSemverCore(Vcurrent, Vpublished) < 0) {
+    // Локаль ПОЗАДУ реєстру: CI вже опублікував новішу версію й закомітив bump назад,
+    // а ти ще не зробив `git pull`. Це не ручний bump (git не дасть запушити
+    // non-fast-forward), тож коміт не блокуємо — лише вимагаємо change-файл на наявні зміни.
+    pass(
+      `${label}: version у ${mf} (${Vcurrent}) позаду опублікованої (${Vpublished}) — ` +
+        `локаль відстала від реєстру (зроби git pull); це не ручний bump`
+    )
+    await checkPublishedWorkspacePendingGitChanges(manifest, Vcurrent, subWorkspaces, pass, fail, cwd)
+    return
+  }
   pass(`${label}: ${name}@${Vcurrent} збігається з реєстром — перевіряємо git на незрелізні зміни`)
   await checkPublishedWorkspacePendingGitChanges(manifest, Vcurrent, subWorkspaces, pass, fail, cwd)
 }
@@ -480,10 +536,11 @@ async function checkLocalOnlyChangedWorkspace(comparisonRef, manifest, baseLabel
   const label = workspaceLabel(manifest)
   const mf = manifestFilePath(manifest.ws, manifest)
   const Vcurrent = manifest.version
-  // Drift version від бази має пріоритет над change-файлом: ручний bump заборонено
-  // навіть якщо change-файл присутній (симетрично з published-шляхом).
+  // Лише drift УПЕРЕД (version > бази) має пріоритет над change-файлом: ручний bump
+  // заборонено навіть із change-файлом (симетрично з published-шляхом). Version позаду
+  // бази (гілка відстала від base-ref) — не порушення, не блокуємо.
   const Vbase = await readBaseVersion(comparisonRef, manifest, cwd)
-  if (Vbase !== null && Vcurrent !== null && Vbase !== Vcurrent) {
+  if (Vbase !== null && Vcurrent !== null && versionIsAhead(Vcurrent, Vbase)) {
     fail(
       `${label}: version у ${mf} змінено поза CI (${Vbase} → ${Vcurrent}) — ручний bump заборонено (на ${baseLabel} — ${Vbase}). ` +
         `Відкоти version і поклади change-файл (npx @nitra/cursor change …); bump зробить CI (n-changelog.mdc)`

package/rules/ci4/ci4.mdc

@@ -66,7 +66,7 @@ RAG витягує **фрагменти**, не цілі документи. Т
 docs/
 ├── adr/
 │   ├── <slug>.md                       # clean ADR-и (MADR v4 minimal, без frontmatter)
-│   ├── YYYYMMDD-HHMMSS-<sid>.md        # drafts (frontmatter session:/captured:/transcript:)
+│   ├── YYMMDD-HHMM-<sid>.md            # drafts (frontmatter session:/captured:/transcript:)
 │   └── index.md                        # autogen — список accepted ADR за датою
 ├── explanation/                        # Diátaxis: чому і що
 │   ├── overview.md                     # Capability Map (autogen)
@@ -86,7 +86,7 @@ docs/
 
 ## ADR як вхід проекцій
 
-Регенератор працює **тільки з clean ADR** (`docs/adr/<slug>.md`, без frontmatter, з рядком `**Status:** Accepted`). Drafts (`YYYYMMDD-HHMMSS-*.md`) ігноруються — їх перетворить у clean ADR `normalize-decisions.sh` із правила `adr`.
+Регенератор працює **тільки з clean ADR** (`docs/adr/<slug>.md`, без frontmatter, з рядком `**Status:** Accepted`). Drafts (`YYMMDD-HHMM-*.md`) ігноруються — їх перетворить у clean ADR `normalize-decisions.sh` із правила `adr`.
 
 Поля, які регенератор читає з clean ADR:
 

package/rules/docker/docker.mdc

@@ -181,7 +181,7 @@ CLI **`hadolint`** приймає лише **явні шляхи** (`[DOCKERFILE
 
 **Область lint-docker (вужча, ніж `check docker`):** лише файли з іменем **`Dockerfile`** та **`*.Dockerfile`** (суфікс **`.dockerfile`** без урахування регістру, наприклад **`api.Dockerfile`**). Файли **`Dockerfile.prod`**, **`Containerfile`** тощо **не** входять у **`lint-docker`**; їх ловить **`check docker`** (`rules/docker/fix.mjs`).
 
-Обхід: **`walkDir`** з тими самими пропусками каталогів, що й **`rules/docker/fix.mjs`**. Виклик **`hadolint`**: **`PATH`**, інакше **`docker run`** — спільна логіка **`npm/rules/docker/js/lint/docker-hadolint.mjs`**.
+Обхід: **`walkDir`** з тими самими пропусками каталогів, що й **`rules/docker/fix.mjs`**. Виклик **`hadolint`** як **нативного бінарника** через **`ensureTool`** (PATH → кеш → авто-install brew/scoop/GitHub Release; **без** `docker run`) — спільна логіка **`npm/rules/docker/lib/docker-hadolint.mjs`**.
 
 - Канон `package.json#scripts.lint-docker`: [package.json.snippet.json](./policy/package_json/template/package.json.snippet.json)
 
@@ -191,14 +191,14 @@ CLI **`hadolint`** приймає лише **явні шляхи** (`[DOCKERFILE
 
 - Канон: [lint-docker.yml.snippet.yml](./policy/lint_docker_yml/template/lint-docker.yml.snippet.yml)
 
-Узгоджуй версію hadolint **v2.12.0** з **`HADOLINT_IMAGE`** у **`npm/rules/docker/js/lint/docker-hadolint.mjs`**.
+Локально hadolint авто-встановлюється через **`ensureTool`** (latest, без піну версії). У CI встанови його кроком із workflow-сніпета (curl-download бінарника — без `docker run`).
 
 Кореневий скрипт **`lint`** (див. **`n-bun.mdc`**) **обов'язково** містить **`bun run lint-docker`**, коли в проєкті підключено правило **`docker`**.
 
 ## Запуск
 
 1. **`bun run lint-docker`** — **`run-docker.mjs`**: **`Dockerfile`** та **`*.Dockerfile`** (див. **`lint-docker`**); у CI встанови hadolint (приклад у workflow).
-2. **`npx @nitra/cursor fix docker`** — **`rules/docker/fix.mjs`**, виклик hadolint як у **`docker-hadolint.mjs`** (**`PATH`** або **`docker run`** з **`hadolint/hadolint:v2.12.0`**).
+2. **`npx @nitra/cursor fix docker`** — **`rules/docker/fix.mjs`**, виклик hadolint як у **`docker-hadolint.mjs`** (нативний бінарник через **`ensureTool`**; **без** `docker run`).
 3. Кореневий **`.hadolint.yaml`**: вимкнення правил, trusted registries — [документація](https://github.com/hadolint/hadolint#configure). Щоб не додавати **`# hadolint ignore=DL3007`** у кожному **`FROM`** з **`:latest`**, у корені репозиторію задати глобально:
 
 ```yaml title=".hadolint.yaml"

package/rules/docker/js/lint.mjs

@@ -29,7 +29,7 @@
  * `USER` у Dockerfile — перевірка non-root для нього пропускається.
  *
  * Знаходить Dockerfile, Dockerfile.*, Containerfile, Containerfile.*; пропускає node_modules, .git
- * тощо. Спочатку hadolint з PATH, інакше docker run з образом hadolint/hadolint.
+ * тощо. hadolint — нативний бінарник через `ensureTool` (PATH/кеш/авто-install; без docker run).
  * Кореневий .hadolint.yaml підхоплюється hadolint автоматично.
  */
 import { readFile } from 'node:fs/promises'

package/rules/docker/lib/docker-hadolint.mjs

@@ -1,20 +1,18 @@
 /**
  * Спільна логіка виклику hadolint для шляхів до Dockerfile (див. docker.mdc).
  *
- * Відносні шляхи з прямими слешами для контейнера; спочатку hadolint з PATH,
- * інакше docker run з образом HADOLINT_IMAGE. Використовується `./check.mjs`
- * (check-docker) та `../../lint/lint.mjs` (run-docker).
+ * Відносні шляхи з прямими слешами; hadolint резолвиться через `ensureTool`
+ * (PATH → кеш → авто-install brew/scoop/GitHub Release per-platform). Docker-fallback
+ * прибрано — hadolint ставиться як **нативний бінарник**, без `docker run`.
+ * Використовується `./check.mjs` (check-docker) та `../../lint/lint.mjs` (run-docker).
  */
 import { spawnSync } from 'node:child_process'
 import { relative, sep } from 'node:path'
 
-import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
-
-/** Тег образу для резервного запуску (узгоджуй з docker.mdc). */
-export const HADOLINT_IMAGE = 'hadolint/hadolint:v2.12.0'
+import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
 
 /**
- * Відносний шлях від root з прямими слешами (hadolint у контейнері).
+ * Відносний шлях від root з прямими слешами (стабільний вивід незалежно від OS).
  * @param {string} root корінь
  * @param {string} absPath абсолютний шлях
  * @returns {string} відносний шлях з прямими слешами
@@ -24,65 +22,39 @@ export function posixRel(root, absPath) {
 }
 
 /**
- * Запуск hadolint: спочатку PATH, інакше Docker.
+ * Запуск hadolint як нативного бінарника. hadolint резолвиться через `ensureTool`
+ * (PATH → кеш → авто-install); якщо авто-install відключено (`N_CURSOR_NO_AUTO_INSTALL`)
+ * чи не вдався — повертаємо `ok: false` з підказкою (без `docker run`).
  * @param {string} root корінь репозиторію
  * @param {string} absPath абсолютний шлях до Dockerfile
- * @returns {{ ok: boolean, stdout: string, stderr: string, via: string }} результат перевірки hadolint та канал запуску
+ * @returns {{ ok: boolean, stdout: string, stderr: string, via: string }} результат перевірки hadolint
  */
 export function lintDockerfileWithHadolint(root, absPath) {
   const rel = posixRel(root, absPath)
-  const hadolintPath = resolveCmd('hadolint')
-  if (hadolintPath) {
-    const local = spawnSync(hadolintPath, [rel], {
-      cwd: root,
-      encoding: 'utf8',
-      maxBuffer: 10 * 1024 * 1024
-    })
-    const ok = local.status === 0
-    return {
-      ok,
-      stdout: local.stdout ?? '',
-      stderr: local.stderr ?? '',
-      via: 'hadolint'
-    }
-  }
-
-  const dockerPath = resolveCmd('docker')
-  if (!dockerPath) {
+  let hadolintPath
+  try {
+    hadolintPath = ensureTool('hadolint')
+  } catch (error) {
     return {
       ok: false,
       stdout: '',
       stderr:
-        'Не знайдено hadolint у PATH і не знайдено docker у PATH. ' +
-        'Встанови hadolint (наприклад brew install hadolint) або Docker (див. docker.mdc).',
-      via: 'docker'
+        `Не вдалося отримати hadolint (${error.message}). ` +
+        'Встанови: brew install hadolint (macOS) / scoop install hadolint (Windows) / ' +
+        'https://github.com/hadolint/hadolint/releases (Linux).',
+      via: 'hadolint'
     }
   }
 
-  const docker = spawnSync(
-    dockerPath,
-    ['run', '--rm', '-v', `${root}:/workdir`, '-w', '/workdir', HADOLINT_IMAGE, rel],
-    {
-      cwd: root,
-      encoding: 'utf8',
-      maxBuffer: 10 * 1024 * 1024
-    }
-  )
-  if (docker.error) {
-    return {
-      ok: false,
-      stdout: '',
-      stderr:
-        `Не знайдено hadolint у PATH і не вдалося запустити Docker (${docker.error.message}). ` +
-        `Встанови hadolint (наприклад brew install hadolint) або Docker (див. docker.mdc).`,
-      via: 'docker'
-    }
-  }
-  const ok = docker.status === 0
+  const local = spawnSync(hadolintPath, [rel], {
+    cwd: root,
+    encoding: 'utf8',
+    maxBuffer: 10 * 1024 * 1024
+  })
   return {
-    ok,
-    stdout: docker.stdout ?? '',
-    stderr: docker.stderr ?? '',
-    via: 'docker'
+    ok: local.status === 0,
+    stdout: local.stdout ?? '',
+    stderr: local.stderr ?? '',
+    via: 'hadolint'
   }
 }