@nitra/cursor 1.23.0 → 1.25.0

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

@@ -34,61 +34,10 @@ mkdir -p "$ADR_DIR" "$LOG_DIR"
 
 log() { printf '%s %s\n' "$(date -Iseconds)" "$*" >> "$LOG"; }
 
-# Структурний скіп ADR-генерації для "tooling-only" сесій.
-# Вхід: рядки-шляхи у stdin (один шлях на лінію), відносні до $PROJECT_ROOT
-# або абсолютні з префіксом $PROJECT_ROOT (нормалізуємо тут).
-# Вихід: 0 — усі шляхи в allowlist; 1 — є хоч один змістовний шлях.
-# Bash 3.2: без mapfile/асоц. масивів.
-is_tooling_only_change() {
-  local proj="$1"
-  local had_file=0
-  local f rel
-  while IFS= read -r f; do
-    [ -z "$f" ] && continue
-    had_file=1
-    case "$f" in
-      "$proj"/*) rel="${f#"$proj"/}" ;;
-      /*) return 1 ;;
-      *)  rel="$f" ;;
-    esac
-    case "$rel" in
-      .cspell.json) ;;
-      docs/adr/*.md) ;;
-      AGENTS.md|CLAUDE.md) ;;
-      CHANGELOG.md) ;;
-      */CHANGELOG.md) ;;
-      package.json|*/package.json)
-        if ! git_diff_only_version_field "$proj" "$rel"; then
-          return 1
-        fi
-        ;;
-      *) return 1 ;;
-    esac
-  done
-  [ "$had_file" = "1" ] && return 0
-  return 1
-}
-
-# Допоміжна: чи git-diff для файлу торкається ЛИШЕ рядків з `"version":`.
-# Поза git-репо або при помилці — вертаємо 1 (не tooling).
-git_diff_only_version_field() {
-  local proj="$1" path="$2"
-  [ -d "$proj/.git" ] || return 1
-  local diff
-  diff=$(cd "$proj" && git diff HEAD --unified=0 -- "$path" 2>/dev/null) || return 1
-  [ -z "$diff" ] && return 1
-  local line
-  while IFS= read -r line; do
-    case "$line" in
-      '+++ '*|'--- '*|'@@ '*|'') continue ;;
-      [+-]*'"version":'*) continue ;;
-      [+-]*) return 1 ;;
-    esac
-  done <<EOF
-$diff
-EOF
-  return 0
-}
+# Підвантажуємо спільний helper (sourcing — не sub-shell, функції видимі поточному скрипту).
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/tooling-only.sh
+. "$SCRIPT_DIR/lib/tooling-only.sh"
 
 log "fired: $SESSION_ID"
 

package/.claude-template/hooks/lib/tooling-only.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Спільний helper для ADR Stop-hook'ів: розпізнавання "tooling-only" сесій.
+# Source'ається з capture-decisions.sh і normalize-decisions.sh — функції стають
+# видимими caller'у, який успадковує `set` опції.
+# Bash 3.2 (macOS /bin/bash) сумісний: без mapfile, без асоц. масивів,
+# без process substitution.
+
+# Структурний скіп ADR-генерації для "tooling-only" сесій.
+# Вхід: рядки-шляхи у stdin (один шлях на лінію), відносні до $PROJECT_ROOT
+# або абсолютні з префіксом $PROJECT_ROOT (нормалізуємо тут).
+# Вихід: 0 — усі шляхи в allowlist; 1 — є хоч один змістовний шлях.
+is_tooling_only_change() {
+  local proj="$1"
+  local had_file=0
+  local f rel
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    had_file=1
+    case "$f" in
+      "$proj"/*) rel="${f#"$proj"/}" ;;
+      /*) return 1 ;;
+      *)  rel="$f" ;;
+    esac
+    case "$rel" in
+      .cspell.json) ;;
+      docs/adr/*.md) ;;
+      AGENTS.md|CLAUDE.md) ;;
+      CHANGELOG.md) ;;
+      */CHANGELOG.md) ;;
+      package.json|*/package.json)
+        if ! git_diff_only_version_field "$proj" "$rel"; then
+          return 1
+        fi
+        ;;
+      *) return 1 ;;
+    esac
+  done
+  [ "$had_file" = "1" ] && return 0
+  return 1
+}
+
+# Допоміжна: чи git-diff для файлу торкається ЛИШЕ рядків з `"version":`.
+# Поза git-репо або при помилці — вертаємо 1 (не tooling).
+git_diff_only_version_field() {
+  local proj="$1" path="$2"
+  [ -d "$proj/.git" ] || return 1
+  local diff
+  diff=$(cd "$proj" && git diff HEAD --unified=0 -- "$path" 2>/dev/null) || return 1
+  [ -z "$diff" ] && return 1
+  local line
+  while IFS= read -r line; do
+    case "$line" in
+      '+++ '*|'--- '*|'@@ '*|'') continue ;;
+      [+-]*'"version":'*) continue ;;
+      [+-]*) return 1 ;;
+    esac
+  done <<EOF
+$diff
+EOF
+  return 0
+}

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

@@ -39,55 +39,10 @@ mkdir -p "$LOG_DIR"
 
 log() { printf '%s %s\n' "$(date -Iseconds)" "$*" >> "$LOG"; }
 
-# Структурний скіп ADR-нормалізації для "tooling-only" сесій.
-# Дублікат із capture-decisions.sh: `.claude-template/hooks/` копіюється плоско,
-# спільний helper-файл туди не вписується.
-is_tooling_only_change() {
-  proj="$1"
-  had_file=0
-  while IFS= read -r f; do
-    [ -z "$f" ] && continue
-    had_file=1
-    case "$f" in
-      "$proj"/*) rel="${f#"$proj"/}" ;;
-      /*) return 1 ;;
-      *)  rel="$f" ;;
-    esac
-    case "$rel" in
-      .cspell.json) ;;
-      docs/adr/*.md) ;;
-      AGENTS.md|CLAUDE.md) ;;
-      CHANGELOG.md) ;;
-      */CHANGELOG.md) ;;
-      package.json|*/package.json)
-        if ! git_diff_only_version_field "$proj" "$rel"; then
-          return 1
-        fi
-        ;;
-      *) return 1 ;;
-    esac
-  done
-  [ "$had_file" = "1" ] && return 0
-  return 1
-}
-
-# Допоміжна: чи git-diff для файлу торкається ЛИШЕ рядків з `"version":`.
-git_diff_only_version_field() {
-  proj="$1"; path="$2"
-  [ -d "$proj/.git" ] || return 1
-  diff=$(cd "$proj" && git diff HEAD --unified=0 -- "$path" 2>/dev/null) || return 1
-  [ -z "$diff" ] && return 1
-  while IFS= read -r line; do
-    case "$line" in
-      '+++ '*|'--- '*|'@@ '*|'') continue ;;
-      [+-]*'"version":'*) continue ;;
-      [+-]*) return 1 ;;
-    esac
-  done <<EOF
-$diff
-EOF
-  return 0
-}
+# Підвантажуємо спільний helper (sourcing — не sub-shell, функції видимі поточному скрипту).
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/tooling-only.sh
+. "$SCRIPT_DIR/lib/tooling-only.sh"
 
 # Витягає поле `transcript:` з YAML frontmatter ADR-чернетки.
 draft_transcript_path() {

package/.pi-template/extensions/n-cursor-adr/index.ts

@@ -10,6 +10,12 @@
  * перед спавном LLM CLI.
  */
 
+import { randomUUID } from 'node:crypto'
+import { writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { env } from 'node:process'
+
 interface PiContext {
   cwd: string
   sessionId?: string
@@ -36,18 +42,12 @@ interface PiExec {
   ) => void
 }
 
-import { writeFileSync } from 'node:fs'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { randomUUID } from 'node:crypto'
-import { env } from 'node:process'
-
 const CAPTURE_HOOK = '.claude/hooks/capture-decisions.sh'
 const NORMALIZE_HOOK = '.claude/hooks/normalize-decisions.sh'
 
 /**
  * Pi extension entry point.
- * @param pi pi.dev extension API
+ * @param {PiExec} pi pi.dev extension API
  */
 export default function (pi: PiExec): void {
   pi.on('agent_end', async (_event, ctx) => {

package/.pi-template/extensions/n-cursor-adr/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "$comment": "TS-конфіг для pi.dev extension. Не компілюється сам пакетом (синкається як є у .pi/extensions/<name>/), потрібен лише для IDE/TS-сервера у проєкті-споживачі, щоб резолвити node:* модулі. Споживачу треба мати @types/node у devDependencies (зазвичай уже є транзитивно).",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "strict": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["index.ts"]
+}

package/CHANGELOG.md

@@ -4,6 +4,35 @@
 
 Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
 
+## [1.25.0] - 2026-05-26
+
+### Added
+
+- **`.claude-template/hooks/lib/tooling-only.sh`** — спільний bash-helper із функціями `is_tooling_only_change` і `git_diff_only_version_field`. Source'ається з `capture-decisions.sh` і `normalize-decisions.sh` через `. "$SCRIPT_DIR/lib/tooling-only.sh"` — caller'и більше не дублюють ~27 рядків логіки розпізнавання "tooling-only" сесій. Bash 3.2 (macOS `/bin/bash`) сумісний.
+- **`syncAdrHookLibScripts(projectRoot, templateDir)`** у `npm/scripts/sync-claude-config.mjs` — копіює всі `*.sh` із `.claude-template/hooks/lib/` у `.claude/hooks/lib/` проєкту-споживача без exec-біта (source-only). Експортується разом із новою `removeOrphanAdrHookLib(projectRoot)` для cleanup-у при вимкненому `adr` правилі.
+- Поле `adrHookLib: string[]` у відповіді `syncClaudeConfig` — список синкнутих lib-файлів. `npm/bin/n-cursor.js` виводить їх у `🤖 Claude-конфіг` логу окремими записами.
+
+### Changed
+
+- **`.claude-template/hooks/{capture,normalize}-decisions.sh`** — обидва скрипти `source`-ять спільний `lib/tooling-only.sh` замість локальних копій функцій. Заголовок `# shellcheck source=lib/tooling-only.sh` тримає shellcheck-аналіз чистим.
+
+### Fixed
+
+- Усунено jscpd-дублікат `is_tooling_only_change`/`git_diff_only_version_field` між `capture-decisions.sh` і `normalize-decisions.sh` (~27 рядків / ~194 токени). Споживачам більше не потрібен ignore-запис для цих файлів у `.jscpd.json`.
+
+## [1.24.0] - 2026-05-26
+
+### Added
+
+- **`.pi-template/extensions/n-cursor-adr/tsconfig.json`** — мінімальний TS-конфіг шаблону pi.dev extension, який синкається у `.pi/extensions/n-cursor-adr/` разом із `index.ts`. Дозволяє IDE/TS-серверу резолвити `node:*` модулі без project-wide tsconfig у проєкті-споживачі (`types: ["node"]`, `module/target: ES2022 + NodeNext`, `noEmit`, `isolatedModules`). Споживачу потрібен `@types/node` у devDeps (зазвичай уже є транзитивно).
+- **`pi` manifest у `npm/package.json`** — `{"skills":"skills","extensions":".pi-template/extensions"}`. Pi.dev під час `pi install npm:@nitra/cursor` тепер бачить explicit-шляхи до bundled-ресурсів, замість convention-auto-discovery. `extensions: ".pi-template/extensions"` критичний — pi за замовч. шукає `extensions/` у корені пакета, а у нас шлях нестандартний.
+- **`"pi-package"` keyword** у `npm/package.json` — пакет з’являється у pi-gallery для discoverability.
+
+### Changed
+
+- **`syncPiExtensions`** тепер копіює **всі файли** з теки `.pi-template/extensions/<name>/`, а не лише `index.ts`. Контракт повернення: `{ written, path, files }` — `path` тепер тека (а не файл), `files` — відсортований список базових імен. У `🤖 Claude-конфіг` логу та у `result.piExtension` caller-стороні виводиться тека.
+- **`.pi-template/extensions/n-cursor-adr/index.ts`** — порядок імпортів виправлено (всі `node:*` імпорти підняті на самий верх, перед `interface PiContext`). Усувало `import/first` ESLint-помилку; функціонально без змін.
+
 ## [1.23.0] - 2026-05-25
 
 ### Added

package/bin/n-cursor.js

@@ -1401,8 +1401,13 @@ async function runSync() {
     if (result.commands.length > 0) parts.push(`${result.commands.length} slash-commands`)
     if (result.adrHook) parts.push('.claude/hooks/capture-decisions.sh')
     if (result.adrNormalizeHook) parts.push('.claude/hooks/normalize-decisions.sh')
+    if (result.adrHookLib?.length > 0) {
+      for (const libPath of result.adrHookLib) {
+        parts.push(libPath)
+      }
+    }
     if (result.gitignoreAdr) parts.push('.gitignore (adr fragment)')
-    if (result.piExtension) parts.push('.pi/extensions/n-cursor-adr/index.ts')
+    if (result.piExtension) parts.push('.pi/extensions/n-cursor-adr/')
     if (parts.length > 0) {
       console.log(`🤖 Claude-конфіг: ${parts.join(', ')}`)
     }

package/package.json

@@ -1,14 +1,19 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
     "cursor",
     "cursor-rules",
     "mdc",
-    "n"
+    "n",
+    "pi-package"
   ],
+  "pi": {
+    "skills": "skills",
+    "extensions": ".pi-template/extensions"
+  },
   "homepage": "https://github.com/n/cursor#readme",
   "bugs": {
     "url": "https://github.com/n/cursor/issues"

package/scripts/sync-claude-config.mjs

@@ -61,6 +61,7 @@ const CURSOR_DIR = '.cursor'
 const CURSOR_HOOKS_FILE = `${CURSOR_DIR}/hooks.json`
 const ADR_HOOK_SCRIPT_NAME = 'capture-decisions.sh'
 const ADR_NORMALIZE_HOOK_SCRIPT_NAME = 'normalize-decisions.sh'
+const ADR_HOOK_LIB_DIR = 'lib'
 const TEMPLATE_DIR_NAME = '.claude-template'
 
 /** Корінь pi.dev артефактів у проєкті-споживачі. */
@@ -415,32 +416,86 @@ export function syncAdrNormalizeHookScript(projectRoot, templateDir) {
 }
 
 /**
- * Копіює bundled pi.dev TS-extension `npm/.pi-template/extensions/n-cursor-adr/index.ts`
- * у `.pi/extensions/n-cursor-adr/index.ts` проєкту-споживача. Файл fully-owned: при кожному
- * sync-у перезаписується. Якщо bundled template відсутній (наприклад, у legacy-версіях
- * пакета без `.pi-template/`) — повертаємо `{written: false}` без помилки.
+ * Копіює всі `.sh`-файли з `.claude-template/hooks/lib/` у `.claude/hooks/lib/` проєкту.
+ * Файли source-only (без exec bit) — їх `source`-ять capture/normalize-decisions.sh,
+ * щоб не дублювати спільну bash-логіку (`is_tooling_only_change`,
+ * `git_diff_only_version_field`).
+ * Тека fully-owned: при кожному sync-у перезаписується.
+ * @param {string} projectRoot корінь проєкту-споживача
+ * @param {string} templateDir каталог `.claude-template/` усередині пакету
+ * @returns {Promise<Array<{ written: boolean, path: string }>>} перелік записаних файлів (порожній, якщо темплейту нема)
+ */
+export async function syncAdrHookLibScripts(projectRoot, templateDir) {
+  const libTemplateDir = join(templateDir, 'hooks', ADR_HOOK_LIB_DIR)
+  if (!existsSync(libTemplateDir)) {
+    return []
+  }
+  const entries = await readdir(libTemplateDir, { withFileTypes: true })
+  const libDestDir = join(projectRoot, CLAUDE_HOOKS_DIR, ADR_HOOK_LIB_DIR)
+  await mkdir(libDestDir, { recursive: true })
+  const written = []
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.sh')) continue
+    const content = await readFile(join(libTemplateDir, entry.name), 'utf8')
+    // НЕ chmod 755 — source-файли не виконувані (їх лише `.`-ять caller-скрипти).
+    await writeFile(join(libDestDir, entry.name), content, 'utf8')
+    written.push({ written: true, path: `${CLAUDE_HOOKS_DIR}/${ADR_HOOK_LIB_DIR}/${entry.name}` })
+  }
+  return written
+}
+
+/**
+ * Видаляє `.claude/hooks/lib/` директорію з проєкту-споживача.
+ * Викликається коли правило `adr` вимкнено — lib-файли не самостійні, без хуків,
+ * що їх source-ять, вони нікому не потрібні (симетрично до `removeOrphanPiExtension`).
+ * @param {string} projectRoot корінь проєкту-споживача
+ * @returns {Promise<{ removed: boolean, path: string }>} чи було щось видалено та відносний шлях
+ */
+export async function removeOrphanAdrHookLib(projectRoot) {
+  const libDir = join(projectRoot, CLAUDE_HOOKS_DIR, ADR_HOOK_LIB_DIR)
+  if (!existsSync(libDir)) {
+    return { removed: false, path: '' }
+  }
+  await rm(libDir, { recursive: true, force: true })
+  return { removed: true, path: `${CLAUDE_HOOKS_DIR}/${ADR_HOOK_LIB_DIR}` }
+}
+
+/**
+ * Копіює bundled pi.dev TS-extension `npm/.pi-template/extensions/n-cursor-adr/` (усі файли —
+ * `index.ts`, `tsconfig.json`, потенційні `package.json`/`.gitignore` тощо) у
+ * `.pi/extensions/n-cursor-adr/` проєкту-споживача. Тека fully-owned: при кожному sync-у
+ * перезаписується. Якщо bundled template відсутній (legacy-версії пакета без `.pi-template/`)
+ * або в ньому немає `index.ts` — повертаємо `{written: false}` без помилки.
  *
+ * Розширення поверх `index.ts` (tsconfig тощо) потрібні, бо `.pi/extensions/` синкається як є
+ * у проєкти-споживачі, а IDE/TS-сервер мусить резолвити `node:*` модулі без додаткових
+ * project-wide конфігів.
  * @param {string} projectRoot корінь проєкту-споживача
  * @param {string} bundledPackageRoot корінь установленого `@nitra/cursor` (із `.pi-template/`)
- * @returns {Promise<{ written: boolean, path: string }>} чи писали файл, та його відносний шлях
+ * @returns {Promise<{ written: boolean, path: string, files: string[] }>} чи писали; відносний шлях до теки розширення; список скопійованих базових імен (відсортований)
  */
 export async function syncPiExtensions(projectRoot, bundledPackageRoot) {
-  const srcPath = join(
-    bundledPackageRoot,
-    PI_TEMPLATE_DIR_NAME,
-    'extensions',
-    PI_EXTENSION_NAME,
-    'index.ts'
-  )
-  if (!existsSync(srcPath)) {
-    return { written: false, path: '' }
+  const srcDir = join(bundledPackageRoot, PI_TEMPLATE_DIR_NAME, 'extensions', PI_EXTENSION_NAME)
+  const indexPath = join(srcDir, 'index.ts')
+  if (!existsSync(indexPath)) {
+    return { written: false, path: '', files: [] }
   }
-  const content = await readFile(srcPath, 'utf8')
   const destDir = join(projectRoot, PI_EXTENSIONS_DIR, PI_EXTENSION_NAME)
   await mkdir(destDir, { recursive: true })
-  const destPath = join(destDir, 'index.ts')
-  await writeFile(destPath, content, 'utf8')
-  return { written: true, path: `${PI_EXTENSIONS_DIR}/${PI_EXTENSION_NAME}/index.ts` }
+  const entries = await readdir(srcDir, { withFileTypes: true })
+  const copied = []
+  for (const entry of entries) {
+    if (!entry.isFile()) continue
+    const name = entry.name
+    const content = await readFile(join(srcDir, name), 'utf8')
+    await writeFile(join(destDir, name), content, 'utf8')
+    copied.push(name)
+  }
+  return {
+    written: true,
+    path: `${PI_EXTENSIONS_DIR}/${PI_EXTENSION_NAME}`,
+    files: copied.toSorted((a, b) => a.localeCompare(b))
+  }
 }
 
 /**
@@ -549,7 +604,7 @@ export async function syncClaudeCommands(projectRoot, templateDir) {
  * @param {string} options.bundledPackageRoot корінь установленого `@nitra/cursor`
  * @param {boolean} options.enabled чи увімкнено sync (з `.n-cursor.json` `claude-config`)
  * @param {string[]} [options.rules] список увімкнених правил із `.n-cursor.json` — впливає на ADR Stop-hook (`adr`)
- * @returns {Promise<{ settings: boolean, cursorHooks: boolean, commands: string[], adrHook: boolean, adrNormalizeHook: boolean, gitignoreAdr: boolean, piExtension: boolean }>} прапорці записів settings/Cursor hooks/ADR-hook(s)/`.gitignore`/pi-extension та список slash-команд
+ * @returns {Promise<{ settings: boolean, cursorHooks: boolean, commands: string[], adrHook: boolean, adrNormalizeHook: boolean, adrHookLib: string[], gitignoreAdr: boolean, piExtension: boolean }>} прапорці записів settings/Cursor hooks/ADR-hook(s)/`.gitignore`/pi-extension, перелік lib-файлів і список slash-команд
  */
 export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enabled, rules = [] }) {
   if (!enabled) {
@@ -559,6 +614,7 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
       commands: [],
       adrHook: false,
       adrNormalizeHook: false,
+      adrHookLib: [],
       gitignoreAdr: false,
       piExtension: false
     }
@@ -571,6 +627,7 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
       commands: [],
       adrHook: false,
       adrNormalizeHook: false,
+      adrHookLib: [],
       gitignoreAdr: false,
       piExtension: false
     }
@@ -580,6 +637,11 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
   const adrNormalizeHook = includeAdrHook
     ? await syncAdrNormalizeHookScript(projectRoot, templateDir)
     : { written: false, path: '' }
+  // Lib-файли мають сенс лише з активним хоча б одним ADR-хуком — без caller'а
+  // нікому source-ити; при вимкненому правилі прибираємо орфан-теку.
+  const adrHookLibEntries = includeAdrHook
+    ? await syncAdrHookLibScripts(projectRoot, templateDir)
+    : (await removeOrphanAdrHookLib(projectRoot), [])
   const gitignoreAdr = includeAdrHook
     ? await syncGitignoreAdrFragment(projectRoot, bundledPackageRoot)
     : { written: false, path: '' }
@@ -595,6 +657,7 @@ export async function syncClaudeConfig({ projectRoot, bundledPackageRoot, enable
     commands,
     adrHook: adrHook.written,
     adrNormalizeHook: adrNormalizeHook.written,
+    adrHookLib: adrHookLibEntries.map(e => e.path),
     gitignoreAdr: gitignoreAdr.written,
     piExtension: piExtension.written
   }

package/skills/coverage-fix/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: n-coverage-fix
+description: >-
+  Автономна команда: запускає coverage, читає ## Recommendations у COVERAGE.md, ітеративно пише тести для вижилих мутантів до конвергенції
+---
+
+# /n-coverage-fix — ітеративне підвищення mutation score
+
+## Важливо
+
+⚠️ Не запускати паралельно з іншим `/n-coverage-fix` або `bun coverage` — Stryker пише `mutation.json` і `incremental.json` в одну директорію. `n-cursor coverage` всередині вже серіалізований через `withLock('coverage')`, але паралельний запуск двох ітерацій скілу зіпсує дані.
+
+## Мета
+
+Автономно підвищити mutation score: запустити `bun coverage`, записати тести для вижилих мутантів, повторити до конвергенції (score перестав зростати).
+
+## Алгоритм
+
+### Крок 1: Запусти coverage
+
+```bash
+bun coverage
+```
+
+(або `bun run coverage` якщо команда у `package.json`)
+
+Чекай завершення. Якщо команди немає у `package.json` — запусти `n-cursor coverage` з кореня.
+
+### Крок 2: Прочитай вижилих мутантів
+
+Прочитай `COVERAGE.md` — знайди секцію `## Recommendations`.
+
+Якщо секції немає або вона порожня:
+```
+✓ Нема вижилих мутантів — mutation score повний
+```
+→ DONE
+
+Запам'ятай поточний mutation score як `baseline_score` (рядок `| **Разом** |` з таблиці у COVERAGE.md).
+
+### Крок 3: Для кожного файлу з Recommendations — пиши тести
+
+Для кожного `### <file>` у секції:
+
+**3a. Читай контекст:**
+- Source-файл (`<file>` від кореня проєкту)
+- Таблицю вижилих мутантів: рядок, оригінал, заміна, тип
+- Блок `**Приклад наявного тесту:**` — style guide для нових тестів
+
+**3b. Знайди тестовий файл:**
+Перший що існує:
+1. `<dir>/<basename>.test.js` — поруч із source
+2. `<dir>/<basename>.spec.js`
+3. `test/<basename>.test.js` від кореня
+4. `tests/<basename>.test.js` від кореня
+
+Якщо жоден не знайдено — створи `<dir>/<basename>.test.js` з правильними imports (орієнтуйся на сусідні файли).
+
+**3c. Напиши тести що вбивають кожен мутант:**
+
+Керуйся типом мутації:
+- `ConditionalExpression` (`→ false` / `→ true`): протестуй обидва branch явно — значення що робить умову `true` і значення що робить її `false`
+- `BooleanLiteral` (`true → false`): перевір початковий стан — `initialValue === false`
+- `LogicalOperator` (`&&` ↔ `||`): передай `null` та `undefined` **окремо**, перевір що результат різний для кожного
+- `StringLiteral` / `EqualityOperator`: перевір точний рядок/значення, а не лише happy-path
+
+Правила:
+- НЕ видаляй і НЕ змінюй наявні тести
+- Стиль: той самий `describe`/`it`/`expect`, мова коментарів — як у прикладі тесту
+- Якщо `**Приклад наявного тесту:**` відсутній — орієнтуйся на інші test-файли у тій самій директорії
+
+**3d. Після написання тестів:**
+```bash
+bun test <testFile>
+```
+
+Якщо FAIL — виправи саме ті тести що впали (до 2 спроб). Якщо не вдалося — логуй і переходь до наступного файлу.
+
+### Крок 4: Перевір що весь suite проходить
+
+```bash
+bun test
+```
+
+Якщо FAIL:
+- Не відкочувати зміни
+- Показати: яка помилка, які файли змінені, що вже покращено
+- Очікувати рішення від user: [виправити вручну → продовжити] / [пропустити файл] / [зупинити]
+
+### Крок 5: Запусти coverage і перевір конвергенцію
+
+```bash
+bun coverage
+```
+
+Якщо CRASH (SIGURG, memory pressure): нагадати user — Stryker incremental зберіг прогрес, перезапустити `bun coverage`.
+
+Прочитай новий COVERAGE.md. Візьми `new_score` з рядка `| **Разом** |`.
+
+**Рішення:**
+- Якщо `new_score > baseline_score` → `baseline_score = new_score` → перейти до Кроку 2 (наступна ітерація)
+- Якщо `new_score <= baseline_score` → конвергенція:
+  ```
+  ✓ Конвергенція: mutation score більше не покращується.
+  Baseline: <baseline_score> → Фінал: <new_score>
+  ```
+  → DONE
+
+## Нотатки
+
+- Stryker `incremental` (`incrementalFile`) зберігає прогрес між запусками — crash ≠ перезапуск з нуля
+- Не комітити зміни автоматично — user вирішує коли комітити
+- Пріоритет файлів: більше вижилих мутантів = важливіший (першим у Recommendations = найважливіший)
+- Якщо `COVERAGE.md` відсутній — запусти `bun coverage` спочатку

package/skills/coverage-fix/auto.md

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