@nitra/cursor 3.10.0 → 3.12.0

package/rules/test/coverage/coverage.mjs

@@ -19,6 +19,8 @@ import { fileURLToPath, pathToFileURL } from 'node:url'
 
 import { applyVerdicts } from '../../../scripts/coverage-classify/apply.mjs'
 import { classify } from '../../../scripts/coverage-classify/index.mjs'
+import { flowStatePath, readState } from '../../../scripts/dispatcher/lib/state-store.mjs'
+import { collectChangedFilesSince } from '../../../scripts/lib/changed-files.mjs'
 import { readNCursorConfigLite } from '../../../scripts/lib/read-n-cursor-config-lite.mjs'
 import { withLock } from '../../../scripts/utils/with-lock.mjs'
 
@@ -194,18 +196,46 @@ async function readClassifyThreshold(cwd) {
   }
 }
 
+/**
+ * Резолвить scope змінених файлів для `--changed`-режиму.
+ *
+ * Base — `metadata.base_commit` зі стану flow (sibling-файл `.flow.json` поруч із
+ * worktree-checkout). `git diff <base>` проти робочого дерева ловить committed і
+ * uncommitted однаково — тож scope не залежить від того, чи executor уже закомітив
+ * крок. Поза flow (нема/пошкоджений стан) — fallback на робоче дерево vs HEAD.
+ * @param {string} cwd корінь проєкту (= worktree-checkout у межах flow)
+ * @returns {{base: string|null, files: string[]}} base-ref і relative-posix список змінених файлів
+ */
+function resolveChangedScope(cwd) {
+  let base = null
+  try {
+    const state = readState(flowStatePath(cwd))
+    base = state?.metadata?.base_commit ?? null
+  } catch {
+    // пошкоджений/несумісний стан — попереджаємо й падаємо на HEAD (working-tree scope).
+    console.error('coverage --changed: стан flow нечитабельний — scope визначається від HEAD робочого дерева')
+    base = null
+  }
+  return { base, files: collectChangedFilesSince(base, cwd) }
+}
+
 /**
  * Виконує coverage-pipeline: discovery провайдерів за `.n-cursor.json#rules`,
  * detect+collect для кожного, агрегація, запис COVERAGE.md.
  * При `opts.fix === true` після запису COVERAGE.md запускає агента (coverage-fix.mjs)
  * для написання тестів по вцілілих мутантах.
- * @param {{cwd?:string, rulesDir?:string, fix?:boolean}} [opts] ін'єкція cwd/rulesDir для тестів; fix — --fix режим
- * @returns {Promise<number>} exit code (0 OK, 1 коли жоден провайдер не дав даних)
+ * При `opts.changed === true` провайдери звужують scope до змінених від base файлів
+ * (для flow-турнікета). Порожній scope (нема релевантних змін) — це pass (exit 0)
+ * без перезапису наявного COVERAGE.md, а НЕ помилка «жодного провайдера».
+ * @param {{cwd?:string, rulesDir?:string, fix?:boolean, changed?:boolean}} [opts] ін'єкція cwd/rulesDir для тестів; fix — --fix режим; changed — scope лише змінених
+ * @returns {Promise<number>} exit code (0 OK, 1 коли жоден провайдер не дав даних у full-режимі)
  */
 export async function runCoverageSteps(opts = {}) {
   const cwd = opts.cwd ?? process.cwd()
   const rulesDir = opts.rulesDir ?? RULES_DIR
   const config = await readNCursorConfigLite(cwd)
+  const scope = opts.changed ? resolveChangedScope(cwd) : null
+  const collectOpts = scope ? { changedFiles: scope.files, base: scope.base } : {}
   const rows = []
 
   for (const ruleId of config.rules) {
@@ -214,14 +244,27 @@ export async function runCoverageSteps(opts = {}) {
     if (!provider) continue
     if (!(await provider.detect(cwd))) continue
     console.log(`→ ${ruleId} coverage…`)
-    rows.push(...(await provider.collect(cwd)))
+    rows.push(...(await provider.collect(cwd, collectOpts)))
   }
 
   if (rows.length === 0) {
+    // --changed: порожній scope = «нема релевантних змін» → pass, не чіпаємо COVERAGE.md.
+    if (opts.changed) {
+      console.log('✓ coverage --changed: немає змінених файлів у scope провайдерів — пропускаю')
+      return 0
+    }
     console.error('✗ Жодного провайдера покриття не знайдено для активних правил у .n-cursor.json#rules')
     return 1
   }
 
+  // --changed (турнікет): рішення гейту визначає лише exit-код — vitest/Stryker кинули б помилку
+  // під час collect, якби тести/прогін упали. Тут НЕ перезаписуємо повний COVERAGE.md частковим
+  // scoped-звітом і не ганяємо LLM-класифікацію (зайвий кошт у per-step циклі).
+  if (opts.changed) {
+    console.log('✓ coverage --changed: змінені файли перевірено')
+    return 0
+  }
+
   // LLM-класифікація survived мутантів (graceful skip без API key)
   const allSurvived = rows.flatMap(r => r.survived ?? [])
   let augmentedRows = rows
@@ -256,18 +299,19 @@ export async function runCoverageSteps(opts = {}) {
 }
 
 /**
- * CLI entrypoint для `n-cursor coverage [--fix]`.
+ * CLI entrypoint для `n-cursor coverage [--fix] [--changed]`.
  * Із `--fix`: збирає метрики → запускає агента → повторно збирає метрики.
  * Без `--fix`: лише збирає метрики.
+ * Із `--changed`: звужує scope до змінених від base файлів (flow-турнікет).
  * Лок охоплює кожен coverage-прогін окремо.
- * @param {{fix?:boolean}} [opts] прапор --fix
+ * @param {{fix?:boolean, changed?:boolean}} [opts] прапори --fix / --changed
  * @returns {Promise<number>} exit code
  */
 export async function runCoverageCli(opts = {}) {
   const code = await withLock('coverage', () => runCoverageSteps(opts))
   if (code === 0 && opts.fix) {
     console.log('\n♻️  Повторний coverage після агента…\n')
-    return withLock('coverage', () => runCoverageSteps({ fix: false }))
+    return withLock('coverage', () => runCoverageSteps({ fix: false, changed: opts.changed }))
   }
   return code
 }

package/rules/test/test.mdc

@@ -130,6 +130,8 @@ test.skipIf(env.STRYKER_MUTATOR_WORKER)('узгоджені з поточним
 
 Канонічна команда — `n-cursor coverage`: збирає метрики покриття (`vitest run --coverage`, `cargo llvm-cov` тощо) і мутаційного тестування (Stryker з vitest-runner + `coverageAnalysis: 'perTest'`, `cargo-mutants`) з усіх активних провайдерів у `.n-cursor.json#rules` і пише `COVERAGE.md` у корінь проєкту. Лок і дедуп — `withLock('coverage', ...)`.
 
+**Scoped-режим `--changed`** (для flow-турнікета): `n-cursor coverage --changed` звужує scope до файлів, змінених від `base_commit` (зі стану flow `.flow.json`; поза flow — робоче дерево vs HEAD). `git diff <base>` проти робочого дерева ловить committed і uncommitted однаково, тож результат не залежить від того, чи крок уже закомічено. Недосяжний `base` (rebase/force-update) — fail-closed (помилка, не тихий pass). JS-провайдер ганяє `vitest --changed <base>` (лише зачеплені тести) і Stryker `--mutate` по змінених production-файлах (тест-файли відкидаються); roots без змінених JS пропускаються. Rust-провайдер пропускається, якщо не змінено `.rs`/`Cargo.*` (інакше — повний crate-прогін; per-file scoping cargo-mutants — окремий крок). Порожній scope (нема релевантних змін) — pass. У changed-режимі `COVERAGE.md` **не** перезаписується (рішення гейту — лише exit-код) і LLM-класифікація не запускається. `DEFAULT_GATES` турнікета викликає саме `coverage --changed`; повний coverage (увесь проєкт, запис `COVERAGE.md`) лишається для `bun run coverage` / `/n-coverage-fix`.
+
 Провайдери живуть у `npm/rules/<rule>/coverage/coverage.mjs` (постачаються правилами мови/рантайму: `js-lint`, `rust`, у майбутньому `python` тощо). Оркестратор — у `npm/rules/test/coverage/coverage.mjs`.
 
 У `package.json` (корінь) має бути `scripts.coverage` із викликом `n-cursor coverage`:

package/scripts/dispatcher/index.mjs

@@ -35,19 +35,52 @@ const USAGE = [
  */
 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 }
+}
+
 /**
  * Точка входу `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>> }} [deps] ін'єкція handler-ів (для тестів)
+ * @param {{ handlers?: Record<string, (rest: string[], deps: object) => Promise<number>>, branch?: string }} [deps] ін'єкція handler-ів (для тестів)
  * @returns {Promise<number>} exit code
  */
 export async function runFlowCli(args, deps = {}) {
-  const [sub, ...rest] = args
+  const [sub, ...raw] = args
   const handlers = deps.handlers ?? DEFAULT_HANDLERS
   if (!sub || ! Object.hasOwn(handlers, sub)) {
     console.error(USAGE)
     return 1
   }
-  return await handlers[sub](rest, deps)
+  const { rest, branch } = extractBranchFlag(raw)
+  return await handlers[sub](rest, { ...deps, branch: deps.branch ?? branch })
 }

package/scripts/dispatcher/lib/commands.mjs

@@ -10,12 +10,15 @@ import { isAbsolute, join } from 'node:path'
 import { cwd as processCwd } from 'node:process'
 
 import { worktreePaths } from '../../lib/worktree.mjs'
+import { collectChangedFilesSince } from '../../lib/changed-files.mjs'
 import { worktreeFingerprint } from '../../utils/worktree-fingerprint.mjs'
+import { getMonorepoProjectRootDirs } from '../../../rules/changelog/lib/package-manifest.mjs'
 import { flowEventsPath } from './events.mjs'
 import { detectLevel, detectRisk } from './level.mjs'
 import { runReview } from './reviewer.mjs'
 import { buildCompletionSnapshot, writeSummaryToTaskRecord } from './snapshot.mjs'
 import { flowStatePath, readState, recordTransition, writeState } from './state-store.mjs'
+import { resolveActiveFlowState } from './flow-resolve.mjs'
 
 /**
  * Реальний sync-runner із захопленням виводу.
@@ -127,12 +130,34 @@ export async function init(rest, deps = {}) {
  */
 export async function verify(_rest, deps = {}) {
   const run = deps.run ?? realRun
-  const cwd = deps.cwd ?? processCwd()
+  const cwd0 = deps.cwd ?? processCwd()
   const log = deps.log ?? console.error
-  const fingerprint = deps.fingerprint ?? (() => worktreeFingerprint())
 
-  const statePath = flowStatePath(cwd)
-  const state = readState(statePath)
+  // cwd-незалежний резолв активного flow. verify толерантний: без активного flow
+  // гейти все одно прогоняються (standalone) у поточному cwd, лише без запису стану.
+  const resolved = resolveActiveFlowState({ cwd: cwd0, branch: deps.branch }, deps)
+  if (resolved.statePath && resolved.autoResolved) {
+    log(`flow: авторезолвлено активний flow «${resolved.label}» (cwd поза worktree)`)
+  }
+  // Явний `--branch`, що не резолвиться, — це помилка наміру: не деградуємо тихо
+  // на поточний cwd (інакше `flow verify --branch typo` міг би «зеленіти» в CI).
+  if (deps.branch && !resolved.statePath) {
+    log(`❌ verify: ${resolved.error}`)
+    return 1
+  }
+  const cwd = resolved.worktreeDir ?? cwd0
+  const fingerprint =
+    deps.fingerprint ?? (() => worktreeFingerprint((cmd, args, opts) => spawnSync(cmd, args, { ...opts, cwd })))
+
+  const statePath = resolved.statePath
+  const state = statePath ? readState(statePath) : null
+  if (!state) {
+    // statePath null → resolved.error пояснює (нема/кілька активних); statePath є,
+    // але стан не читається → пошкоджений .flow.json. В обох випадках verify
+    // толерантний: гейти прогоняються standalone у `cwd`, без запису стану.
+    if (resolved.error) log(`⚠️ verify: ${resolved.error}`)
+    log(`⚠️ verify: активного flow не визначено — гейти прогнано у ${cwd} без запису стану`)
+  }
   // М'які ворота: відсутній план — лише попередження, exit-код визначають gate-и.
   if (state && !(state.plan?.length)) {
     log('⚠️ verify: плану не зафіксовано (`flow plan`) — рекомендовано спершу сформувати план')
@@ -162,6 +187,56 @@ export async function verify(_rest, deps = {}) {
   return verdict.pass ? 0 : 1
 }
 
+/**
+ * Які з subworkspace-тек мають змінені файли — для авто-`--ws` у `release`.
+ * Кожен файл відноситься до НАЙГЛИБШОГО воркспейсу-збігу, тож вкладені воркспейси
+ * (`apps` + `apps/web`) не дають хибного «кілька воркспейсів» для `apps/web/x`.
+ * @param {string[]} subWorkspaces теки воркспейсів без кореня (`.`)
+ * @param {string[]} changedFiles змінені шляхи відносно кореня репо (posix)
+ * @returns {string[]} підмножина `subWorkspaces`, під якими є зміни (у вхідному порядку)
+ */
+export function matchChangedWorkspaces(subWorkspaces, changedFiles) {
+  const byDepthDesc = subWorkspaces.toSorted((a, b) => b.length - a.length)
+  const hit = new Set()
+  for (const f of changedFiles) {
+    const ws = byDepthDesc.find(w => f === w || f.startsWith(`${w}/`))
+    if (ws) hit.add(ws)
+  }
+  return subWorkspaces.filter(w => hit.has(w))
+}
+
+/**
+ * Додає `--ws <шлях>` до аргументів `change`, інферячи воркспейс зі змін від
+ * `base_commit`, якщо `--ws` не задано явно. Один змінений subworkspace → авто-`--ws`;
+ * кілька → `{ error: true }` (fail-hard, exit 1 у release); нуль / без subworkspace →
+ * лишаємо як є (change дефолтиться на `.`). Помилку самого інференсу (недосяжний base,
+ * збій `listWorkspaces`) трактуємо fail-soft — не блокуємо, лишаємо дефолт.
+ * @param {{ rest: string[], baseCommit: string | null, cwd: string, listWorkspaces: (cwd: string) => Promise<string[]>, changedFilesSince: (base: string | null, cwd: string) => string[], log: (m: string) => void }} input ін'єкції
+ * @returns {Promise<{ args: string[], error?: boolean }>} аргументи для `change` або `{ error: true }`
+ */
+async function resolveChangeWsArgs({ rest, baseCommit, cwd, listWorkspaces, changedFilesSince, log }) {
+  // Поважаємо явно заданий воркспейс в обох формах (`--ws x` і `--ws=x`).
+  if (rest.includes('--ws') || rest.some(a => a.startsWith('--ws='))) return { args: rest }
+  try {
+    const workspaces = await listWorkspaces(cwd)
+    const subWs = workspaces.filter(w => w !== '.')
+    if (subWs.length === 0) return { args: rest }
+    const hits = matchChangedWorkspaces(subWs, changedFilesSince(baseCommit, cwd))
+    if (hits.length > 1) {
+      log(`release: зміни у кількох воркспейсах (${hits.join(', ')}) — вкажи --ws явно`)
+      return { args: rest, error: true }
+    }
+    if (hits.length === 1) {
+      log(`release: change → воркспейс «${hits[0]}» (інферено з diff від base)`)
+      return { args: [...rest, '--ws', hits[0]] }
+    }
+    return { args: rest }
+  } catch (error) {
+    log(`⚠️ release: інференс воркспейсу пропущено (${error instanceof Error ? error.message : String(error)})`)
+    return { args: rest }
+  }
+}
+
 /**
  * `flow release [--bump … --section … --message …]` — генерує `.changes` і пише
  * completion snapshot (§3 Ф5, §7). Потребує наявного стану (`init`).
@@ -175,7 +250,14 @@ export async function release(rest, deps = {}) {
   const log = deps.log ?? console.error
   const now = deps.now ?? Date.now
 
-  const statePath = flowStatePath(cwd)
+  const resolved = resolveActiveFlowState({ cwd, branch: deps.branch }, deps)
+  if (!resolved.statePath) {
+    log(`release: ${resolved.error}`)
+    return 1
+  }
+  if (resolved.autoResolved) log(`flow: авторезолвлено активний flow «${resolved.label}» (cwd поза worktree)`)
+  const effectiveCwd = resolved.worktreeDir ?? cwd
+  const statePath = resolved.statePath
   const state = readState(statePath)
   if (!state) {
     log('release: стану нема — спершу `flow init`')
@@ -186,7 +268,17 @@ export async function release(rest, deps = {}) {
     log(`⚠️ release: gate = FAIL (score ${state.gate.score}) — релізиш свідомо? (див. flow gate)`)
   }
 
-  const ch = run('npx', ['@nitra/cursor', 'change', ...rest], { cwd })
+  const wsResolved = await resolveChangeWsArgs({
+    rest,
+    baseCommit: state.metadata?.base_commit ?? null,
+    cwd: effectiveCwd,
+    listWorkspaces: deps.listWorkspaces ?? getMonorepoProjectRootDirs,
+    changedFilesSince: deps.changedFilesSince ?? collectChangedFilesSince,
+    log
+  })
+  if (wsResolved.error) return 1
+
+  const ch = run('npx', ['@nitra/cursor', 'change', ...wsResolved.args], { cwd: effectiveCwd })
   if ((ch.status ?? 1) !== 0) {
     const detail = ch.stderr ? `: ${ch.stderr.trim()}` : ''
     log(`release: change не вдався${detail}`)
@@ -195,13 +287,13 @@ export async function release(rest, deps = {}) {
 
   const snapshot = buildCompletionSnapshot({ ...state, status: 'done' }, now)
   recordTransition(
-    { statePath, eventsPath: flowEventsPath(cwd) },
+    { statePath, eventsPath: flowEventsPath(effectiveCwd) },
     { type: 'release' },
     state_ => ({ ...state_, status: 'done', completion: snapshot }),
     now
   )
   if (state.task) {
-    writeSummaryToTaskRecord(isAbsolute(state.task) ? state.task : join(cwd, state.task), snapshot)
+    writeSummaryToTaskRecord(isAbsolute(state.task) ? state.task : join(effectiveCwd, state.task), snapshot)
   }
   log('release: done')
   return 0

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

@@ -0,0 +1,154 @@
+/**
+ * cwd-незалежний резолвер активного flow (беклог адаптації #1).
+ *
+ * Команди `spec/plan/verify/review/gate/release` мають знаходити `.flow.json`
+ * поточної задачі навіть коли їх запущено НЕ з кореня worktree (напр. з головного
+ * дерева чи з підтеки worktree) — інакше `flowStatePath(cwd)` обчислює хибний шлях
+ * і видає «стану нема», хоча flow активний.
+ *
+ * Порядок (spec 2026-06-01-flow-cwd-state-resolution):
+ *  1. явний `branch` → `.worktrees/<sanitizeBranch>.flow.json`;
+ *  2. toplevel-резолвинг: `git rev-parse --show-toplevel` від `cwd`; якщо toplevel
+ *     лежить безпосередньо під `<repoRoot>/.worktrees/` і для нього є стан — беремо;
+ *  3. скан `<repoRoot>/.worktrees/*.flow.json` зі `status: in_progress`: рівно один →
+ *     авторезолв; кілька → помилка зі списком; нуль → «стану нема».
+ *
+ * Резолвер не пише на диск. `git`/FS ін'єктуються — тестується без репозиторію.
+ */
+import { existsSync, readdirSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+import { basename, dirname, join } from 'node:path'
+import { cwd as processCwd } from 'node:process'
+
+import { sanitizeBranch, worktreePaths } from '../../lib/worktree.mjs'
+import { flowStatePath, readState as defaultReadState } from './state-store.mjs'
+
+const FLOW_STATE_SUFFIX = '.flow.json'
+
+/**
+ * Реальний sync git-runner у заданому `cwd`.
+ * @param {string[]} args аргументи git
+ * @param {string} cwd робочий каталог
+ * @returns {{ status: number, stdout: string }} результат
+ */
+function realGit(args, cwd) {
+  const r = spawnSync('git', args, { encoding: 'utf8', cwd })
+  return { status: r.status ?? 1, stdout: r.stdout ?? '' }
+}
+
+/**
+ * Корінь головного worktree через `git worktree list --porcelain` (перший запис).
+ * @param {(args: string[]) => { status: number, stdout: string }} git git-runner
+ * @returns {string | null} абсолютний шлях кореня репо або `null`
+ */
+function mainRepoRoot(git) {
+  const r = git(['worktree', 'list', '--porcelain'])
+  if ((r.status ?? 1) !== 0) return null
+  const line = r.stdout.split('\n').find(l => l.startsWith('worktree '))
+  const root = line ? line.slice('worktree '.length).trim() : ''
+  return root.length > 0 ? root : null
+}
+
+/**
+ * Корінь поточного worktree (`git rev-parse --show-toplevel`).
+ * @param {(args: string[]) => { status: number, stdout: string }} git git-runner
+ * @returns {string | null} абсолютний шлях або `null`
+ */
+function currentToplevel(git) {
+  const r = git(['rev-parse', '--show-toplevel'])
+  return (r.status ?? 1) === 0 && r.stdout.trim().length > 0 ? r.stdout.trim() : null
+}
+
+/**
+ * @typedef {object} ResolvedFlow
+ * @property {string | null} statePath абсолютний шлях `.flow.json` або `null`
+ * @property {string | null} worktreeDir тека worktree (ефективний cwd для гейтів) або `null`
+ * @property {string | null} label мітка flow (sanitized branch) або `null`
+ * @property {boolean} autoResolved `true`, якщо знайдено скануванням (cwd поза worktree)
+ * @property {string | null} error повідомлення для логу, якщо `statePath === null`
+ */
+
+/**
+ * Резолвить активний flow незалежно від `cwd`.
+ * @param {{ cwd?: string, branch?: string }} [params] параметри
+ * @param {{ git?: (args: string[]) => { status: number, stdout: string }, exists?: (p: string) => boolean, readState?: (p: string) => object | null, readdir?: (d: string) => string[], repoRoot?: string }} [deps] ін'єкції
+ * @returns {ResolvedFlow} результат
+ */
+export function resolveActiveFlowState({ cwd = processCwd(), branch } = {}, deps = {}) {
+  const git = deps.git ?? (args => realGit(args, cwd))
+  const exists = deps.exists ?? existsSync
+  const readState = deps.readState ?? defaultReadState
+  const readdir = deps.readdir ?? (d => (existsSync(d) ? readdirSync(d) : []))
+
+  const resolveRoot = () => deps.repoRoot ?? mainRepoRoot(git)
+
+  // 1. Явний --branch завжди перемагає. Валідуємо існування теки worktree, щоб
+  //    команда не пішла виконувати гейти в неіснуючому каталозі (ENOENT).
+  if (branch) {
+    const repoRoot = resolveRoot()
+    if (!repoRoot) return notFound('стану нема — спершу `flow init`')
+    const label = sanitizeBranch(branch)
+    const worktreeDir = worktreePaths(repoRoot, branch).checkout
+    if (!exists(worktreeDir)) {
+      return notFound(`worktree для гілки «${branch}» не знайдено (${worktreeDir}) — перевір назву або зроби \`flow init\``)
+    }
+    return { statePath: flowStatePath(worktreeDir), worktreeDir, label, autoResolved: false, error: null }
+  }
+
+  // 2. Швидкий шлях без git: `cwd` уже є текою worktree зі станом-sibling
+  //    (звичайний запуск із кореня worktree).
+  const direct = flowStatePath(cwd)
+  if (exists(direct)) {
+    return { statePath: direct, worktreeDir: cwd, label: basename(cwd), autoResolved: false, error: null }
+  }
+
+  // Далі потрібен корінь репо (git). Якщо недоступний — трактуємо як «стану нема».
+  const repoRoot = resolveRoot()
+  if (!repoRoot) return notFound('стану нема — спершу `flow init`')
+  const worktreesDir = join(repoRoot, '.worktrees')
+
+  // 3. Якщо ми ВСЕРЕДИНІ worktree (toplevel під .worktrees/, у т.ч. з підтеки) —
+  //    беремо стан саме цього worktree. Якщо його нема — це проблема цього worktree
+  //    (`flow init` не зроблено); чужий активний flow НЕ підтягуємо.
+  const top = currentToplevel(git)
+  if (top && dirname(top) === worktreesDir) {
+    const statePath = flowStatePath(top)
+    if (exists(statePath)) {
+      return { statePath, worktreeDir: top, label: basename(top), autoResolved: false, error: null }
+    }
+    return notFound('стану нема — спершу `flow init`')
+  }
+
+  // 4. Поза worktree (головне дерево) — скан активних flow.
+  const active = []
+  for (const name of readdir(worktreesDir)) {
+    if (!name.endsWith(FLOW_STATE_SUFFIX)) continue
+    const statePath = join(worktreesDir, name)
+    let state
+    try {
+      state = readState(statePath)
+    } catch {
+      continue // пошкоджений стан — пропускаємо при скануванні
+    }
+    if (state?.status === 'in_progress') {
+      const label = name.slice(0, -FLOW_STATE_SUFFIX.length)
+      active.push({ statePath, worktreeDir: join(worktreesDir, label), label })
+    }
+  }
+  if (active.length === 1) {
+    return { ...active[0], autoResolved: true, error: null }
+  }
+  if (active.length > 1) {
+    const list = active.map(a => `  - ${a.label}`).join('\n')
+    return notFound(`кілька активних flow — уточни \`--branch <гілка>\` або \`cd\` у потрібний worktree:\n${list}`)
+  }
+  return notFound('стану нема — спершу `flow init`')
+}
+
+/**
+ * @param {string} error повідомлення
+ * @returns {ResolvedFlow} результат без statePath
+ */
+function notFound(error) {
+  return { statePath: null, worktreeDir: null, label: null, autoResolved: false, error }
+}

package/scripts/dispatcher/lib/gate.mjs

@@ -10,7 +10,8 @@
 import { cwd as processCwd } from 'node:process'
 
 import { flowEventsPath } from './events.mjs'
-import { flowStatePath, readState, recordTransition } from './state-store.mjs'
+import { readState, recordTransition } from './state-store.mjs'
+import { resolveActiveFlowState } from './flow-resolve.mjs'
 
 /** Штрафи score за кожен тип проблеми. */
 const PENALTY = { failedGate: 40, high: 25, med: 8, noVerify: 15 }
@@ -58,11 +59,18 @@ export function computeGate(state) {
  * @returns {Promise<number>} exit code (FAIL → 1; PASS/CONCERNS → 0)
  */
 export async function gate(_rest, deps = {}) {
-  const cwd = deps.cwd ?? processCwd()
+  const cwd0 = deps.cwd ?? processCwd()
   const log = deps.log ?? console.error
   const now = deps.now ?? Date.now
 
-  const statePath = flowStatePath(cwd)
+  const resolved = resolveActiveFlowState({ cwd: cwd0, branch: deps.branch }, deps)
+  if (!resolved.statePath) {
+    log(`gate: ${resolved.error}`)
+    return 1
+  }
+  if (resolved.autoResolved) log(`flow: авторезолвлено активний flow «${resolved.label}» (cwd поза worktree)`)
+  const cwd = resolved.worktreeDir ?? cwd0
+  const statePath = resolved.statePath
   const state = readState(statePath)
   if (!state) {
     log('gate: стану нема — спершу `flow init`')

package/scripts/dispatcher/lib/plan.mjs

@@ -15,7 +15,8 @@ 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'
+import { readState, recordTransition } from './state-store.mjs'
+import { resolveActiveFlowState } from './flow-resolve.mjs'
 
 /**
  * @param {string[]} rest аргументи (`--panel`, опц. `<plan.md>`)
@@ -23,9 +24,16 @@ import { flowStatePath, readState, recordTransition } from './state-store.mjs'
  * @returns {Promise<number>} exit code (0 ok, 1 нема стану/доку/невалідний план)
  */
 export async function plan(rest, deps = {}) {
-  const cwd = deps.cwd ?? processCwd()
+  const cwd0 = deps.cwd ?? processCwd()
   const log = deps.log ?? console.error
-  const statePath = flowStatePath(cwd)
+  const resolved = resolveActiveFlowState({ cwd: cwd0, branch: deps.branch }, deps)
+  if (!resolved.statePath) {
+    log(`plan: ${resolved.error}`)
+    return 1
+  }
+  if (resolved.autoResolved) log(`flow: авторезолвлено активний flow «${resolved.label}» (cwd поза worktree)`)
+  const cwd = resolved.worktreeDir ?? cwd0
+  const statePath = resolved.statePath
   const state = readState(statePath)
   if (!state) {
     log('plan: стану нема — спершу `flow init`')

package/scripts/dispatcher/lib/review.mjs

@@ -12,7 +12,8 @@ import { cwd as processCwd } from 'node:process'
 import { realRun } from './commands.mjs'
 import { flowEventsPath } from './events.mjs'
 import { reviewersFor } from './level.mjs'
-import { flowStatePath, readState, recordTransition } from './state-store.mjs'
+import { readState, recordTransition } from './state-store.mjs'
+import { resolveActiveFlowState } from './flow-resolve.mjs'
 import { createRunner } from './subagent-runner.mjs'
 
 /** Ліміт diff у промпті (символів) — щоб не роздувати контекст рецензента. */
@@ -108,12 +109,19 @@ function severityIcon(severity) {
  * @returns {Promise<number>} exit code (0 завжди — інформативна; 1 лише якщо нема стану/runner)
  */
 export async function review(_rest, deps = {}) {
-  const cwd = deps.cwd ?? processCwd()
+  const cwd0 = 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 resolved = resolveActiveFlowState({ cwd: cwd0, branch: deps.branch }, deps)
+  if (!resolved.statePath) {
+    log(`review: ${resolved.error}`)
+    return 1
+  }
+  if (resolved.autoResolved) log(`flow: авторезолвлено активний flow «${resolved.label}» (cwd поза worktree)`)
+  const cwd = resolved.worktreeDir ?? cwd0
+  const statePath = resolved.statePath
   const state = readState(statePath)
   if (!state) {
     log('review: стану нема — спершу `flow init`')

package/scripts/dispatcher/lib/reviewer.mjs

@@ -11,12 +11,16 @@
 import { worktreeFingerprint } from '../../utils/worktree-fingerprint.mjs'
 
 /**
- * Канонічний gate verify — лише `lint`. Coverage (vitest-покриття + Stryker-
- * мутації) навмисно ПОЗА turnstile: повний прогін надто довгий і ламкий у
- * worktree, тож тести/мутації запускаються окремо (`npx \@nitra/cursor coverage`)
- * або в CI, а не на кожному `flow verify`.
+ * Канонічні gate-и verify (lint + coverage; coverage включає тести+мутації).
+ * Обидва — scoped до змінених файлів: `lint` через quick-режим (`changed-files.mjs`),
+ * `coverage --changed` через vitest `--changed`/Stryker `--mutate` по diff від base.
+ * Турнікет (`flow verify`/per-step) перевіряє лише змінене; повний coverage —
+ * окремо (`bun run coverage`, `/n-coverage-fix`).
  */
-export const DEFAULT_GATES = [{ name: 'lint', cmd: ['npx', '@nitra/cursor', 'lint'] }]
+export const DEFAULT_GATES = [
+  { name: 'lint', cmd: ['npx', '@nitra/cursor', 'lint'] },
+  { name: 'coverage', cmd: ['npx', '@nitra/cursor', 'coverage', '--changed'] }
+]
 
 /**
  * Проганяє gate-и й повертає verdict.

package/scripts/dispatcher/lib/spec.mjs

@@ -14,7 +14,8 @@ 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'
+import { readState, recordTransition } from './state-store.mjs'
+import { resolveActiveFlowState } from './flow-resolve.mjs'
 import { parseFrontMatter } from '../trace.mjs'
 
 /** Допустимі значення ризику у spec-frontmatter. */
@@ -42,9 +43,16 @@ function riskFromSpec(doc, current) {
  * @returns {Promise<number>} exit code (0 ok, 1 нема стану/доку)
  */
 export async function spec(rest, deps = {}) {
-  const cwd = deps.cwd ?? processCwd()
+  const cwd0 = deps.cwd ?? processCwd()
   const log = deps.log ?? console.error
-  const statePath = flowStatePath(cwd)
+  const resolved = resolveActiveFlowState({ cwd: cwd0, branch: deps.branch }, deps)
+  if (!resolved.statePath) {
+    log(`spec: ${resolved.error}`)
+    return 1
+  }
+  if (resolved.autoResolved) log(`flow: авторезолвлено активний flow «${resolved.label}» (cwd поза worktree)`)
+  const cwd = resolved.worktreeDir ?? cwd0
+  const statePath = resolved.statePath
   const state = readState(statePath)
   if (!state) {
     log('spec: стану нема — спершу `flow init`')