@nitra/cursor 1.35.5 → 1.37.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.37.0] - 2026-05-31
+
+### Changed
+
+- skills: meta.json замість auto.md (+ worktree-прапорець з вшиванням у SKILL.md і забороною паралелі)
+
+## [1.36.0] - 2026-05-31
+
+### Added
+
+- test rule v2.7: канони Console mocking (vi.spyOn), Sandbox-aware тестів (withTmpDir+git init як default, skipIf STRYKER_MUTATOR_WORKER як виняток для smoke-аудиту) і явний {cwd:dir} у child_process
+
+### Changed
+
+- withLock: стан локу спільний для всіх git-worktree через resolveLockCacheDir (git-common-dir) — серіалізація важких команд між worktree, не лише в одному checkout
+
 ## [1.35.5] - 2026-05-30
 
 ### Changed

package/README.md

@@ -114,7 +114,7 @@ npm/
 ```
 npm/rules/<id>/
 ├── <id>.mdc              # текст правила (після синку — .cursor/rules/n-<id>.mdc)
-├── auto.md               # умова автоактивації скілу (опційно)
+├── meta.json             # метадані скілу: auto (автоактивація) + worktree
 ├── js/                  # JS для `npx @nitra/cursor fix`
 │   └── <concern>/
 │       ├── check.mjs     # діагностика — повертає список violations

package/bin/n-cursor.js

@@ -88,6 +88,8 @@ import {
   RULE_MIGRATIONS
 } from '../scripts/auto-rules.mjs'
 import { detectAutoSkills } from '../scripts/auto-skills.mjs'
+import { readSkillMetaRaw } from '../scripts/lib/skill-meta.mjs'
+import { injectWorktreeNotice } from '../scripts/lib/worktree-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'
@@ -762,10 +764,15 @@ async function syncSkills(configSkills, bundledSkillsDir = BUNDLED_SKILLS_DIR) {
       process.stdout.write(`  ⬇  ${id} → ${SKILLS_DIR}/${destDirName} ... `)
       try {
         await mkdir(destDir, { recursive: true })
+        const meta = readSkillMetaRaw(srcDir)
+        const worktree = meta?.worktree === true
         const files = await readdir(srcDir)
         for (const file of files) {
-          if (file === 'auto.md') continue
-          const content = await readFile(join(srcDir, file), 'utf8')
+          if (file === 'meta.json') continue
+          let content = await readFile(join(srcDir, file), 'utf8')
+          if (file === 'SKILL.md') {
+            content = injectWorktreeNotice(content, worktree)
+          }
           await writeFile(join(destDir, file), content, 'utf8')
         }
         console.log(`✅`)

package/package.json

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

package/rules/graphql/js/tooling.mjs

@@ -82,7 +82,9 @@ function checkExtensionsRecommendation(pass, fail, cwd) {
   const pathRel = '.vscode/extensions.json'
   const pathAbs = join(cwd, pathRel)
   if (!existsSync(pathAbs)) {
-    fail(`${pathRel} не існує — створи файл і додай у recommendations ${REQUIRED_GRAPHQL_VSCODE_EXTENSION} (graphql.mdc)`)
+    fail(
+      `${pathRel} не існує — створи файл і додай у recommendations ${REQUIRED_GRAPHQL_VSCODE_EXTENSION} (graphql.mdc)`
+    )
     return
   }
   const violations = runConftestBatch({

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

@@ -422,7 +422,10 @@ async function collectPublishedFiles(filesField, cwd) {
     }
     if (!s.isDirectory()) continue
     await walkDir(fullPath, p => {
-      const rel = p.slice(npmRoot.length + 1).split(sep).join('/')
+      const rel = p
+        .slice(npmRoot.length + 1)
+        .split(sep)
+        .join('/')
       collected.add(rel)
     })
   }

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

@@ -0,0 +1,61 @@
+/**
+ * Перевірка метаданих скілів пакета `@nitra/cursor` (концерн правила npm-module).
+ *
+ * Кожен `npm/skills/<id>/` має містити валідний `meta.json`:
+ *  - `worktree` присутнє і boolean;
+ *  - `auto` (якщо присутнє) — розпізнане (`"завжди"` або непорожній масив рядків);
+ *  - залишковий `auto.md` заборонено (міграція на meta.json завершена).
+ *
+ * Концерн застосовний лише в репо самого пакета (де є `npm/skills/`); у споживача
+ * каталогу `npm/skills/` нема, тож перевірка мовчки проходить.
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
+import { parseSkillAutoSpec, readSkillMetaRaw } from '../../../scripts/lib/skill-meta.mjs'
+
+/**
+ * Валідує всі `npm/skills/<id>/meta.json`.
+ * @param {string} [cwd] корінь репозиторію
+ * @returns {Promise<number>} 0 — OK, 1 — порушення
+ */
+export function check(cwd = process.cwd()) {
+  const reporter = createCheckReporter()
+  const skillsDir = join(cwd, 'npm', 'skills')
+  if (!existsSync(skillsDir)) {
+    reporter.pass('npm/skills/ відсутній — немає скілів для валідації')
+    return Promise.resolve(reporter.getExitCode())
+  }
+
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue
+    const id = entry.name
+    const skillDir = join(skillsDir, id)
+    let skillOk = true
+
+    if (existsSync(join(skillDir, 'auto.md'))) {
+      reporter.fail(`skills/${id}: залишковий auto.md — видали (метадані тепер у meta.json)`)
+      skillOk = false
+    }
+
+    const raw = readSkillMetaRaw(skillDir)
+    if (!raw) {
+      reporter.fail(`skills/${id}: відсутній або невалідний meta.json (очікується {"auto"?, "worktree": bool})`)
+      continue
+    }
+    if (typeof raw.worktree !== 'boolean') {
+      reporter.fail(`skills/${id}: meta.json.worktree має бути boolean`)
+      skillOk = false
+    }
+    if (raw.auto !== undefined && parseSkillAutoSpec(raw.auto) === null) {
+      reporter.fail(`skills/${id}: meta.json.auto нерозпізнане — очікується "завжди" або непорожній масив правил`)
+      skillOk = false
+    }
+    if (skillOk) {
+      reporter.pass(`skills/${id}: meta.json валідний`)
+    }
+  }
+
+  return Promise.resolve(reporter.getExitCode())
+}

package/rules/release/change.mjs

@@ -43,7 +43,9 @@ export async function runChangeCli(args) {
   const message = get('--message')
   const ws = get('--ws') ?? '.'
   if (!bump || !section || !message) {
-    console.error('❌ Використання: n-cursor change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<опис>" [--ws <шлях>]')
+    console.error(
+      '❌ Використання: n-cursor change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<опис>" [--ws <шлях>]'
+    )
     return 1
   }
   try {

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

@@ -45,7 +45,9 @@ export function parseChangeFile(text) {
     throw new Error(`change-файл: bump має бути одним із ${VALID_BUMPS.join('|')} (отримано «${fm.bump ?? ''}»)`)
   }
   if (!VALID_SECTIONS.includes(fm.section)) {
-    throw new Error(`change-файл: section має бути одним із ${VALID_SECTIONS.join('|')} (отримано «${fm.section ?? ''}»)`)
+    throw new Error(
+      `change-файл: section має бути одним із ${VALID_SECTIONS.join('|')} (отримано «${fm.section ?? ''}»)`
+    )
   }
   if (!description) throw new Error('change-файл: порожній опис')
   return { bump: fm.bump, section: fm.section, description }

package/rules/release/release.mjs

@@ -28,7 +28,9 @@ async function writeManifestVersion(cwd, manifest, newVersion) {
   const re = manifest.kind === 'npm' ? SEMVER_LINE_RE : PY_VERSION_LINE_RE
   const replaced = text.replace(re, `$1${newVersion}$2`)
   if (replaced === text) {
-    throw new Error(`release: не вдалося оновити version у ${manifest.ws}/${manifest.manifestRel} — патерн version не знайдено`)
+    throw new Error(
+      `release: не вдалося оновити version у ${manifest.ws}/${manifest.manifestRel} — патерн version не знайдено`
+    )
   }
   await writeFile(path, replaced)
 }
@@ -117,11 +119,12 @@ export async function release(opts = {}) {
 
 /**
  * @param {string[]} _args аргументи CLI (наразі без опцій)
+ * @param {import('./release.mjs').ReleaseOpts} [opts] опції для тестів (cwd, date, runGit)
  * @returns {Promise<number>} exit-код
  */
-export async function runReleaseCli(_args) {
+export async function runReleaseCli(_args, opts = {}) {
   try {
-    const released = await release()
+    const released = await release(opts)
     if (released.length === 0) {
       console.log('release: немає змін для релізу')
     } else {

package/rules/test/js/data/stryker_config/stryker-vue-macros-ignorer.mjs

@@ -24,7 +24,8 @@ const VUE_SETUP_MACROS = new Set([
   'defineOptions'
 ])
 
-const IGNORE_MESSAGE = 'Vue <script setup> macro call cannot be mutated (defineProps/defineEmits/etc. must be statically analyzable for @vue/compiler-sfc).'
+const IGNORE_MESSAGE =
+  'Vue <script setup> macro call cannot be mutated (defineProps/defineEmits/etc. must be statically analyzable for @vue/compiler-sfc).'
 
 /**
  * @param {{isCallExpression: () => boolean, node: {callee: {type: string, name?: string}}}} path babel NodePath, переданий Stryker-instrumenter

package/rules/test/js/stryker_config.mjs

@@ -111,13 +111,7 @@ export async function check(cwd = process.cwd()) {
   for (const jsRoot of jsRoots) {
     const isVueRoot = await hasVueFiles(jsRoot)
     const strykerBaseline = isVueRoot ? STRYKER_VUE_BASELINE_PATH : STRYKER_BASELINE_PATH
-    await ensureBaselineFile(
-      reporter,
-      cwd,
-      strykerBaseline,
-      join(jsRoot, 'stryker.config.mjs'),
-      'stryker.config.mjs'
-    )
+    await ensureBaselineFile(reporter, cwd, strykerBaseline, join(jsRoot, 'stryker.config.mjs'), 'stryker.config.mjs')
     if (isVueRoot) {
       await ensureBaselineFile(
         reporter,
@@ -133,7 +127,11 @@ export async function check(cwd = process.cwd()) {
   // Гарантуємо що тест-артефакти (Stryker output, lcov HTML-звіт) ніколи не
   // потрапляють у commit. Patterns покривають усі workspaces через `**/`-префікс
   // (єдиний root .gitignore).
-  const { added } = await ensureGitignoreEntries(cwd, TEST_GITIGNORE_ENTRIES, 'Test artifacts: Stryker + coverage (test.mdc)')
+  const { added } = await ensureGitignoreEntries(
+    cwd,
+    TEST_GITIGNORE_ENTRIES,
+    'Test artifacts: Stryker + coverage (test.mdc)'
+  )
   if (added.length > 0) {
     reporter.pass(`.gitignore: додано тест-патерни (${added.join(', ')}) (test.mdc)`)
   }

package/rules/test/test.mdc

@@ -1,6 +1,6 @@
 ---
 description: JS-тести (*.test.mjs) живуть у tests/. Правило `test` керує stryker.config.mjs + vitest.config.js (якщо js-lint enabled) і .cargo/mutants.toml (якщо rust enabled).
-version: '2.6'
+version: '2.7'
 globs: "**/{.n-cursor.json,package.json,Cargo.toml,stryker.config.mjs,vitest.config.js,.cargo/mutants.toml},**/*.test.mjs"
 alwaysApply: false
 ---
@@ -81,6 +81,51 @@ Recursive globs ловлять файли всередині `tests/` так с
 
 Canonical `vitest.config.js` (для довідки — `pool: 'forks'` + `include` + `coverage`) — у `rules/test/js/data/vitest_config/vitest.config.baseline.js` (концерн `stryker_config` копіює його у кожен JS-root).
 
+## Console mocking у тестах
+
+`console.log` / `console.error` / `console.warn` — **process-wide** мутації, рівно як `process.cwd()`. Якщо тест перехоплює їх через `const orig = console.log; console.log = (...) => …; try { … } finally { console.log = orig }`, паралельний test файл у `pool: 'forks'` (різний процес) ізольований, але в межах **одного** процесу всі тести у файлі ділять єдиний `console`-об'єкт. Якщо try/finally не виконається (наприклад, асинхронний помилка повз `await`), restore не спрацює і наступні тести втрачають вивід.
+
+Тому:
+
+- **Канон**: `vi.spyOn(console, 'log').mockReturnValue()` (та аналоги для `error`/`warn`/`info`) + `afterEach(() => vi.restoreAllMocks())`. Vitest сам слідкує за scope mock-у і гарантовано відновлює оригінал між тестами, навіть якщо тест кинув виняток.
+- **Заборонено**: ручний store/restore (`const orig = console.log; console.log = stub`). Виняток — коли тест **необхідно** перехопити вивід **до** того, як завантажиться модуль із top-level-логуванням; у цьому випадку фіксуй pattern explicit-коментарем.
+- Якщо потрібен лог зі stub-ом — `const logs = []; vi.spyOn(console, 'log').mockImplementation((...args) => logs.push(args.join(' ')))`.
+
+Перевірка — концерн `no-console-store-restore` (`rules/test/js/no-console-store-restore.mjs`): AST-сканер, який ловить присвоєння `console.<method> = …` у `*.test.{js,mjs}`.
+
+## Sandbox-aware тести (Stryker)
+
+Stryker за замовчуванням копіює репо у sandbox-каталог (`reports/stryker/.tmp/sandbox-XXX/`), щоб AST-патчити мутантів без зачеплення робочого дерева. У sandbox **немає `.git/`**, і будь-який тест, що звертається до **реального** git-дерева через `import.meta.url + N≥3 рівнів вгору` (типу `const REPO_ROOT = join(import.meta.dirname, '..', '..', '..', '..', '..')`) фактично адресує sandbox-корінь, а не справжній репо. Це ламає `git rev-parse`/`git ls-files`/перевірки `.n-cursor.json`/CHANGELOG-співставлення — Stryker dry-run падає, мутаційний прогон не стартує, `mutation.json` лишається stale.
+
+**Канон**: тест не повинен залежати від реального git-дерева через `import.meta.url + N≥3 рівнів вгору`. Якщо тест перевіряє git-логіку — ізолюй **повністю**:
+
+```js
+await withTmpDir(async dir => {
+  execFileSync('git', ['init', '-q', '--initial-branch=main'], { cwd: dir })
+  await writeFile(join(dir, 'a.sh'), '#!/bin/sh\n', 'utf8')
+  execFileSync('git', ['add', '-A'], { cwd: dir })
+  expect(listShellScriptPaths(dir)).toEqual(['a.sh'])
+})
+```
+
+Приклад у репо: `rules/text/lint/tests/run-shellcheck.test.mjs` — тест `listShellScriptPaths всередині git-репо`.
+
+**Виняток** — top-level smoke-аудит тести, що **за визначенням** перевіряють інваріанти **живого** репо (структура файлів, узгодженість CHANGELOG з `package.json`, кожне правило має fixture). Приклади: `tests/integration-repo-checks.test.mjs`, `tests/check-rule-fixtures.test.mjs`. Такі тести **не дають додаткового coverage у unit-сенсі** — концерни, які вони перевіряють, уже покриті per-rule unit-тестами (`rules/<rule>/js/tests/`). Захищаємо їх `test.skipIf(env.STRYKER_MUTATOR_WORKER)` від запуску всередині Stryker-sandbox:
+
+```js
+import { env } from 'node:process'
+
+test.skipIf(env.STRYKER_MUTATOR_WORKER)('узгоджені з поточним деревом', async () => {
+  // …перевірки на REPO_ROOT
+})
+```
+
+Перевірка — концерн `sandbox-aware-test` (`rules/test/js/sandbox-aware-test.mjs`): сканер `*.test.{js,mjs}`, який знаходить тести з `import.meta.url`-deep-relative навігацією (4+ `..`-рівнів) і вимагає або `withTmpDir` у їхніх `test`-блоках, або `test.skipIf(env.STRYKER_MUTATOR_WORKER)`.
+
+## `child_process` у тестах: явний `cwd`
+
+Уже зазначено в `## Заборона process.chdir у тестах`. Підсилення: **кожен** виклик `execFile`/`execFileSync`/`spawn`/`spawnSync` у `*.test.{js,mjs}` приймає або **явний `{ cwd: dir }`** (де `dir` — змінна, не `process.cwd()`), або працює з **абсолютними шляхами** до бінарників/fixture-файлів (наприклад `spawnSync('node', [absoluteFixturePath])`). Це гарантує, що мутаційний test-flow у `pool: 'forks'` не страждає від implicit-`process.cwd()`-stride між тестами в одному воркері.
+
 ## Покриття + мутаційне тестування
 
 Канонічна команда — `n-cursor coverage`: збирає метрики покриття (`vitest run --coverage`, `cargo llvm-cov` тощо) і мутаційного тестування (Stryker з vitest-runner + `coverageAnalysis: 'perTest'`, `cargo-mutants`) з усіх активних провайдерів у `.n-cursor.json#rules` і пише `COVERAGE.md` у корінь проєкту. Лок і дедуп — `withLock('coverage', ...)`.

package/rules/vue/js/packages.mjs

@@ -422,15 +422,7 @@ async function checkVuePackage(rootDir, ignorePaths, fail, passFn, cwd) {
   await checkViteClientEnvAndEditorConfig(rootDir, prefix, passFn, fail, cwd)
 
   const { hasVueAutoImport } = await checkViteConfig(rootDir, prefix, passFn, fail, cwd)
-  await checkVueImportViolations(
-    rootDir,
-    join(cwd, rootDir),
-    ignorePaths,
-    hasVueAutoImport,
-    prefix,
-    passFn,
-    fail
-  )
+  await checkVueImportViolations(rootDir, join(cwd, rootDir), ignorePaths, hasVueAutoImport, prefix, passFn, fail)
   await checkVueNodeImportViolations(rootDir, join(cwd, rootDir), ignorePaths, prefix, passFn, fail)
   await checkEsbuildMentions(rootDir, join(cwd, rootDir), ignorePaths, prefix, passFn, fail)
 }

package/schemas/skill-meta.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://unpkg.com/@nitra/cursor/schemas/skill-meta.json",
+  "title": "n-cursor skill meta",
+  "description": "Метадані скіла @nitra/cursor: умова автоактивації (auto) і чи виконувати в окремому git-worktree (worktree). Файл npm/skills/<id>/meta.json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["worktree"],
+  "properties": {
+    "auto": {
+      "description": "Умова автоактивації: \"завжди\" або непорожній масив id правил, від яких залежить скіл.",
+      "oneOf": [
+        { "const": "завжди" },
+        { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1 }
+      ]
+    },
+    "worktree": {
+      "type": "boolean",
+      "description": "true — виконувати скіл в окремому git-worktree, один інстанс за раз (без паралельного запуску); false — у worktree не виконується."
+    }
+  }
+}

package/schemas/v8r-catalog.json

@@ -25,6 +25,11 @@
       "description": "TypeScript config для pi extension templates, які Schema Store не матчить через вкладений/прихований шлях",
       "url": "https://json.schemastore.org/tsconfig.json",
       "fileMatch": [".pi/extensions/*/tsconfig.json", "npm/.pi-template/extensions/*/tsconfig.json"]
+    },
+    {
+      "name": "n-cursor skill meta",
+      "fileMatch": ["npm/skills/*/meta.json"],
+      "url": "https://unpkg.com/@nitra/cursor/schemas/skill-meta.json"
     }
   ]
 }

package/scripts/auto-skills.mjs

@@ -1,56 +1,33 @@
 /**
- * Автовизначення skills для `.n-cursor.json` за умовами зі `npm/skills/<skill>/auto.md`.
+ * Автовизначення skills для `.n-cursor.json` за умовами з `npm/skills/<skill>/meta.json`.
  *
- * `auto.md` — джерело правди (а не hardcoded мапа). Підтримуються три варіанти:
+ * `meta.json` — джерело правди (а не hardcoded мапа). Підтримуються три варіанти:
  *
- *  - `завжди` — скіл активується незалежно від інших правил
+ *  - `auto: "завжди"` — скіл активується незалежно від інших правил
  *    (приклади: `fix`, `lint`, `llm-patch`, `publish-telegram`).
- *  - `[rule, rule, …]` — скіл активується, якщо ВСІ перелічені правила вже виявлені
- *    auto-rules (приклади: `adr-normalize - [adr]`, `taze - [bun]`).
- *  - файл відсутній або формат не розпізнано — скіл opt-in лише через `.n-cursor.json:skills`.
+ *  - `auto: ["rule", …]` — скіл активується, якщо ВСІ перелічені правила вже виявлені
+ *    auto-rules (приклади: `adr-normalize - ["adr"]`, `taze - ["bun"]`).
+ *  - поле `auto` відсутнє або формат не розпізнано — скіл opt-in лише через `.n-cursor.json:skills`.
  *
  * Сканування `npm/skills/` — sync під час завантаження модуля (детермінізм + sync API
  * `auto-rules.mjs`-сусіда). Кеш на час процесу.
  */
-import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { existsSync, readdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { parseSkillAutoSpec, readSkillMetaRaw } from './lib/skill-meta.mjs'
+
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)))
 const SKILLS_DIR = join(PACKAGE_ROOT, 'skills')
 
-const ALWAYS_LITERAL = 'завжди'
-const BRACKET_LIST_RE = /^\[([^\]]+)\]$/u
-
 /**
  * @typedef {{ always: true } | { rules: readonly string[] }} SkillAutoSpec
  */
 
 /**
- * Парсить тіло `auto.md` одного скіла.
- * @param {string} text вміст файла (без `trim`)
- * @returns {SkillAutoSpec | null} `null` — формат не розпізнано (= opt-in)
- */
-function parseSkillAutoSpec(text) {
-  const trimmed = text.trim()
-  if (trimmed === ALWAYS_LITERAL) {
-    return { always: true }
-  }
-  const m = trimmed.match(BRACKET_LIST_RE)
-  if (m) {
-    const rules = m[1]
-      .split(',')
-      .map(s => s.trim())
-      .filter(s => s.length > 0)
-    if (rules.length === 0) return null
-    return { rules: Object.freeze(rules) }
-  }
-  return null
-}
-
-/**
- * Сканує `npm/skills/<id>/auto.md`. Скіли без `auto.md` або з нерозпізнаним
- * вмістом не потрапляють у результат — їх можна вмикати лише вручну в конфізі.
+ * Сканує `npm/skills/<id>/meta.json`. Скіли без `meta.json` або без розпізнаного
+ * `auto` не потрапляють у результат — їх вмикають лише вручну в конфізі.
  * @param {string} [skillsDir] override для тестів
  * @returns {Record<string, SkillAutoSpec>} мапа `skillId → spec`
  */
@@ -60,9 +37,9 @@ export function discoverSkillAutoActivation(skillsDir = SKILLS_DIR) {
   const out = {}
   for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
     if (!entry.isDirectory() || entry.name.startsWith('.')) continue
-    const autoMdPath = join(skillsDir, entry.name, 'auto.md')
-    if (!existsSync(autoMdPath)) continue
-    const spec = parseSkillAutoSpec(readFileSync(autoMdPath, 'utf8'))
+    const raw = readSkillMetaRaw(join(skillsDir, entry.name))
+    if (!raw) continue
+    const spec = parseSkillAutoSpec(raw.auto)
     if (spec) out[entry.name] = spec
   }
   return out

package/scripts/lib/skill-meta.mjs

@@ -0,0 +1,54 @@
+/**
+ * Спільний парсер метаданих скіла з `npm/skills/<id>/meta.json`.
+ *
+ * `meta.json` — єдине джерело правди для скіла замість колишнього `auto.md`:
+ *  - `auto` — умова автоактивації (`"завжди"` | масив id правил), опційне;
+ *  - `worktree` — boolean: чи виконувати скіл в окремому git-worktree (один інстанс).
+ *
+ * Цим хелпером користуються `auto-skills.mjs` (автоактивація), `n-cursor.js`
+ * (sync + вшивання worktree-блоку) і check-концерн `npm-module/js/skill_meta.mjs`,
+ * щоб не дублювати парсинг і форму валідації.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Літерал безумовної автоактивації (українською, як у `auto-skills.mjs`). */
+export const SKILL_ALWAYS = 'завжди'
+
+/**
+ * @typedef {{ always: true } | { rules: string[] }} SkillAutoSpec
+ */
+
+/**
+ * Перетворює значення поля `auto` з `meta.json` у `SkillAutoSpec`.
+ * @param {unknown} value значення `meta.json.auto`
+ * @returns {SkillAutoSpec | null} `null` — формат не розпізнано (= opt-in)
+ */
+export function parseSkillAutoSpec(value) {
+  if (value === SKILL_ALWAYS) {
+    return { always: true }
+  }
+  if (Array.isArray(value)) {
+    const rules = value.map(s => String(s).trim()).filter(s => s.length > 0)
+    if (rules.length === 0) return null
+    return { rules }
+  }
+  return null
+}
+
+/**
+ * Читає й парсить `meta.json` одного скіла.
+ * @param {string} skillDir абсолютний шлях до каталогу скіла
+ * @returns {Record<string, unknown> | null} розпарсений обʼєкт або `null` (немає файлу / невалідний JSON / не-обʼєкт)
+ */
+export function readSkillMetaRaw(skillDir) {
+  const metaPath = join(skillDir, 'meta.json')
+  if (!existsSync(metaPath)) return null
+  try {
+    const parsed = JSON.parse(readFileSync(metaPath, 'utf8'))
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null
+    return /** @type {Record<string, unknown>} */ (parsed)
+  } catch {
+    return null
+  }
+}

package/scripts/lib/worktree-notice.mjs

@@ -0,0 +1,55 @@
+/**
+ * Вшивання worktree-інструкції у синкнутий `SKILL.md` (рішення D2 зі spec).
+ *
+ * Коли `meta.json.worktree === true`, скіл має виконуватись в окремому git-worktree
+ * і не паралелитись. Підказка адресована агенту, який читає `SKILL.md`, тож
+ * вставляється в текст між стабільними маркерами — ре-синк ідемпотентний:
+ * наявний блок замінюється, при `worktree:false` — видаляється.
+ */
+
+/** Маркер початку worktree-блоку (стабільний, не залежить від тексту всередині). */
+export const WORKTREE_START = '<!-- n-cursor:worktree:start -->'
+/** Маркер кінця worktree-блоку. */
+export const WORKTREE_END = '<!-- n-cursor:worktree:end -->'
+
+const NOTICE_BODY =
+  '> **Worktree:** виконуй цей скіл в окремому git-worktree (`git worktree add`); ' +
+  '**не** запускай паралельно — один інстанс за раз.'
+
+/** Наявний блок разом із сусідніми порожніми рядками (для чистого видалення). */
+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
+
+/**
+ * Канонічний блок worktree-інструкції.
+ * @returns {string} текст блоку від START до END
+ */
+function buildBlock() {
+  return `${WORKTREE_START}\n${NOTICE_BODY}\n${WORKTREE_END}`
+}
+
+/**
+ * Вставляє / оновлює / видаляє worktree-блок у вмісті `SKILL.md`.
+ * @param {string} content вміст `SKILL.md`
+ * @param {boolean} enabled чи має бути блок (значення `meta.json.worktree`)
+ * @returns {string} оновлений вміст (ідемпотентно)
+ */
+export function injectWorktreeNotice(content, enabled) {
+  const hadBlock = content.includes(WORKTREE_START)
+  const withoutBlock = content.replace(BLOCK_RE, '\n\n')
+
+  if (!enabled) {
+    return hadBlock ? withoutBlock : content
+  }
+
+  const block = buildBlock()
+  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/utils/lock-cache-dir.mjs

@@ -0,0 +1,37 @@
+/**
+ * Обчислення директорії стану `withLock` (lock + dedup), СПІЛЬНОЇ для всіх git-worktree.
+ *
+ * Лок-стан (`lock/owner.json`, `result.json`) має бути один на головний checkout
+ * і всі linked-worktree. Інакше важкі команди (eslint/oxlint/jscpd, conftest,
+ * hadolint, per-rule fix), запущені в різних worktree, НЕ серіалізуються —
+ * кожен worktree має власний `node_modules/.cache/`, локи одне одного не бачать,
+ * і паралельний eslint перевантажує CPU/диск на macOS.
+ *
+ * `git rev-parse --git-common-dir` повертає той самий `.git` головного репо з
+ * будь-якого worktree, тож стан кладемо під `<git-common-dir>/n-cursor/<key>`
+ * (всередині `.git` — спільне, ніколи не трекається, переживає `bun i`).
+ * Поза git-репо (git недоступний / каталог не репо) — fallback на per-checkout
+ * `node_modules/.cache/n-cursor/<key>`, як було історично.
+ */
+import { spawnSync } from 'node:child_process'
+import { join, resolve } from 'node:path'
+
+/**
+ * @param {string} key ключ локу (`lint-ga`, `fix-bun`, …)
+ * @param {{cwd?:string, spawn?:typeof import('child_process').spawnSync}} [opts] робоча директорія та sync-виклик git (ін'єкція для тестів)
+ * @returns {string} абсолютний шлях до директорії стану локу для цього ключа
+ */
+export function resolveLockCacheDir(key, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd()
+  const spawn = opts.spawn ?? spawnSync
+
+  const r = spawn('git', ['rev-parse', '--git-common-dir'], { cwd, encoding: 'utf8' })
+  const commonDir = r.status === 0 && !r.error ? r.stdout.trim() : ''
+
+  if (commonDir === '') {
+    return join(cwd, 'node_modules/.cache/n-cursor', key)
+  }
+  // commonDir буває відносним (`.git` з кореня) або абсолютним (linked-worktree):
+  // resolve проти cwd дає однаковий абсолютний `<main>/.git` в обох випадках.
+  return join(resolve(cwd, commonDir), 'n-cursor', key)
+}

package/scripts/utils/with-lock.mjs

@@ -6,6 +6,7 @@ import * as fs from 'node:fs'
 import { join } from 'node:path'
 import * as os from 'node:os'
 import { setTimeout as sleep } from 'node:timers/promises'
+import { resolveLockCacheDir } from './lock-cache-dir.mjs'
 import { worktreeFingerprint } from './worktree-fingerprint.mjs'
 
 const DEFAULTS = {
@@ -62,7 +63,7 @@ export function shouldDedup(result, fingerprint, ttl) {
 export async function withLock(key, runFn, opts = {}) {
   const { ttl, staleThreshold, waitTimeout, pollInterval } = { ...DEFAULTS, ...opts }
   const getFingerprint = opts.getFingerprint ?? worktreeFingerprint
-  const cacheDir = opts.cacheDir ?? join(process.cwd(), 'node_modules/.cache/n-cursor', key)
+  const cacheDir = opts.cacheDir ?? resolveLockCacheDir(key)
   const lockDir = join(cacheDir, 'lock')
   const ownerFile = join(lockDir, 'owner.json')
   const resultFile = join(cacheDir, 'result.json')

package/skills/adr-normalize/meta.json

@@ -0,0 +1 @@
+{ "auto": ["adr"], "worktree": true }

package/skills/coverage-fix/meta.json

@@ -0,0 +1 @@
+{ "auto": ["js-lint"], "worktree": true }

package/skills/fix/meta.json

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

package/skills/fix-tests/meta.json

@@ -0,0 +1 @@
+{ "auto": ["js-lint"], "worktree": true }

package/skills/lint/meta.json

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

package/skills/llm-patch/meta.json

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

package/skills/publish-telegram/meta.json

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

package/skills/start-check/meta.json

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

package/skills/taze/meta.json

@@ -0,0 +1 @@
+{ "auto": ["bun"], "worktree": true }

package/skills/adr-normalize/auto.md

@@ -1 +0,0 @@
-[adr]

package/skills/coverage-fix/auto.md

@@ -1 +0,0 @@
-[js-lint]

package/skills/fix/auto.md

@@ -1 +0,0 @@
-завжди

package/skills/fix-tests/auto.md

@@ -1 +0,0 @@
-[js-lint]

package/skills/lint/auto.md

@@ -1 +0,0 @@
-завжди

package/skills/llm-patch/auto.md

@@ -1 +0,0 @@
-завжди

package/skills/publish-telegram/auto.md

@@ -1 +0,0 @@
-завжди

package/skills/start-check/auto.md

@@ -1 +0,0 @@
-[bun]

package/skills/taze/auto.md

@@ -1 +0,0 @@
-[bun]