@nitra/cursor 1.34.1 → 1.35.2

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.35.2] - 2026-05-30
+
+### Fixed
+
+- test: meta-тести no-process-chdir і test-helpers перенесено на конкатенацію/Identifier-аргументи, щоб не тригерити власні сканери (false positives)
+
+## [1.35.1] - 2026-05-30
+
+### Added
+
+- Нові тести для підвищення coverage: run-dotenv-linter (spawnSync error paths), lint.mjs preflight-OK paths, ua_http_route.mjs (default cwd + readFile chmod-fail), auto-rules.mjs (readdir/JSON catch-блоки), run-shellcheck-errors, run-v8r, sync-claude-config, test-helpers absolute-path guard, rename-yaml-extensions sort, graphql langFromPath, capacitor segmentMinMajor, coverage-classify cache/retry/fallback, npm-module package_structure, changelog consistency, bun-sql-scan BinaryExpression. Lines coverage: ~83.59% → 88.32%.
+
+## [1.35.0] - 2026-05-30
+
+### Added
+
+- LLM-класифікатор survived мутантів у n-cursor coverage: для кожного survived Claude Sonnet 4.6 виносить verdict (worth-testing/equivalent/defensive/glue/wrapper) з reasoning + confidence. Allowed gaps виключаються з знаменника mutation score. Cache по git-blob-hash. Graceful skip без API key. Threshold у .n-cursor.json#coverage.classifyConfidenceThreshold (default 1.1 — rollout mode).
+
 ## [1.34.1] - 2026-05-30
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "1.34.1",
+  "version": "1.35.2",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -52,11 +52,12 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.0",
-    "@anthropic-ai/sdk": "^0.54.0",
+    "@anthropic-ai/sdk": "^0.100.1",
     "oxc-parser": "^0.128.0",
     "picomatch": "^4.0.4",
     "smol-toml": "^1.6.1",
-    "yaml": "^2.8.3"
+    "yaml": "^2.8.3",
+    "zod": "^4.4.3"
   },
   "engines": {
     "bun": ">=1.3",

package/rules/changelog/changelog.mdc

@@ -1,6 +1,6 @@
 ---
 description: CHANGELOG.md в кожному workspace, з двома моделями бази порівняння (npm і Python)
-version: '3.0'
+version: '3.1'
 alwaysApply: true
 ---
 
@@ -9,14 +9,12 @@ alwaysApply: true
 > **Якщо в цій сесії ти змінив(ла) файли в пакетному workspace** (код, rego, правила, скіли, скрипти, конфіги, тести — **не** лише `docs/` / `doc/`) — **не завершуй задачу**, поки не виконаєш **усі три** кроки нижче в **тому ж** наборі змін. Це не «опційно після синку» — це частина PR.
 
 1. **Поклади change-файл** `<ws>/.changes/<timestamp>-<rand>.md` з frontmatter `bump:` (`major|minor|patch`) + `section:` (`Added|Changed|Fixed|Removed`) і текстом опису. Команда: `npx @nitra/cursor change --bump <…> --section <…> --message "<…>" [--ws <шлях>]`.
-2. **Не** редагуй `version` і `CHANGELOG.md` вручну — їх формує `n-cursor release` у CI на `main` (агрегує change-файли, ставить git-тег `<name>@<version>`).
-3. **`npx @nitra/cursor fix changelog`** → exit **`0`** (м'яка перевірка: достатньо наявності change-файлу **або** вже піднятого `version`).
-
-**Legacy / hotfix:** ручний bump `version` + новий запис у `CHANGELOG.md` усе ще приймається перевіркою як альтернатива change-файлу.
+2. **Ніколи** не редагуй `version` і `CHANGELOG.md` вручну — навіть для hotfix. Єдиний артефакт зміни — change-файл; `version`/CHANGELOG формує `n-cursor release` у CI на `main` (агрегує change-файли, ставить git-тег `<name>@<version>`). Будь-яка зміна `version` поза CI (drift від бази чи опублікованої) завалює `check changelog` — навіть якщо поряд є change-файл.
+3. **`npx @nitra/cursor fix changelog`** → exit **`0`** (достатньо наявності change-файлу; `version` лишається незмінним).
 
 **Тригер шляхів (приклади):** `npm/**`, `packages/foo/**`, будь-який каталог з власним `package.json` / `pyproject.toml`, куди потрапили правки.
 
-**Інверсія (bump не потрібен):** лише `docs/` / `doc/`; синхронізований із `@nitra/cursor` інструментарій (`.cursor/`, `.claude/`); лише `.gitignore`; лише сам релізний крок (`CHANGELOG.md` + `version`). **Корінь монорепо** (воркспейс `.` за наявності підпакетів) не перевіряється взагалі — отже й кореневі `AGENTS.md` / `CLAUDE.md` та bump `@nitra/cursor` у `devDependencies`.
+**Інверсія (change-файл не потрібен):** лише `docs/` / `doc/`; синхронізований із `@nitra/cursor` інструментарій (`.cursor/`, `.claude/`); лише `.gitignore`. **Корінь монорепо** (воркспейс `.` за наявності підпакетів) не перевіряється взагалі — отже й кореневі `AGENTS.md` / `CLAUDE.md` та bump `@nitra/cursor` у `devDependencies`. Окремого «релізного кроку» у feature-флоу немає — `version`/`CHANGELOG.md` змінює лише CI.
 
 **Pre-commit (людина):** `hk` у цьому репо також запускає `check changelog` при змінах під `npm/**` — агент не покладайся лише на commit hook; виконай кроки 1–3 **до** фінальної відповіді.
 
@@ -35,15 +33,14 @@ alwaysApply: true
 
 Повний алгоритм — у блоці **STOP** вище; тут лише уточнення.
 
-**Інверсія (за замовчуванням не вимагають bump/CHANGELOG):**
+**Інверсія (за замовчуванням не вимагають change-файлу):**
 
 - зміни **лише** під `docs/` або `doc/`;
 - синхронізований із `@nitra/cursor` інструментарій під `.cursor/` (канонічні правила та скіли) і `.claude/` (ADR-хуки) — це дзеркало tooling-пакета, а не логіка воркспейсу;
 - будь-які зміни в **корені монорепо** (воркспейс `.` за наявності підпакетів) — корінь веде glue/конфіг/tooling, власного CHANGELOG не має; помітні зміни документують підпакети. Сюди потрапляють і кореневі `AGENTS.md` / `CLAUDE.md`, і bump `@nitra/cursor` у `devDependencies`;
-- файли під **`.gitignore`**;
-- правки **лише** `CHANGELOG.md` або поля `version` у маніфесті як сам релізний крок.
+- файли під **`.gitignore`**.
 
-**Вимагають bump + нову секцію CHANGELOG** — усі інші зміни в каталозі workspace (код, rego, правила, скіли, конфіги, тести тощо). Виняток `.cursor/` / `.claude/` **не** поширюється на джерело правил у репо `@nitra/cursor` — воно лежить під `npm/`, тож зміни в ньому далі вимагають bump.
+**Вимагають change-файл** — усі інші зміни в каталозі workspace (код, rego, правила, скіли, конфіги, тести тощо). Виняток `.cursor/` / `.claude/` **не** поширюється на джерело правил у репо `@nitra/cursor` — воно лежить під `npm/`, тож зміни в ньому далі вимагають change-файлу.
 
 Перевірка програмна (`changelog/js/consistency.mjs`).
 
@@ -57,8 +54,8 @@ alwaysApply: true
 
 **Python:** статичні `project.name` і `project.version` у `pyproject.toml` (або Poetry-секція).
 
-1. **Локальна `version` ≠ опублікованій** (npm / PyPI): запис у `<ws>/CHANGELOG.md`; для npm також `"CHANGELOG.md"` у `files`.
-2. **Версії збігаються**, але в git є **релевантні** зміни без bump → fail.
+1. **Локальна `version` ≠ опублікованій** (npm / PyPI): drift поза CI → **fail** (ручний bump заборонено; навіть із change-файлом). Відкоти `version`.
+2. **Версії збігаються**, але в git є **релевантні** зміни без change-файлу → fail. Для npm `"CHANGELOG.md"` має бути в `files` (публікується разом із пакетом).
 3. **Реєстр недосяжний** — fail-safe pass.
 4. **Немає релевантних змін** — pass.
 
@@ -69,7 +66,7 @@ alwaysApply: true
 1. На **`dev`** local-only не активний (крім незакомічених registry-published).
 2. На **`main`** — diff від **`origin/main`** (попередній опублікований `main`); без remote — від `HEAD~1`. **`dev` не використовується** як база на `main`.
 3. На **feature-гілці** — `merge-base` з **`dev`**, якщо є; інакше з **`main`** (репо без `dev`).
-4. Bump + CHANGELOG **раз на PR** / direct-commit на `main`.
+4. Drift `version` від бази → **fail** (ручний bump заборонено). Зміни фіксуй change-файлом; bump зробить CI.
 
 Якщо немає git або немає `dev`/`main`/`origin/main` — local-only пропускається.
 

package/rules/changelog/js/consistency.mjs

@@ -1,25 +1,24 @@
 /**
- * Перевіряє, що в кожному workspace із релізно-релевантними змінами підвищена `version`
- * у маніфесті (`package.json` або `pyproject.toml`) і в `<ws>/CHANGELOG.md` є запис
- * `## [version] - YYYY-MM-DD` (формат Keep a Changelog).
+ * Перевіряє, що кожен workspace із релізно-релевантними змінами зафіксував їх через
+ * change-файл `<ws>/.changes/*.md` — єдиний дозволений артефакт зміни. Bump `version`
+ * і генерацію `CHANGELOG.md` робить виключно `n-cursor release` у CI на `main`.
+ *
+ * Інваріант (на будь-якій гілці): `version` не має відхилятися від бази. Будь-який drift
+ * `version` (vs опублікована в реєстрі або vs git-база) — ручний bump поза CI — завалює
+ * перевірку, навіть якщо присутній change-файл. Pass лише коли є change-файл, а version
+ * не зрушено; зміни без change-файлу — fail.
  *
  * Дві моделі бази — на рівні воркспейсу (див. n-changelog.mdc):
  *
  * 1) **registry-published** (npm: `name` + `files`, не `private`; Python: `project.name` +
- *    статична `project.version` у `pyproject.toml`): база = опублікована версія в npm / PyPI.
- *    Якщо локальна версія відрізняється — потрібен CHANGELOG; для npm також `"CHANGELOG.md"`
- *    у `files`. Якщо версії збігаються, але в git є релевантні зміни без bump — fail.
- *
- * 2) **local-only** (приватні npm, без `files`, Python без імені/версії для реєстру):
+ *    статична `project.version`): база = опублікована версія в npm / PyPI.
+ * 2) **local-only** (приватні npm без `files`, Python без імені/версії для реєстру):
  *    feature-гілка — `merge-base` з `dev`, інакше з `main`; на `main` — diff від
- *    `origin/main` (попередній опублікований main) або `HEAD~1` без remote.
+ *    `origin/main` (або `HEAD~1` без remote).
  *
  * Усі `git` і зовнішні виклики — через `execFile` / `fetch`, без shell-інтерполяції.
  */
 import { execFile } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { readFile } from 'node:fs/promises'
-import { join } from 'node:path'
 import { promisify } from 'node:util'
 
 import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
@@ -277,16 +276,6 @@ async function readBaseVersion(baseRef, manifest, cwd) {
   return parsePyprojectFields(out).version
 }
 
-/**
- * @param {string} text параметр
- * @param {string} version параметр
- * @returns {boolean} результат
- */
-function changelogHasVersionEntry(text, version) {
-  const needle = `## [${version}]`
-  return text.startsWith(needle) || text.includes(`\n${needle}`)
-}
-
 /**
  * @param {string} name параметр
  * @returns {Promise<string | null>} результат
@@ -363,31 +352,6 @@ function checkNpmFilesArrayContainsChangelog(manifest, pass, fail) {
   }
 }
 
-/**
- * @param {string} ws параметр
- * @param {string} version параметр
- * @param {(msg: string) => void} pass параметр
- * @param {(msg: string) => void} fail параметр
- * @param {string} cwd робочий каталог
- * @returns {Promise<boolean>} результат
- */
-async function verifyChangelogEntry(ws, version, pass, fail, cwd) {
-  const label = ws === '.' ? '<root>' : ws
-  const changelogRel = join(ws, 'CHANGELOG.md')
-  const changelogAbs = join(cwd, changelogRel)
-  if (!existsSync(changelogAbs)) {
-    fail(`${label}: відсутній ${changelogRel} (Keep a Changelog, див. n-changelog.mdc)`)
-    return false
-  }
-  const text = await readFile(changelogAbs, 'utf8')
-  if (changelogHasVersionEntry(text, version)) {
-    pass(`${changelogRel}: знайдено запис для версії ${version}`)
-    return true
-  }
-  fail(`${changelogRel}: відсутній запис для ${version} (формат "## [${version}] - YYYY-MM-DD")`)
-  return false
-}
-
 /**
  * @param {import('../lib/package-manifest.mjs').PackageManifest} manifest параметр
  * @returns {string} результат
@@ -396,6 +360,20 @@ function workspaceLabel(manifest) {
   return manifest.ws === '.' ? '<root>' : manifest.ws
 }
 
+/**
+ * Повідомлення «поклади change-файл» для workspace з релевантними змінами без change-файлу.
+ * @param {string} label мітка воркспейсу
+ * @param {string} mf шлях до маніфесту
+ * @returns {string} текст fail
+ */
+function missingChangeFileMessage(label, mf) {
+  return (
+    `${label}: є релевантні зміни, але немає change-файлу (version у ${mf} не чіпай вручну). ` +
+    `Поклади change-файл: npx @nitra/cursor change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<…>"; ` +
+    `bump зробить CI на main (n-changelog.mdc)`
+  )
+}
+
 /**
  * Чи має workspace незрелізні change-файли (намір зафіксовано — bump зробить CI).
  * @param {string} ws workspace
@@ -409,18 +387,20 @@ async function hasPendingChangeFiles(ws, cwd) {
 
 /**
  * @param {import('../lib/package-manifest.mjs').PackageManifest} manifest параметр
- * @param {string} Vcurrent параметр
+ * @param {string} _Vcurrent параметр (для сумісності сигнатури; bump робить CI)
  * @param {string[]} subWorkspaces параметр
  * @param {(msg: string) => void} pass параметр
  * @param {(msg: string) => void} fail параметр
  * @param {string} cwd робочий каталог
  * @returns {Promise<void>} результат
  */
-async function checkPublishedWorkspacePendingGitChanges(manifest, Vcurrent, subWorkspaces, pass, fail, cwd) {
+async function checkPublishedWorkspacePendingGitChanges(manifest, _Vcurrent, subWorkspaces, pass, fail, cwd) {
   const label = workspaceLabel(manifest)
   const mf = manifestFilePath(manifest.ws, manifest)
   if (await hasPendingChangeFiles(manifest.ws, cwd)) {
     pass(`${label}: є change-файл(и) у .changes/ — bump зробить CI (n-changelog.mdc)`)
+    // Реліз наближається → CHANGELOG має публікуватися разом із пакетом.
+    checkNpmFilesArrayContainsChangelog(manifest, pass, fail)
     return
   }
   if (!(await isInsideGitRepo(cwd))) {
@@ -431,42 +411,19 @@ async function checkPublishedWorkspacePendingGitChanges(manifest, Vcurrent, subW
 
   if (branch === LOCAL_ONLY_SKIP_BRANCH) {
     if (await workspaceHasRelevantChangesAgainstBase('HEAD', manifest.ws, subWorkspaces, cwd)) {
-      fail(
-        `${label}: у registry-published пакеті є незакомічені зміни при version ${Vcurrent}, що вже в реєстрі. ` +
-          `Підвищ version у ${mf} і додай запис у CHANGELOG.md (n-changelog.mdc)`
-      )
+      fail(missingChangeFileMessage(label, mf))
     }
     return
   }
 
   const comparison = await resolveChangelogComparisonPoint(branch, cwd)
-  if (
-    comparison &&
-    (await workspaceHasRelevantChangesAgainstBase(comparison.ref, manifest.ws, subWorkspaces, cwd))
-  ) {
-    const Vbase = await readBaseVersion(comparison.ref, manifest, cwd)
-    const baseLabel = comparison.label
-    if (Vbase === null) {
-      pass(
-        `${label}: новий registry-published воркспейс (на ${baseLabel} відсутній ${mf}) — перевіряємо CHANGELOG для ${Vcurrent}`
-      )
-      await verifyChangelogEntry(manifest.ws, Vcurrent, pass, fail, cwd)
-      checkNpmFilesArrayContainsChangelog(manifest, pass, fail)
-    } else if (Vbase === Vcurrent) {
-      fail(
-        `${label}: у цій гілці є зміни в registry-published пакеті, але version у ${mf} ` +
-          `не підвищено (на ${baseLabel} — ${Vbase}). Bump + запис у CHANGELOG.md обов'язкові (n-changelog.mdc)`
-      )
-    } else {
-      pass(`${label}: version змінено (${Vbase} → ${Vcurrent}) — очікується запис CHANGELOG після bump`)
-    }
+  if (comparison && (await workspaceHasRelevantChangesAgainstBase(comparison.ref, manifest.ws, subWorkspaces, cwd))) {
+    fail(missingChangeFileMessage(label, mf))
+    return
   }
 
   if (branch === 'main' && (await workspaceHasRelevantChangesAgainstBase('HEAD', manifest.ws, subWorkspaces, cwd))) {
-    fail(
-      `${label}: у registry-published пакеті є незакомічені зміни при version ${Vcurrent}, що вже в реєстрі. ` +
-        `Підвищ version у ${mf} і додай запис у CHANGELOG.md (n-changelog.mdc)`
-    )
+    fail(missingChangeFileMessage(label, mf))
   }
 }
 
@@ -497,14 +454,18 @@ async function checkPublishedWorkspace(manifest, subWorkspaces, getPublishedVers
     pass(`${label}: ${name} — опублікована версія недоступна (мережа/реєстр), перевірку пропущено`)
     return
   }
-  if (Vpublished === Vcurrent) {
-    pass(`${label}: ${name}@${Vcurrent} збігається з реєстром — перевіряємо git на незрелізні зміни`)
-    await checkPublishedWorkspacePendingGitChanges(manifest, Vcurrent, subWorkspaces, pass, fail, cwd)
+  // Drift від опублікованої версії має пріоритет над change-файлом: ручний bump
+  // заборонено навіть із change-файлом (симетрично з local-only-шляхом).
+  if (Vpublished !== Vcurrent) {
+    fail(
+      `${label}: version у ${mf} (${Vcurrent}) розходиться з опублікованою (${Vpublished}) — ` +
+        `ручний bump заборонено. Відкоти version і поклади change-файл ` +
+        `(npx @nitra/cursor change …); bump зробить CI на main (n-changelog.mdc)`
+    )
     return
   }
-  pass(`${label}: ${name} — нова локальна версія (${Vpublished} → ${Vcurrent})`)
-  await verifyChangelogEntry(manifest.ws, Vcurrent, pass, fail, cwd)
-  checkNpmFilesArrayContainsChangelog(manifest, pass, fail)
+  pass(`${label}: ${name}@${Vcurrent} збігається з реєстром — перевіряємо git на незрелізні зміни`)
+  await checkPublishedWorkspacePendingGitChanges(manifest, Vcurrent, subWorkspaces, pass, fail, cwd)
 }
 
 /**
@@ -518,31 +479,22 @@ async function checkPublishedWorkspace(manifest, subWorkspaces, getPublishedVers
 async function checkLocalOnlyChangedWorkspace(comparisonRef, manifest, baseLabel, pass, fail, cwd) {
   const label = workspaceLabel(manifest)
   const mf = manifestFilePath(manifest.ws, manifest)
-  if (await hasPendingChangeFiles(manifest.ws, cwd)) {
-    pass(`${label}: є change-файл(и) у .changes/ — bump зробить CI (n-changelog.mdc)`)
-    return
-  }
   const Vcurrent = manifest.version
-  if (!Vcurrent) {
-    fail(`${label}: у ${mf} відсутнє поле version (потрібне для запису в CHANGELOG)`)
-    return
-  }
+  // Drift version від бази має пріоритет над change-файлом: ручний bump заборонено
+  // навіть якщо change-файл присутній (симетрично з published-шляхом).
   const Vbase = await readBaseVersion(comparisonRef, manifest, cwd)
-  if (Vbase === null) {
-    pass(`${label}: новий воркспейс (на ${baseLabel} відсутній ${mf}) — перевіряємо CHANGELOG для ${Vcurrent}`)
-    if (!(await verifyChangelogEntry(manifest.ws, Vcurrent, pass, fail, cwd))) return
-    checkNpmFilesArrayContainsChangelog(manifest, pass, fail)
-    return
-  }
-  if (Vbase === Vcurrent) {
+  if (Vbase !== null && Vcurrent !== null && Vbase !== Vcurrent) {
     fail(
-      `${label}: у цій гілці є зміни, але version у ${mf} не підвищено (на ${baseLabel} — ${Vbase}). Bump + запис у CHANGELOG.md обов'язкові на PR`
+      `${label}: version у ${mf} змінено поза CI (${Vbase} → ${Vcurrent}) — ручний bump заборонено (на ${baseLabel} — ${Vbase}). ` +
+        `Відкоти version і поклади change-файл (npx @nitra/cursor change …); bump зробить CI (n-changelog.mdc)`
     )
     return
   }
-  pass(`${label}: version підвищено (${Vbase} → ${Vcurrent})`)
-  if (!(await verifyChangelogEntry(manifest.ws, Vcurrent, pass, fail, cwd))) return
-  checkNpmFilesArrayContainsChangelog(manifest, pass, fail)
+  if (await hasPendingChangeFiles(manifest.ws, cwd)) {
+    pass(`${label}: є change-файл(и) у .changes/ — bump зробить CI (n-changelog.mdc)`)
+    return
+  }
+  fail(missingChangeFileMessage(label, mf))
 }
 
 /**

package/rules/test/coverage/coverage.mjs

@@ -13,10 +13,12 @@
  * specs/2026-05-24-coverage-rule-design.md).
  */
 import { existsSync } from 'node:fs'
-import { writeFile } from 'node:fs/promises'
+import { readFile, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 
+import { applyVerdicts } from '../../../scripts/coverage-classify/apply.mjs'
+import { classify } from '../../../scripts/coverage-classify/index.mjs'
 import { readNCursorConfigLite } from '../../../scripts/lib/read-n-cursor-config-lite.mjs'
 import { withLock } from '../../../scripts/utils/with-lock.mjs'
 
@@ -72,11 +74,14 @@ export function formatScore({ caught, total }) {
  * Рендерить таблицю покриття + мутаційного тестування як Markdown.
  * Якщо будь-який рядок містить непустий `survived`, додає секцію
  * `## Вцілілі мутанти` з JSON-блоком для `/n-fix-tests`.
+ * Якщо `allowedGaps` непустий, додає секцію `## Allowed gaps` з таблицею
+ * verdict/confidence/reason для кожного LLM-класифікованого мутанта.
  * Без timestamp, щоб git diff рухався лише при зміні метрик.
  * @param {Array<{area:string, coverage:{lines:{covered:number,total:number},functions:{covered:number,total:number}}, mutation:{caught:number,total:number}, survived?: Array<{file:string,line:number,col:number,mutantType:string,original:string,replacement:string}>}>} rows рядки провайдерів
+ * @param {Array<{file:string, mutant:{line:number,col:number,mutantType:string,original:string,replacement:string}, verdict:{verdict:string,confidence:number,reason:string}}>} [allowedGaps] мутанти виключені класифікатором
  * @returns {string} Markdown з заголовком `# Coverage`
  */
-export function renderMarkdown(rows) {
+export function renderMarkdown(rows, allowedGaps = []) {
   const lines = [
     '# Coverage',
     '',
@@ -115,6 +120,29 @@ export function renderMarkdown(rows) {
     }
   }
 
+  if (allowedGaps.length > 0) {
+    // Group allowed gaps by file
+    const gapsByFile = new Map()
+    for (const gap of allowedGaps) {
+      if (!gapsByFile.has(gap.file)) gapsByFile.set(gap.file, [])
+      gapsByFile.get(gap.file).push(gap)
+    }
+
+    lines.push('', '## Allowed gaps', '')
+    lines.push(`> LLM-класифікатор виключив ${allowedGaps.length} survived мутант(ів) зі знаменника mutation score.`)
+    lines.push('> Категорії: equivalent (поведінково еквівалентний), defensive (impossible state), glue/wrapper (integration test покриває).')
+
+    for (const [file, gaps] of gapsByFile) {
+      lines.push('', `### ${file}`, '', '| Line | Mutant | Verdict | Confidence | Reason |', '| --- | --- | --- | --- | --- |')
+      for (const { mutant, verdict } of gaps) {
+        const sanitizedReason = verdict.reason.replaceAll('|', '\\|').replaceAll('\n', ' ')
+        lines.push(
+          `| ${mutant.line} | \`${mutant.original}\` → \`${mutant.replacement}\` | ${verdict.verdict} | ${verdict.confidence.toFixed(2)} | ${sanitizedReason} |`
+        )
+      }
+    }
+  }
+
   return `${lines.join('\n')}\n`
 }
 
@@ -152,6 +180,22 @@ function buildTotalsRow(rows) {
   return { area: '**Разом**', coverage: totalCoverage, mutation: totalMutation }
 }
 
+/**
+ * Читає `.n-cursor.json#coverage.classifyConfidenceThreshold` (default 1.1 — rollout mode).
+ * @param {string} cwd корінь проєкту
+ * @returns {Promise<number>} threshold у [0, 1.1]
+ */
+async function readClassifyThreshold(cwd) {
+  try {
+    const raw = await readFile(join(cwd, '.n-cursor.json'), 'utf8')
+    const parsed = JSON.parse(raw)
+    const t = parsed?.coverage?.classifyConfidenceThreshold
+    return typeof t === 'number' && Number.isFinite(t) ? t : 1.1
+  } catch {
+    return 1.1
+  }
+}
+
 /**
  * Виконує coverage-pipeline: discovery провайдерів за `.n-cursor.json#rules`,
  * detect+collect для кожного, агрегація, запис COVERAGE.md.
@@ -180,16 +224,31 @@ export async function runCoverageSteps(opts = {}) {
     return 1
   }
 
+  // LLM-класифікація survived мутантів (graceful skip без API key)
+  const allSurvived = rows.flatMap(r => r.survived ?? [])
+  let augmentedRows = rows
+  let allowedGaps = []
+  if (allSurvived.length > 0) {
+    const verdicts = await classify(allSurvived, cwd)
+    if (verdicts.length > 0) {
+      const threshold = await readClassifyThreshold(cwd)
+      const applied = applyVerdicts(rows, verdicts, threshold)
+      augmentedRows = applied.rows
+      allowedGaps = applied.allowedGaps
+    }
+  }
+
   // Підсумок «Разом» має сенс лише коли провайдерів ≥2; для єдиного рядка він
   // дублює його значення, тож не додаємо.
-  if (rows.length > 1) rows.push(buildTotalsRow(rows))
-  const md = renderMarkdown(rows)
+  if (augmentedRows.filter(r => r.area !== '**Разом**').length > 1) {
+    augmentedRows.push(buildTotalsRow(augmentedRows.filter(r => r.area !== '**Разом**')))
+  }
+  const md = renderMarkdown(augmentedRows, allowedGaps)
   // Stryker disable next-line StringLiteral: equivalent – writeFile(path, str, '') behaves identically to 'utf8' in Node/Bun
   await writeFile(join(cwd, 'COVERAGE.md'), md, 'utf8')
   console.log('✓ COVERAGE.md')
 
   if (opts.fix) {
-    const allSurvived = rows.flatMap(r => r.survived ?? [])
     // eslint-disable-next-line no-unsanitized/method -- шлях відносний до пакету, не user-input
     const { fixSurvivedMutants } = await import(new URL('../../../scripts/coverage-fix.mjs', import.meta.url).href)
     await fixSurvivedMutants(allSurvived, cwd)

package/scripts/coverage-classify/apply.mjs

@@ -0,0 +1,67 @@
+/**
+ * Застосовує verdicts до coverage rows: фільтрує survived мутантів,
+ * декрементує mutation.total на кількість allowed-gaps, повертає окремий
+ * список allowedGaps для рендеру в COVERAGE.md.
+ *
+ * Skip rule: verdict ∈ {equivalent,defensive,glue,wrapper} AND confidence ≥ threshold.
+ * Решта (включно з worth-testing і low-confidence skip-verdicts) залишаються в survived.
+ */
+
+const SKIP_VERDICTS = new Set(['equivalent', 'defensive', 'glue', 'wrapper'])
+
+/**
+ * Чи verdict кваліфікує мутанта як allowed-gap (виключити з Killable).
+ * @param {{verdict: string, confidence: number}} verdict verdict-об'єкт
+ * @param {number} threshold confidence threshold (наприклад 0.7)
+ * @returns {boolean} true якщо мутант — allowed gap
+ */
+export function isAllowedGap(verdict, threshold) {
+  return SKIP_VERDICTS.has(verdict.verdict) && verdict.confidence >= threshold
+}
+
+/**
+ * Застосовує verdicts до coverage rows. Фільтрує `survived` за isAllowedGap,
+ * зменшує `mutation.total` на скільки мутантів стало allowed-gap.
+ * Не мутує вхідні дані.
+ * @param {Array<{area: string, coverage: object, mutation: {caught: number, total: number}, survived?: Array<{file: string, mutants: Array<object>, exampleTest?: object|null, recommendationText?: string|null}>}>} rows вхідні рядки
+ * @param {Array<{key: string, verdict: {verdict: string, confidence: number, reason: string}}>} verdicts класифіковані verdict-и
+ * @param {number} threshold confidence threshold для allowed-gap
+ * @returns {{rows: Array<object>, allowedGaps: Array<{file: string, mutant: object, verdict: object}>}} augmented rows + список allowed-gaps
+ */
+export function applyVerdicts(rows, verdicts, threshold) {
+  const verdictByKey = new Map()
+  for (const { key, verdict } of verdicts) verdictByKey.set(key, verdict)
+
+  const allowedGaps = []
+
+  const augmentedRows = rows.map(row => {
+    const survived = row.survived ?? []
+    let skippedCount = 0
+    const remainingSurvived = []
+
+    for (const group of survived) {
+      const remainingMutants = []
+      for (const mutant of group.mutants) {
+        const key = `${group.file}:${mutant.line}:${mutant.col}:${mutant.replacement}`
+        const verdict = verdictByKey.get(key)
+        if (verdict && isAllowedGap(verdict, threshold)) {
+          allowedGaps.push({ file: group.file, mutant, verdict })
+          skippedCount += 1
+        } else {
+          remainingMutants.push(mutant)
+        }
+      }
+      if (remainingMutants.length > 0) {
+        remainingSurvived.push({ ...group, mutants: remainingMutants })
+      }
+    }
+
+    return {
+      ...row,
+      survived: remainingSurvived,
+      mutation: { ...row.mutation, total: row.mutation.total - skippedCount }
+    }
+  })
+
+  return { rows: augmentedRows, allowedGaps }
+}

package/scripts/coverage-classify/cache.mjs

@@ -0,0 +1,77 @@
+/**
+ * File-hash-keyed cache для coverage-classify verdicts.
+ *
+ * Cache key = `<blob-hash>:<line>:<col>:<base64url(replacement)>`.
+ * Blob hash рахуємо через `git hash-object <file>` (детерміновано на working tree)
+ * з fallback на sha1(readFile) якщо git недоступний.
+ *
+ * Cache schema:
+ *   { version: 1, model: string|null, entries: Record<key, { verdict, confidence, reason, suggestedTest?, classifiedAt }> }
+ *
+ * Інвалідація: будь-яка зміна source → новий blob-hash → cache miss → re-classify.
+ */
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+const CACHE_VERSION = 1
+
+/**
+ * Хеш контенту файла (sha1, 40 hex chars). Спочатку `git hash-object`,
+ * інакше sha1 контенту.
+ * @param {string} filePath абсолютний шлях до файла
+ * @returns {string | null} 40-char hex hash або null якщо файл недоступний
+ */
+export function deriveBlobHash(filePath) {
+  if (!existsSync(filePath)) return null
+  try {
+    return execFileSync('git', ['hash-object', filePath], { encoding: 'utf8' }).trim()
+  } catch {
+    const content = readFileSync(filePath)
+    return createHash('sha1').update(content).digest('hex')
+  }
+}
+
+/**
+ * Cache-ключ для конкретного мутанта в конкретному стані файла.
+ * @param {string} filePath абсолютний шлях до source файла
+ * @param {{line: number, col: number, replacement: string}} mutant параметри мутанта
+ * @returns {string | null} ключ або null якщо файл недоступний
+ */
+export function deriveCacheKey(filePath, mutant) {
+  const blobHash = deriveBlobHash(filePath)
+  if (!blobHash) return null
+  const replacement = Buffer.from(mutant.replacement, 'utf8').toString('base64url')
+  return `${blobHash}:${mutant.line}:${mutant.col}:${replacement}`
+}
+
+/**
+ * Читає cache з диска. При будь-якій проблемі (file absent, corrupt JSON,
+ * schema/version mismatch, entries не object) — повертає empty cache.
+ * @param {string} cachePath абсолютний шлях до cache.json
+ * @returns {{version: number, model: string|null, entries: Record<string, object>}} cache
+ */
+export function readCache(cachePath) {
+  const empty = { version: CACHE_VERSION, model: null, entries: {} }
+  if (!existsSync(cachePath)) return empty
+  try {
+    const data = JSON.parse(readFileSync(cachePath, 'utf8'))
+    if (data?.version !== CACHE_VERSION) return empty
+    if (!data.entries || typeof data.entries !== 'object' || Array.isArray(data.entries)) return empty
+    return data
+  } catch {
+    return empty
+  }
+}
+
+/**
+ * Записує cache на диск. Створює батьківські директорії.
+ * @param {string} cachePath абсолютний шлях
+ * @param {{version: number, model: string|null, entries: Record<string, object>}} cache cache-об'єкт
+ * @returns {void}
+ */
+export function writeCache(cachePath, cache) {
+  mkdirSync(dirname(cachePath), { recursive: true })
+  writeFileSync(cachePath, `${JSON.stringify(cache, null, 2)}\n`, 'utf8')
+}

package/scripts/coverage-classify/index.mjs

@@ -0,0 +1,129 @@
+/**
+ * Public API класифікатора: classify(survived, cwd, opts) → verdicts[]
+ *
+ * Orchestration:
+ *   1. Перевірка ANTHROPIC_API_KEY + dynamic import SDK (graceful skip).
+ *   2. Для кожного мутанта: cache lookup → класифікація → cache write.
+ *   3. На неуспішну класифікацію після retries — conservative fallback worth-testing/confidence=0.
+ *
+ * Prompt caching: system-prompt передається з cache_control: ephemeral —
+ * усі мутанти одного прогону reuse кешований префікс на стороні API.
+ */
+import { join } from 'node:path'
+import { env } from 'node:process'
+import { setTimeout } from 'node:timers/promises'
+
+import { deriveCacheKey, readCache, writeCache } from './cache.mjs'
+import { buildUserPrompt, SYSTEM_PROMPT } from './prompt.mjs'
+import { parseVerdict } from './verdict-schema.mjs'
+
+const MODEL = 'claude-sonnet-4-6'
+const MAX_RETRIES = 2
+const DEFAULT_RETRY_DELAY_MS = 1000
+
+const FALLBACK_VERDICT = {
+  verdict: 'worth-testing',
+  confidence: 0,
+  reason: 'LLM-classification unavailable, conservative fallback (treat as worth-testing)'
+}
+
+/**
+ * Класифікує survived мутантів через Claude API.
+ * Без API key / без SDK / при критичних помилках — повертає [] (graceful skip).
+ * @param {Array<{file: string, mutants: Array<object>, exampleTest?: object|null, recommendationText?: string|null}>} survived список survived груп (як у COVERAGE.md)
+ * @param {string} cwd корінь проєкту
+ * @param {{cachePath?: string, client?: object, retryDelayMs?: number}} [opts] ін'єкції для тестів
+ * @returns {Promise<Array<{key: string, verdict: object}>>} verdicts
+ */
+export async function classify(survived, cwd, opts = {}) {
+  const cachePath = opts.cachePath ?? join(cwd, 'npm/reports/coverage-classify.cache.json')
+  const retryDelayMs = opts.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS
+
+  if (!env.ANTHROPIC_API_KEY) {
+    console.warn('⚠ coverage classify: ANTHROPIC_API_KEY not set, classification skipped')
+    return []
+  }
+
+  let SDK
+  try {
+    SDK = await import('@anthropic-ai/sdk')
+  } catch {
+    console.warn('⚠ coverage classify: @anthropic-ai/sdk not installed, classification skipped')
+    return []
+  }
+  const Anthropic = SDK.default
+  const client = opts.client ?? new Anthropic()
+
+  const cache = readCache(cachePath)
+  if (cache.model !== MODEL) {
+    cache.entries = {}
+    cache.model = MODEL
+  }
+
+  const verdicts = []
+  for (const group of survived) {
+    for (const mutant of group.mutants) {
+      const lookupKey = `${group.file}:${mutant.line}:${mutant.col}:${mutant.replacement}`
+      const cacheKey = deriveCacheKey(join(cwd, group.file), mutant)
+
+      let verdict = null
+      if (cacheKey && cache.entries[cacheKey]) {
+        const cached = cache.entries[cacheKey]
+        verdict = {
+          verdict: cached.verdict,
+          confidence: cached.confidence,
+          reason: cached.reason,
+          ...(cached.suggestedTest ? { suggestedTest: cached.suggestedTest } : {})
+        }
+      }
+      if (!verdict) {
+        verdict = await classifyOne(client, group, mutant, cwd, retryDelayMs)
+        if (cacheKey) {
+          cache.entries[cacheKey] = { ...verdict, classifiedAt: new Date().toISOString() }
+        }
+      }
+
+      verdicts.push({ key: lookupKey, verdict })
+    }
+  }
+
+  writeCache(cachePath, cache)
+  return verdicts
+}
+
+/**
+ * Один виклик API з retry. На фейл після MAX_RETRIES — повертає FALLBACK_VERDICT.
+ * @param {{messages: {create: Function}}} client SDK client
+ * @param {{file: string}} group group для контексту
+ * @param {object} mutant mutant data
+ * @param {string} cwd корінь
+ * @param {number} retryDelayMs base delay для exp-backoff (0 у тестах)
+ * @returns {Promise<object>} verdict (parsed або fallback)
+ */
+async function classifyOne(client, group, mutant, cwd, retryDelayMs) {
+  const userPrompt = buildUserPrompt({ ...mutant, file: group.file }, cwd)
+  let lastError = null
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    try {
+      const response = await client.messages.create({
+        model: MODEL,
+        max_tokens: 1024,
+        system: [{ type: 'text', text: SYSTEM_PROMPT, cache_control: { type: 'ephemeral' } }],
+        messages: [{ role: 'user', content: userPrompt }]
+      })
+      const text = response?.content?.[0]?.text ?? ''
+      return parseVerdict(text)
+    } catch (err) {
+      lastError = err
+      if (attempt < MAX_RETRIES && retryDelayMs > 0) {
+        await setTimeout(retryDelayMs * Math.pow(2, attempt))
+      }
+    }
+  }
+
+  console.warn(
+    `⚠ coverage classify: ${group.file}:${mutant.line}:${mutant.col} failed after ${MAX_RETRIES + 1} attempts: ${lastError?.message ?? 'unknown'}`
+  )
+  return { ...FALLBACK_VERDICT }
+}

package/scripts/coverage-classify/prompt.mjs

@@ -0,0 +1,126 @@
+/**
+ * Промпт-builder для coverage-classify.
+ * SYSTEM_PROMPT — статичний, кешується через cache_control: ephemeral у API call.
+ * buildUserPrompt — асемблює per-mutant контекст (location, source ±10, tests, git).
+ */
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+
+const CONTEXT_LINES = 10
+const TEST_FILE_MAX_LINES = 2000
+
+export const SYSTEM_PROMPT = `You are a mutation testing classifier.
+
+For each survived Stryker mutant, classify it into exactly one verdict:
+
+- **worth-testing**: pure logic with real branches that should be tested. The mutant
+  exposes a missing assertion in a unit test. Recommend a test approach.
+- **equivalent**: the mutated code is behaviorally indistinguishable from the original
+  (e.g., both branches produce the same observable output, or the mutant lies on dead
+  code). You MUST cite a concrete reason referencing input flow or output equivalence.
+- **defensive**: the branch guards against an impossible state given input contracts
+  or type system. You MUST identify the invariant that makes the state unreachable.
+- **glue**: thin CLI entrypoint, factory, or boilerplate (e.g., runStandardRule
+  wrapper, fix.mjs stubs). Integration tests via subprocess cover the behavior.
+  Name the integration test or pattern.
+- **wrapper**: thin shell around an external tool (spawnSync, fetch, dynamic import).
+  The wrapper has no logic worth unit-testing in isolation; behavior comes from the
+  wrapped tool. Name the integration test or pattern.
+
+Output ONLY a single JSON object matching this schema:
+
+\`\`\`
+{
+  "verdict": "worth-testing" | "equivalent" | "defensive" | "glue" | "wrapper",
+  "confidence": number 0-1,
+  "reason": string (20-500 chars; concrete code-level reference, not "seems like"),
+  "suggestedTest": string (max 300 chars; required only when verdict is worth-testing)
+}
+\`\`\`
+
+Confidence guidance:
+- 0.9+: cite specific code fragment, identifier, or input contract proving the verdict.
+- 0.7-0.9: strong inference from visible code structure.
+- <0.7: ambiguity, lacking context, or unfamiliar pattern. Be honest.
+
+Never invent integration test names. If you cannot identify a covering test, use
+worth-testing with low confidence instead of glue/wrapper.
+`
+
+/**
+ * Витягує describe/test/it title з рядка тексту.
+ * @param {string} content повний текст test-файла
+ * @returns {string} список "describe: <title>" / "test: <title>" або порожній
+ */
+function extractTestTitles(content) {
+  const titles = []
+  for (const match of content.matchAll(/^\s*(describe|test|it)\(['"`](.+?)['"`]/gmu)) {
+    titles.push(`${match[1]}: ${match[2]}`)
+  }
+  return titles.join('\n') || '(no describe/test blocks found)'
+}
+
+/**
+ * Будує користувацький промпт для класифікації одного мутанта.
+ * @param {{file: string, line: number, col: number, mutantType: string, original: string, replacement: string}} mutant параметри мутанта (file — відносний до cwd)
+ * @param {string} cwd корінь проєкту
+ * @returns {string} user prompt
+ */
+export function buildUserPrompt(mutant, cwd) {
+  const absPath = join(cwd, mutant.file)
+
+  // Source context
+  let srcContext = '(source file unavailable)'
+  if (existsSync(absPath)) {
+    const lines = readFileSync(absPath, 'utf8').split('\n')
+    const start = Math.max(0, mutant.line - 1 - CONTEXT_LINES)
+    const end = Math.min(lines.length, mutant.line + CONTEXT_LINES)
+    srcContext = lines
+      .slice(start, end)
+      .map((l, i) => `${start + i + 1}: ${l}`)
+      .join('\n')
+  }
+
+  // Existing tests
+  const testPath = join(dirname(absPath), 'tests', `${basename(absPath, '.mjs')}.test.mjs`)
+  let existingTests = '(no test file)'
+  if (existsSync(testPath)) {
+    const content = readFileSync(testPath, 'utf8')
+    if (content.split('\n').length > TEST_FILE_MAX_LINES) {
+      existingTests = extractTestTitles(content)
+    } else {
+      existingTests = content
+    }
+  }
+
+  // Recent git activity (graceful если нет git або untracked)
+  let recentActivity = '(no git history)'
+  try {
+    const out = execFileSync('git', ['log', '-1', '--format=%ar', '--', absPath], {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim()
+    if (out) recentActivity = out
+  } catch {
+    // git unavailable or file untracked — keep placeholder
+  }
+
+  return `# Mutant
+File: ${mutant.file}
+Line: ${mutant.line}:${mutant.col}
+Type: ${mutant.mutantType}
+Original code: \`${mutant.original}\`
+Mutated to: \`${mutant.replacement}\`
+
+# Source context (±${CONTEXT_LINES} lines)
+${srcContext}
+
+# Existing tests
+${existingTests}
+
+# Recent activity
+File last modified: ${recentActivity}
+`
+}

package/scripts/coverage-classify/verdict-schema.mjs

@@ -0,0 +1,35 @@
+/**
+ * Zod-схема для verdict-відповіді LLM-класифікатора (coverage-classify).
+ * parseVerdict — витяг JSON з raw-text LLM-відповіді + validate.
+ *
+ * Категорії:
+ *   - worth-testing: pure logic, real branches — пиши тест
+ *   - equivalent:    мутант поведінково еквівалентний (не killable)
+ *   - defensive:     гілка для impossible state (не killable)
+ *   - glue:          CLI entry / runStandardRule wrapper (integration covers)
+ *   - wrapper:       тонкий spawn/fetch wrapper (integration covers)
+ */
+import { z } from 'zod'
+
+export const VerdictSchema = z.object({
+  verdict: z.enum(['worth-testing', 'equivalent', 'defensive', 'glue', 'wrapper']),
+  confidence: z.number().min(0).max(1),
+  reason: z.string().min(20).max(500),
+  suggestedTest: z.string().max(300).optional()
+})
+
+/**
+ * Витягує JSON-об'єкт з raw-text LLM-відповіді і валідує через VerdictSchema.
+ * @param {string} rawText raw-text відповідь LLM
+ * @returns {{verdict: string, confidence: number, reason: string, suggestedTest?: string}} verdict
+ * @throws якщо JSON не знайдено, не парситься, або не відповідає схемі
+ */
+export function parseVerdict(rawText) {
+  const jsonStart = rawText.indexOf('{')
+  const jsonEnd = rawText.lastIndexOf('}')
+  if (jsonStart < 0 || jsonEnd < 0) {
+    throw new Error('No JSON object found in LLM response')
+  }
+  const json = JSON.parse(rawText.slice(jsonStart, jsonEnd + 1))
+  return VerdictSchema.parse(json)
+}