@nitra/cursor 3.2.3 → 3.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [3.4.0] - 2026-06-01
+
+### Added
+
+- flow: команда review (adversarial diff-review за рівнем) + scale-adaptive level в init (L0–L3, керує глибиною review)
+
+## [3.3.0] - 2026-06-01
+
+### Added
+
+- flow: фази spec і plan (brainstorm human↔agent + agent↔agent --panel), trace простежує лінк plan→flow, verify м'яко попереджає про відсутній план
+
 ## [3.2.3] - 2026-06-01
 
 ### Fixed

package/package.json

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

package/rules/flow/flow.mdc

@@ -1,5 +1,5 @@
 ---
-description: Контракт Пасивного Турнікета n-cursor flow — IDE-агент сам пише код, але ізолює/перевіряє/релізить через flow init/verify/release.
+description: Контракт Пасивного Турнікета n-cursor flow — IDE-агент сам пише код, але ізолює/планує/перевіряє/релізить через flow init/spec/plan/verify/release.
 globs:
 alwaysApply: true
 ---
@@ -20,11 +20,43 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
    ```
 
    Створює ізольований worktree (`.worktrees/<branch>/`) і стан задачі. Якщо ти
-   вже в worktree — новий не вкладається.
+   вже в worktree — новий не вкладається. `init` визначає **рівень** задачі
+   (L0 тривіальне … L3 архітектурне) за описом: для L0 (fix/typo/bump) фази
+   Spec/План можна пропустити; для L≥1 вони рекомендовані. Рівень також керує
+   глибиною `review`.
 
-2. **Пиши код** сам, кроками. TDD: спершу падаючі тести, тоді реалізація.
+2. **Spec (дизайн)** — рекомендовано, не блокує. Brainstorm нашими термінами
+   (НЕ викликаючи superpowers):
 
-3. **Перевіряй** після кожного логічного кроку:
+   - **human↔agent (дефолт):** питання по одному (перевага multiple-choice) →
+     2-3 підходи з рекомендацією → дизайн секціями з апрувом людини;
+   - **agent↔agent:** `npx @nitra/cursor flow spec --panel` — панель персон
+     (architect/skeptic/tester) → суддя-синтез; презентуй синтез людині.
+
+   Збережи дизайн → `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
@@ -33,10 +65,21 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
    Проганяє Quality Gates (lint + coverage). Повертає `0` (pass) або `1` із
    виводом проваленого gate.
 
-4. **На провал** — виправ код за виводом і виклич `flow verify` знову. Максимум
+6. **Review (adversarial)** — рекомендовано перед release:
+
+   ```
+   npx @nitra/cursor flow review
+   ```
+
+   Незалежний субагент читає ЛИШЕ `git diff` від `base_commit` і шукає логічні
+   баги/ризики, яких не ловлять механічні гейти. Кількість рецензентів — за
+   рівнем (L0→1 … L3→3). Findings пишуться у `.flow.json` (не блокує); high-
+   severity варто виправити перед фінішем.
+
+7. **На провал** — виправ код за виводом і виклич `flow verify` знову. Максимум
    **3 спроби**; якщо не вдається — зупинись і поклич людину.
 
-5. **Фініш** — лише після зеленого `verify`:
+8. **Фініш** — лише після зеленого `verify`:
 
    ```
    npx @nitra/cursor flow release --bump <patch|minor|major> --section <Added|Changed|Fixed> --message "<що зроблено>"
@@ -49,3 +92,5 @@ Composer, Claude Code) працює **Пасивний Турнікет**: ти,
 - Не обходь `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/scripts/dispatcher/index.mjs

@@ -9,11 +9,17 @@
  */
 import { cancel, repair, resume, run } from './lib/active.mjs'
 import { init, release, verify } from './lib/commands.mjs'
+import { plan } from './lib/plan.mjs'
+import { review } from './lib/review.mjs'
+import { spec } from './lib/spec.mjs'
 
 const USAGE = [
   'Usage:',
-  '  npx @nitra/cursor flow init "<опис>"      # Фасад A: worktree + .flow.json',
+  '  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 release            # Фасад A: .changes + completion snapshot',
   '  npx @nitra/cursor flow run "<опис>"       # Фасад B: повний 5-фазний цикл',
   '  npx @nitra/cursor flow resume             # продовжити з чекпойнта',
@@ -22,13 +28,13 @@ const USAGE = [
 ].join('\n')
 
 /** Підкоманди flow. */
-export const SUBCOMMANDS = ['init', 'verify', 'release', 'run', 'resume', 'cancel', 'repair']
+export const SUBCOMMANDS = ['init', 'spec', 'plan', 'verify', 'review', 'release', 'run', 'resume', 'cancel', 'repair']
 
 /**
- * Усі handler-и реальні (Ф2 Турнікет + Ф4 Активний Раннер).
+ * Усі handler-и реальні (Ф1 Spec/Plan + Ф2 Турнікет + Ф4 Активний Раннер).
  * @type {Record<string, (rest: string[], deps: object) => Promise<number>>}
  */
-export const DEFAULT_HANDLERS = { init, verify, release, run, resume, cancel, repair }
+export const DEFAULT_HANDLERS = { init, spec, plan, verify, review, release, run, resume, cancel, repair }
 
 /**
  * Точка входу `case 'flow'` у `bin/n-cursor.js`. Парсить підкоманду й

package/scripts/dispatcher/lib/artifact.mjs

@@ -0,0 +1,67 @@
+/**
+ * Спільні утиліти фаз `spec`/`plan` (Пасивний Турнікет): резолв traceable-
+ * артефакту в `docs/<kind>/`, екстракт кроків плану зі секції `## Кроки`, і
+ * read-only перевірка цілісності ланцюга через `n-cursor trace` (`trace.mjs`).
+ *
+ * Лінки front-matter (`spec.plan`/`plan.spec`/`plan.flow`) пише сам агент за
+ * контрактом `flow.mdc` — тут лише ВЕРИФІКАЦІЯ (мутатора `trace link` нема).
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { runTraceCli } from '../trace.mjs'
+
+/**
+ * Найсвіжіший `docs/<kind>/*.md` (лексикографічно — дата у префіксі назви).
+ * @param {string} cwd корінь worktree
+ * @param {'specs' | 'plans'} kind підкаталог `docs`
+ * @returns {string | null} абсолютний шлях або null, якщо каталог/файли відсутні
+ */
+export function resolveArtifact(cwd, kind) {
+  const dir = join(cwd, 'docs', kind)
+  if (!existsSync(dir)) return null
+  const md = readdirSync(dir)
+    .filter(f => f.endsWith('.md'))
+    .toSorted()
+  return md.length > 0 ? join(dir, md.at(-1)) : null
+}
+
+/** Маркер критерію приймання в рядку кроку (порівняння — case-insensitive). */
+const ACCEPTANCE_MARK = '— acceptance:'
+/** Лише цифри — перевірка нумерації кроку (лінійний, без backtracking). */
+const DIGITS_RE = /^\d+$/u
+
+/**
+ * Кроки зі секції плану — нумерований список `N. <task> — acceptance: <crit>`.
+ * Best-effort парсинг через `indexOf` (без regex-backtracking): рядки поза
+ * форматом ігноруються.
+ * @param {string} text вміст plan-doc
+ * @returns {{ task: string, acceptance?: string }[]} кроки у порядку появи
+ */
+export function extractSteps(text) {
+  const steps = []
+  for (const raw of String(text).split('\n')) {
+    const line = raw.trim()
+    const dot = line.indexOf('. ')
+    if (dot <= 0 || !DIGITS_RE.test(line.slice(0, dot))) continue
+    const body = line.slice(dot + 2).trim()
+    const sep = body.toLowerCase().indexOf(ACCEPTANCE_MARK)
+    if (sep === -1) {
+      steps.push({ task: body })
+    } else {
+      steps.push({ task: body.slice(0, sep).trim(), acceptance: body.slice(sep + ACCEPTANCE_MARK.length).trim() })
+    }
+  }
+  return steps
+}
+
+/**
+ * Read-only перевірка цілісності ланцюга артефактів (не мутує — лише сигнал).
+ * @param {string} cwd корінь worktree
+ * @param {(cwd: string) => number} [runTrace] runner trace (0 — цілісно, 1 — розрив); ін'єкція для тестів
+ * @returns {boolean} true, якщо ланцюг цілісний
+ */
+export function verifyTrace(cwd, runTrace) {
+  const run = runTrace ?? (c => runTraceCli([], { cwd: c, log: () => {} }))
+  return run(cwd) === 0
+}

package/scripts/dispatcher/lib/commands.mjs

@@ -12,6 +12,7 @@ import { cwd as processCwd } from 'node:process'
 import { worktreePaths } from '../../lib/worktree.mjs'
 import { worktreeFingerprint } from '../../utils/worktree-fingerprint.mjs'
 import { flowEventsPath } from './events.mjs'
+import { detectLevel } from './level.mjs'
 import { runReview } from './reviewer.mjs'
 import { buildCompletionSnapshot, writeSummaryToTaskRecord } from './snapshot.mjs'
 import { flowStatePath, readState, recordTransition, writeState } from './state-store.mjs'
@@ -101,14 +102,16 @@ export async function init(rest, deps = {}) {
   const now = deps.now ?? Date.now
   const log = deps.log ?? console.error
   const statePath = flowStatePath(ew.worktreeDir)
+  const level = detectLevel(ew.desc)
   writeState(statePath, {
     branch: ew.branch,
     status: 'in_progress',
     started_at: new Date(now()).toISOString(),
     metadata: { base_commit: ew.baseCommit },
+    level,
     plan: []
   })
-  log(`init: ${ew.branch} → ${statePath}`)
+  log(`init: ${ew.branch} (level ${level}) → ${statePath}`)
   return 0
 }
 
@@ -126,6 +129,13 @@ export async function verify(_rest, deps = {}) {
   const log = deps.log ?? console.error
   const fingerprint = deps.fingerprint ?? (() => worktreeFingerprint())
 
+  const statePath = flowStatePath(cwd)
+  const state = readState(statePath)
+  // М'які ворота: відсутній план — лише попередження, exit-код визначають gate-и.
+  if (state && !(state.plan?.length)) {
+    log('⚠️ verify: плану не зафіксовано (`flow plan`) — рекомендовано спершу сформувати план')
+  }
+
   const verdict = runReview({ run, cwd, fingerprint })
 
   for (const g of verdict.gates) {
@@ -134,8 +144,7 @@ export async function verify(_rest, deps = {}) {
   if (!verdict.pass && verdict.failedOutput) log(verdict.failedOutput)
   log(verdict.pass ? '✅ verify: усі gate-и пройдено' : '❌ verify: провалено')
 
-  const statePath = flowStatePath(cwd)
-  if (readState(statePath)) {
+  if (state) {
     recordTransition(
       { statePath, eventsPath: flowEventsPath(cwd) },
       { type: 'verify', pass: verdict.pass },

package/scripts/dispatcher/lib/level.mjs

@@ -0,0 +1,41 @@
+/**
+ * Scale-adaptive рівень задачі (ідея з BMAD project-levels, у наших термінах).
+ * `init` визначає рівень за описом; рівень right-size'ить, скільки adversarial-
+ * рецензентів спавнить `flow review`, і які фази рекомендовані (контракт).
+ *
+ * Детекція — підрядками (case-insensitive), без regex (уникаємо slow-regex і
+ * проблем зі словомежами для кирилиці).
+ */
+
+/** L3 — велике/архітектурне. */
+const L3_KEYS = ['platform', 'migration', 'rewrite', 'architecture', 'enterprise', 'редизайн', 'міграц', 'переписат']
+/** L0 — тривіальне. */
+const L0_KEYS = ['fix', 'typo', 'bump', 'rename', 'hotfix', 'опечат', 'перейменув']
+/** L2 — багатофайлова фіча/рефактор. */
+const L2_KEYS = ['feature', 'epic', 'refactor', 'рефактор', 'фіча']
+
+/**
+ * Рівень складності задачі за описом: 0 (тривіальне) … 3 (архітектурне).
+ * Пріоритет: L3 > L0 > L2 > дефолт L1.
+ * @param {string} desc опис задачі
+ * @returns {0 | 1 | 2 | 3} рівень
+ */
+export function detectLevel(desc) {
+  const d = String(desc ?? '').toLowerCase()
+  const has = keys => keys.some(k => d.includes(k))
+  if (has(L3_KEYS)) return 3
+  if (has(L0_KEYS)) return 0
+  if (has(L2_KEYS)) return 2
+  return 1
+}
+
+/**
+ * Скільки adversarial-рецензентів спавнити для рівня (глибина review за ризиком).
+ * @param {number} level рівень 0..3
+ * @returns {number} кількість рецензентів (1..3)
+ */
+export function reviewersForLevel(level) {
+  if (level >= 3) return 3
+  if (level === 2) return 2
+  return 1
+}

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

@@ -0,0 +1,76 @@
+/**
+ * Agent↔agent brainstorm (bmad party-mode + superpowers dispatching у наших
+ * термінах): персони-субагенти пропонують погляди, суддя-субагент синтезує одну
+ * відповідь. Спільний для фази `spec` (mode: 'spec' — підходи) і `plan`
+ * (mode: 'plan' — JSON-кроки). Перевикористовує runner-інтерфейс Фасада B
+ * (`runStep(prompt, opts) => { ok, output }`, як `planner.mjs`/`active.mjs`).
+ *
+ * HITL: panel лише ПОВЕРТАЄ синтез — апрув людини й збереження артефакту робить
+ * агент за контрактом `flow.mdc` (фіксація — окрема команда `flow spec`/`flow plan`).
+ */
+
+/** Персони панелі: [ім'я, системний промпт]. */
+const PERSONAS = [
+  ['architect', 'Ти — architect. Запропонуй найчистішу архітектуру розв’язання. Стисло, по суті.'],
+  ['skeptic', 'Ти — skeptic. Назви ризики, граничні випадки і що може піти не так. Стисло.'],
+  ['tester', 'Ти — tester. Опиши, які тести доведуть коректність. Стисло.']
+]
+
+/**
+ * Промпт судді за режимом.
+ * @param {'spec' | 'plan'} mode режим синтезу
+ * @param {string} proposals склеєні думки персон
+ * @param {string} task опис задачі
+ * @returns {string} промпт судді
+ */
+function judgePrompt(mode, proposals, task) {
+  const head =
+    mode === 'plan'
+      ? [
+          'Синтезуй із думок персон ОДИН покроковий план реалізації.',
+          'Кожен крок — ≤ 5 хв розробки, з критерієм приймання.',
+          'Поверни ЛИШЕ JSON-масив без коментарів: [{ "task": "...", "acceptance": "..." }, ...].'
+        ]
+      : [
+          'Синтезуй із думок персон 2-3 підходи до розв’язання з рекомендацією й коротким дизайном.',
+          'Поверни людино-читабельний текст (Markdown).'
+        ]
+  return [...head, '', proposals, '', `Задача: ${task}`].join('\n')
+}
+
+/**
+ * Проводить панель і повертає синтез.
+ * @param {{ task: string, cwd: string, runner: { runStep: (p: string, o?: object) => { ok: boolean, output: string } | Promise<{ ok: boolean, output: string }> }, log?: (m: string) => void, mode?: 'spec' | 'plan' }} input ін'єкції
+ * @returns {Promise<{ task: string, acceptance?: string }[] | string | null>} кроки (plan), текст (spec) або null (фейл)
+ */
+export async function runPanel({ task, cwd, runner, log = console.error, mode = 'plan' }) {
+  if (!runner) {
+    log('panel: нема runner — режим --panel недоступний')
+    return null
+  }
+  const proposals = await Promise.all(
+    PERSONAS.map(async ([name, sys]) => {
+      const r = await runner.runStep(`${sys}\n\nЗадача: ${task}`, { cwd })
+      return `### ${name}\n${r.ok ? r.output : '(порожньо)'}`
+    })
+  )
+  const judge = await runner.runStep(judgePrompt(mode, proposals.join('\n\n'), task), { cwd })
+  if (!judge.ok) {
+    log('panel: суддя-синтез завершився помилкою')
+    return null
+  }
+  if (mode === 'spec') return judge.output
+
+  const start = judge.output.indexOf('[')
+  const end = judge.output.lastIndexOf(']')
+  if (start === -1 || end === -1 || end < start) {
+    log('panel: суддя не повернув JSON-план')
+    return null
+  }
+  try {
+    return JSON.parse(judge.output.slice(start, end + 1))
+  } catch {
+    log('panel: невалідний JSON синтезу')
+    return null
+  }
+}

package/scripts/dispatcher/lib/plan.mjs

@@ -0,0 +1,80 @@
+/**
+ * `flow plan [--panel] [<plan.md>]` — фаза плану (Пасивний Турнікет, lifecycle
+ * §4). Фіксує `docs/plans/<date>-<slug>.md`: дзеркалить кроки (`## Кроки`) у
+ * `.flow.json plan[]`, виставляє `status: planned`, верифікує ланцюг через
+ * read-only `trace`. Код не пише; лінки front-matter (`spec`/`flow`) пише агент.
+ *
+ * Brainstorm: human↔agent (агент пише plan-doc у діалозі) або agent↔agent
+ * (`--panel`: панель персон → суддя синтезує кроки).
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { cwd as processCwd } from 'node:process'
+
+import { extractSteps, resolveArtifact, verifyTrace } from './artifact.mjs'
+import { flowEventsPath } from './events.mjs'
+import { parsePlan } from './planner.mjs'
+import { runPanel } from './plan-panel.mjs'
+import { createRunner } from './subagent-runner.mjs'
+import { flowStatePath, readState, recordTransition } from './state-store.mjs'
+
+/**
+ * @param {string[]} rest аргументи (`--panel`, опц. `<plan.md>`)
+ * @param {{ cwd?: string, log?: (m: string) => void, runner?: object, trace?: (cwd: string) => number, now?: () => number }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code (0 ok, 1 нема стану/доку/невалідний план)
+ */
+export async function plan(rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const statePath = flowStatePath(cwd)
+  const state = readState(statePath)
+  if (!state) {
+    log('plan: стану нема — спершу `flow init`')
+    return 1
+  }
+  if (state.status !== 'spec' && !state.spec_doc) {
+    log('plan: дизайн ще не зафіксовано — рекомендовано спершу `flow spec` (не блокує)')
+  }
+
+  const doc = rest.find(a => a.endsWith('.md')) ?? resolveArtifact(cwd, 'plans')
+  let steps
+  if (rest.includes('--panel')) {
+    let runner = deps.runner
+    if (!runner) {
+      try {
+        runner = await createRunner(deps)
+      } catch (error) {
+        log(`plan: ${error.message}`)
+        return 1
+      }
+    }
+    steps = await runPanel({ task: state.branch, cwd, runner, log, mode: 'plan' })
+    if (!steps) return 1
+  } else {
+    if (!doc || !existsSync(doc)) {
+      log('plan: нема docs/plans/<date>-<slug>.md — спершу пройди brainstorm (див. flow.mdc)')
+      return 1
+    }
+    steps = extractSteps(readFileSync(doc, 'utf8'))
+  }
+
+  let normalized
+  try {
+    normalized = parsePlan(JSON.stringify(steps))
+  } catch (error) {
+    log(`plan: ${error.message}`)
+    return 1
+  }
+
+  if (!verifyTrace(cwd, deps.trace)) {
+    log('⚠️ plan: trace виявив розрив ланцюга — перевір лінки spec/plan/flow')
+  }
+
+  recordTransition(
+    { statePath, eventsPath: flowEventsPath(cwd) },
+    { type: 'plan', steps: normalized.length },
+    s => ({ ...s, plan: normalized, plan_doc: doc ?? null, status: 'planned' }),
+    deps.now ?? Date.now
+  )
+  log(`plan: зафіксовано ${normalized.length} кроків → status: planned`)
+  return 0
+}

package/scripts/dispatcher/lib/planner.mjs

@@ -4,6 +4,9 @@
  * Нормалізує кроки до `{ step, task, status: 'pending', retry_count: 0 }`.
  */
 
+/** Заборонені плейсхолдер-значення `task` (план із ними — не план, fail-closed). */
+const PLACEHOLDER = /^(tbd|todo|fixme|\.\.\.|placeholder)$/i
+
 /**
  * Системно-користувацький промпт планувальника.
  * @param {string} task опис фічі
@@ -45,6 +48,10 @@ export function parsePlan(text) {
     if (!task || typeof task !== 'string') {
       throw new Error(`planner: крок ${i} без текстового поля task — fail-closed`)
     }
+    const trimmed = task.trim()
+    if (!trimmed || PLACEHOLDER.test(trimmed)) {
+      throw new Error(`planner: крок ${i} — placeholder/порожній task (${task}) — fail-closed`)
+    }
     const step = { step: i, task, status: 'pending', retry_count: 0 }
     if (s?.acceptance) step.acceptance = String(s.acceptance)
     return step

package/scripts/dispatcher/lib/review.mjs

@@ -0,0 +1,150 @@
+/**
+ * `flow review` — adversarial-перевірка коду ПІСЛЯ написання (ідея з BMAD
+ * quick-dev: self-check → adversarial-review). Незалежний субагент читає ЛИШЕ
+ * `git diff base_commit` і шукає логічні баги/ризики, яких не ловлять механічні
+ * гейти `verify` (lint+coverage). Findings пишуться у `.flow.json`; команда
+ * інформативна (м'які ворота — завжди код 0). Кількість рецензентів — за `level`.
+ *
+ * Уся IO (`run`/`runner`/`now`) ін'єктується — тестується без git/LLM.
+ */
+import { cwd as processCwd } from 'node:process'
+
+import { realRun } from './commands.mjs'
+import { flowEventsPath } from './events.mjs'
+import { reviewersForLevel } from './level.mjs'
+import { flowStatePath, readState, recordTransition } from './state-store.mjs'
+import { createRunner } from './subagent-runner.mjs'
+
+/** Ліміт diff у промпті (символів) — щоб не роздувати контекст рецензента. */
+const DIFF_LIMIT = 12_000
+
+/**
+ * Текст diff від base: `base...HEAD` (закомічене) + `git diff` (робоче дерево).
+ * @param {string} base базовий комміт
+ * @param {(cmd: string, args: string[], opts: object) => { stdout: string }} run git-runner
+ * @param {string} cwd worktree
+ * @returns {string} склеєний diff (trim)
+ */
+export function diffFromBase(base, run, cwd) {
+  const committed = run('git', ['diff', `${base}...HEAD`], { cwd })
+  const working = run('git', ['diff'], { cwd })
+  return `${committed.stdout ?? ''}\n${working.stdout ?? ''}`.trim()
+}
+
+/**
+ * Промпт adversarial-рецензента (читає ЛИШЕ diff).
+ * @param {string} diff текст diff
+ * @returns {string} промпт
+ */
+export function reviewerPrompt(diff) {
+  return [
+    'Ти — прискіпливий adversarial-рецензент. Знайди баги, ризики й smells ЛИШЕ в цьому diff.',
+    'Поверни ЛИШЕ JSON-масив: [{ "severity": "high|med|low", "file": "...", "issue": "...", "suggestion": "..." }].',
+    'Якщо проблем нема — поверни [].',
+    '',
+    diff.slice(0, DIFF_LIMIT)
+  ].join('\n')
+}
+
+/**
+ * Парсить findings із відповіді рецензента. Fail-soft: сміття/невалідний JSON → [].
+ * @param {string} text відповідь субагента
+ * @returns {{ severity?: string, file?: string, issue?: string, suggestion?: string }[]} findings
+ */
+export function parseFindings(text) {
+  const s = String(text)
+  const start = s.indexOf('[')
+  const end = s.lastIndexOf(']')
+  if (start === -1 || end === -1 || end < start) return []
+  try {
+    const arr = JSON.parse(s.slice(start, end + 1))
+    return Array.isArray(arr) ? arr : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * Дедуплікує findings за (file, issue).
+ * @param {object[]} findings вхідні
+ * @returns {object[]} без дублікатів
+ */
+export function dedupeFindings(findings) {
+  const seen = new Set()
+  const out = []
+  for (const f of findings) {
+    const key = `${f?.file ?? ''}::${f?.issue ?? ''}`
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(f)
+  }
+  return out
+}
+
+/**
+ * Іконка за severity finding-а.
+ * @param {string} severity рівень
+ * @returns {string} емодзі
+ */
+function severityIcon(severity) {
+  if (severity === 'high') return '🔴'
+  if (severity === 'med') return '🟡'
+  return '⚪'
+}
+
+/**
+ * `flow review` — спавнить adversarial-рецензента(ів) на diff від base.
+ * @param {string[]} _rest аргументи (не використовуються)
+ * @param {{ cwd?: string, log?: (m: string) => void, run?: (cmd: string, args: string[], opts: object) => { stdout: string }, runner?: object, now?: () => number }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code (0 завжди — інформативна; 1 лише якщо нема стану/runner)
+ */
+export async function review(_rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const run = deps.run ?? realRun
+  const now = deps.now ?? Date.now
+
+  const statePath = flowStatePath(cwd)
+  const state = readState(statePath)
+  if (!state) {
+    log('review: стану нема — спершу `flow init`')
+    return 1
+  }
+
+  const base = state.metadata?.base_commit ?? 'HEAD~1'
+  const diff = diffFromBase(base, run, cwd)
+  if (!diff) {
+    log('review: нема змін від base — нічого ревʼювити')
+    return 0
+  }
+
+  let runner = deps.runner
+  if (!runner) {
+    try {
+      runner = await createRunner(deps)
+    } catch (error) {
+      log(`review: ${error.message}`)
+      return 1
+    }
+  }
+
+  const reviewers = reviewersForLevel(state.level ?? 1)
+  const prompt = reviewerPrompt(diff)
+  const results = await Promise.all(Array.from({ length: reviewers }, () => runner.runStep(prompt, { cwd })))
+  const findings = dedupeFindings(results.flatMap(r => (r.ok ? parseFindings(r.output) : [])))
+
+  recordTransition(
+    { statePath, eventsPath: flowEventsPath(cwd) },
+    { type: 'review', findings: findings.length },
+    s => ({ ...s, review: { at: new Date(now()).toISOString(), reviewers, findings } }),
+    now
+  )
+
+  for (const f of findings) {
+    log(`${severityIcon(f.severity)} ${f.file ?? '?'}: ${f.issue ?? ''}`)
+  }
+  const high = findings.filter(f => f.severity === 'high').length
+  if (high > 0) log(`⚠️ review: ${high} high-severity — рекомендовано виправити перед release`)
+  log(`review: ${findings.length} findings (рецензентів: ${reviewers})`)
+  return 0
+}

package/scripts/dispatcher/lib/spec.mjs

@@ -0,0 +1,68 @@
+/**
+ * `flow spec [--panel] [<spec.md>]` — фаза дизайну (Пасивний Турнікет, lifecycle
+ * §3). Фіксує `docs/specs/<date>-<slug>.md` (дизайн із brainstorm) у стані й
+ * верифікує ланцюг через read-only `trace`. Код не пише; лінки front-matter
+ * пише агент за контрактом `flow.mdc`.
+ *
+ * Brainstorm: human↔agent — у діалозі IDE-агента (контракт); agent↔agent —
+ * `--panel` (панель персон → суддя, синтез презентується людині).
+ */
+import { existsSync } from 'node:fs'
+import { cwd as processCwd } from 'node:process'
+
+import { resolveArtifact, verifyTrace } from './artifact.mjs'
+import { flowEventsPath } from './events.mjs'
+import { runPanel } from './plan-panel.mjs'
+import { createRunner } from './subagent-runner.mjs'
+import { flowStatePath, readState, recordTransition } from './state-store.mjs'
+
+/**
+ * @param {string[]} rest аргументи (`--panel`, опц. `<spec.md>`)
+ * @param {{ cwd?: string, log?: (m: string) => void, runner?: object, trace?: (cwd: string) => number, now?: () => number }} [deps] ін'єкції
+ * @returns {Promise<number>} exit code (0 ok, 1 нема стану/доку)
+ */
+export async function spec(rest, deps = {}) {
+  const cwd = deps.cwd ?? processCwd()
+  const log = deps.log ?? console.error
+  const statePath = flowStatePath(cwd)
+  const state = readState(statePath)
+  if (!state) {
+    log('spec: стану нема — спершу `flow init`')
+    return 1
+  }
+
+  if (rest.includes('--panel')) {
+    let runner = deps.runner
+    if (!runner) {
+      try {
+        runner = await createRunner(deps)
+      } catch (error) {
+        log(`spec: ${error.message}`)
+        return 1
+      }
+    }
+    const synth = await runPanel({ task: state.branch, cwd, runner, log, mode: 'spec' })
+    if (synth) {
+      log('spec: панель синтезувала підходи (нижче) — збережи дизайн у docs/specs/ і повтори `flow spec`:')
+      log(typeof synth === 'string' ? synth : JSON.stringify(synth))
+    }
+  }
+
+  const doc = rest.find(a => a.endsWith('.md')) ?? resolveArtifact(cwd, 'specs')
+  if (!doc || !existsSync(doc)) {
+    log('spec: нема docs/specs/<date>-<slug>.md — спершу пройди brainstorm (див. flow.mdc)')
+    return 1
+  }
+  if (!verifyTrace(cwd, deps.trace)) {
+    log('⚠️ spec: trace виявив розрив ланцюга — перевір лінки front-matter (adr/spec/plan)')
+  }
+
+  recordTransition(
+    { statePath, eventsPath: flowEventsPath(cwd) },
+    { type: 'spec' },
+    s => ({ ...s, spec_doc: doc, status: 'spec' }),
+    deps.now ?? Date.now
+  )
+  log(`spec: зафіксовано ${doc} → status: spec`)
+  return 0
+}

package/scripts/dispatcher/trace.mjs

@@ -11,7 +11,7 @@ import { join } from 'node:path'
 import { cwd as processCwd } from 'node:process'
 
 /** Поля-лінки у front-matter, що утворюють ланцюг. */
-const LINK_FIELDS = ['adr', 'spec', 'plan', 'change', 'task']
+const LINK_FIELDS = ['adr', 'spec', 'plan', 'flow', 'change', 'task']
 
 /** Каталоги з traceable-артефактами. */
 const DIRS = ['docs/tasks', 'docs/specs', 'docs/plans', 'docs/adr']