@nitra/cursor 3.19.0 → 3.21.0

package/rules/ga/lint/lint.mjs

@@ -1,6 +1,6 @@
 /**
- * CLI-обгортка над канонічним `lint-ga` (ga.mdc): робить preflight на `shellcheck`, `uv` (для `uvx`)
- * і `conftest` (для rego-полісі у `check-ga`),
+ * CLI-обгортка над канонічним `lint-ga` (ga.mdc): авто-встановлює `shellcheck` і `conftest`
+ * через `ensureTool` (brew/scoop/GitHub Release per-platform), перевіряє наявність `uv` (для `uvx`),
  * тоді послідовно виконує `bunx github-actionlint`, `uvx zizmor --offline --collect=workflows .` і
  * делегує до `rules/ga/fix.mjs::check()` — там і Rego-частина (через `runConftestBatch`),
  * і JS cross-file перевірки правил `ga.mdc`.
@@ -13,14 +13,10 @@
  *
  * Без preflight `actionlint` (через `bunx github-actionlint`) мовчки пропускає shell-перевірки в
  * `run:` блоках, коли `shellcheck` відсутній у PATH; локально `bun lint-ga` лишається зеленим, а CI
- * на ubuntu-latest (де shellcheck передвстановлений) падає. Preflight робить цю різницю явною.
+ * на ubuntu-latest (де shellcheck передвстановлений) падає. ensureTool('shellcheck') усуває цю різницю.
  *
- * `uv` потрібен для `uvx zizmor`. Якщо його нема — `uvx zizmor` падає неінформативно («command not
- * found»); підказка з командою встановлення коротша й корисніша.
- *
- * `conftest` потрібен для `rules/ga/fix.mjs::runAllGaRego` (`runConftestBatch`). Без preflight крок
- * check-ga кидає виняток, який глобальний `catch` у `bin/n-cursor.js` раніше ковтав без логу —
- * локально це виглядало як мовчазний exit 1.
+ * `uv` потрібен для `uvx zizmor`. Якщо його нема — `uvx zizmor` падає неінформативно; підказка
+ * з командою встановлення коротша й корисніша. `uv` не в реєстрі ensureTool → hint-only.
  *
  * Експортовано окремо `runLintGaCli` — використовується з `bin/n-cursor.js` як підкоманда `lint-ga`.
  *
@@ -33,6 +29,7 @@ import { check as checkGa } from '../js/workflows.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
 import { runLintStep } from '../../../scripts/lib/run-lint-step.mjs'
 import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
+import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
 
 /**
  * Опис залежності preflight-ом: бінарник, для чого потрібен, і команди встановлення.
@@ -44,23 +41,6 @@ import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
  * @property {string} successMsg повідомлення на pass-шлях
  */
 
-/** @type {PreflightDep} */
-const SHELLCHECK_PREFLIGHT = {
-  bin: 'shellcheck',
-  winBins: ['shellcheck.exe'],
-  explanation: [
-    'Без нього `actionlint` пропускає shell-перевірки в run: блоках,',
-    'тож локальний прогін зеленіє, а CI на ubuntu-latest (де shellcheck',
-    'передвстановлений) падає на тих самих workflow.'
-  ].join('\n   '),
-  install: [
-    'macOS:        brew install shellcheck',
-    'Debian/Ubuntu: sudo apt-get install -y shellcheck',
-    'Arch:         sudo pacman -S shellcheck'
-  ],
-  successMsg: '✅ shellcheck знайдено в PATH — actionlint виконуватиме SC-правила, як у CI'
-}
-
 /** @type {PreflightDep} */
 const UV_PREFLIGHT = {
   bin: 'uv',
@@ -77,18 +57,6 @@ const UV_PREFLIGHT = {
   successMsg: '✅ uv знайдено в PATH — uvx zizmor запуститься'
 }
 
-/** @type {PreflightDep} */
-const CONFTEST_PREFLIGHT = {
-  bin: 'conftest',
-  winBins: ['conftest.exe'],
-  explanation: [
-    'Без нього не запускається пер-документна валідація через rego-полісі (npm/rules/*/policy/)',
-    'у кроці check-ga — `runConftestBatch` завершується hard-fail.'
-  ].join('\n   '),
-  install: ['macOS:     brew install conftest', 'Universal: https://www.conftest.dev/install/'],
-  successMsg: '✅ conftest знайдено в PATH — check-ga виконає rego-полісі через runConftestBatch'
-}
-
 /**
  * Шукає бінарник у PATH з урахуванням Windows: спершу `winBins`, потім `bin`.
  * @param {PreflightDep} dep опис залежності
@@ -134,29 +102,25 @@ function preflight(dep) {
 }
 
 /**
- * Виконує канонічний `lint-ga` з preflight-перевірками і делегує до `check-ga.check()`.
+ * Виконує канонічний `lint-ga` — авто-встановлює shellcheck/conftest, перевіряє uv, запускає actionlint/zizmor/check-ga.
  *
  * Послідовність:
- * 1) preflight: `shellcheck`, `uv` (для `uvx zizmor`) і `conftest` (для check-ga); відсутній → exit 1;
- * 2) `bunx github-actionlint`;
- * 3) `uvx zizmor --offline --collect=workflows .`;
- * 4) `rules/ga/fix.mjs::check()` — Rego-полісі (батч conftest з `npm/policy/ga/`) + JS cross-file
+ * 1) ensureTool: `shellcheck` і `conftest` (авто-install або hard-fail);
+ * 2) preflight: `uv` (для `uvx zizmor`) — hint-only, без авто-install;
+ * 3) `bunx github-actionlint`;
+ * 4) `uvx zizmor --offline --collect=workflows .`;
+ * 5) `rules/ga/fix.mjs::check()` — Rego-полісі (батч conftest з `npm/policy/ga/`) + JS cross-file
  *    перевірки правил `ga.mdc`. Це **те саме**, що робить `npx \@nitra/cursor check ga`, тож
  *    `lint-ga` тепер є суперсетом перевірки правила: external-tools + check.
- *
- * Якщо хоча б один preflight не пройшов — виходимо одразу з кодом 1, **до** запуску actionlint/zizmor,
- * бо їхні власні повідомлення про відсутність залежностей менш інформативні (особливо для shellcheck —
- * actionlint мовчки пропускає SC-правила; ця перевірка — головний сенс обгортки).
- *
- * Першу помилку від actionlint/zizmor/check повертаємо як код виходу; наступні кроки не запускаються.
  * @returns {Promise<number>} 0 — все OK, інакше — код першого кроку, що впав
  */
 async function runLintGaSteps() {
-  let preflightOk = true
-  for (const dep of [SHELLCHECK_PREFLIGHT, UV_PREFLIGHT, CONFTEST_PREFLIGHT]) {
-    if (!preflight(dep)) preflightOk = false
-  }
-  if (!preflightOk) return 1
+  // Auto-install: throws on failure → propagates as exit 1 from runStandardLint
+  ensureTool('shellcheck')
+  ensureTool('conftest')
+
+  // uv is hint-only (not in auto-install registry)
+  if (!preflight(UV_PREFLIGHT)) return 1
 
   const actionlintCode = runLintStep('actionlint', 'bunx', ['github-actionlint'])
   if (actionlintCode !== 0) return actionlintCode

package/rules/js-run/js/runtime.mjs

@@ -26,6 +26,8 @@
  *  - «Паузи через setTimeout»: `new Promise(resolve => setTimeout(resolve, ms))` (з/без `await`)
  *    треба замінити на `await setTimeout(ms)` з `node:timers/promises`
  *    (див. `utils/promise-settimeout-scan.mjs`);
+ *  - «Temporal у Bun runtime»: identifier `Temporal` заборонений, бо поточний Bun runtime
+ *    не має глобального Temporal API (див. `utils/temporal-scan.mjs`);
  *  - «jsconfig.json»: у backend-пакеті з каталогом `src/` у корені має бути `jsconfig.json`,
  *    вміст якого збігається з каноном js-run.mdc (NodeNext і include на дерево `src`).
  *
@@ -50,6 +52,7 @@ import {
 } from '../lib/conn-imports-scan.mjs'
 import { loadCursorIgnorePaths } from '../../../scripts/lib/load-cursor-config.mjs'
 import { findPromiseSetTimeoutInText, isPromiseSetTimeoutScanSourceFile } from '../lib/promise-settimeout-scan.mjs'
+import { findTemporalUsageInText, isTemporalScanSourceFile } from '../lib/temporal-scan.mjs'
 import { walkDir } from '../../../scripts/utils/walkDir.mjs'
 import { getMonorepoPackageRootDirs } from '../../../scripts/lib/workspaces.mjs'
 
@@ -313,6 +316,30 @@ async function checkPromiseSetTimeoutPause(absPackageRoot, sourcePaths, label, f
   return violations
 }
 
+/**
+ * Сканує джерела пакета на `Temporal`, який у Bun runtime ще недоступний.
+ * @param {string} absPackageRoot абсолютний корінь пакета
+ * @param {string[]} sourcePaths абсолютні шляхи до файлів
+ * @param {string} label префікс повідомлення `[<pkg>] `
+ * @param {(msg: string) => void} fail callback при помилці
+ * @returns {Promise<number>} кількість порушень
+ */
+async function checkTemporalUsage(absPackageRoot, sourcePaths, label, fail) {
+  let violations = 0
+  for (const absPath of sourcePaths) {
+    const rel = relPosix(absPackageRoot, absPath)
+    if (!isTemporalScanSourceFile(rel)) continue
+    const content = await readFile(absPath, 'utf8')
+    for (const v of findTemporalUsageInText(content, rel)) {
+      violations++
+      fail(
+        `${label}${rel}:${v.line} — Temporal API заборонений у Bun runtime; використовуй Date або інʼєктований timestamp`
+      )
+    }
+  }
+  return violations
+}
+
 /**
  * Перевіряє відповідність правилам js-run.mdc для одного workspace-пакета.
  * @param {string} rootDir відносний шлях workspace (не `'.'`)
@@ -371,6 +398,11 @@ async function checkWorkspacePackage(rootDir, ignorePaths, fail, passFn, cwd) {
     passFn(`${label}немає 'new Promise(r => setTimeout(r, ms))' — паузи через 'node:timers/promises'`)
   }
 
+  const temporalViolations = await checkTemporalUsage(absPackageRoot, sourcePaths, label, fail)
+  if (temporalViolations === 0) {
+    passFn(`${label}немає Temporal API у Bun runtime-коді`)
+  }
+
   checkOtelConfigmap(rootDir, passFn, cwd)
 }
 

package/rules/js-run/js-run.mdc

@@ -30,6 +30,12 @@ version: '1.11'
 
 Це **не** стосується поля `engines.node` (мінімальна версія Node для сумісності інструментів) і **не** стосується frontend-пакетів з `vite` у `devDependencies`.
 
+## Temporal API
+
+У backend/Bun runtime-коді **не використовуй `Temporal`** (`Temporal.Now`, `Temporal.Instant`, імпорти з polyfill тощо). Поточний Bun runtime ще не має глобального `Temporal` (`typeof Temporal === "undefined"`), тому агентам треба лишатися на сумісному `Date` API або передавати timestamp у чисті функції через параметр.
+
+Перевірка `npx @nitra/cursor fix js-run` сканує JS/TS AST і падає на identifier `Temporal` у backend workspace-коді.
+
 Канон заборонених патернів у `scripts`: [package.json.deny.json](./policy/package_json/template/package.json.deny.json) (`scriptsForbidden`).
 
 ## Структура проекту

package/rules/js-run/lib/temporal-scan.mjs

@@ -0,0 +1,52 @@
+/**
+ * AST-сканер заборони `Temporal` у Bun runtime-коді.
+ *
+ * Bun 1.3.x ще не має глобального `Temporal`, тому правило js-run забороняє
+ * будь-який identifier `Temporal` у backend workspace-коді. Заборона свідомо
+ * охоплює polyfill/import-сценарії: у цьому репозиторії канон для часу лишається
+ * через `Date` або ін'єкцію timestamp у чисті функції.
+ */
+import {
+  normalizeSnippet,
+  offsetToLine,
+  parseProgramOrNull,
+  walkAstWithAncestors
+} from '../../../scripts/utils/ast-scan-utils.mjs'
+
+const SOURCE_FILE_RE = /\.([cm]?[jt]sx?)$/u
+
+/**
+ * Знаходить використання identifier `Temporal` у тексті.
+ * @param {string} content вихідний код
+ * @param {string} [virtualPath] шлях для вибору `lang` (наприклад `pkg/src/foo.ts`)
+ * @returns {{ line: number, snippet: string }[]} список порушень
+ */
+export function findTemporalUsageInText(content, virtualPath = 'scan.ts') {
+  const program = parseProgramOrNull(content, virtualPath)
+  if (!program) return []
+  /** @type {{ line: number, snippet: string }[]} */
+  const out = []
+  /** @type {Set<string>} */
+  const seen = new Set()
+  walkAstWithAncestors(program, [], node => {
+    if (node.type !== 'Identifier' || node.name !== 'Temporal') return
+    const key = `${node.start}:${node.end}`
+    if (seen.has(key)) return
+    seen.add(key)
+    out.push({
+      line: offsetToLine(content, node.start),
+      snippet: normalizeSnippet(content.slice(node.start, node.end))
+    })
+  })
+  return out
+}
+
+/**
+ * Чи сканувати цей файл за розширенням (JS/TS-сім'я, виключно з `.d.ts`).
+ * @param {string} relativePath відносний шлях до файлу
+ * @returns {boolean} `true`, якщо розширення підходить для сканування
+ */
+export function isTemporalScanSourceFile(relativePath) {
+  if (!SOURCE_FILE_RE.test(relativePath)) return false
+  return !relativePath.endsWith('.d.ts')
+}

package/rules/k8s/lint/lint.mjs

@@ -24,6 +24,7 @@ import { basename, dirname, join, relative } from 'node:path'
 import { parse } from 'yaml'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
 import { loadCursorIgnorePaths } from '../../../scripts/lib/load-cursor-config.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
 import { walkDir } from '../../../scripts/utils/walkDir.mjs'
@@ -123,11 +124,7 @@ function runKubeconform(dirs) {
     '-ignore-missing-schemas',
     ...dirs
   ]
-  const kubeconformPath = resolveCmd('kubeconform')
-  if (!kubeconformPath) {
-    console.error('kubeconform не знайдено в PATH. Встанови з https://github.com/yannh/kubeconform#readme')
-    return 127
-  }
+  const kubeconformPath = ensureTool('kubeconform')
   const r = spawnSync(kubeconformPath, args, { stdio: 'inherit', shell: false })
   if (r.error && 'code' in r.error && r.error.code === 'ENOENT') {
     console.error('kubeconform не знайдено в PATH. Встанови з https://github.com/yannh/kubeconform#readme')
@@ -297,11 +294,7 @@ async function runKubescape(dirs, root) {
   if (exceptionsArgs.length > 0) {
     console.log(`run-k8s: kubescape exceptions — ${KUBESCAPE_EXCEPTIONS_FILE}`)
   }
-  const kubescapePath = resolveCmd('kubescape')
-  if (!kubescapePath) {
-    console.error(KUBESCAPE_MISSING_HINT)
-    return 127
-  }
+  const kubescapePath = ensureTool('kubescape')
   let kubectlPath = null
   for (const d of dirs) {
     const kdirs = await findKustomizationDirs(d)

package/rules/nginx-default-tpl/js/template.mjs

@@ -12,6 +12,9 @@
  * У дереві від **cwd** усі **default.tpl.conf** стають **default.conf.template**: перейменування, або
  * якщо **default.conf.template** уже є — він перезаписується вмістом **default.tpl.conf**, після чого
  * **default.tpl.conf** видаляється. Якщо після міграції шаблону немає — перевірка пропускається (0).
+ *
+ * Невалідна директива **`error_log off;`** (nginx трактує "off" як ім'я файлу `/etc/nginx/off` і падає під
+ * readOnlyRootFilesystem) автоматично замінюється на **`error_log /dev/null crit;`** у кожному шаблоні.
  */
 import { existsSync } from 'node:fs'
 import { readdir, readFile, rename, unlink, writeFile } from 'node:fs/promises'
@@ -33,6 +36,11 @@ const FIND_CMD_RE = /\bfind\b/u
 const GZIP_CMD_RE = /\bgzip\b/u
 const GZIP_EXTENSION_RE = /\*\.(?:js|css)/u
 
+// `error_log off;` — НЕ валідний nginx: "off" трактується як ім'я файлу (/etc/nginx/off)
+// і падає під readOnlyRootFilesystem. /dev/null — writable device, тому канон — `error_log /dev/null crit;`.
+const ERROR_LOG_OFF_RE = /error_log\s+off\s*;/gu
+const ERROR_LOG_CANONICAL = 'error_log /dev/null crit;'
+
 /**
  * Збирає абсолютні шляхи до **default.conf.template** у репозиторії; будь-який сегмент
  * `fixtures/` у шляху виключається — це тестові артефакти (як `tests/fixtures/` так і
@@ -98,6 +106,28 @@ export async function migrateDefaultTplConfFiles(root, ignorePaths = []) {
   return { renamed, overwritten }
 }
 
+/**
+ * Замінює невалідну директиву `error_log off;` на `error_log /dev/null crit;` у всіх
+ * **default.conf.template** від `root`. `error_log off;` — НЕ валідний nginx: "off" трактується
+ * як ім'я файлу (`/etc/nginx/off`) і падає під readOnlyRootFilesystem; `/dev/null` — writable device.
+ * @param {string} root корінь обходу (зазвичай cwd репозиторію)
+ * @param {string[]} ignorePaths абсолютні шляхи каталогів, повністю виключених з обходу
+ * @returns {Promise<string[]>} відносні шляхи виправлених шаблонів (для звіту)
+ */
+export async function migrateErrorLogOffDirective(root, ignorePaths = []) {
+  const templates = await findDefaultConfTemplatePaths(root, ignorePaths)
+  /** @type {string[]} */
+  const fixed = []
+  for (const abs of templates) {
+    const body = await readFile(abs, 'utf8')
+    const next = body.replace(ERROR_LOG_OFF_RE, ERROR_LOG_CANONICAL)
+    if (next === body) continue
+    await writeFile(abs, next, 'utf8')
+    fixed.push(relative(root, abs).replaceAll('\\', '/') || abs)
+  }
+  return fixed
+}
+
 /**
  * Імена змінних з ini (рядки KEY=value, без коментарів і порожніх).
  * @param {string} iniText вміст *.ini
@@ -131,7 +161,10 @@ export function nginxTemplateViolations(content) {
     { msg: 'відсутнє listen 8080', ok: c => c.includes('listen 8080') },
     { msg: 'відсутнє server_name _', ok: c => c.includes('server_name _') },
     { msg: 'відсутнє access_log off', ok: c => c.includes('access_log off') },
-    { msg: 'відсутнє error_log off', ok: c => c.includes('error_log off') },
+    {
+      msg: 'відсутнє error_log /dev/null crit (error_log off — НЕ валідний nginx, падає під readOnlyRootFilesystem)',
+      ok: c => c.includes('error_log /dev/null crit')
+    },
     { msg: 'відсутнє root /usr/share/nginx/html', ok: c => c.includes('root /usr/share/nginx/html') },
     {
       msg: 'location /healthz має повертати healthy (див. nginx-default-tpl.mdc)',
@@ -416,6 +449,11 @@ export async function check(cwd = process.cwd()) {
     pass(`Перезаписано default.conf.template змістом default.tpl.conf: ${rel}`)
   }
 
+  const errorLogFixed = await migrateErrorLogOffDirective(root, ignorePaths)
+  for (const rel of errorLogFixed) {
+    pass(`Замінено невалідне error_log off; → error_log /dev/null crit; у ${rel}`)
+  }
+
   const templates = await findDefaultConfTemplatePaths(root, ignorePaths)
 
   if (templates.length === 0) {

package/rules/nginx-default-tpl/nginx-default-tpl.mdc

@@ -19,7 +19,9 @@ server {
 
     # disable all log
     access_log off;
-    error_log off;
+    # `error_log off;` — НЕ валідний nginx: "off" трактується як ім'я файлу (/etc/nginx/off)
+    # і падає під readOnlyRootFilesystem. /dev/null — writable device.
+    error_log /dev/null crit;
 
     # This would be the directory where your Vite app's static files are stored at
     root /usr/share/nginx/html;

package/rules/npm-module/js/skill_meta.mjs

@@ -4,6 +4,8 @@
  * Кожен `npm/skills/<id>/` має містити валідний `meta.json`:
  *  - `worktree` присутнє і boolean;
  *  - `auto` (якщо присутнє) — розпізнане (`"завжди"` або непорожній масив рядків);
+ *  - `requireRoot` (якщо присутнє) — boolean; не може бути `false` при `worktree:true`
+ *    (worktree вже вимагає кореня — суперечність вводить в оману);
  *  - залишковий `auto.md` заборонено (міграція на meta.json завершена).
  *
  * Концерн застосовний лише в репо самого пакета (де є `npm/skills/`); у споживача
@@ -52,6 +54,16 @@ export function check(cwd = process.cwd()) {
       reporter.fail(`skills/${id}: meta.json.auto нерозпізнане — очікується "завжди" або непорожній масив правил`)
       skillOk = false
     }
+    if (raw.requireRoot !== undefined && typeof raw.requireRoot !== 'boolean') {
+      reporter.fail(`skills/${id}: meta.json.requireRoot має бути boolean`)
+      skillOk = false
+    }
+    if (raw.worktree === true && raw.requireRoot === false) {
+      reporter.fail(
+        `skills/${id}: requireRoot:false суперечить worktree:true (worktree вже вимагає кореня — прибери поле)`
+      )
+      skillOk = false
+    }
     if (skillOk) {
       reporter.pass(`skills/${id}: meta.json валідний`)
     }

package/rules/npm-module/npm-module.mdc

@@ -65,7 +65,7 @@ bunx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly
 
 **`npm-publish.yml`:** push у **`main`**, **`on.push.paths`** з **`npm/**`**, **`JS-DevTools/npm-publish@v4.1.5`**, **`with.package: npm/package.json`**, **`permissions.id-token: write`** (OIDC на npm).
 
-Workflow робить **release + publish** одним job (`release-publish`): крок **`Release (bump + CHANGELOG + tag)`** (`node npm/bin/n-cursor.js release` — агрегує change-файли, bump `version`, генерує секцію `CHANGELOG.md`, ставить git-тег) виконується **перед** публікацією. Тому потрібні **`permissions.contents: write`** і **`persist-credentials: true`** з **`fetch-depth: 0`** на `checkout` (release пушить commit-back версії та тег), а також локальний composite **`./.github/actions/setup-bun-deps`** і крок `Configure git identity`. Це узгоджено з **`n-changelog`**: `version`/`CHANGELOG.md` змінює лише `n-cursor release` у CI на `main`. Програмна перевірка (`npm_module.npm_publish_yml`) лишається subset-of — enforce-ить `on.push.paths`/`branches`, `id-token: write` і наявність publish-кроку; додаткові кроки (release, git identity) дозволені.
+Workflow робить **release + publish** одним job (`release-publish`): крок **`Release (bump + CHANGELOG + tag)`** (`node npm/bin/n-cursor.js release` — агрегує change-файли, bump `version`, генерує секцію `CHANGELOG.md`, ставить git-тег) виконується **перед** публікацією. Тому потрібні **`permissions.contents: write`** і **`persist-credentials: true`** з **`fetch-depth: 0`** на `checkout` (release пушить commit-back версії та тег), а також локальний composite **`./.github/actions/setup-bun-deps`** і крок `Configure git identity`. Це узгоджено з **`n-changelog`**: `version`/`CHANGELOG.md` змінює лише `n-cursor release` у CI на `main`. Програмна перевірка (`npm_module.npm_publish_yml`) звіряє **весь канонічний сніпет** напряму (`target.json:"check":"template"`, generic deep-subset): усі поля й кроки сніпета (`on.push.paths`/`branches`, `concurrency`, `permissions.contents/id-token`, `checkout` з `persist-credentials/fetch-depth`, `setup-bun-deps`, `Configure git identity`, `Release`, publish-крок) **обовʼязкові**; зайві кроки/поля дозволені (subset-of), масиви матчаться за наявністю (порядок кроків не важить). Сніпет — єдине джерело істини: його редагування одразу змінює enforce, без правок rego й без міграторів.
 
 - Канон: [npm-publish.yml.snippet.yml](./policy/npm_publish_yml/template/npm-publish.yml.snippet.yml)
 

package/rules/npm-module/policy/npm_publish_yml/target.json

@@ -1,4 +1,5 @@
 {
   "$schema": "https://unpkg.com/@nitra/cursor/schemas/target.json",
+  "check": "template",
   "files": { "single": ".github/workflows/npm-publish.yml" }
 }

package/rules/rego/lint/lint.mjs

@@ -1,7 +1,7 @@
 /**
- * Лінт Rego-полісі (`conftest.mdc` + `rego.mdc`): preflight на `opa` і `regal`,
- * далі послідовно `opa check --strict`, `regal lint` і опційний
- * `conftest verify` (для `*_test.rego`-файлів) якщо conftest у PATH.
+ * Лінт Rego-полісі (`conftest.mdc` + `rego.mdc`): `ensureTool` на `opa` і `regal`
+ * (авто-install per-platform або hard-fail), далі послідовно `opa check --strict`,
+ * `regal lint` і опційний `conftest verify` (для `*_test.rego`-файлів) якщо conftest у PATH.
  *
  * Чому два-три інструменти:
  * - `opa check --strict` — компіляція з типами і строгим режимом (мертвий код, неоднозначні
@@ -13,10 +13,10 @@
  *   Якщо conftest відсутній у PATH — пропускаємо без помилки (тести опційні в локальному середовищі;
  *   у CI потрібно встановити conftest).
  *
- * Без preflight-у на бінарники лінт мовчки злетить з невиразним повідомленням від shell —
- * друкуємо явні install-hints (як це робить `lint-ga.mjs` для shellcheck/uv). `opa` додатково
- * потрібен VS Code-розширенню `tsandall.opa` (LSP, format-on-save через `opa fmt`) — деталі в
- * `mdc/rego.mdc`.
+ * `opa`/`regal` резолвляться через `ensureTool` (PATH → кеш → авто-install brew/scoop/GitHub
+ * Release → hard-fail) — без них лінт мовчки злетів би з невиразним повідомленням від shell.
+ * `opa` додатково потрібен VS Code-розширенню `tsandall.opa` (LSP, format-on-save через
+ * `opa fmt`) — деталі в `mdc/rego.mdc`.
  *
  * Цілі лінту: `npm/rules/` (де живуть Rego-полісі пакета `@nitra/cursor` — у
  * `npm/rules/<id>/policy/<concern>/`). Усі три інструменти приймають один шлях
@@ -31,47 +31,13 @@ import { existsSync } from 'node:fs'
 import { resolve } from 'node:path'
 
 import { isRunAsCli } from '../../../scripts/cli-entry.mjs'
+import { ensureTool } from '../../../scripts/lib/ensure-tool.mjs'
 import { resolveCmd } from '../../../scripts/utils/resolve-cmd.mjs'
 import { runStandardLint } from '../../../scripts/lib/run-standard-lint.mjs'
 
 /** Шляхи з Rego-полісі (відносно cwd). Існують не всі на ранніх стадіях — фільтруємо нижче. */
 const LINT_TARGETS = ['npm/rules']
 
-/**
- * Друкує підказку зі встановлення `opa` (потрібен для `opa check --strict` і VS Code LSP).
- * @returns {void}
- */
-function printOpaInstallHints() {
-  process.stderr.write(
-    [
-      '❌ opa не знайдено в PATH.',
-      '   Без нього не запускається `opa check --strict` (типи + мертвий код у *.rego),',
-      '   і не працює VS Code-розширення `tsandall.opa` (LSP, format-on-save через opa fmt).',
-      '   Встанови:',
-      '     macOS:     brew install opa',
-      '     Universal: https://www.openpolicyagent.org/docs/latest/#1-download-opa',
-      ''
-    ].join('\n')
-  )
-}
-
-/**
- * Друкує підказку зі встановлення `regal`.
- * @returns {void}
- */
-function printRegalInstallHints() {
-  process.stderr.write(
-    [
-      '❌ regal не знайдено в PATH.',
-      '   Без нього не перевіряється rego.v1 синтаксис у *.rego (правило `conftest`).',
-      '   Встанови:',
-      '     macOS:     brew install regal',
-      '     Universal: https://docs.styra.com/regal#installation',
-      ''
-    ].join('\n')
-  )
-}
-
 /**
  * Запускає крок з відображенням команди користувачу. Stdout/stderr передаємо як є
  * (`stdio: 'inherit'`), щоб виглядало як прямий виклик у shell.
@@ -101,19 +67,8 @@ function runStep(bin, args, cwd) {
  */
 export function runLintRegoSteps(cwd = process.cwd()) {
   const root = resolve(cwd)
-  const opa = resolveCmd('opa')
-  const regal = resolveCmd('regal')
-
-  let preflightOk = true
-  if (!opa) {
-    printOpaInstallHints()
-    preflightOk = false
-  }
-  if (!regal) {
-    printRegalInstallHints()
-    preflightOk = false
-  }
-  if (!preflightOk) return 1
+  const opa = ensureTool('opa')
+  const regal = ensureTool('regal')
 
   const targets = LINT_TARGETS.filter(rel => existsSync(resolve(root, rel)))
   if (targets.length === 0) {

package/rules/release/change.mjs

@@ -1,11 +1,40 @@
 /**
- * `n-cursor change` — пише один change-файл `<ws>/.changes/<timestamp>-<rand>.md`.
+ * `n-cursor change` — пише один change-файл `<ws>/.changes/YYMMDD-HHMM.md`.
+ * Якщо файл за ту саму хвилину вже існує, додає `-2`, `-3` тощо.
  * Замінює ручне редагування CHANGELOG у feature-флоу (n-changelog.mdc v3.0).
  */
 import { mkdir, writeFile } from 'node:fs/promises'
 import { join } from 'node:path'
 
-import { CHANGES_DIR, newChangeFileName, parseChangeFile, serializeChangeFile } from './lib/change-file.mjs'
+import { CHANGES_DIR, changeFileName, parseChangeFile, serializeChangeFile } from './lib/change-file.mjs'
+
+/**
+ * @param {unknown} error помилка `writeFile`
+ * @returns {boolean} true, якщо файл уже існує
+ */
+function isFileExistsError(error) {
+  return error instanceof Error && 'code' in error && error.code === 'EEXIST'
+}
+
+/**
+ * Записує change-файл create-only, додаючи числовий suffix лише при локальній колізії.
+ * @param {string} dir абсолютний шлях до `.changes`
+ * @param {string} content вміст change-файлу
+ * @param {number} timestamp epoch milliseconds
+ * @returns {Promise<string>} створене ім'я файла
+ */
+async function writeUniqueChangeFile(dir, content, timestamp) {
+  for (let sequence = 1; ; sequence++) {
+    const name = changeFileName(timestamp, sequence)
+    try {
+      await writeFile(join(dir, name), content, { flag: 'wx' })
+      return name
+    } catch (error) {
+      if (isFileExistsError(error)) continue
+      throw error
+    }
+  }
+}
 
 /**
  * @param {object} params параметри
@@ -14,9 +43,10 @@ import { CHANGES_DIR, newChangeFileName, parseChangeFile, serializeChangeFile }
  * @param {string} params.message опис
  * @param {string} [params.ws] workspace (за замовчуванням `.`)
  * @param {string} [params.cwd] корінь
+ * @param {number} [params.timestamp] epoch milliseconds для детермінованих тестів
  * @returns {Promise<string>} відносний шлях створеного файлу (від ws)
  */
-export async function writeChange({ bump, section, message, ws = '.', cwd = process.cwd() }) {
+export async function writeChange({ bump, section, message, ws = '.', cwd = process.cwd(), timestamp = Date.now() }) {
   const description = (message ?? '').trim()
   const content = serializeChangeFile({ bump, section, description })
   // Валідація полів: parseChangeFile кидає зрозумілу помилку на невалідних bump/section/порожньому описі.
@@ -24,8 +54,7 @@ export async function writeChange({ bump, section, message, ws = '.', cwd = proc
 
   const dir = join(cwd, ws, CHANGES_DIR)
   await mkdir(dir, { recursive: true })
-  const name = newChangeFileName()
-  await writeFile(join(dir, name), content)
+  const name = await writeUniqueChangeFile(dir, content, timestamp)
   return join(CHANGES_DIR, name)
 }
 

package/rules/release/lib/change-file.mjs

@@ -1,10 +1,10 @@
 /**
- * Один change-файл `<ws>/.changes/<timestamp>-<rand>.md`: YAML-подібний frontmatter
+ * Один change-файл `<ws>/.changes/YYMMDD-HHMM.md`: YAML-подібний frontmatter
  * із двома ключами (`bump`, `section`) + текст опису. Парсер мінімальний — лише ці два
- * ключі, без зовнішніх залежностей.
+ * ключі, без зовнішніх залежностей. Якщо файл за ту саму хвилину вже існує, writer додає
+ * числовий suffix (`-2`, `-3`) атомарним create-only записом.
  */
 
-import { randomBytes } from 'node:crypto'
 import { existsSync } from 'node:fs'
 import { readdir, readFile } from 'node:fs/promises'
 import { join } from 'node:path'
@@ -65,21 +65,36 @@ export function serializeChangeFile(entry) {
 export const CHANGES_DIR = '.changes'
 
 /**
- * @param {number} timestamp `Date.now()`
- * @param {string} suffix короткий випадковий суфікс (hex)
- * @returns {string} `<timestamp>-<suffix>.md`
+ * @param {number} timestamp epoch milliseconds
+ * @returns {string} local timestamp prefix `YYMMDD-HHMM`
  */
-export function changeFileName(timestamp, suffix) {
-  return `${timestamp}-${suffix}.md`
+function formatChangeTimestamp(timestamp) {
+  const d = new Date(timestamp)
+  const yy = String(d.getFullYear()).slice(-2)
+  const month = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  const hour = String(d.getHours()).padStart(2, '0')
+  const minute = String(d.getMinutes()).padStart(2, '0')
+  return `${yy}${month}${day}-${hour}${minute}`
 }
 
 /**
- * Унікальне ім'я для нового change-файлу: timestamp (порядок) + rand (анти-колізія
- * для паралельних агентів у різних worktree, що пишуть у ту саму мілісекунду).
+ * @param {number} timestamp epoch milliseconds
+ * @param {number} [sequence] collision sequence; `1`/omitted has no suffix
+ * @returns {string} `YYMMDD-HHMM.md` or `YYMMDD-HHMM-<n>.md`
+ */
+export function changeFileName(timestamp, sequence = 1) {
+  const base = formatChangeTimestamp(timestamp)
+  return sequence > 1 ? `${base}-${sequence}.md` : `${base}.md`
+}
+
+/**
+ * Базове ім'я для нового change-файлу. Унікальність забезпечує writer: він спершу
+ * пробує `YYMMDD-HHMM.md`, а suffix додає лише при локальному `EEXIST`.
  * @returns {string} результат
  */
 export function newChangeFileName() {
-  return changeFileName(Date.now(), randomBytes(3).toString('hex'))
+  return changeFileName(Date.now())
 }
 
 /**