@nitra/cursor 3.29.0 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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/package.json

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

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
+}

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

@@ -0,0 +1,127 @@
+/**
+ * Handler `flow verify` — Stage 2 structural check (думка.MD § "flow verify").
+ *
+ * Перевіряє що `outputs_NNN.md` існує і непорожній у директорії поточного вузла
+ * (CWD). Якщо так — виводить `## Done when` секцію з `task.md` та вміст
+ * `outputs_NNN.md` на stdout для агентської self-evaluation.
+ *
+ * exit 0 = структурно OK
+ * exit 1 = структурна помилка (outputs відсутній або порожній)
+ *
+ * НІЯКОГО артефакту не пишеться. FS ін'єктується для тестування без диска.
+ */
+import { existsSync, readdirSync, readFileSync } 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---/
+const SECTION_RE = /^## (.+)$/m
+
+/**
+ * Читає секцію за заголовком із markdown-файлу.
+ * Повертає вміст від заголовка до наступного `## ` або кінця файлу.
+ * @param {string} text вміст файлу
+ * @param {string} heading заголовок без `## `
+ * @returns {string | null} вміст секції (включно з рядком заголовка) або null
+ */
+function extractSection(text, heading) {
+  const lines = text.split(/\r?\n/)
+  const start = lines.findIndex(l => l === `## ${heading}`)
+  if (start === -1) return null
+  const end = lines.findIndex((l, i) => i > start && SECTION_RE.test(l))
+  const section = end === -1 ? lines.slice(start) : lines.slice(start, end)
+  return section.join('\n').trimEnd()
+}
+
+/**
+ * Знаходить outputs-файл з найбільшим NNN у директорії вузла.
+ * @param {string[]} files список файлів директорії
+ * @returns {string | null} ім'я файлу (напр. `outputs_001.md`) або null
+ */
+export function findLatestOutputs(files) {
+  let max = -1
+  let best = null
+  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
+        best = f
+      }
+    }
+  }
+  return best
+}
+
+/**
+ * `flow verify` handler.
+ *
+ * @param {string[]} _rest аргументи після `verify` (не використовуються)
+ * @param {{
+ *   cwd?: string,
+ *   log?: (m: string) => void,
+ *   readFile?: (path: string, enc: string) => string,
+ *   readdir?: (dir: string) => string[],
+ *   exists?: (path: string) => boolean
+ * }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code (0=OK, 1=структурна помилка)
+ */
+export async function verify(_rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const readFile = deps.readFile ?? ((p, enc) => readFileSync(p, enc))
+  const readdir = deps.readdir ?? (d => (existsSync(d) ? readdirSync(d) : []))
+  const exists = deps.exists ?? existsSync
+
+  // Перевіряємо outputs_NNN.md
+  const files = readdir(cwd)
+  const outputsName = findLatestOutputs(files)
+  if (!outputsName) {
+    log('flow verify: outputs_NNN.md не знайдено — структурна помилка')
+    return 1
+  }
+
+  const outputsPath = join(cwd, outputsName)
+  if (!exists(outputsPath)) {
+    log(`flow verify: ${outputsName} не існує — структурна помилка`)
+    return 1
+  }
+
+  let outputsContent
+  try {
+    outputsContent = readFile(outputsPath, 'utf8')
+  } catch (err) {
+    log(`flow verify: не вдалося прочитати ${outputsName} — ${err instanceof Error ? err.message : String(err)}`)
+    return 1
+  }
+
+  // Перевіряємо що файл не порожній (без front-matter — суто тіло)
+  const withoutFm = outputsContent.replace(FRONT_MATTER_RE, '').trim()
+  if (withoutFm.length === 0) {
+    log(`flow verify: ${outputsName} порожній — структурна помилка`)
+    return 1
+  }
+
+  // Виводимо Done when + outputs на stdout для агентської self-evaluation
+  const outLines = [`## verify context`, ``]
+
+  const taskPath = join(cwd, 'task.md')
+  if (exists(taskPath)) {
+    try {
+      const taskContent = readFile(taskPath, 'utf8')
+      const doneWhen = extractSection(taskContent, 'Done when')
+      if (doneWhen) {
+        outLines.push(doneWhen, '')
+      }
+    } catch {
+      // якщо task.md недоступний — не блокуємо verify
+    }
+  }
+
+  outLines.push(`### ${outputsName}`, ``, outputsContent.trimEnd())
+
+  console.log(outLines.join('\n'))
+
+  return 0
+}

package/scripts/worktree-cli.mjs

@@ -15,7 +15,6 @@ import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'no
 import { join } from 'node:path'
 import { cwd as processCwd } from 'node:process'
 
-import { cleanupFlowSiblings } from './dispatcher/lib/state-store.mjs'
 import {
   buildDescription,
   buildDirtyNotice,
@@ -161,7 +160,8 @@ function cmdRemove(rest, ctx) {
     return 1
   }
   if (existsSync(paths.descFile)) rmSync(paths.descFile, { force: true })
-  cleanupFlowSiblings(paths.checkout) // flow-sibling-и (.flow.json/.events.jsonl/lock) — інакше осиротіють (§1.4)
+  // В новій архітектурі (думка.MD) state зберігається у файлах вузлів (task.md, outputs, run),
+  // а не у .flow.json/.events.jsonl/lock sibling-ах. Cleanup sibling-ів більше не потрібен.
   ctx.log(`✅ прибрано: ${paths.checkout} (гілку ${branch} лишено)`)
   return 0
 }