@nitra/cursor 4.1.0 → 4.1.2

package/skills/docgen/js/docgen-prompts.mjs

@@ -6,11 +6,15 @@ export const STYLE = [
   'Заборонено: сигнатури, типи, параметри функцій; перелік stdlib-модулів; опис regex чи внутрішніх приватних імен.'
 ].join(' ')
 
-/** Короткий людиночитний витяг фактів (без коду). */
+/**
+ * Короткий людиночитний витяг фактів (без коду).
+ * @param {object} facts факт-лист про файл
+ * @returns {string} текстовий блок «factsTxt» для system-prompt
+ */
 function factsSummary(facts) {
   const m = facts.markers || {}
   const lines = []
-  if (facts.header) lines.push(`Намір файлу: ${facts.header.replace(/\n/g, ' ')}`)
+  if (facts.header) lines.push(`Намір файлу: ${facts.header.replaceAll('\n', ' ')}`)
   if (facts.exports?.length) lines.push(`Публічні функції: ${facts.exports.map(e => e.name).join(', ')}`)
   if (m.skips?.length) lines.push(`Свідомо пропускає шляхи: ${m.skips.join(', ')}`)
   lines.push(`Read-only: ${m.readOnly ? 'так' : 'ні'}`)
@@ -30,7 +34,9 @@ const msgs = (system, user) => [
 /**
  * Секційні набори messages з МІНІМАЛЬНИМ контекстом під кожну секцію.
  * Код потрапляє лише в `behavior`; решта секцій — на факт-листі.
- * @returns {Array<{key:string, messages:object[], numPredict:number}>}
+ * @param {object} facts факт-лист про файл
+ * @param {string} src вміст файлу
+ * @returns {Array<{key:string, messages:object[], numPredict:number}>} набір секційних промптів
  */
 export function sectionMessages(facts, src) {
   const factsTxt = factsSummary(facts)
@@ -83,7 +89,12 @@ export function sectionMessages(facts, src) {
   return out
 }
 
-/** One-shot messages (база для порівняння). */
+/**
+ * One-shot messages (база для порівняння).
+ * @param {object} facts факт-лист про файл
+ * @param {string} src вміст файлу
+ * @returns {Array<object>} messages-масив для LLM API
+ */
 export function oneShotMessages(facts, src) {
   const multi = (facts.exports?.length || 0) > 1
   return msgs(
@@ -92,7 +103,12 @@ export function oneShotMessages(facts, src) {
   )
 }
 
-/** Лише текст user-промпту для one-shot (для хмарного fallback через Anthropic SDK). */
+/**
+ * Лише текст user-промпту для one-shot (для хмарного fallback через Anthropic SDK).
+ * @param {object} facts факт-лист про файл
+ * @param {string} src вміст файлу
+ * @returns {string} plain-text user-prompt
+ */
 export function oneShotPromptText(facts, src) {
   const multi = (facts.exports?.length || 0) > 1
   return `Напиши документацію для файлу. Секції: ## Огляд (1-3 речення), ## Поведінка (нумерований/маркований алгоритм), ${multi ? '## Публічний API (назва + що робить), ' : ''}## Гарантії поведінки.\n\nФАЙЛ ${facts.relPath}:\n\`\`\`\n${src}\n\`\`\``

package/skills/fix/js/llm-worker.mjs

@@ -11,10 +11,11 @@ import { resolveModel } from '../../../lib/models.mjs'
 export const MODEL = env.N_CURSOR_FIX_MODEL ?? resolveModel('min')
 export const MODEL_HEAVY = env.N_CURSOR_FIX_MODEL_HEAVY ?? resolveModel('avg')
 
+const JSON_CODE_BLOCK_RE = /```(?:json)?\s*([\s\S]*?)```/
+
 /**
  * Витягує відносні шляхи файлів із violation output.
  * Розуміє workspace-prefix: `[npm] skills/foo.mjs` → `npm/skills/foo.mjs`.
- *
  * @param {string} output violation output з fix check
  * @returns {string[]} унікальні відносні шляхи (від кореня проєкту)
  */
@@ -23,7 +24,7 @@ function extractFilePaths(output) {
   const results = []
 
   // Патерн з workspace: [npm] skills/foo.mjs або [demo] src/bar.ts
-  const wsRe = /\[([\w-]+)\]\s+([\w./][\w./\-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
+  const wsRe = /\[([\w-]+)\]\s+([\w./][\w./-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
   for (const m of output.matchAll(wsRe)) {
     const p = `${m[1]}/${m[2]}`
     if (!seen.has(p)) {
@@ -33,7 +34,7 @@ function extractFilePaths(output) {
   }
 
   // Патерн без workspace: просто path/to/file.ext або ./file.ext
-  const re = /(?:^|\s)(\.?[\w][\w./\-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
+  const re = /(?:^|\s)(\.?[\w][\w./-]*\.(?:json|js|mjs|ts|vue|yml|yaml|toml|mdc|md|sh|py))(?::\d+)?/gm
   for (const m of output.matchAll(re)) {
     const p = m[1]
     if (!seen.has(p)) {
@@ -47,12 +48,11 @@ function extractFilePaths(output) {
 
 /**
  * Будує prompt для pi: правило + порушення + поточний вміст файлів.
- *
- * @param {string} ruleId
+ * @param {string} ruleId ID правила
  * @param {string} ruleMdc   вміст .mdc-файлу правила
  * @param {string} output    violation output
- * @param {Array<{path:string, content:string}>} files
- * @returns {string}
+ * @param {Array<{path:string, content:string}>} files прочитані файли (path + content)
+ * @returns {string} текст промпта для pi
  */
 function buildPrompt(ruleId, ruleMdc, output, files) {
   const filesBlock =
@@ -87,10 +87,9 @@ function buildPrompt(ruleId, ruleMdc, output, files) {
 
 /**
  * Запускає pi і повертає stdout як рядок.
- *
- * @param {string} prompt
- * @param {string} model
- * @returns {{ text: string, error?: string }}
+ * @param {string} prompt текст промпта
+ * @param {string} model назва моделі (provider/id)
+ * @returns {{ text: string, error?: string }} stdout pi або повідомлення про помилку
  */
 function callPi(prompt, model) {
   const modelArgs = model ? ['--model', model] : []
@@ -120,9 +119,8 @@ function callPi(prompt, model) {
 /**
  * Парсить JSON-відповідь від pi.
  * pi може обгорнути JSON у ```json ... ```, тому пробуємо витягти.
- *
- * @param {string} text
- * @returns {{ changes: Array<{path:string,content:string}>, error?: string } | null}
+ * @param {string} text сирий stdout pi
+ * @returns {{ changes: Array<{path:string,content:string}>, error?: string } | null} розпарсений патч або null
  */
 function parseResponse(text) {
   // Спроба 1: прямий JSON
@@ -133,7 +131,7 @@ function parseResponse(text) {
   }
 
   // Спроба 2: витягти з ```json ... ```
-  const m = text.match(/```(?:json)?\s*([\s\S]*?)```/)
+  const m = text.match(JSON_CODE_BLOCK_RE)
   if (m) {
     try {
       return JSON.parse(m[1].trim())
@@ -158,14 +156,13 @@ function parseResponse(text) {
 
 /**
  * LLM-worker: виправляє одне rule-порушення через pi (C1 pattern).
- *
- * @param {string} ruleId
+ * @param {string} ruleId ID правила
  * @param {string} violationOutput  output з fix check для цього rule
  * @param {string} projectRoot      абсолютний шлях до кореня проєкту
- * @param {{ model?: string }} opts
- * @returns {Promise<{ ok: boolean, error?: string }>}
+ * @param {{ model?: string }} opts опції (model — перевизначення моделі)
+ * @returns {Promise<{ ok: boolean, error?: string }>} статус виправлення і можлива помилка
  */
-export async function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
+export function runLlmWorker(ruleId, violationOutput, projectRoot, opts = {}) {
   const model = opts.model ?? MODEL
 
   // 1. Читаємо rule .mdc
@@ -207,8 +204,8 @@ export async function runLlmWorker(ruleId, violationOutput, projectRoot, opts =
     const abs = join(projectRoot, change.path)
     try {
       writeFileSync(abs, change.content, 'utf8')
-    } catch (e) {
-      return { ok: false, error: `write ${change.path}: ${e.message}` }
+    } catch (error) {
+      return { ok: false, error: `write ${change.path}: ${error.message}` }
     }
   }
 

package/skills/fix/js/orchestrator.mjs

@@ -20,8 +20,8 @@ export async function runOrchestratorCli(args, cwd) {
 
   const maxIterIdx = args.indexOf('--max-iter')
   const maxIter =
-    maxIterIdx !== -1 ? Number(args[maxIterIdx + 1] ?? DEFAULT_MAX_ITER) || DEFAULT_MAX_ITER : DEFAULT_MAX_ITER
-  const skipIdxs = new Set(maxIterIdx !== -1 ? [maxIterIdx, maxIterIdx + 1] : [])
+    maxIterIdx === -1 ? DEFAULT_MAX_ITER : (Number(args[maxIterIdx + 1] ?? DEFAULT_MAX_ITER) || DEFAULT_MAX_ITER)
+  const skipIdxs = new Set(maxIterIdx === -1 ? [] : [maxIterIdx, maxIterIdx + 1])
   const ruleFilter = args.filter((a, i) => !a.startsWith('-') && !skipIdxs.has(i))
 
   /** @type {Map<string, number>} ruleId → кількість LLM-провалів підряд */
@@ -53,7 +53,7 @@ export async function runOrchestratorCli(args, cwd) {
 
     const afterT0 = runFixCheck(cwd, ruleFilter)
     const failedAfterT0 = afterT0?.rules.filter(r => !r.ok) ?? failed
-    const t0Fixed = failed.filter(r => !failedAfterT0.find(f => f.ruleId === r.ruleId))
+    const t0Fixed = failed.filter(r => !failedAfterT0.some(f => f.ruleId === r.ruleId))
 
     if (t0Fixed.length > 0) {
       console.log(`  ⚙️  T0-auto: ${t0Fixed.map(r => r.ruleId).join(', ')}`)
@@ -98,10 +98,9 @@ export async function runOrchestratorCli(args, cwd) {
 /**
  * Внутрішня check-gate: запускає fix-перевірки і повертає структурований результат.
  * Не є публічним CLI — викликається лише оркестратором.
- *
- * @param {string}   cwd
- * @param {string[]} ruleFilter
- * @returns {{ total: number, failed: number, rules: Array<{ ruleId: string, ok: boolean, output: string }> } | null}
+ * @param {string}   cwd корінь проєкту
+ * @param {string[]} ruleFilter список ID правил (порожній — усі)
+ * @returns {{ total: number, failed: number, rules: Array<{ ruleId: string, ok: boolean, output: string }> } | null} JSON-результат або null якщо stdout порожній/невалідний
  */
 function runFixCheck(cwd, ruleFilter = []) {
   const r = spawnSync('bun', [N_CURSOR_BIN, '_fix-check', ...ruleFilter], {

package/skills/fix/js/t0.mjs

@@ -1,10 +1,14 @@
 /** @see ./docs/t0.md */
 import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { spawnSync } from 'node:child_process'
-import { dirname } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+const REC_REQUIRE_RE = /recommendations має містити "[^"]+"/
+const REC_MATCH_ALL_RE = /recommendations має містити "([^"]+)"/g
+const FORBIDDEN_FILE_RE = /Знайдено заборонений файл: \S+/
+const FORBIDDEN_FILE_MATCH_ALL_RE = /Знайдено заборонений файл: (\S+)/g
+
 /**
  * Патерни T0-auto.
  * Кожен паттерн: {
@@ -19,9 +23,9 @@ const PATTERNS = [
   // Fix: додати рядок у .vscode/extensions.json#recommendations
   {
     id: 'vscode-ext-add',
-    test: out => /recommendations має містити "[^"]+"/.test(out),
+    test: out => REC_REQUIRE_RE.test(out),
     apply: (out, cwd) => {
-      const matches = [...out.matchAll(/recommendations має містити "([^"]+)"/g)]
+      const matches = [...out.matchAll(REC_MATCH_ALL_RE)]
       if (matches.length === 0) return { ok: false, action: 'no match' }
 
       const extPath = join(cwd, '.vscode/extensions.json')
@@ -51,9 +55,9 @@ const PATTERNS = [
   // Fix: видалити файл
   {
     id: 'rm-forbidden-file',
-    test: out => /Знайдено заборонений файл: \S+/.test(out),
+    test: out => FORBIDDEN_FILE_RE.test(out),
     apply: (out, cwd) => {
-      const matches = [...out.matchAll(/Знайдено заборонений файл: (\S+)/g)]
+      const matches = [...out.matchAll(FORBIDDEN_FILE_MATCH_ALL_RE)]
       if (matches.length === 0) return { ok: false, action: 'no match' }
 
       const removed = []
@@ -72,11 +76,10 @@ const PATTERNS = [
 
 /**
  * Застосовує всі T0-auto паттерни до одного violation-output.
- *
  * @param {string} ruleId id правила (для логу)
  * @param {string} violationOutput рядок з поля `output` у `fix --json`
  * @param {string} cwd корінь проєкту
- * @returns {{ applied: boolean, actions: string[] }}
+ * @returns {{ applied: boolean, actions: string[] }} результат: чи щось застосовано і список дій
  */
 export function applyT0Auto(ruleId, violationOutput, cwd) {
   const actions = []
@@ -97,9 +100,8 @@ export function applyT0Auto(ruleId, violationOutput, cwd) {
 /**
  * Повертає список id правил, для яких є хоча б один T0-auto паттерн
  * (визначається по violation-output із `fix --json`).
- *
- * @param {{ ruleId: string, output: string }[]} failedRules
- * @returns {string[]}
+ * @param {{ ruleId: string, output: string }[]} failedRules повний список правил із output
+ * @returns {string[]} ID правил із наявним T0-auto патерном
  */
 export function filterT0AutoRules(failedRules) {
   return failedRules.filter(r => PATTERNS.some(p => p.test(r.output))).map(r => r.ruleId)
@@ -115,12 +117,11 @@ const N_CURSOR_BIN = join(HERE, '../../../bin/n-cursor.js')
  * CLI підкоманда `n-cursor fix-t0 [rule...]`.
  * Запускає `fix --json`, застосовує T0-auto для кожного violation,
  * повторно перевіряє check-gate, виводить підсумок.
- *
  * @param {string[]} args аргументи підкоманди (опційний список rule-ids)
  * @param {string}   cwd  корінь проєкту
  * @returns {Promise<number>} 0 — T0-auto закрив всі або немає порушень; 1 — лишились
  */
-export async function runT0AutoCli(args, cwd) {
+export function runT0AutoCli(args, cwd) {
   const ruleFilter = args.filter(a => !a.startsWith('--'))
   const verbose = args.includes('--verbose') || args.includes('-v')
 

package/types/bin/n-cursor.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {}
+export {};

package/rules/flow/docs/fix.md

@@ -1,152 +0,0 @@
-# `npm/rules/flow/fix.mjs`
-
-## Огляд
-
-Файл є точкою входу (entry point) правила `flow` у каталозі правил пакета `@nitra/cursor`. Правило `flow` належить до категорії **pure-doc contract-правил**: воно не має програмних concern-ів і фактично валідує лише супровідний документ `.mdc` (Markdown-Contract) у тій самій теці.
-
-Модуль виконує дві основні задачі:
-
-1. Експортує функцію `run(ctx)`, яка делегує всю роботу стандартному пайплайну виконання правил (`runStandardRule`). Цей експорт використовується диспетчером CLI `@nitra/cursor` (наприклад, командою `npx @nitra/cursor fix flow`) та внутрішніми оркестраторами правил.
-2. Підтримує **standalone-режим** — якщо файл запущено напряму як CLI-скрипт (через `bun rules/flow/fix.mjs`), він викликає універсальний CLI-раннер `runRuleCli` і завершує процес коректним exit-кодом, придатним для CI/IDE-інтеграцій.
-
-Стандартний пайплайн правила, який запускає `runStandardRule`, виглядає так (порядок фіксований):
-`applies` → `JS-concerns` → `policy` → `mdc-refs`. Оскільки в цьому правилі програмних concern-ів немає, реальна перевірка зводиться до етапів `applies`, `policy` та валідації посилань у `.mdc`-файлі.
-
-## Експорти / API
-
-Модуль є **ES-модулем** (`.mjs`), має такі експорти:
-
-| Експорт | Тип                                            | Призначення                                                                                                     |
-| ------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `run`   | `function(ctx?: RuleContext): Promise<number>` | Іменований експорт; основна точка входу для виконання правила. Викликається диспетчером правил `@nitra/cursor`. |
-
-Side-effect верхнього рівня (не експорт, але частина публічної поведінки модуля):
-
-- Якщо `import.meta.url` відповідає стартовому файлу процесу (`isRunAsCli`), модуль запускає `runRuleCli(import.meta.dirname)` та викликає `process.exit(...)` із кодом, який повернув раннер.
-
-Default-експорту **немає**.
-
-## Функції
-
-### `run(ctx)`
-
-```js
-export function run(ctx)
-```
-
-- **Призначення.** Запустити стандартизований пайплайн правила `flow` для поточної теки (`import.meta.dirname` — каталог, де лежить `fix.mjs`, тобто `npm/rules/flow/`).
-- **Параметри:**
-  - `ctx` _(необов'язковий, `RuleContext`)_ — контекст прогону правил. Тип `RuleContext` імпортується з `../../scripts/lib/run-standard-rule.mjs`. У контексті, зокрема, передаються спільні структури між правилами — наприклад, `walkCache` (кеш обходу файлової системи), щоб не повторювати дорогі сканування при послідовному запуску багатьох правил.
-- **Повертає:** `Promise<number>`.
-  - `0` — правило виконано успішно, порушень не виявлено.
-  - `1` — знайдено порушення (наприклад, проблеми у відповідному `.mdc`-файлі).
-- **Side effects:** жодних безпосередньо у функції; усі побічні ефекти (читання FS, виведення повідомлень, агрегація знахідок) інкапсульовані всередині `runStandardRule`.
-- **Контракт пайплайну, який вмикає `runStandardRule`:**
-  - `applies` — визначає, чи правило застосовне до поточного проєкту/контексту.
-  - `JS-concerns` — програмні перевірки JS/MJS-коду (у цьому правилі — фактично відсутні, бо правило pure-doc).
-  - `policy` — політики/обмеження, спільні для всіх правил.
-  - `mdc-refs` — валідація посилань і структури супровідного `.mdc`-файлу.
-
-### IIFE-блок CLI-режиму (top-level, не функція)
-
-```js
-if (isRunAsCli(import.meta.url)) {
-  process.exit(await runRuleCli(import.meta.dirname))
-}
-```
-
-- **Призначення.** Дозволити запуск файлу як самостійного скрипта (`bun rules/flow/fix.mjs`), повністю еквівалентний `npx @nitra/cursor fix flow`.
-- **Семантика умови.** `isRunAsCli(import.meta.url)` повертає `true`, якщо цей файл є стартовим модулем процесу (а не імпортованим іншим модулем). Це стандартний у пакеті паттерн dual-mode (бібліотека + CLI).
-- **Параметри `runRuleCli`:** передається `import.meta.dirname` — абсолютний шлях до каталогу `npm/rules/flow/`. Раннер сам читає `meta.json`/`fix.mjs`/`.mdc` із цього каталогу.
-- **Завершення.** `process.exit(...)` із цілочисельним exit-кодом, який повернув `runRuleCli`. Це важливо для CI/IDE: ненульовий код → провалена перевірка.
-- **ESLint-винятки в коді:** рядок із `process.exit` навмисно вимикає правила `n/no-process-exit` та `unicorn/no-process-exit` через коментар `// eslint-disable-next-line ... -- standalone entry-point має повертати exit-code для CI/IDE`. Це задокументоване відхилення: для standalone CLI вихід кодом потрібен.
-
-## Залежності
-
-Усі залежності — **внутрішні**, з підкаталогу `scripts/lib/` пакета:
-
-| Імпорт            | Шлях                                      | Що дає                                                                                                                                                 |
-| ----------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `isRunAsCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Предикат: чи `import.meta.url` модуля збігається зі стартовим файлом процесу (визначає standalone-запуск).                                             |
-| `runRuleCli`      | `../../scripts/lib/run-rule-cli.mjs`      | Універсальний CLI-раннер для одного правила: парсить аргументи, готує контекст, викликає `run`, форматує вивід, повертає exit-код.                     |
-| `runStandardRule` | `../../scripts/lib/run-standard-rule.mjs` | Стандартний пайплайн правил `applies → JS-concerns → policy → mdc-refs`; читає сусідній `.mdc`, виконує перевірки, агрегує результат у код повернення. |
-
-Зовнішніх (npm-пакетних) залежностей файл не імпортує.
-
-Опосередковано (через `runStandardRule`) використовуються:
-
-- Сусідні файли у каталозі `npm/rules/flow/` — насамперед `.mdc` (Markdown-Contract правила) та `meta.json` (метадані правила), якщо такі присутні.
-- Спільна інфраструктура з `npm/scripts/lib/` (логування, форматування результатів, утиліти FS-обходу).
-
-## Потік виконання / Використання
-
-### Сценарій 1. Виклик з диспетчера правил (типовий)
-
-1. CLI `@nitra/cursor` (або інший оркестратор) визначає, що потрібно запустити правило `flow` у режимі `fix`.
-2. Диспетчер імпортує `fix.mjs` як модуль і викликає `run(ctx)`, передаючи спільний `ctx` (наприклад, із заповненим `walkCache`).
-3. `run` делегує виконання `runStandardRule(import.meta.dirname, ctx)`.
-4. `runStandardRule` послідовно виконує етапи `applies → JS-concerns → policy → mdc-refs`.
-5. Повертається `Promise<number>` — `0` або `1`.
-6. Оркестратор агрегує коди повернення з усіх правил.
-
-### Сценарій 2. Standalone CLI-запуск
-
-Команда:
-
-```bash
-bun npm/rules/flow/fix.mjs
-```
-
-(еквівалентно `npx @nitra/cursor fix flow`).
-
-1. Інтерпретатор виконує модуль як стартовий файл процесу.
-2. Рядок `if (isRunAsCli(import.meta.url))` повертає `true`.
-3. Викликається `await runRuleCli(import.meta.dirname)`:
-   - Раннер парсить CLI-аргументи (флаги, шляхи).
-   - Готує `ctx` для одиничного запуску.
-   - Викликає `run` цього ж модуля (або еквівалентний внутрішній механізм через `runStandardRule`).
-   - Форматує вивід (звіт про знахідки, кольори, summary).
-4. `process.exit(<код>)` — процес завершується з кодом раннера: `0` за успіху, `1` за порушень.
-
-### Сценарій 3. Імпорт у тестах / скриптах
-
-Можливий імпорт `run` для unit-/інтеграційного тестування або для написання кастомних оркестраторів:
-
-```js
-import { run } from '@nitra/cursor/rules/flow/fix.mjs'
-
-const code = await run() // або await run(customCtx)
-if (code !== 0) {
-  // обробити порушення
-}
-```
-
-У цьому випадку top-level блок `if (isRunAsCli(...))` **не спрацьовує** (файл імпортовано, а не запущено напряму), отже `process.exit` не викликається — побічних ефектів на процес немає.
-
-### Контракт повернення
-
-| Код | Значення                                                                                         | Дія викликача                                    |
-| --- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
-| `0` | Правило застосоване й порушень немає; або правило не застосовне (etap `applies` повернув false). | Продовжувати конвеєр.                            |
-| `1` | Знайдено порушення (зазвичай — невідповідність `.mdc`-файлу контракту).                          | CI має зафейлити збірку; IDE — показати помилку. |
-
-## Особливості реалізації / Нотатки
-
-- **Pure-doc rule.** За коментарем у JSDoc функції `run`, правило `flow` не має програмних concern-ів. Це означає, що каталог `npm/rules/flow/` навмисно не містить (або містить лише мінімум) перевірок поверх JS-коду — основний контракт описано в `.mdc`-файлі, який і валідується через підетап `mdc-refs`.
-- **Стандартизований шаблон.** Файл написаний за єдиним шаблоном для всіх правил пакета: тонкий wrapper над `runStandardRule` + опційний standalone CLI-блок. Це спрощує генерацію/підтримку правил і робить їх взаємозамінними для оркестратора.
-- **`import.meta.dirname`** використовується замість `__dirname` (який недоступний в ES-модулях) і передається у `runStandardRule`/`runRuleCli` як локалізатор каталогу правила.
-- **Top-level `await`** у блоці `process.exit(await runRuleCli(...))` дозволений, тому що модуль є ES-модулем (`.mjs`).
-- **ESLint-disable з обґрунтуванням.** Вимкнення `n/no-process-exit` та `unicorn/no-process-exit` зроблено з явним коментарем-обґрунтуванням після `--`, що відповідає внутрішнім js-lint правилам пакета (вимога описувати причину disable).
-
-## Rebuild Test (контрольна реконструкція)
-
-Спираючись виключно на цю документацію, файл `fix.mjs` можна відновити так:
-
-1. Створити ES-модуль `npm/rules/flow/fix.mjs`.
-2. Імпортувати з `../../scripts/lib/run-rule-cli.mjs` іменовані експорти `isRunAsCli` та `runRuleCli`.
-3. Імпортувати з `../../scripts/lib/run-standard-rule.mjs` іменований експорт `runStandardRule`.
-4. Експортувати функцію `run(ctx)`, яка повертає результат виклику `runStandardRule(import.meta.dirname, ctx)`. Контракт: `Promise<number>` (`0` — OK, `1` — порушення). JSDoc описує пайплайн `applies → JS-concerns → policy → mdc-refs` та зазначає, що правило pure-doc.
-5. Додати top-level блок: `if (isRunAsCli(import.meta.url)) process.exit(await runRuleCli(import.meta.dirname))`.
-6. Поряд із `process.exit` поставити `eslint-disable-next-line` для `n/no-process-exit` та `unicorn/no-process-exit` з обґрунтуванням, що standalone entry-point має повертати exit-code для CI/IDE.
-
-Такий файл буде функціонально еквівалентним оригіналу.

package/rules/flow/fix.mjs

@@ -1,18 +0,0 @@
-import { isRunAsCli, runRuleCli } from '../../scripts/lib/run-rule-cli.mjs'
-import { runStandardRule } from '../../scripts/lib/run-standard-rule.mjs'
-
-/**
- * Запускає правило: applies → JS-concerns → policy → mdc-refs (через runStandardRule).
- * Pure-doc contract-правило: програмних concern-ів немає, тож по суті валідує `.mdc`.
- * @param {import('../../scripts/lib/run-standard-rule.mjs').RuleContext} [ctx] контекст прогону (walkCache тощо)
- * @returns {Promise<number>} 0 — OK, 1 — порушення
- */
-export function run(ctx) {
-  return runStandardRule(import.meta.dirname, ctx)
-}
-
-if (isRunAsCli(import.meta.url)) {
-  // Standalone: bun rules/flow/fix.mjs — повний еквівалент `npx @nitra/cursor fix flow`.
-  // eslint-disable-next-line n/no-process-exit, unicorn/no-process-exit -- standalone entry-point має повертати exit-code для CI/IDE
-  process.exit(await runRuleCli(import.meta.dirname))
-}

package/rules/flow/flow.mdc

@@ -1,127 +0,0 @@
----
-description: Контракт Пасивного Турнікета n-cursor flow — IDE-агент сам пише код, але ізолює/планує/перевіряє/релізить через flow init/spec/plan/verify/release.
-globs:
-alwaysApply: true
----
-
-# n-cursor flow — Пасивний Турнікет (контракт виконавця)
-
-`n-cursor flow` — це Dual-Mode Dispatcher. В інтерактивному середовищі (Cursor
-Composer, Claude Code) працює **Пасивний Турнікет**: ти, агент, **сам пишеш
-код**, а `n-cursor` лише ізолює роботу, **судить** її якість і релізить. Жодного
-прихованого спавну субагентів — керуєш ти.
-
-## Контракт (виконуй у цьому порядку)
-
-1. **Старт** — на початку задачі:
-
-   ```
-   npx @nitra/cursor flow init <branch> "<опис>"
-   ```
-
-   Створює ізольований worktree (`.worktrees/<branch>/`) і стан задачі. Якщо ти
-   вже в worktree — новий не вкладається. `init` визначає **рівень** задачі
-   (L0 тривіальне … L3 архітектурне) і **ризик** (low/med/high — за описом:
-   security/auth/secret → high) за описом: для L0 (fix/typo/bump) фази Spec/План
-   можна пропустити; для L≥1 вони рекомендовані. Рівень **і ризик** разом керують
-   глибиною та фокусом `review`. Ризик можна уточнити полем `risk:` у frontmatter
-   spec — `flow spec` його підхопить.
-
-2. **Spec (дизайн)** — рекомендовано, не блокує. Brainstorm нашими термінами
-   (НЕ викликаючи superpowers):
-
-   - **human↔agent (дефолт):** питання по одному (перевага multiple-choice) →
-     2-3 підходи з рекомендацією → дизайн секціями з апрувом людини;
-   - **agent↔agent:** `npx @nitra/cursor flow spec --panel` — панель персон
-     (architect/skeptic/tester) → суддя-синтез; презентуй синтез людині.
-
-   **Поглиблення (advanced elicitation, за потреби).** Якщо чернетка дизайну
-   «сира» чи є непевність — запропонуй людині одну з технік (по одній за раз),
-   застосуй обрану, повтори до «досить»:
-
-   - **Expand / Contract** — розгорнути деталь, що бракує, або згорнути зайве до суті;
-   - **Critique & Refine** — самокритика чернетки (слабкі місця, припущення), тоді доопрацювання;
-   - **Identify Risks** — явно перелічити ризики/граничні випадки (наповнює поле `risk:` у frontmatter);
-   - **Tree-of-Thoughts** — кілька гілок рішення паралельно, обрати найкращу з обґрунтуванням;
-   - **Stakeholder Roundtable** — пройтись поглядами ролей (user / ops / security / maintainer);
-   - **Self-Consistency** — 2-3 незалежні версії відповіді, звірити на суперечності.
-
-   Що застосовано — фіксуй коротко в секції `## Elicitation History` спеки
-   (traceability рішень).
-
-   Збережи дизайн → `docs/specs/<date>-<slug>.md` (`kind: nitra-spec`,
-   `plan: null`), тоді зафіксуй:
-
-   ```
-   npx @nitra/cursor flow spec
-   ```
-
-3. **План** — декомпозиція дизайну в кроки:
-
-   - збережи `docs/plans/<date>-<slug>.md` (`kind: nitra-plan`, `spec:` → лінк на
-     spec, `flow:` → шлях `.flow.json`; секція `## Кроки` — нумерований список
-     `N. <task> — acceptance: <критерій>`);
-   - зафіксуй (`--panel` — для agent↔agent синтезу кроків):
-
-   ```
-   npx @nitra/cursor flow plan
-   ```
-
-   Команда дзеркалить кроки у `.flow.json` (`status: planned`) і запускає `trace`
-   для перевірки ланцюга spec↔plan↔flow. `verify` без плану лише попередить.
-
-4. **Пиши код** сам, кроками. TDD: спершу падаючі тести, тоді реалізація.
-
-5. **Перевіряй** після кожного логічного кроку:
-
-   ```
-   npx @nitra/cursor flow verify
-   ```
-
-   Проганяє Quality Gates (lint + coverage). Повертає `0` (pass) або `1` із
-   виводом проваленого gate. **Обидва гейти перевіряють лише змінені файли**
-   (diff від `base_commit`): `lint` — quick-режим, `coverage --changed` — vitest
-   `--changed` + Stryker `--mutate` по diff. Працює однаково, незалежно від того,
-   чи зміни вже закомічені у worktree. Повний coverage (увесь проєкт) — окремо:
-   `bun run coverage` або `/n-coverage-fix`.
-
-6. **Review (adversarial)** — рекомендовано перед release:
-
-   ```
-   npx @nitra/cursor flow review
-   ```
-
-   Незалежний субагент читає ЛИШЕ `git diff` від `base_commit` і шукає логічні
-   баги/ризики, яких не ловлять механічні гейти. Кількість рецензентів —
-   `max(рівень, ризик)` (L0→1 … L3→3; high-risk → 3, з безпековим фокусом
-   промпта). Findings пишуться у `.flow.json` (не блокує); high-severity варто
-   виправити перед фінішем.
-
-7. **На провал** — виправ код за виводом і виклич `flow verify` знову. Максимум
-   **3 спроби**; якщо не вдається — зупинись і поклич людину.
-
-8. **Gate (вердикт готовності)** — перед фінішем:
-
-   ```
-   npx @nitra/cursor flow gate
-   ```
-
-   Синтезує verify-гейти і review-findings у `PASS / CONCERNS / FAIL` + score +
-   причини (пише у `.flow.json`). `FAIL` (провалений gate або high-severity
-   finding) → код 1; `release` на FAIL лише попередить (рішення за тобою).
-
-9. **Фініш** — після зеленого `verify` і бажано `gate` ≠ FAIL:
-
-   ```
-   npx @nitra/cursor flow release --bump <patch|minor|major> --section <Added|Changed|Fixed> --message "<що зроблено>"
-   ```
-
-   Генерує `.changes/` і пише completion snapshot. Гілка готова до merge.
-
-## Чого не роби
-
-- Не обходь `verify` — це єдиний критерій «готово».
-- Не редагуй `version` чи `CHANGELOG.md` вручну (це робить CI з `.changes/`).
-- Не коміть стан `.worktrees/<branch>.flow.json` у гілку — він поза git.
-- Не лінкуй spec↔plan неконсистентно — тримай `spec.plan`/`plan.spec`/`plan.flow`
-  у front-matter; `flow spec`/`flow plan` перевіряють їх через `trace`.

package/rules/flow/meta.json

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