@nitra/cursor 12.0.3 → 12.2.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [12.2.0] - 2026-06-19
+
+### Changed
+
+- lint fail-fast лише для --read-only: у fix-режимі per-file правило з ненульовим кодом не спиняє — прогін доходить до кроку виправлення (конформність-драбина). + applyChanges створює батьківську теку (mkdirSync) перед записом. + детермінований T0-патерн changelog-create-change-file (writeChange замість LLM)
+
+## [12.1.0] - 2026-06-19
+
+### Added
+
+- fix-конформність: драбина ескалації моделей (local-min → local-min+feedback → cloud-min → cloud-avg) із per-рунговим escalation-логом (.n-cursor/fix-escalation.jsonl, поле diagnosis) і кепом --max-avg; прибрано --max-iter/MODEL_HEAVY
+- analyze-escalation: аналіз escalation-логу хмарною avg-моделлю (чанкінг + map-reduce) → markdown-звіт із пропозиціями нових T0-патернів / правок .mdc / змін скриптів; CLI n-cursor analyze-escalation і авто-хук наприкінці lint --full (kill-switch N_CURSOR_FIX_ANALYZE)
+
 ## [12.0.3] - 2026-06-18
 
 ### Fixed

package/bin/n-cursor.js

@@ -1599,6 +1599,15 @@ try {
 
       break
     }
+    case 'analyze-escalation': {
+      // n-cursor analyze-escalation — читає весь escalation-лог (.n-cursor/fix-escalation.jsonl),
+      // чанкує й просить хмарну avg-модель запропонувати, як зменшити LLM-залежність fix-
+      // конформності (нові T0-патерни / правки .mdc / зміни скриптів). Звіт → markdown.
+      const { runEscalationAnalysisCli } = await import('../scripts/lib/fix/analyze-escalation.mjs')
+      process.exitCode = await runEscalationAnalysisCli(args)
+
+      break
+    }
     case 'taze': {
       // n-cursor taze diff — read-only semver-diff package.json ↔ package.json.taze-bak
       // (root + воркспейси) для скілу n-taze: скрипт класифікує major-оновлення,
@@ -1697,7 +1706,7 @@ try {
     default: {
       console.error(`❌ Невідома команда: ${command}`)
       console.error(
-        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, post-tool-use-fix, adr-normalize-local, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, lint-doc-files, fix-doc-files, coverage, coverage-fix, taze, start-check, change, release, skill, trace, doc-aggregate`
+        `   Очікується: (без аргументів) синхронізація правил, rename-yaml-extensions, post-tool-use-fix, adr-normalize-local, lint, lint-ga, lint-rego, lint-k8s, lint-docker, lint-text, lint-doc-files, fix-doc-files, coverage, coverage-fix, analyze-escalation, taze, start-check, change, release, skill, trace, doc-aggregate`
       )
       process.exitCode = 1
     }

package/package.json

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

package/rules/lint/js/docs/orchestrate.md

@@ -3,7 +3,7 @@ type: JS Module
 title: orchestrate.mjs
 resource: npm/rules/lint/js/orchestrate.mjs
 docgen:
-  crc: aed5ffe7
+  crc: f4eb439d
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
 ---
@@ -14,7 +14,9 @@ docgen:
 
 Поведінка
 selectLintRules вибирає і сортує ідентифікатори правил на основі їхнього обсягу дії (`per-file` або `full`) та прапорця `--full`.
-runLint запускає оркестрацію лінтування: або виконує перевірку конформності для заданих правил, або ітерує по алфавітно відсортованих правилах, запускаючи лінтер для змінених файлів (за замовчуванням), або виконує перевірку конформності всього репозиторію при використанні прапорця `--full`.
+runLint запускає оркестрацію лінтування: або виконує перевірку конформності для заданих правил, або ітерує по алфавітно відсортованих правилах (`runPerFileRules`), запускаючи лінтер для змінених файлів (за замовчуванням), або виконує перевірку конформності всього репозиторію при використанні прапорця `--full`.
+**Fail-fast — лише в `--read-only`** (CI/детект): перший ненульовий код спиняє. У fix-режимі (default) ненульовий код per-file правила НЕ спиняє — проганяються всі правила й виконується крок виправлення (конформність-драбина), а повертається найгірший код.
+У режимі `--full` без `--read-only` після конформність-фази (`runFullConformancePhase`) викликається escalation-аналітика (`analyze-escalation.mjs`): фіксує зсув escalation-логу до фази, після — аналізує записи саме цього прогону. Аналіз не впливає на exit-код lint.
 
 ## Публічний API
 

package/rules/lint/js/orchestrate.mjs

@@ -9,7 +9,9 @@
  * викликає `rules/<id>/js/lint.mjs` → `lint(files, cwd, { readOnly })`:
  *  - default scope: `files` = змінені відносно origin (`collectChangedFilesSince`);
  *  - `--full`:      `files = undefined` — весь проєкт.
- * Порядок правил — алфавітний. Fail-fast: перший ненульовий код спиняє.
+ * Порядок правил — алфавітний. Fail-fast **лише в `--read-only`** (CI/детект): перший
+ * ненульовий код спиняє. У fix-режимі (default) ненульовий код НЕ спиняє — проганяємо всі
+ * правила й доходимо до кроку виправлення (конформність-драбина), повертаючи найгірший код.
  */
 import { existsSync, readdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
@@ -80,6 +82,53 @@ function readAllMeta(rulesDir) {
   return out
 }
 
+/**
+ * Per-file фаза: проганяє лінтер кожного правила. Fail-fast лише в read-only.
+ * @param {string[]} ids id правил (алфавітно)
+ * @param {{ rulesDir: string, changed: string[]|undefined, cwd: string, readOnly: boolean, metaById: Record<string, {llmFix?: boolean}>, log: (s: string) => void }} ctx контекст
+ * @returns {Promise<{ stop: boolean, code: number }>} `stop` — read-only fail-fast; `code` — найгірший код
+ */
+async function runPerFileRules(ids, ctx) {
+  const { rulesDir, changed, cwd, readOnly, metaById, log } = ctx
+  let worst = 0
+  for (const id of ids) {
+    const lintPath = join(rulesDir, id, 'js', 'lint.mjs')
+    if (!existsSync(lintPath)) {
+      log(`⚠️  lint: правило ${id} має lint-фазу, але немає js/lint.mjs — пропускаю.\n`)
+      continue
+    }
+    // lintPath = join(rulesDir, id, …) — суто package-internal (rulesDir пакета + id зі
+    // selectLintRules за власним meta), не зовнішній вхід → ін'єкції немає.
+    // eslint-disable-next-line no-unsanitized/method
+    const mod = await import(lintPath)
+    // `llmFix` (opt-in opportunistic LLM-fix, спека 2026-06-15): лише правила з
+    // `meta.json: llmFix:true` отримують fix-сходинку; решта — detect-only.
+    const llmFix = metaById[id]?.llmFix === true
+    const code = await mod.lint(changed, cwd, { readOnly, llmFix })
+    if (code !== 0) {
+      if (readOnly) return { stop: true, code } // read-only — fail-fast (детект для CI)
+      worst = code // fix-режим — фіксуємо, але йдемо далі до кроку виправлення
+    }
+  }
+  return { stop: false, code: worst }
+}
+
+/**
+ * Конформність-фаза `--full` (поглинула `fix`): escalation-аналітику обрамляє зсувом логу
+ * (записи саме цього прогону), у fix-режимі по конформності викликає аналіз.
+ * @param {string} cwd корінь
+ * @param {boolean} readOnly лише детект
+ * @param {(s: string) => void} log логер
+ * @returns {Promise<number>} код конформності
+ */
+async function runFullConformancePhase(cwd, readOnly, log) {
+  const { escalationLogSize, maybeAnalyzeEscalation } = await import('../../../scripts/lib/fix/analyze-escalation.mjs')
+  const escOffset = readOnly ? 0 : escalationLogSize()
+  const conformanceCode = await runConformance(cwd, readOnly, log)
+  if (!readOnly) maybeAnalyzeEscalation(cwd, escOffset, log)
+  return conformanceCode
+}
+
 /**
  * Запускає lint-оркестрацію.
  * @param {{ full?: boolean, readOnly?: boolean, rules?: string[], cwd?: string, rulesDir?: string, log?: (s: string) => void }} [opts] параметри
@@ -110,29 +159,18 @@ export async function runLint(opts = {}) {
 
   const metaById = readAllMeta(rulesDir)
   const ids = selectLintRules(metaById, full)
-  for (const id of ids) {
-    const lintPath = join(rulesDir, id, 'js', 'lint.mjs')
-    if (!existsSync(lintPath)) {
-      log(`⚠️  lint: правило ${id} має lint-фазу, але немає js/lint.mjs — пропускаю.\n`)
-      continue
-    }
-    // lintPath = join(rulesDir, id, …) — суто package-internal (rulesDir пакета + id зі
-    // selectLintRules за власним meta), не зовнішній вхід → ін'єкції немає.
-    // eslint-disable-next-line no-unsanitized/method
-    const mod = await import(lintPath)
-    // `llmFix` (opt-in opportunistic LLM-fix, спека 2026-06-15): лише правила з
-    // `meta.json: llmFix:true` отримують fix-сходинку; решта — detect-only. Це й
-    // забезпечує safety-тріаж (логічні лінтери не вмикають LLM-fix випадково).
-    const llmFix = metaById[id]?.llmFix === true
-    const code = await mod.lint(changed, cwd, { readOnly, llmFix })
-    if (code !== 0) return code
-  }
+  const perFile = await runPerFileRules(ids, { rulesDir, changed, cwd, readOnly, metaById, log })
+  if (perFile.stop) return perFile.code
+  let worst = perFile.code
 
-  // Конформність-фаза (поглинула `fix`): whole-repo, лише у `--full`. Кастомний rulesDir
-  // (юніт-тести селектора) — реальний пакет недоступний, тож пропускаємо.
+  // Конформність-фаза: whole-repo, лише у `--full`. Кастомний rulesDir (юніт-тести
+  // селектора) — реальний пакет недоступний, тож пропускаємо.
   if (full && opts.rulesDir === undefined) {
-    const conformanceCode = await runConformance(cwd, readOnly, log)
-    if (conformanceCode !== 0) return conformanceCode
+    const conformanceCode = await runFullConformancePhase(cwd, readOnly, log)
+    if (conformanceCode !== 0) {
+      if (readOnly) return conformanceCode
+      worst = conformanceCode
+    }
   }
-  return 0
+  return worst
 }

package/rules/release/docs/release.md

@@ -3,224 +3,26 @@ type: JS Module
 title: release.mjs
 resource: npm/rules/release/release.mjs
 docgen:
-  crc: 9aa2796b
+  crc: 06d3556b
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Модуль `npm/rules/release/release.mjs` — це ядро команди `n-cursor release`. Він агрегує per-workspace change-файли (накопичені у `CHANGES_DIR` кожного воркспейсу) у:
+## Огляд
 
-1. version-bump у маніфесті пакета (`package.json` для npm-пакетів або `pyproject.toml` для Python),
-2. новий розділ у `CHANGELOG.md` відповідного воркспейсу,
-3. git-коміт зі стандартизованим subject `release: <name@version>, ...`,
-4. git-теги у форматі `<name>@<version>` для кожного зрелізованого пакета,
-5. фізичне видалення «спожитих» change-файлів,
-6. `git push --follow-tags`.
+Файл автоматизує процес випуску версій. Він агрегує зміна-файли для всіх робочих просторів у `version-bump` та `CHANGELOG`, комітить зміни, ставить тег `<name>@<version>` та видаляє використані зміна-файли. Цей процес виконується у CI на гілці `main` (n-cursor-release-design, варіант A). Публічні функції, що надає модуль, — `release` та `runReleaseCli`.
 
-Модуль розрахований на запуск у CI на гілці `main` (варіант A з ADR `n-cursor-release-design`). Сам він **нічого не публікує** у реєстри (npm/PyPI) — цим займаються окремі CI-кроки, орієнтовані на створені теги.
+## Поведінка
 
-Підтримуються:
+release агрегує change-файли для всіх робочих просторів, оновлює версії в маніфестах, додає секції до `CHANGELOG.md`, видаляє використані change-файли, створює коміт та анотовані теги для всіх зібраних релізів, а потім намагається пушити їх у апстрім з повторними спробами.
+runReleaseCli виконує процес релізу, викликаючи функцію release, та виводить відповідний статус у консоль.
 
-- monorepo (root має суб-воркспейси) — root-пакет автоматично пропускається, релізиться лише кожен суб-воркспейс окремо;
-- single-package репо (`workspaces === ['.']`) — релізиться сам root.
+## Публічний API
 
-Якщо явних change-файлів у воркспейсі немає, але в історії з останнього тегу `<name>@<version>` є коміти, модуль робить **fallback-синтез** запису з commit log (через `synthesizeChangeFromCommits`).
+release — агрегує change-файли для кожного робочого простору у version-bump та CHANGELOG, комітить зміни, ставить тег `<name>@<version>` та видаляє використані change-файли.
+runReleaseCli — виконує команди командного інтерфейсу для запуску процесу випуску.
 
-## Експорти / API
+## Гарантії поведінки
 
-| Символ                        | Тип              | Призначення                                                                                       |
-| ----------------------------- | ---------------- | ------------------------------------------------------------------------------------------------- |
-| `release(opts?)`              | `async function` | Програмний API: виконує повний реліз-цикл і повертає масив зрелізованих пакетів.                  |
-| `runReleaseCli(_args, opts?)` | `async function` | CLI-обгортка: запускає `release`, друкує підсумок у stdout/stderr, повертає exit-код (`0` / `1`). |
-
-Внутрішні (не експортовані) функції-помічники: `writeManifestVersion`, `prependWorkspaceChangelog`, `collectChangeFiles`.
-
-Внутрішні константи: `SEMVER_LINE_RE`, `PY_VERSION_LINE_RE` — regex для in-place заміни рядка `version` у відповідних типах маніфесту.
-
-## Функції
-
-### `writeManifestVersion(cwd, manifest, newVersion)` (внутрішня)
-
-Записує нову version у маніфест пакета, зберігаючи форматування файлу.
-
-- **Сигнатура:** `async (cwd: string, manifest: PackageManifest, newVersion: string) => Promise<void>`
-- **Параметри:**
-  - `cwd` — абсолютний шлях кореня репо (root проекту);
-  - `manifest` — об'єкт маніфесту з типу `PackageManifest`, що містить поля `ws` (відносний шлях до воркспейсу, або `.` для root), `manifestRel` (відносний шлях до файлу маніфесту в межах воркспейсу) і `kind` (`'npm'` чи інший — трактується як Python);
-  - `newVersion` — новий рядок версії (SemVer для npm, PEP 440 / SemVer для Python — не валідується тут).
-- **Повертає:** `Promise<void>` після успішного запису.
-- **Side effects:**
-  - читає файл маніфесту з диска;
-  - перезаписує його зі зміненим рядком версії;
-  - **обирає regex за типом маніфесту**: `SEMVER_LINE_RE` для `'npm'`, `PY_VERSION_LINE_RE` інакше;
-  - **кидає `Error`**, якщо в файлі не знайдено патерн рядка `version` (тобто `text.replace(...)` не змінив текст).
-
-### `prependWorkspaceChangelog(cwd, ws, sectionBlock)` (внутрішня)
-
-Доклеює (prepend) новий блок CHANGELOG до початку `<ws>/CHANGELOG.md`; якщо файл не існує — створює.
-
-- **Сигнатура:** `async (cwd: string, ws: string, sectionBlock: string) => Promise<void>`
-- **Параметри:**
-  - `cwd` — корінь репо;
-  - `ws` — відносний шлях воркспейсу від `cwd` (наприклад, `'npm'`, `'.'`);
-  - `sectionBlock` — готовий markdown-блок нового розділу (формат сформований `aggregateWorkspace`).
-- **Повертає:** `Promise<void>`.
-- **Side effects:** читає (за наявності) і пише `<cwd>/<ws>/CHANGELOG.md`. Логіку конкатенації керує `prependChangelogSection` з `./lib/aggregate.mjs` — модуль `release.mjs` лише викликає її, не дублюючи правил вставки.
-
-### `collectChangeFiles(cwd, manifest, runGit)` (внутрішня)
-
-Збирає всі change-записи для воркспейсу: спочатку явні файли з `CHANGES_DIR`, інакше — fallback-синтез з історії комітів.
-
-- **Сигнатура:** `async (cwd: string, manifest: PackageManifest, runGit: (args: string[]) => Promise<string | null>) => Promise<Array<{ file: string | null, entry: { bump: string, section: string, description: string } }>>`
-- **Параметри:**
-  - `cwd` — корінь репо;
-  - `manifest` — маніфест воркспейсу;
-  - `runGit` — git-раннер; повертає stdout як рядок, або `null`, якщо команда зафейлилася.
-- **Повертає:** масив об'єктів `{ file, entry }`:
-  - `file` — ім'я change-файлу у `CHANGES_DIR` (для подальшого видалення), або `null` для синтезованого запису;
-  - `entry` — нормалізований опис зміни: `{ bump, section, description }` (типи `bump`/`section` визначаються форматом change-файлу і `synthesizeChangeFromCommits`).
-- **Поведінка:**
-  1. Викликає `readChangeFiles(manifest.ws, cwd)`; якщо результат непустий — повертає його (явні мають пріоритет).
-  2. Інакше: якщо у маніфесті немає `name` — повертає `[]` (без імені неможливо знайти попередній тег для fallback).
-  3. Інакше викликає `synthesizeChangeFromCommits(name, ws, { runGit })`; якщо нічого не синтезувалося — `[]`.
-  4. Якщо синтезовано — друкує в stderr попередження `⚠️  <ws>: немає change-файлів — синтезовано запис із комітів (fallback)` і повертає `[{ file: null, entry: synthesized }]`.
-- **Side effects:** виклики git через `runGit` (всередині `synthesizeChangeFromCommits`); `console.warn` при fallback.
-
-### `release(opts?)` (експорт)
-
-Основний програмний вхід — виконує повний реліз-цикл для всіх релевантних воркспейсів.
-
-- **Сигнатура:**
-  ```
-  async (opts?: {
-    cwd?: string,
-    date?: string,
-    runGit?: (args: string[]) => Promise<string | null>,
-  }) => Promise<Array<{ ws: string, name: string | null, newVersion: string }>>
-  ```
-- **Параметри `opts` (усі необов'язкові):**
-  - `cwd` — корінь репо; за замовчуванням `process.cwd()`;
-  - `date` — рядок у форматі `YYYY-MM-DD` для дати релізу в CHANGELOG; за замовчуванням сьогоднішня UTC-дата (`new Date().toISOString().slice(0, 10)`);
-  - `runGit` — інжектований git-раннер; за замовчуванням `defaultRunGit(cwd)` (виконує справжні git-команди у `cwd`).
-- **Повертає:** масив зрелізованих пакетів, кожен — `{ ws, name, newVersion }`. Якщо релізити нічого не було — повертає `[]` (без коміту/тегу/пушу).
-- **Алгоритм:**
-  1. Отримує список воркспейсів через `getMonorepoProjectRootDirs(cwd)`.
-  2. Визначає, чи це monorepo: `subWorkspaces = workspaces.filter(w => w !== '.')`, `isMonorepoRoot = subWorkspaces.length > 0`.
-  3. Для кожного `ws`:
-     - якщо `ws === '.'` і `isMonorepoRoot` — пропустити (root у monorepo не релізиться сам по собі);
-     - читає маніфест через `readPackageManifest(ws, cwd)`; якщо манfest відсутній або без `version` — пропустити;
-     - збирає change-записи через `collectChangeFiles`;
-     - викликає `aggregateWorkspace({ currentVersion, changeFiles, date })` — якщо повертає `null` (нема чого релізити, всі записи відфільтровано) — пропустити;
-     - інакше: записує нову версію у маніфест (`writeManifestVersion`), prepend новий розділ у `CHANGELOG.md` (`prependWorkspaceChangelog`), видаляє кожен спожитий change-файл (`rm` у `<cwd>/<ws>/<CHANGES_DIR>/<file>`), додає запис у `released`, а якщо є `manifest.name` — формує тег `<name>@<newVersion>`.
-  4. Якщо `released.length > 0`:
-     - формує subject коміту: список тегів через `, `, або (якщо тегів нема — наприклад, у пакетів без `name`) — `<ws>@<newVersion>`-значення;
-     - `git add -A`;
-     - `git commit -m "release: <subject>"` — якщо `runGit` повертає `null` (коміт не вдався), кидає `Error('release: git commit не вдався — теги та push скасовано')`;
-     - для кожного тегу — `git tag <tag>`;
-     - `git push --follow-tags`.
-- **Side effects:**
-  - читання/запис файлів маніфестів і `CHANGELOG.md`;
-  - видалення change-файлів з диска (`rm`);
-  - виконання git-команд через `runGit` (включно з push до remote);
-  - `console.warn` при fallback (через `collectChangeFiles`).
-- **Помилки:** кидаються через `throw new Error(...)` у двох місцях:
-  - не знайдено патерн `version` у маніфесті (`writeManifestVersion`);
-  - не вдався `git commit` (`runGit` повернув `null`).
-
-### `runReleaseCli(_args, opts?)` (експорт)
-
-CLI-фасад: викликає `release(opts)`, друкує підсумок, мапить помилки на exit-код.
-
-- **Сигнатура:** `async (_args: string[], opts?: { cwd?: string, date?: string, runGit?: ... }) => Promise<number>`
-- **Параметри:**
-  - `_args` — позиційні CLI-аргументи (поточна імплементація опцій з CLI не приймає, тому ігнорується; параметр підкреслений `_` для лінту);
-  - `opts` — ті самі опції, що в `release` (використовується тестами для інжекції `cwd`/`date`/`runGit`).
-- **Повертає:** `Promise<number>` — exit-код:
-  - `0` — успіх (включно з випадком «немає що релізити»);
-  - `1` — будь-яка помилка з `release`.
-- **Поведінка:**
-  - якщо `released.length === 0` — друкує `release: немає змін для релізу`;
-  - інакше для кожного запису — `console.log` рядок `✅ <name або ws>@<newVersion>`;
-  - при exception — `console.error("❌ <message>")` і повертає `1`. Підтримує і `Error` (бере `.message`), і не-`Error`-значення (приводить через `String(...)`).
-
-## Залежності
-
-### Стандартна бібліотека Node.js
-
-- `node:fs` — `existsSync` (для перевірки існування `CHANGELOG.md`);
-- `node:fs/promises` — `readFile`, `writeFile`, `rm`;
-- `node:path` — `join`.
-
-### Внутрішні модулі проекту
-
-- `../changelog/lib/package-manifest.mjs`:
-  - `getMonorepoProjectRootDirs(cwd)` — повертає список воркспейсів (включно з `.`);
-  - `readPackageManifest(ws, cwd)` — читає маніфест воркспейсу;
-  - тип `PackageManifest` (через JSDoc-імпорт).
-- `./lib/aggregate.mjs`:
-  - `aggregateWorkspace({ currentVersion, changeFiles, date })` — обчислює `newVersion` і `sectionBlock` CHANGELOG за зібраними change-записами; повертає `null`, якщо немає змін до релізу;
-  - `prependChangelogSection(existing, sectionBlock)` — формує новий вміст `CHANGELOG.md` зі вставкою блоку на початок.
-- `./lib/change-file.mjs`:
-  - константа `CHANGES_DIR` — назва теки з change-файлами всередині воркспейсу;
-  - `readChangeFiles(ws, cwd)` — читає всі change-файли воркспейсу.
-- `./lib/fallback.mjs`:
-  - `defaultRunGit(cwd)` — фабрика git-раннера з прив'язкою до `cwd`;
-  - `synthesizeChangeFromCommits(name, ws, { runGit })` — синтезує change-запис із commit-історії з останнього тегу `<name>@*`.
-
-### Зовнішні залежності
-
-Жодних npm-пакетів — лише вбудовані модулі Node.js та внутрішні модулі проекту.
-
-## Потік виконання / Використання
-
-### CLI-використання (через диспатчер `n-cursor`)
-
-`runReleaseCli` під'єднується до точки входу `n-cursor release`. Зазвичай викликається в CI на `main` після злиття PR:
-
-```bash
-n-cursor release
-```
-
-Exit-код `0` — навіть якщо нічого не зрелізовано (в стандартний випадок «нічого не змінилось»). Exit-код `1` — фейл (помилка запису маніфесту, фейл `git commit`, тощо).
-
-### Програмне використання (у тестах / інших скриптах)
-
-```js
-import { release, runReleaseCli } from './release.mjs'
-
-// 1) Прямий виклик
-const released = await release({
-  cwd: '/abs/path/to/repo',
-  date: '2026-06-03',
-  runGit: async args => '...stdout...' // або null при помилці
-})
-
-// 2) Через CLI-фасад
-const code = await runReleaseCli([], { cwd, date, runGit })
-process.exit(code)
-```
-
-### Послідовність кроків у `release()`
-
-1. **Дискавер воркспейсів** — `getMonorepoProjectRootDirs(cwd)`.
-2. **Класифікація** — root пропускається у monorepo (де є суб-воркспейси).
-3. **Для кожного воркспейсу:**
-   - читання маніфесту;
-   - збір change-файлів (явні → fallback-синтез з комітів);
-   - агрегація → `newVersion` + `sectionBlock`;
-   - запис маніфесту;
-   - prepend CHANGELOG;
-   - видалення «спожитих» change-файлів;
-   - реєстрація запису і (за наявності `name`) тегу.
-4. **Якщо є зрелізоване хоча б одне:**
-   - формування subject коміту;
-   - `git add -A` → `git commit -m "release: <subject>"`;
-   - перевірка успішності коміту (інакше throw);
-   - проставляння всіх тегів;
-   - `git push --follow-tags`.
-5. **Повернення масиву** зрелізованих пакетів.
-
-### Інваріанти
-
-- Жодних версій/тегів/коміту, якщо немає реальних змін у жодному воркспейсі — масив `released` залишається порожнім, і блок git взагалі не виконується.
-- Якщо хоча б у одному воркспейсі не вдалось оновити маніфест — функція кидає виняток до `git add -A`; часткові зміни на диску можуть залишитися (виклик не транзакційний — це відповідальність CI/runner-а відкотити робоче дерево).
-- Якщо `git commit` зафейлився — теги не проставляються і push не виконується; кидається явна помилка.
-- Усі git-операції проходять через інжектований `runGit`, що дає змогу тестувати функцію без реальних git-викликів.
+- (специфічних машинно-виведених гарантій немає)

package/rules/tool-surface/docs/fix.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: fix.mjs
+resource: npm/rules/tool-surface/fix.mjs
+docgen:
+  crc: 38cf876b
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.93
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей файл запускає логіку перевірки відповідності політики через функцію `run`, використовуючи контекст прогону, який містить дані, кешовані у межах цього прогону. При самостійному запуску скрипт ініціює повний цикл: завантажує конфігурацію, перевіряє білий список та формує підсумок. Результат виконання визначається кодом виходу, що сигналізує про успішне виконання або виявлені порушення.
+
+## Поведінка
+
+1. Викликається функція `run` для запуску правила.
+2. Правило виконується, використовуючи контекст прогону, що може містити кеш.
+3. Якщо скрипт виконується як окрема програма (standalone), запускається оркестрація правила.
+4. Оркестрація виконує завантаження конфігурації, перевірку білого списку та підсумок.
+5. Код завершує роботу з кодом виходу, який вказує на успіх або наявність порушень.
+
+## Публічний API
+
+run — виконує послідовність перевірок: застосовує правила, аналізує JS-занепокоєння, перевіряє політику та посилання MDC.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Кешує результати в межах одного прогону.

package/rules/tool-surface/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/tool-surface
+resource: npm/rules/tool-surface/
+---
+
+# npm/rules/tool-surface
+
+| Файл | Тип |
+|---|---|
+| [fix.mjs](fix.md) | JS Module |

package/scripts/lib/adr/docs/normalize-pipeline.md

@@ -3,36 +3,45 @@ type: JS Module
 title: normalize-pipeline.mjs
 resource: npm/scripts/lib/adr/normalize-pipeline.mjs
 docgen:
-  crc: 6eb6ba69
+  crc: 9f2d42d3
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
+  issues: judge:inaccurate:0.99
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Файл реалізує локально-орієнтований конвеєр для нормалізації чернеток ADR. Він використовує LLM лише для вузьких, верифікованих бінарних суджень. Конвеєр працює у послідовних стадіях: JS виконує пошук кандидатів-ребер на основі лексичної схожості, LLM оцінює ці ребра (Stage 1: `same/different`) та драфти (Stage 1b: `standalone/trivial`), JS кластеризує підтверджені ребра (використовуючи `union-find`), LLM реформатує анотера (Stage 2: `gen-MADR`), а LLM генерує доповнення для злиття (Stage 3: `gen-merge`). Глобальний стан (кластери, слаги, покриття) зберігається в JS. Конвеєр повертає операції у форматі `operations[]`, сумісного з контрактом `apply-ops`.
+## Огляд
+
+Файл реалізує локально-орієнтований конвеєр для нормалізації чернеток архітектурних рішень (ADR). Він працює за принципом інверсії керування: JavaScript оркеструє процес, а LLM відповідає лише на вузькі, верифіковані запитання, будучи заточеним під малу локальну модель (omlx/gemma-4b). LLM використовується лише для бінарного судження схожості між записами (наприклад, через `edge-judge`) та витягування змісту секцій у JSON (через `gen-MADR`). Конвеєр збирає, валідує та складає повний MADR-каркас, використовуючи кластеризацію (`cluster` та `union-find`) та проходить через `validation gate`, повертаючи результат у вигляді операцій для застосування.
 
 ## Поведінка
 
-tokenize токенізує назву або слаг у множину значущих токенів, виключаючи стоп-слова.
-jaccard обчислює Jaccard-схожість між двома множинами токенів.
-draftTitle витягує заголовок чернетки, надаючи пріоритет заголовку ADR.
-isNoDecision визначає, чи не прийнято рішення у чернетці, аналізуючи секцію Decision Outcome.
-buildEdges будує кандидати-ребра між чернетками та між чернетками і чистими ADR на основі лексичної схожості.
-validateMadr перевіряє згенерований контент на відповідність канону чистого MADR.
-normalizePipeline виконує повний конвеєр нормалізації, групуючи чернетки, оцінюючи їх та генеруючи операції для застосування.
+tokenize: Токенізує назву або слаг, видаляючи стоп-слова та розширюючи його на значущі токени.
+jaccard: Обчислює коефіцієнт Jaccard між двома множинами токенів.
+draftTitle: Витягує заголовок з тіла чернетки, використовуючи ADR-шаблон або перший не-MADR заголовок.
+isNoDecision: Детерміновано визначає, чи рішення в чернетці явно не прийняте.
+buildEdges: Будує кандидати-ребра між чернетками та між чернетками і чистими ADR-файлами на основі лексичної схожості.
+validateMadr: Перевіряє згенерований MADR-текст на відповідність вимогам OKF та структурним елементам.
+madrDate: Детерміновано визначає ISO-дату для поля **Date:**, використовуючи дані з чернетки або імені файлу.
+normalizeSections: Нормалізує сирий JSON-вивід LLM у строгу структуру секцій MADR, толерантно до дрібних відхилень моделі.
+assembleMadr: Збирає канонічний MADR-markdown, використовуючи заголовок, дату та нормалізований контент секцій.
+genMadr: Витягує зміст архітектурного рішення з чернетки у JSON, а потім збирає його у валідний MADR-текст.
+normalizePipeline: Виконує повний конвеєр нормалізації, кластеризуючи чернетки та генеруючи операції для застосування.
 
 ## Публічний API
 
-tokenize — розбиває назву чи слаг на значущі частини, замінюючи пробіли та дефіси, і відсіюючи загальні слова.
-jaccard — обчислює ступінь подібності між двома наборами слів.
-draftTitle — витягує заголовок з чернетки, надаючи пріоритет заголовку у форматі `## ADR <title>`, а у відсутності такого — використовує перший не-ADR заголовок або ім'я файлу.
-isNoDecision — визначає, чи не містить чернетка чіткого рішення, що робить її непотрібною для окремого ADR.
-buildEdges — створює потенційні зв'язки між елементами на основі схожості слів.
-validateMadr — перевіряє якість згенерованого документа ADR.
-normalizePipeline — виконує повний процес обробки, повертаючи список виконаних кроків та статистику.
+tokenize — Розбиває назву чи слаг на значущі слова, ігноруючи стоп-слова.
+jaccard — Вимірює схожість двох наборів слів.
+draftTitle — Витягує заголовок з чернетки, надаючи пріоритет заголовку ADR.
+isNoDecision — Визначає, чи не було прийнято рішення у чернетці, щоб уникнути створення зайвих ADR.
+buildEdges — Створює потенційні зв'язки між елементами на основі схожості слів.
+validateMadr — Перевіряє якість згенерованого документа ADR.
+madrDate — Формує стандартизовану дату для документа, використовуючи метадані або ім'я файлу.
+normalizeSections — Приводить неструктурований вивід генеративної моделі до чіткого формату секцій.
+assembleMadr — Збирає повний, стандартизований документ ADR, використовуючи фіксовані шаблони.
+genMadr — Створює чернетку документа ADR на основі вхідних даних.
+normalizePipeline — Виконує повний потік обробки даних, повертаючи результати та статистику.
 
 ## Гарантії поведінки
 
-- Read-only: файл не виконує операцій запису у файлову систему.
-- Перехоплює помилки і не пропускає винятків назовні (fail-safe).
-- За невдачі повертає значення помилки (`false`/`null`/`Err`) замість генерування винятку чи паніки.
-- Не звертається до мережі.
+- (специфічних машинно-виведених гарантій немає)

package/scripts/lib/docs/worktree-notice.md

@@ -3,29 +3,28 @@ type: JS Module
 title: worktree-notice.mjs
 resource: npm/scripts/lib/worktree-notice.mjs
 docgen:
-  crc: dc4fba22
+  crc: 1f7d5e0d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
 ---
 
-Цей файл вбудовує інструкції щодо використання git-worktree, коли `meta.json.worktree` встановлено в `true`. Він забезпечує паралельне виконання скілу лише в окремому git-worktree, запобігаючи потенційним проблемам з паралелізмом. Цей механізм дозволяє уникнути гонки з CDN та забезпечує надійний запуск скілу з локальною копією CLI.
+## Огляд
+
+Цей файл вшиває worktree-інструкцію у синкнутий `SKILL.md` (рішення D2 зі spec). Коли `meta.json.worktree === true`, скіл вставляє/замінює ідемпотентний ре-синкнутий блок, що містить маркери WORKTREE_START та WORKTREE_END, забезпечуючи виконання скілу в окремому git-worktree та запобігаючи паралелізації. Функція `injectWorktreeNotice` керує наявністю або відсутністю цього блоку в `SKILL.md` на основі конфігурації.
 
 ## Поведінка
 
-WORKTREE_START: вставляє маркер початку worktree-блоку.
-WORKTREE_END: вставляє маркер кінця worktree-блоку.
-injectWorktreeNotice: вставляє або видаляє worktree-блок у `SKILL.md` на основі значення `meta.json.worktree`. Якщо `meta.json.worktree` `true`, вставляє блок; інакше видаляє. Якщо блок вже існує, замінює його; якщо ні — додає. Враховує наявність YAML-frontmatter та вставляє блок після нього. Використовує транслітерацію для створення суфікса гілки. Реалізує retry-обгортку для `npx` з обмеженням часу та інтервалом для перевірки.
+WORKTREE_START — Маркер початку блоку інструкцій для роботи в окремому git-worktree.
+WORKTREE_END — Маркер кінця блоку інструкцій для роботи в окремому git-worktree.
+injectWorktreeNotice — Вставляє, оновлює або видаляє блок інструкцій для роботи в worktree у вмісті SKILL.md залежно від булевого значення.
 
 ## Публічний API
 
-WORKTREE_START — Початок блоку worktree.
-WORKTREE_END — Кінець блоку worktree.
-injectWorktreeNotice — Змінює вміст SKILL.md, додаючи, оновлюючи або видаляючи worktree-блок.
+WORKTREE_START — Позначає початок секції, що описує робоче дерево.
+WORKTREE_END — Позначає кінець секції, що описує робоче дерево.
+injectWorktreeNotice — Вставляє, змінює або видаляє блок інформації про робоче дерево у файлі `SKILL.md`.
 
 ## Гарантії поведінки
 
-Якщо `meta.json.worktree === true`, то скіл виконується в окремому git-worktree.
-Скіл не паралелізується.
-Після створення worktree виконується `bun install` у цьому worktree.
-Виконується shell-обгортка `n_cursor_npx` навколо `npx` для bootstrap-виклику.
-Обгортка `n_cursor_npx` виконує retry на транзитні помилки реєстру/мережі (інтервал 30с, дефолт 5 хв, `N_CURSOR_NPX_RETRY_MAX_MIN`, ceiling 10 хв).
-При виникненні nonzero CLI повертається одразу.
-Команди, що вимагають command substitution, виконуються після створення worktree.
+- Read-only: не виконує операцій запису (ФС/БД).