@nitra/cursor 3.29.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [4.1.0] - 2026-06-07
+
+### Added
+
+- checkOllama() + ollama HTTP як primary path, pi як fallback у docgen-gen
+
+## [4.0.0] - 2026-06-07
+
+### Changed
+
+- major version bump to 4.0.0
+- docgen Tier 1: пряму ollama HTTP замінено на pi+resolveModel('min') — universally через каскад
+
 ## [3.29.0] - 2026-06-07
 
 ### Added

package/lib/models.mjs

@@ -0,0 +1,68 @@
+/**
+ * Глобальна класифікація моделей для pi.
+ *
+ * Формат значень: "provider/model-id" (pi --model формат).
+ * Налаштовується один раз у середовищі; кожен скіл посилається на потрібний тир.
+ *
+ * Приклад ~/.bashrc або .env:
+ *   N_LOCAL_MIN_MODEL=ollama/gemma3:4b
+ *   N_CLOUD_MIN_MODEL=openai/gpt-5.4-mini
+ *   N_CLOUD_AVG_MODEL=openai/gpt-5.4
+ *   N_CLOUD_MAX_MODEL=openai/gpt-5.5
+ *
+ * Значення '' означає "pi дефолтний провайдер" (залежить від ~/.pi конфігу).
+ *
+ * ## Каскад local → cloud (контракт)
+ *
+ * Використовуйте resolveModel(tier) замість прямих констант — система прозоро
+ * відпрацює навіть без локальних моделей:
+ *
+ *   resolveModel('min') → LOCAL_MIN → LOCAL_AVG → LOCAL_MAX → CLOUD_MIN
+ *   resolveModel('avg') → LOCAL_AVG → LOCAL_MAX → CLOUD_AVG
+ *   resolveModel('max') → LOCAL_MAX → CLOUD_MAX
+ *
+ * Якщо жоден тир не задано — повертає '' (pi-дефолт провайдера).
+ * Прямі константи (LOCAL_MIN тощо) залишені для випадків, де потрібен
+ * явний контроль (напр., ollama HTTP, explicit retry до хмари).
+ */
+
+import { env } from 'node:process'
+
+// ── Локальні (offline, без API-ключа) ────────────────────────────────────────
+
+/** Швидкий локальний inference. Напр.: ollama/gemma3:4b */
+export const LOCAL_MIN = env.N_LOCAL_MIN_MODEL ?? ''
+
+/** Середній локальний. Напр.: ollama/gemma4:26b-moe */
+export const LOCAL_AVG = env.N_LOCAL_AVG_MODEL ?? ''
+
+/** Максимальний локальний. Напр.: ollama/llama4-maverick */
+export const LOCAL_MAX = env.N_LOCAL_MAX_MODEL ?? ''
+
+// ── Хмарні (потрібен API-ключ у pi) ─────────────────────────────────────────
+
+/** Мінімальний хмарний. Напр.: openai/gpt-5.4-mini, google/gemini-2.5-flash, anthropic/claude-haiku-4-5 */
+export const CLOUD_MIN = env.N_CLOUD_MIN_MODEL ?? ''
+
+/** Середній хмарний. Напр.: openai/gpt-5.4, google/gemini-2.5-pro, anthropic/claude-sonnet-4-6 */
+export const CLOUD_AVG = env.N_CLOUD_AVG_MODEL ?? ''
+
+/** Максимальний хмарний. Напр.: openai/gpt-5.5, anthropic/claude-opus-4-8 */
+export const CLOUD_MAX = env.N_CLOUD_MAX_MODEL ?? ''
+
+// ── Каскадне розв'язання ─────────────────────────────────────────────────────
+
+/**
+ * Повертає перший непорожній model-id для запитаного тиру,
+ * каскадно перевіряючи локальні тири, а тоді хмарний еквівалент.
+ *
+ * @param {'min'|'avg'|'max'} tier
+ * @returns {string} provider/model-id або '' для pi-дефолту
+ * @throws {TypeError} якщо tier невідомий
+ */
+export function resolveModel(tier) {
+  if (tier === 'min') return LOCAL_MIN || LOCAL_AVG || LOCAL_MAX || CLOUD_MIN
+  if (tier === 'avg') return LOCAL_AVG || LOCAL_MAX || CLOUD_AVG
+  if (tier === 'max') return LOCAL_MAX || CLOUD_MAX
+  throw new TypeError(`resolveModel: unknown tier "${tier}". Use 'min', 'avg', or 'max'.`)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/cursor",
-  "version": "3.29.0",
+  "version": "4.1.0",
   "description": "CLI для завантаження cursor-правил (префікс n-) у локальний репозиторій",
   "keywords": [
     "cli",
@@ -29,6 +29,7 @@
     "bin",
     "github-actions",
     "schemas",
+    "lib",
     "scripts",
     "skills",
     ".claude-template",

package/scripts/dispatcher/index.mjs

@@ -1,86 +1,45 @@
 /**
- * CLI-диспетчер `n-cursor flow` (spec §8 Dual-Mode Dispatcher).
+ * CLI-диспетчер `n-cursor flow` (думка.MD — протокол всередині вузла графу).
  *
- * Два фасади навколо єдиного джерела істини `.flow.json`:
- *  - **Пасивний Турнікет** (Фасад A): `init`, `verify`, `release` — для IDE-
- *    агентів (Cursor/Claude Code), що самі пишуть код; `n-cursor` лише судить.
- *  - **Активний Раннер** (Фасад B): `run`, `resume`, `cancel`, `repair` —
- *    повний 5-фазний polyfill-цикл для headless/CI.
+ * flow plan    — Stage 1: читає task.md, створює plan_NNN.md, виводить контекст
+ * flow verify  — Stage 2: структурний check + ## Done when + outputs на stdout
+ * flow done    — CWD → node path → `graph done <path>`
+ * flow audit   — CWD → node path → pending-audit_NNN.md → `graph audit <path>`
+ * flow failed  — CWD → node path → `graph failed <path>`
+ * flow spawn   — CWD → node path → `graph spawn <path>`
  */
-import { cancel, repair, resume, run } from './lib/active.mjs'
-import { init, release, verify } from './lib/commands.mjs'
-import { gate } from './lib/gate.mjs'
-import { plan } from './lib/plan.mjs'
-import { review } from './lib/review.mjs'
-import { spec } from './lib/spec.mjs'
+import { plan } from './lib/flow-plan.mjs'
+import { verify } from './lib/flow-verify.mjs'
+import { audit, done, failed, spawn } from './lib/flow-signals.mjs'
 
 const USAGE = [
   'Usage:',
-  '  npx @nitra/cursor flow init "<опис>"      # Фасад A: worktree + .flow.json (+ level)',
-  '  npx @nitra/cursor flow spec [--panel]     # Фасад A: фаза дизайну → docs/specs/<…>',
-  '  npx @nitra/cursor flow plan [--panel]     # Фасад A: фаза плану → docs/plans/<…> + state',
-  '  npx @nitra/cursor flow verify             # Фасад A: Quality Gates (pass/fail)',
-  '  npx @nitra/cursor flow review             # Фасад A: adversarial diff-review (за level)',
-  '  npx @nitra/cursor flow gate               # Фасад A: вердикт PASS/CONCERNS/FAIL (verify+review)',
-  '  npx @nitra/cursor flow release            # Фасад A: .changes + completion snapshot',
-  '  npx @nitra/cursor flow run "<опис>"       # Фасад B: повний 5-фазний цикл',
-  '  npx @nitra/cursor flow resume             # продовжити з чекпойнта',
-  '  npx @nitra/cursor flow cancel             # скасувати, прибрати стан',
-  '  npx @nitra/cursor flow repair [--discard-step-work]   # відновлення пошкодженого стану'
+  '  npx @nitra/cursor flow plan     # Stage 1: читає task.md, створює plan_NNN.md',
+  '  npx @nitra/cursor flow verify   # Stage 2: структурна перевірка + stdout-контекст для агента',
+  '  npx @nitra/cursor flow done     # успіх → graph done <node-path>',
+  '  npx @nitra/cursor flow audit    # аудит → pending-audit_NNN.md → graph audit <node-path>',
+  '  npx @nitra/cursor flow failed   # провал → graph failed <node-path>',
+  '  npx @nitra/cursor flow spawn    # розклад → graph spawn <node-path>'
 ].join('\n')
 
 /**
- * Усі handler-и реальні (Ф1 Spec/Plan + Ф2 Турнікет + Ф4 Активний Раннер).
  * @type {Record<string, (rest: string[], deps: object) => Promise<number>>}
  */
-export const DEFAULT_HANDLERS = { init, spec, plan, verify, review, gate, release, run, resume, cancel, repair }
-
-/**
- * Витягує опційний `--branch <гілка>` з аргументів (для cwd-незалежного резолву
- * стану — беклог #1). Повертає очищені аргументи й значення гілки.
- * @param {string[]} args аргументи після підкоманди
- * @returns {{ rest: string[], branch: string | undefined }} очищені аргументи + гілка
- */
-export function extractBranchFlag(args) {
-  const rest = []
-  let branch
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--branch') {
-      const val = args[i + 1]
-      // Поглинаємо наступний аргумент як значення лише якщо це справді значення,
-      // а не інший прапорець / кінець аргументів (інакше `--branch` був би no-op,
-      // що тихо ковтав би сусідній прапорець).
-      if (val !== undefined && !val.startsWith('-')) {
-        branch = val
-        i++
-      }
-      continue
-    }
-    const inline = args[i].startsWith('--branch=') ? args[i].slice('--branch='.length) : null
-    if (inline !== null) {
-      if (inline !== '') branch = inline
-      continue
-    }
-    rest.push(args[i])
-  }
-  return { rest, branch }
-}
+export const DEFAULT_HANDLERS = { plan, verify, done, audit, failed, spawn }
 
 /**
  * Точка входу `case 'flow'` у `bin/n-cursor.js`. Парсить підкоманду й
  * маршрутизує до handler-а. Невідома/відсутня підкоманда → usage + код 1.
- * Опційний `--branch <гілка>` прокидається в `deps.branch` (резолв стану поза worktree).
  * @param {string[]} args аргументи після `flow`
- * @param {{ handlers?: Record<string, (rest: string[], deps: object) => Promise<number>>, branch?: string }} [deps] ін'єкція handler-ів (для тестів)
+ * @param {{ handlers?: Record<string, (rest: string[], deps: object) => Promise<number>> }} [deps] ін'єкція handler-ів (для тестів)
  * @returns {Promise<number>} exit code
  */
 export async function runFlowCli(args, deps = {}) {
-  const [sub, ...raw] = args
+  const [sub, ...rest] = args
   const handlers = deps.handlers ?? DEFAULT_HANDLERS
   if (!sub || !Object.hasOwn(handlers, sub)) {
     console.error(USAGE)
     return 1
   }
-  const { rest, branch } = extractBranchFlag(raw)
-  return await handlers[sub](rest, { ...deps, branch: deps.branch ?? branch })
+  return await handlers[sub](rest, deps)
 }

package/scripts/dispatcher/lib/flow-plan.mjs

@@ -0,0 +1,153 @@
+/**
+ * Handler `flow plan` — Stage 1 (думка.MD § "flow plan").
+ *
+ * Читає `task.md` у поточному вузлі, розбирає `mode` і `hint` з front-matter,
+ * знаходить наступний номер `plan_NNN.md`, пише шаблон і виводить контекст для
+ * агента (task + mode + hint) на stdout.
+ *
+ * FS та path-резолвінг ін'єктуються — тестується без реального диска.
+ */
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+const FRONT_MATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/
+
+/**
+ * Парсить YAML front-matter (мінімально: лише прості `key: value` рядки).
+ * @param {string} text вміст файлу
+ * @returns {Record<string, string>} ключ-значення з front-matter (рядки)
+ */
+function parseFrontMatter(text) {
+  const m = text.match(FRONT_MATTER_RE)
+  if (!m) return {}
+  const result = {}
+  for (const line of m[1].split(/\r?\n/)) {
+    const idx = line.indexOf(':')
+    if (idx === -1) continue
+    const key = line.slice(0, idx).trim()
+    const val = line.slice(idx + 1).trim()
+    if (key) result[key] = val
+  }
+  return result
+}
+
+/**
+ * Знаходить наступний номер `plan_NNN.md` у директорії вузла.
+ * @param {string} dir абсолютний шлях до директорії вузла
+ * @param {(dir: string) => string[]} readdir інжектована readdir
+ * @returns {string} рядок типу `001`, `002`, …
+ */
+function nextPlanNumber(dir, readdir) {
+  const files = readdir(dir)
+  let max = 0
+  for (const f of files) {
+    const m = f.match(/^plan_(\d+)\.md$/)
+    if (m) {
+      const n = parseInt(m[1], 10)
+      if (n > max) max = n
+    }
+  }
+  return String(max + 1).padStart(3, '0')
+}
+
+/**
+ * Будує вміст шаблону `plan_NNN.md`.
+ * @param {{ mode: string, hint: string, now: string }} params параметри
+ * @returns {string} вміст файлу
+ */
+export function buildPlanTemplate({ mode, hint, now }) {
+  return [
+    '---',
+    `created_at: ${now}`,
+    `mode: ${mode}`,
+    `decision: ${hint || 'atomic | composite'}`,
+    '---',
+    '',
+    '## Context',
+    "<!-- Чому саме такий підхід — що агент/людина з'ясували -->",
+    '',
+    '## Approach',
+    '<!-- atomic: покроковий план виконання -->',
+    '<!-- composite: список дочірніх вузлів з описами -->',
+    '',
+    '## Risks',
+    '<!-- Що може піти не так -->',
+    ''
+  ].join('\n')
+}
+
+/**
+ * `flow plan` handler.
+ *
+ * @param {string[]} _rest аргументи після `plan` (не використовуються)
+ * @param {{
+ *   cwd?: string,
+ *   log?: (m: string) => void,
+ *   readFile?: (path: string, enc: string) => string,
+ *   writeFile?: (path: string, content: string, enc: string) => void,
+ *   readdir?: (dir: string) => string[],
+ *   exists?: (path: string) => boolean,
+ *   now?: () => string
+ * }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function plan(_rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const readFile = deps.readFile ?? ((p, enc) => readFileSync(p, enc))
+  const writeFile = deps.writeFile ?? ((p, c, enc) => writeFileSync(p, c, enc))
+  const readdir = deps.readdir ?? (d => (existsSync(d) ? readdirSync(d) : []))
+  const exists = deps.exists ?? existsSync
+  const nowFn = deps.now ?? (() => new Date().toISOString())
+
+  const taskPath = join(cwd, 'task.md')
+  if (!exists(taskPath)) {
+    log('flow plan: task.md не знайдено в CWD')
+    return 1
+  }
+
+  let taskContent
+  try {
+    taskContent = readFile(taskPath, 'utf8')
+  } catch (err) {
+    log(`flow plan: не вдалося прочитати task.md — ${err instanceof Error ? err.message : String(err)}`)
+    return 1
+  }
+
+  const fm = parseFrontMatter(taskContent)
+  const mode = fm.mode || 'human'
+  const hint = fm.hint || ''
+
+  const num = nextPlanNumber(cwd, readdir)
+  const planPath = join(cwd, `plan_${num}.md`)
+
+  const content = buildPlanTemplate({ mode, hint, now: nowFn() })
+  try {
+    writeFile(planPath, content, 'utf8')
+  } catch (err) {
+    log(`flow plan: не вдалося записати ${planPath} — ${err instanceof Error ? err.message : String(err)}`)
+    return 1
+  }
+
+  log(`flow plan: створено ${planPath}`)
+
+  // Виводимо контекст для агента на stdout
+  const outLines = [
+    `## flow plan context`,
+    ``,
+    `mode: ${mode}`,
+    hint ? `hint: ${hint}` : `hint: (не задано — агент вирішує сам)`,
+    `plan: plan_${num}.md`,
+    ``
+  ]
+  // Додаємо вміст task.md для контексту (без front-matter)
+  outLines.push(`### task.md`)
+  const bodyStart = taskContent.indexOf('\n---\n', 4)
+  const taskBody = bodyStart !== -1 ? taskContent.slice(bodyStart + 5).trimStart() : taskContent
+  outLines.push(taskBody.trimEnd())
+
+  console.log(outLines.join('\n'))
+
+  return 0
+}

package/scripts/dispatcher/lib/flow-signals.mjs

@@ -0,0 +1,235 @@
+/**
+ * Handlers сигнальних команд `flow done/audit/failed/spawn` (думка.MD).
+ *
+ * Агент ніколи не знає свій абсолютний path — команди обчислюють path вузла з
+ * env var `NCURSOR_NODE_PATH` (встановлюється wrapper-скриптом) або з файлу
+ * `.n-cursor/current-node` у корені worktree. Якщо нічого — error.
+ *
+ * done    → делегує `n-cursor graph done <path>`
+ * audit   → створює `pending-audit_NNN.md` → делегує `n-cursor graph audit <path>`
+ * failed  → делегує `n-cursor graph failed <path>`
+ * spawn   → делегує `n-cursor graph spawn <path>`
+ *
+ * Всі IO ін'єктуються для тестування без реальних процесів і диска.
+ */
+import { spawnSync } from 'node:child_process'
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+/**
+ * Резолвить шлях вузла з env або fallback-файлу.
+ * @param {{
+ *   env?: Record<string, string | undefined>,
+ *   cwd?: string,
+ *   readFile?: (p: string, enc: string) => string,
+ *   exists?: (p: string) => boolean
+ * }} deps ін'єкції
+ * @returns {{ nodePath: string | null, error: string | null }} результат
+ */
+export function resolveNodePath(deps = {}) {
+  const env = deps.env ?? process.env
+  const cwd = deps.cwd ?? processCwd()
+  const exists = deps.exists ?? existsSync
+  const readFile = deps.readFile ?? ((p, enc) => readFileSync(p, enc))
+
+  // 1. Env var
+  const fromEnv = env['NCURSOR_NODE_PATH']
+  if (fromEnv && fromEnv.trim().length > 0) {
+    return { nodePath: fromEnv.trim(), error: null }
+  }
+
+  // 2. Fallback-файл .n-cursor/current-node у CWD (корінь worktree)
+  const fallbackPath = join(cwd, '.n-cursor', 'current-node')
+  if (exists(fallbackPath)) {
+    try {
+      const content = readFile(fallbackPath, 'utf8').trim()
+      if (content.length > 0) {
+        return { nodePath: content, error: null }
+      }
+    } catch {
+      // якщо не читається — fallthrough до error
+    }
+  }
+
+  return { nodePath: null, error: 'NCURSOR_NODE_PATH not set and .n-cursor/current-node not found' }
+}
+
+/**
+ * Знаходить поточний найбільший номер `outputs_NNN.md`.
+ * @param {string} dir директорія вузла
+ * @param {(dir: string) => string[]} readdir ін'єктована readdir
+ * @returns {string | null} рядок типу `001` або null якщо не знайдено
+ */
+function findCurrentOutputsNum(dir, readdir) {
+  const files = readdir(dir)
+  let max = -1
+  for (const f of files) {
+    const m = f.match(/^outputs_(\d+)\.md$/)
+    if (m) {
+      const n = parseInt(m[1], 10)
+      if (n > max) max = n
+    }
+  }
+  return max >= 0 ? String(max).padStart(3, '0') : null
+}
+
+/**
+ * Виконує n-cursor graph <sub> <nodePath>.
+ * @param {string} sub підкоманда graph
+ * @param {string} nodePath шлях вузла
+ * @param {{
+ *   run: (cmd: string, args: string[]) => { status: number, stdout: string, stderr: string }
+ * }} deps
+ * @returns {number} exit code
+ */
+function delegateToGraph(sub, nodePath, deps) {
+  const result = deps.run('npx', ['@nitra/cursor', 'graph', sub, nodePath])
+  return result.status ?? 1
+}
+
+/**
+ * Реальний sync-runner процесу.
+ * @param {string} cmd
+ * @param {string[]} args
+ * @returns {{ status: number, stdout: string, stderr: string }}
+ */
+function realRun(cmd, args) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8' })
+  return { status: r.status ?? 1, stdout: r.stdout ?? '', stderr: r.stderr ?? '' }
+}
+
+/**
+ * Базовий handler для сигнальних команд без аудиту.
+ * @param {string} sub підкоманда graph
+ * @param {{
+ *   cwd?: string,
+ *   env?: Record<string, string | undefined>,
+ *   log?: (m: string) => void,
+ *   run?: (cmd: string, args: string[]) => { status: number, stdout: string, stderr: string },
+ *   readFile?: (p: string, enc: string) => string,
+ *   exists?: (p: string) => boolean
+ * }} deps ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+async function signalHandler(sub, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const run = deps.run ?? realRun
+
+  const { nodePath, error } = resolveNodePath({ env: deps.env, cwd, readFile: deps.readFile, exists: deps.exists })
+  if (!nodePath) {
+    log(`flow ${sub}: ${error}`)
+    return 1
+  }
+
+  log(`flow ${sub}: node path = ${nodePath}`)
+  const code = delegateToGraph(sub, nodePath, { run })
+  if (code !== 0) {
+    log(`flow ${sub}: graph ${sub} завершився з кодом ${code}`)
+  }
+  return code
+}
+
+/**
+ * `flow done` — сигналізує успіх → `graph done <path>`.
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {object} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function done(_rest, deps = {}) {
+  return signalHandler('done', deps)
+}
+
+/**
+ * `flow failed` — сигналізує провал → `graph failed <path>`.
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {object} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function failed(_rest, deps = {}) {
+  return signalHandler('failed', deps)
+}
+
+/**
+ * `flow spawn` — сигналізує розклад → `graph spawn <path>`.
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {object} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function spawn(_rest, deps = {}) {
+  return signalHandler('spawn', deps)
+}
+
+/**
+ * `flow audit` — створює `pending-audit_NNN.md` → `graph audit <path>`.
+ *
+ * NNN у `pending-audit_NNN.md` = NNN відповідного `outputs_NNN.md`.
+ * Якщо outputs відсутні — error.
+ *
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {{
+ *   cwd?: string,
+ *   env?: Record<string, string | undefined>,
+ *   log?: (m: string) => void,
+ *   run?: (cmd: string, args: string[]) => { status: number, stdout: string, stderr: string },
+ *   readFile?: (p: string, enc: string) => string,
+ *   writeFile?: (p: string, content: string, enc: string) => void,
+ *   readdir?: (dir: string) => string[],
+ *   exists?: (p: string) => boolean,
+ *   now?: () => string
+ * }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code
+ */
+export async function audit(_rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const readdir = deps.readdir ?? (d => (existsSync(d) ? readdirSync(d) : []))
+  const writeFile = deps.writeFile ?? ((p, c, enc) => writeFileSync(p, c, enc))
+  const exists = deps.exists ?? existsSync
+  const nowFn = deps.now ?? (() => new Date().toISOString())
+  const run = deps.run ?? realRun
+
+  const { nodePath, error } = resolveNodePath({ env: deps.env, cwd, readFile: deps.readFile, exists })
+  if (!nodePath) {
+    log(`flow audit: ${error}`)
+    return 1
+  }
+
+  // Знаходимо поточний outputs NNN
+  const outputsNum = findCurrentOutputsNum(cwd, readdir)
+  if (!outputsNum) {
+    log('flow audit: outputs_NNN.md не знайдено — спершу напиши outputs')
+    return 1
+  }
+
+  const pendingPath = join(cwd, `pending-audit_${outputsNum}.md`)
+  if (exists(pendingPath)) {
+    log(`flow audit: ${pendingPath} вже існує — audit вже запитано для outputs_${outputsNum}.md`)
+    return 1
+  }
+
+  const content = [
+    '---',
+    `created_at: ${nowFn()}`,
+    `outputs_ref: outputs_${outputsNum}.md`,
+    `actor: agent`,
+    '---',
+    ''
+  ].join('\n')
+
+  try {
+    writeFile(pendingPath, content, 'utf8')
+  } catch (err) {
+    log(`flow audit: не вдалося записати ${pendingPath} — ${err instanceof Error ? err.message : String(err)}`)
+    return 1
+  }
+
+  log(`flow audit: ${pendingPath} створено`)
+  log(`flow audit: node path = ${nodePath}`)
+  const code = delegateToGraph('audit', nodePath, { run })
+  if (code !== 0) {
+    log(`flow audit: graph audit завершився з кодом ${code}`)
+  }
+  return code
+}