@nitra/cursor 3.19.0 → 3.21.0

package/scripts/lib/root-notice.mjs

@@ -0,0 +1,64 @@
+/**
+ * Вшивання root-guard preflight у синкнутий `SKILL.md` для скілів, що **мутують
+ * проєкт у поточному каталозі**, але виконуються **in-place** (без worktree-
+ * ізоляції) — `meta.json` → `requireRoot: true` і `worktree: false`.
+ *
+ * Worktree-скіли (`worktree: true`) свій root-assert уже мають у worktree-блоці
+ * (`worktree-notice.mjs`): корінь worktree = його toplevel. Цей модуль — для
+ * не-worktree-кейсу (напр. `n-start-check`, що прогоняє `start` усіх воркспейсів
+ * у місці й має стартувати з кореня монорепо).
+ *
+ * Блок — інструкція агенту, що читає `SKILL.md`; вставляється між стабільними
+ * маркерами, ре-синк ідемпотентний: наявний блок замінюється, при `false` —
+ * видаляється. Програмний аналог для CLI-команд — `assertCwdIsProjectRoot`.
+ */
+
+/** Маркер початку root-блоку. */
+export const ROOT_START = '<!-- n-cursor:root:start -->'
+/** Маркер кінця root-блоку. */
+export const ROOT_END = '<!-- n-cursor:root:end -->'
+
+/** Наявний блок разом із сусідніми порожніми рядками (для чистого видалення). */
+const BLOCK_RE = /\n*<!-- n-cursor:root:start -->[\s\S]*?<!-- n-cursor:root:end -->\n*/u
+
+/** Закриття YAML-frontmatter на початку файла. */
+const FRONTMATTER_RE = /^(---\n[\s\S]*?\n---\n)/u
+
+/** Тіло root-guard інструкції. */
+const NOTICE_BODY = `> [!IMPORTANT]
+> **Root-only skill.** Скіл мутує проєкт у поточному каталозі й має запускатися **з кореня репозиторію**.
+
+**Крок 0 — preflight (обовʼязковий, перед будь-якими іншими діями).**
+
+\`\`\`bash
+pwd
+git rev-parse --show-toplevel
+\`\`\`
+
+Якщо \`pwd\` **не** збігається з виводом \`git rev-parse --show-toplevel\` — ти в **піддиректорії**. **STOP**: перейди в корінь (\`cd <toplevel>\`, literal-шлях із виводу) і лише тоді виконуй наступні кроки скіла. Поза git-репо (команда без виводу) — продовжуй (корінь визначити неможливо).`
+
+/** Канонічний блок root-інструкції (з маркерами). */
+const BLOCK = `${ROOT_START}\n${NOTICE_BODY}\n${ROOT_END}`
+
+/**
+ * Вставляє / оновлює / видаляє root-guard блок у вмісті `SKILL.md`.
+ * @param {string} content вміст `SKILL.md`
+ * @param {boolean} enabled чи має бути блок (`requireRoot && !worktree`)
+ * @returns {string} оновлений вміст (ідемпотентно)
+ */
+export function injectRootNotice(content, enabled) {
+  const hadBlock = content.includes(ROOT_START)
+  const withoutBlock = content.replace(BLOCK_RE, '\n\n')
+
+  if (!enabled) {
+    return hadBlock ? withoutBlock : content
+  }
+
+  const fm = withoutBlock.match(FRONTMATTER_RE)
+  if (fm) {
+    const head = fm[1]
+    const rest = withoutBlock.slice(head.length).replace(/^\n+/u, '')
+    return `${head}\n${BLOCK}\n\n${rest}`
+  }
+  return `${BLOCK}\n\n${withoutBlock.replace(/^\n+/u, '')}`
+}

package/scripts/lib/run-conftest-batch.mjs

@@ -4,15 +4,13 @@
  * пер-документні правила винесені у `npm/policy/<rule>/<name>/` як rego-полісі
  * (Rego-authoritative). JS у `check-*.mjs` робить cross-file частину (walking
  * дерева, парність, kustomize-резолюція), а пер-документне валідаційне ядро
- * делегується сюди — один спавн `conftest` на (`namespace`, `policyDir`),
+ * делегується сюді — один спавн `conftest` на (`namespace`, `policyDir`),
  * незалежно від кількості файлів. Це закриває дублювання JS↔rego і прибирає
  * ризик дрифту (типу `spec.config` vs `spec.default.config` у
  * `health_check_policy.rego`, що ми ловили cross-check тестами).
  *
- * Hard-fail на відсутність `conftest` у PATH — узгоджено з рішенням Plan B:
- * якщо правило делегує свою логіку до Rego, а інструмент відсутній, тиха
- * відмова приховує реальні порушення. Друкуємо install-hint (як `lint-rego.mjs`
- * робить для opa/regal).
+ * Hard-fail на відсутність `conftest` — через `ensureTool`, що спочатку
+ * намагається авто-встановити, і лише після невдачі кидає виняток.
  */
 import { spawnSync } from 'node:child_process'
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
@@ -20,7 +18,7 @@ import { tmpdir } from 'node:os'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { resolveCmd } from '../utils/resolve-cmd.mjs'
+import { ensureTool } from './ensure-tool.mjs'
 
 /**
   Каталог пакета `@nitra/cursor`, від якого ресолвимо вшиті директорії правил.
@@ -30,23 +28,6 @@ const PACKAGE_ROOT = dirname(dirname(dirname(fileURLToPath(import.meta.url))))
 /** Шлях до кореня правил. У npm-tarball публікується через `files: ["rules"]`. Кожне правило: `rules/<id>/policy/<name>/`. */
 const RULES_ROOT = join(PACKAGE_ROOT, 'rules')
 
-/**
- * Друкує install-hint для conftest і кидає виняток, щоб викликана `check-*`
- * команда ясно завершилась з кодом 1.
- * @returns {never} завжди кидає; для точки виклику — non-returning
- */
-function failConftestMissing() {
-  throw new Error(
-    [
-      '❌ conftest не знайдено в PATH.',
-      '   Без нього не запускається пер-документна валідація через rego-полісі (npm/policy/).',
-      '   Встанови:',
-      '     macOS:     brew install conftest',
-      '     Universal: https://www.conftest.dev/install/'
-    ].join('\n')
-  )
-}
-
 /**
  * @typedef {object} ConftestViolation
  * @property {string} filename абсолютний шлях до файла, що дав порушення (з output conftest)
@@ -80,16 +61,13 @@ export function buildConftestArgs(p) {
 /**
  * Виконує `conftest test` для всіх файлів одним спавном і повертає масив
  * порушень. Якщо `files` порожній — повертає `[]` без спавна. Якщо `conftest`
- * не у PATH — кидає виняток (hard fail, див. модульний docstring).
+ * не у PATH і авто-встановлення не вдалось — кидає виняток (hard fail).
  * @param {ConftestBatchOptions} opts параметри запуску
  * @returns {ConftestViolation[]} масив порушень (порожній — все ок)
  */
 export function runConftestBatch(opts) {
   if (opts.files.length === 0) return []
-  const conftestBin = resolveCmd('conftest')
-  if (!conftestBin) {
-    failConftestMissing()
-  }
+  const conftestBin = ensureTool('conftest')
   // policyDirRel — формат `<rule>/<name>` (наприклад `abie/base_deployment_preem`).
   // Реальний шлях у новій структурі: `rules/<rule>/policy/<name>`.
   const slash = opts.policyDirRel.indexOf('/')

package/scripts/lib/run-rule.mjs

@@ -13,13 +13,20 @@
  * Це дає той самий 0/1 контракт, що й попередня модель «один check.mjs на правило».
  */
 import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { join, relative } from 'node:path'
 
 import { findMissingMdcRefs } from './check-mdc-template-refs.mjs'
 import { createCheckReporter } from './check-reporter.mjs'
 import { resolveTargetFiles } from './resolve-target-files.mjs'
 import { runConftestBatch } from './run-conftest-batch.mjs'
-import { resolveConcernTemplateData } from './template.mjs'
+import {
+  checkContains,
+  checkDeny,
+  checkSnippet,
+  checkTextSubset,
+  parseByExt,
+  resolveConcernTemplateData
+} from './template.mjs'
 
 const APPLIES_CONCERN_NAME = 'applies'
 
@@ -52,6 +59,46 @@ async function evaluateAppliesGate(bundledRulesDir, rule) {
   return Boolean(await mod.applies())
 }
 
+/**
+ * Snippet-driven перевірка концерну (`target.json:"check":"template"`): канон зі
+ * `template/<target>.snippet|deny|contains.<ext>` звіряється з actual-файлом
+ * generic deep-subset-ом, без `.rego`. Семантика — subset-of: усі канонічні
+ * поля/елементи обовʼязкові, зайві дозволені; масиви матчаться за наявністю
+ * (order-insensitive). Сніпет — єдине джерело істини: його зміна одразу змінює enforce.
+ * @param {string} concernAbsDir абсолютний `rules/<id>/policy/<concern>/`
+ * @param {object} target розпарсений `target.json`
+ * @param {string[]} files актуальні файли-таргети (resolveTargetFiles)
+ * @param {string} ruleId id правила (для `source` у повідомленнях)
+ * @param {string} concernName імʼя концерну (для summary)
+ * @returns {Promise<number>} 0 — OK, 1 — є порушення
+ */
+export async function runTemplateSubsetConcern(concernAbsDir, target, files, ruleId, concernName) {
+  const reporter = createCheckReporter()
+  const data = await resolveConcernTemplateData(concernAbsDir, target)
+  if (!data) {
+    reporter.pass(`${concernName}: немає template-сніпета — пропущено`)
+    return reporter.getExitCode()
+  }
+  for (const file of files) {
+    const rel = relative(process.cwd(), file) || file
+    const actual = await parseByExt(file)
+    const opts = { targetPath: rel, source: `${ruleId}.mdc` }
+    const violations = [
+      ...(typeof data.snippet === 'string'
+        ? checkTextSubset(actual, data.snippet, opts)
+        : checkSnippet(actual, data.snippet, opts)),
+      ...checkDeny(actual, data.deny, opts),
+      ...checkContains(actual, data.contains, opts)
+    ]
+    if (violations.length === 0) {
+      reporter.pass(`${concernName}: ${rel} відповідає канону (template subset)`)
+    } else {
+      for (const v of violations) reporter.fail(v)
+    }
+  }
+  return reporter.getExitCode()
+}
+
 /**
  * Запускає одну policy-полісі через `runConftestBatch`. Створює локальний репортер,
  * читає `target.json`, визначає файли, фіксує fail/pass — і повертає exit-код.
@@ -63,8 +110,9 @@ async function evaluateAppliesGate(bundledRulesDir, rule) {
  */
 async function runPolicyConcern(bundledRulesDir, ruleId, concernName, walkCache) {
   const reporter = createCheckReporter()
-  const targetPath = join(bundledRulesDir, ruleId, 'policy', concernName, 'target.json')
-  /** @type {{ files: { single?: string, walkGlob?: string|string[], required?: boolean }, missingMessage?: string }} */
+  const concernAbsDir = join(bundledRulesDir, ruleId, 'policy', concernName)
+  const targetPath = join(concernAbsDir, 'target.json')
+  /** @type {{ check?: 'template', files: { single?: string, walkGlob?: string|string[], required?: boolean }, missingMessage?: string }} */
   const target = JSON.parse(await readFile(targetPath, 'utf8'))
   const files = await resolveTargetFiles(target.files, process.cwd(), walkCache)
   if (files.length === 0) {
@@ -76,10 +124,18 @@ async function runPolicyConcern(bundledRulesDir, ruleId, concernName, walkCache)
     }
     return reporter.getExitCode()
   }
+
+  // `"check": "template"` — концерн без власного `.rego`: канон зі `template/`
+  // звіряється напряму через generic deep-subset (`checkSnippet`/`checkDeny`/
+  // `checkContains`/`checkTextSubset`). Редагування сніпета автоматично змінює
+  // enforce — без правок rego й без міграторів.
+  if (target.check === 'template') {
+    return runTemplateSubsetConcern(concernAbsDir, target, files, ruleId, concernName)
+  }
+
   // Rego не дозволяє '-' в імені пакета, тому kebab-id у `.n-cursor.json:rules`
   // мапиться на snake у namespace. Файлова структура `rules/<id>/policy/` лишається kebab.
   const regoNamespace = `${ruleId.replaceAll('-', '_')}.${concernName}`
-  const concernAbsDir = join(bundledRulesDir, ruleId, 'policy', concernName)
   const templateData = await resolveConcernTemplateData(concernAbsDir, target)
   const violations = runConftestBatch({
     policyDirRel: `${ruleId}/${concernName}`,

package/scripts/lib/skill-meta.mjs

@@ -3,10 +3,14 @@
  *
  * `meta.json` — єдине джерело правди для скіла замість колишнього `auto.md`:
  *  - `auto` — умова автоактивації (`"завжди"` | масив id правил), опційне;
- *  - `worktree` — boolean: чи виконувати скіл в окремому git-worktree (один інстанс).
+ *  - `worktree` — boolean: чи виконувати скіл в окремому git-worktree (один інстанс);
+ *  - `requireRoot` — boolean, опційне: чи скіл вимагає запуску з кореня репо.
+ *    Worktree-скіли (`worktree:true`) вимагають кореня неявно (корінь worktree =
+ *    його toplevel), тож для них поле зайве. Явний `requireRoot:true` — для
+ *    in-place скілів, що мутують CWD без worktree-ізоляції (напр. `n-start-check`).
  *
  * Цим хелпером користуються `auto-skills.mjs` (автоактивація), `n-cursor.js`
- * (sync + вшивання worktree-блоку) і check-концерн `npm-module/js/skill_meta.mjs`,
+ * (sync + вшивання worktree/root-блоку) і check-концерн `npm-module/js/skill_meta.mjs`,
  * щоб не дублювати парсинг і форму валідації.
  */
 import { existsSync, readFileSync } from 'node:fs'
@@ -36,6 +40,16 @@ export function parseSkillAutoSpec(value) {
   return null
 }
 
+/**
+ * Чи вимагає скіл запуску з кореня репо («активовано root-захист»). Єдина похідна
+ * ознака: `worktree:true` (корінь гарантує worktree) АБО явний `requireRoot:true`.
+ * @param {Record<string, unknown> | null} meta розпарсений `meta.json` (або null)
+ * @returns {boolean} true — скіл мутує проєкт і має стартувати з кореня
+ */
+export function skillRequiresRoot(meta) {
+  return meta?.worktree === true || meta?.requireRoot === true
+}
+
 /**
  * Читає й парсить `meta.json` одного скіла.
  * @param {string} skillDir абсолютний шлях до каталогу скіла

package/scripts/lib/template.mjs

@@ -26,7 +26,7 @@ const LEADING_BANG_RE = /^!/
  * @param {string} path шлях до файлу
  * @returns {Promise<unknown>} розпарсений вміст
  */
-async function parseByExt(path) {
+export async function parseByExt(path) {
   const raw = await readFile(path, 'utf8')
   const ext = extname(path).toLowerCase()
   if (ext === '.json' || ext === '.jsonc') return JSON.parse(stripJsonComments(raw))
@@ -112,6 +112,27 @@ function quote(v) {
   return typeof v === 'string' ? JSON.stringify(v) : String(v)
 }
 
+/** Ключі, за якими ідентифікуємо елемент масиву обʼєктів у повідомленні (напр. workflow-крок). */
+const ELEMENT_ID_KEYS = ['uses', 'name', 'id', 'run']
+
+/**
+ * Людинозрозумілий опис елемента масиву для повідомлення про відсутність.
+ * Для скаляра — `quote`; для обʼєкта — перший наявний ідентифікуючий ключ
+ * (`uses`/`name`/`id`/`run`), інакше компактний JSON.
+ * @param {unknown} needle елемент сніпета, якого бракує в actual
+ * @returns {string} опис для тексту порушення
+ */
+function describeElement(needle) {
+  if (needle !== null && typeof needle === 'object' && !Array.isArray(needle)) {
+    const obj = /** @type {Record<string, unknown>} */ (needle)
+    for (const k of ELEMENT_ID_KEYS) {
+      if (typeof obj[k] === 'string') return `елемент з ${k}: ${quote(obj[k])}`
+    }
+    return `елемент ${JSON.stringify(needle)}`
+  }
+  return quote(needle)
+}
+
 /**
  * Deep subset-of check. Every leaf in `snippet` must equal same path in `actual`.
  * Arrays in snippet: every element must be present in actual array.
@@ -131,10 +152,15 @@ export function checkSnippet(actual, snippet, opts, path = []) {
       violations.push(`${targetPath}: ${formatPath(path)} має бути масивом (${source})`)
       return violations
     }
+    // Subset-of, order-insensitive: кожен елемент сніпета має структурно міститись
+    // хоча б в одному елементі actual. Для обʼєктів — рекурсивний subset
+    // (`checkSnippet` без порушень), тож порядок ключів, зайві поля й зайві елементи
+    // не ламають збіг. Критично для впорядкованих масивів як `steps`, де елементи
+    // сортувати не можна (порядок кроків семантичний) — матч лишається за наявністю.
     for (const needle of snippet) {
-      const found = actual.some(a => JSON.stringify(a) === JSON.stringify(needle))
+      const found = actual.some(a => checkSnippet(a, needle, opts, [...path, '[]']).length === 0)
       if (!found) {
-        violations.push(`${targetPath}: ${formatPath(path)} має містити ${quote(needle)} (${source})`)
+        violations.push(`${targetPath}: ${formatPath(path)} має містити ${describeElement(needle)} (${source})`)
       }
     }
     return violations

package/scripts/lib/worktree-notice.mjs

@@ -5,69 +5,78 @@
  * і не паралелитись. Підказка адресована агенту, який читає `SKILL.md`, тож
  * вставляється в текст між стабільними маркерами — ре-синк ідемпотентний:
  * наявний блок замінюється, при `worktree:false` — видаляється.
+ *
+ * Крок 0.1 блоку додає `bun install` у щойно створеному дереві (локальна копія
+ * CLI усуває гонку з CDN) і shell-обгортку `n_cursor_npx` навколо bootstrap-виклику
+ * `npx`: на ETARGET/notarget та мережевих помилках npm падає ДО запуску бінарника,
+ * тож retry мусить жити на рівні shell-інструкції, а не в JS-хендлерах CLI.
+ * Обгортка ретраїть лише транзитні помилки реєстру/мережі (30с інтервал, дефолт
+ * 5 хв, env `N_CURSOR_NPX_RETRY_MAX_MIN`, ceiling 10 хв) і віддає реальний nonzero
+ * CLI одразу. Команди винесені окремим кроком ПІСЛЯ worktree-створення, бо
+ * вимагають command substitution, заборонену у «без-expansion» preflight-снипеті
+ * (узгоджено з worktree.mdc).
  */
 
 /** Маркер початку worktree-блоку (стабільний, не залежить від тексту всередині). */
-export const WORKTREE_START = "<!-- n-cursor:worktree:start -->";
+export const WORKTREE_START = '<!-- n-cursor:worktree:start -->'
 /** Маркер кінця worktree-блоку. */
-export const WORKTREE_END = "<!-- n-cursor:worktree:end -->";
+export const WORKTREE_END = '<!-- n-cursor:worktree:end -->'
 
-const FALLBACK_SUFFIX = "task";
+const FALLBACK_SUFFIX = 'task'
 
 /** Наявний блок разом із сусідніми порожніми рядками (для чистого видалення). */
-const BLOCK_RE =
-  /\n*<!-- n-cursor:worktree:start -->[\s\S]*?<!-- n-cursor:worktree:end -->\n*/u;
+const BLOCK_RE = /\n*<!-- n-cursor:worktree:start -->[\s\S]*?<!-- n-cursor:worktree:end -->\n*/u
 
 /** Закриття YAML-frontmatter на початку файла. */
-const FRONTMATTER_RE = /^(---\n[\s\S]*?\n---\n)/u;
+const FRONTMATTER_RE = /^(---\n[\s\S]*?\n---\n)/u
 
 /** Значення `name` з YAML-frontmatter. */
-const NAME_RE = /^name:\s*["']?([^"'\n]+)["']?\s*$/mu;
+const NAME_RE = /^name:\s*["']?([^"'\n]+)["']?\s*$/mu
 
 /** Перший H1 як fallback, якщо frontmatter не містить `name`. */
-const H1_RE = /^#\s+(.+)$/mu;
+const H1_RE = /^#\s+(.+)$/mu
 
 const CYRILLIC_TRANSLIT = new Map(
   Object.entries({
-    а: "a",
-    б: "b",
-    в: "v",
-    г: "h",
-    ґ: "g",
-    д: "d",
-    е: "e",
-    є: "ye",
-    ж: "zh",
-    з: "z",
-    и: "y",
-    і: "i",
-    ї: "yi",
-    й: "y",
-    к: "k",
-    л: "l",
-    м: "m",
-    н: "n",
-    о: "o",
-    п: "p",
-    р: "r",
-    с: "s",
-    т: "t",
-    у: "u",
-    ф: "f",
-    х: "kh",
-    ц: "ts",
-    ч: "ch",
-    ш: "sh",
-    щ: "shch",
-    ь: "",
-    ю: "yu",
-    я: "ya",
-    ы: "y",
-    э: "e",
-    ё: "yo",
-    ъ: "",
-  }),
-);
+    а: 'a',
+    б: 'b',
+    в: 'v',
+    г: 'h',
+    ґ: 'g',
+    д: 'd',
+    е: 'e',
+    є: 'ye',
+    ж: 'zh',
+    з: 'z',
+    и: 'y',
+    і: 'i',
+    ї: 'yi',
+    й: 'y',
+    к: 'k',
+    л: 'l',
+    м: 'm',
+    н: 'n',
+    о: 'o',
+    п: 'p',
+    р: 'r',
+    с: 's',
+    т: 't',
+    у: 'u',
+    ф: 'f',
+    х: 'kh',
+    ц: 'ts',
+    ч: 'ch',
+    ш: 'sh',
+    щ: 'shch',
+    ь: '',
+    ю: 'yu',
+    я: 'ya',
+    ы: 'y',
+    э: 'e',
+    ё: 'yo',
+    ъ: ''
+  })
+)
 
 /**
  * Транслітерує кирилицю в ASCII для короткого suffix.
@@ -75,8 +84,7 @@ const CYRILLIC_TRANSLIT = new Map(
  * @returns {string} транслітерований текст
  */
 function transliterate(value) {
-  return Array.from(value.toLowerCase(), (char) => CYRILLIC_TRANSLIT.get(char) ?? char)
-    .join("");
+  return Array.from(value.toLowerCase(), char => CYRILLIC_TRANSLIT.get(char) ?? char).join('')
 }
 
 /**
@@ -85,20 +93,16 @@ function transliterate(value) {
  * @returns {string} suffix до 10 символів
  */
 function deriveSuffix(content) {
-  const raw =
-    content.match(NAME_RE)?.[1] ?? content.match(H1_RE)?.[1] ?? FALLBACK_SUFFIX;
+  const raw = content.match(NAME_RE)?.[1] ?? content.match(H1_RE)?.[1] ?? FALLBACK_SUFFIX
   const slug = transliterate(raw)
     .trim()
-    .replace(/^n-/u, "")
-    .normalize("NFKD")
-    .replaceAll(/[\u0300-\u036F]/gu, "")
-    .replaceAll(/[^a-z0-9]+/gu, "-")
-    .replaceAll(/^-+|-+$/gu, "");
-
-  return (
-    (slug || FALLBACK_SUFFIX).slice(0, 10).replace(/-+$/u, "") ||
-    FALLBACK_SUFFIX
-  );
+    .replace(/^n-/u, '')
+    .normalize('NFKD')
+    .replaceAll(/[\u0300-\u036F]/gu, '')
+    .replaceAll(/[^a-z0-9]+/gu, '-')
+    .replaceAll(/^-+|-+$/gu, '')
+
+  return (slug || FALLBACK_SUFFIX).slice(0, 10).replace(/-+$/u, '') || FALLBACK_SUFFIX
 }
 
 /**
@@ -113,18 +117,62 @@ function buildNoticeBody(suffix) {
 **Крок 0 — preflight (обовʼязковий, перед будь-якими іншими діями).** Якщо перевірка падає — **STOP**: не питай користувача про назву гілки, а сам створи worktree від поточної гілки за конвенцією \`<current-branch>-${suffix}\`. Суфікс \`${suffix}\` — коротка (до 10 символів) транслітерація задачі. Не виконуй **жоден** наступний крок скіла, поки preflight не завершився успіхом.
 
 \`\`\`bash
+pwd
 git rev-parse --show-toplevel
 git branch --show-current
 \`\`\`
 
-Якщо перша команда показала, що ти **не** в \`.worktrees/\`, візьми вивід другої команди як \`<current-branch>\` і виконай **literal-команди без shell expansion** (без command substitution, variable expansion чи backticks). Наприклад, якщо поточна гілка \`feature/x\`:
+**Root-assert.** Якщо \`pwd\` **не** збігається з виводом \`git rev-parse --show-toplevel\` — ти в **піддиректорії** робочого дерева (worktree-шляхи нижче відносні до кореня репо). Спершу перейди в корінь: \`cd <toplevel>\` (literal-шлях із виводу), і лише тоді продовжуй preflight. Не створюй worktree з піддиректорії — \`cd .worktrees/<…>\` звідти впаде.
+
+Якщо \`git rev-parse --show-toplevel\` показав, що ти **не** в \`.worktrees/\`, візьми вивід \`git branch --show-current\` як \`<current-branch>\` і виконай **literal-команди без shell expansion** (без command substitution, variable expansion чи backticks). Наприклад, якщо поточна гілка \`feature/x\`:
 
 \`\`\`bash
 npx @nitra/cursor worktree add "feature/x-${suffix}" "n-${suffix}: worktree-only skill"
 cd ".worktrees/feature-x-${suffix}"
 \`\`\`
 
-Тобто branch-argument лишає slash як у git-гілці, а шлях для \`cd\` бере sanitized форму: slash → \`-\`.`;
+Тобто branch-argument лишає slash як у git-гілці, а шлях для \`cd\` бере sanitized форму: slash → \`-\`.
+
+**Крок 0.1 — bootstrap у новому дереві (після \`cd\`, окремий крок — поза «без-expansion» блоком вище).** Дерево щойно створене й **без** \`node_modules\`. Спершу постав залежності локально: тоді \`npx\` бере локальну копію \`@nitra/cursor\` і гонки з CDN немає взагалі. Retry-обгортка нижче — safety-net на випадок, коли версію щойно опубліковано, але edge-кеш CDN ще її не має: \`npm\` тоді падає з \`ETARGET\`/\`notarget\` **до** запуску бінарника (внутрішній JS-retry у \`n-cursor\` для цього кейсу марний — бінарник ще не стартував).
+
+\`\`\`bash
+# Локальна копія @nitra/cursor (девзалежність споживача) — npx бере її, без походу в реєстр.
+bun install
+
+# n_cursor_npx <args> — обгортка bootstrap-виклику "npx @nitra/cursor <args>".
+# Ретраїмо ЛИШЕ транзитні помилки реєстру/мережі (CDN ще не пропагував щойно
+# опубліковану версію). Реальний nonzero від CLI (fix повернув ❌, lint-помилка) —
+# віддаємо одразу, без ретраю. Інтервал 30с; дефолт-ліміт 5 хв
+# (env N_CURSOR_NPX_RETRY_MAX_MIN), hard-ceiling 10 хв.
+# Чому 5 хв: CDN-пропагація npm зазвичай < 2 хв, 5 хв — запас; довше → ймовірно
+# реальна проблема (невірна версія / аутейдж), краще віддати помилку, ніж висіти.
+n_cursor_npx() {
+  max_min="\${N_CURSOR_NPX_RETRY_MAX_MIN:-5}"
+  case "$max_min" in '' | *[!0-9]*) max_min=5 ;; esac
+  [ "$max_min" -gt 10 ] && max_min=10
+  deadline=$(( $(date +%s) + max_min * 60 ))
+  attempt=1
+  transient='ETARGET|notarget|No matching version|ENOTFOUND|ETIMEDOUT|EAI_AGAIN|ECONNRESET|50[0-9] |502 Bad Gateway|503 Service Unavailable|504 Gateway'
+  while :; do
+    err=$(mktemp)
+    npx @nitra/cursor "$@" 2>"$err"
+    code=$?
+    cat "$err" >&2
+    [ "$code" -eq 0 ] && { rm -f "$err"; return 0; }
+    if grep -Eq "$transient" "$err" && [ "$(date +%s)" -lt "$deadline" ]; then
+      rm -f "$err"
+      echo "n-cursor: очікую пропагації версії по CDN… спроба $attempt, повтор через 30с" >&2
+      attempt=$((attempt + 1))
+      sleep 30
+    else
+      rm -f "$err"
+      return "$code"
+    fi
+  done
+}
+\`\`\`
+
+Усі подальші bootstrap-виклики \`npx @nitra/cursor <cmd>\` у цій сесії роби через \`n_cursor_npx <cmd>\`. Якщо опинився у свіжому shell без цієї функції — спершу повтори блок вище (\`bun install\` + визначення \`n_cursor_npx\`).`
 }
 
 /**
@@ -133,7 +181,7 @@ cd ".worktrees/feature-x-${suffix}"
  * @returns {string} текст блоку від START до END
  */
 function buildBlock(content) {
-  return `${WORKTREE_START}\n${buildNoticeBody(deriveSuffix(content))}\n${WORKTREE_END}`;
+  return `${WORKTREE_START}\n${buildNoticeBody(deriveSuffix(content))}\n${WORKTREE_END}`
 }
 
 /**
@@ -143,19 +191,19 @@ function buildBlock(content) {
  * @returns {string} оновлений вміст (ідемпотентно)
  */
 export function injectWorktreeNotice(content, enabled) {
-  const hadBlock = content.includes(WORKTREE_START);
-  const withoutBlock = content.replace(BLOCK_RE, "\n\n");
+  const hadBlock = content.includes(WORKTREE_START)
+  const withoutBlock = content.replace(BLOCK_RE, '\n\n')
 
   if (!enabled) {
-    return hadBlock ? withoutBlock : content;
+    return hadBlock ? withoutBlock : content
   }
 
-  const block = buildBlock(withoutBlock);
-  const fm = withoutBlock.match(FRONTMATTER_RE);
+  const block = buildBlock(withoutBlock)
+  const fm = withoutBlock.match(FRONTMATTER_RE)
   if (fm) {
-    const head = fm[1];
-    const rest = withoutBlock.slice(head.length).replace(/^\n+/u, "");
-    return `${head}\n${block}\n\n${rest}`;
+    const head = fm[1]
+    const rest = withoutBlock.slice(head.length).replace(/^\n+/u, '')
+    return `${head}\n${block}\n\n${rest}`
   }
-  return `${block}\n\n${withoutBlock.replace(/^\n+/u, "")}`;
+  return `${block}\n\n${withoutBlock.replace(/^\n+/u, '')}`
 }

package/scripts/sync-claude-config.mjs

@@ -21,8 +21,8 @@
  *   entries додаються, коли правило `adr` увімкнене, і видаляються, коли вимкнене.
  * - `.gitignore` — **merge** (лише з `adr`): дописує відсутні рядки з канонічного
  *   фрагмента `rules/adr/js/hooks/template/.gitignore.snippet` (`node_modules/`, `dist/`,
- *   `*.secret`, логи capture/normalize, `.normalize-state`, `.normalize.lock`); існуючі
- *   рядки не перезаписуються.
+ *   `*.secret`, логи capture/normalize, `.normalize-state`, `.normalize.lock`,
+ *   `.claude/scheduled_tasks.lock`); існуючі рядки не перезаписуються.
  *
  * Опт-аут — `claude-config: false` у `.n-cursor.json`.
  */

package/skills/fix/SKILL.md

@@ -12,10 +12,10 @@ description: >-
 
 ## Workflow
 
-1. **Діагностика** — запусти перевірку (за замовчуванням лише правила з `.cursor/rules/*.mdc`, для яких у пакеті є programmatic check; повний набір — явні аргументи: `npx @nitra/cursor fix bun ga …`):
+1. **Діагностика** — запусти перевірку через retry-обгортку `n_cursor_npx` (визначена у worktree-preflight, крок 0.1: переживає транзитну CDN-гонку щойно опублікованої версії, а реальний `❌` від `fix` віддає одразу). За замовчуванням — лише правила з `.cursor/rules/*.mdc`, для яких у пакеті є programmatic check; повний набір — явні аргументи: `n_cursor_npx fix bun ga …`:
 
 ```bash
-npx @nitra/cursor fix
+n_cursor_npx fix
 ```
 
 2. **Аналіз** — зчитай вивід, знайди всі `❌` та визнач які правила порушено
@@ -40,10 +40,10 @@ bun i
 oxfmt .
 ```
 
-6. **Верифікація** — перевір що все виправлено:
+6. **Верифікація** — перевір що все виправлено (та сама retry-обгортка `n_cursor_npx`):
 
 ```bash
-npx @nitra/cursor fix
+n_cursor_npx fix
 ```
 
 7. **Результат** — всі `❌` від `npx @nitra/cursor fix` мають стати `✅`. Якщо залишились `❌` — повтори кроки 3-6. Лінт-помилки від `bun run lint` тут **не виправляй** — вони на скіл `/n-lint`.

package/skills/llm-patch/meta.json

@@ -1 +1 @@
-{ "auto": "завжди", "worktree": false }
+{ "auto": "завжди", "worktree": false, "requireRoot": false }

package/skills/publish-telegram/meta.json

@@ -1 +1 @@
-{ "auto": "завжди", "worktree": false }
+{ "auto": "завжди", "worktree": false, "requireRoot": false }