@nitra/cursor 3.11.0 → 3.12.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [3.12.0] - 2026-06-02
+
+### Added
+
+- flow: cwd-незалежний резолвинг активного стану — spec/plan/verify/review/gate/release знаходять .flow.json поточної гілки навіть із головного дерева (швидкий шлях без git, toplevel-резолв, авторезолв єдиного активного flow), + опційний --branch <гілка>. Гейти виконуються у теці worktree.
+- flow release: інференс зміненого воркспейсу з diff від base_commit — авто-додає --ws у change, якщо не задано явно (один змінений subworkspace → його .changes/; кілька → fail з підказкою явного --ws; лише корінь → дефолт). Усуває потрапляння change-файлу в корінь монорепо при змінах під підпакетом.
+
+### Fixed
+
+- Усунуто суперечність n-changelog.mdc ↔ n-npm-module.mdc: прибрано перевірки version/CHANGELOG у package_structure.mjs, що штовхали до ручного bump (єдиний артефакт змін — change-файл; узгодженість валідує changelog/consistency.mjs); npm-module.mdc делегує bump/CHANGELOG у changelog.mdc, який отримав post-release-інваріант.
+- trace: резолв лінків front-matter відносно теки артефакту (+ root-relative fallback) — file-relative spec/plan лінки (`../specs/…`) більше не дають хибний «розрив ланцюга»; поле `flow` (runtime `.flow.json`) показується, але не рахується розривом. Розрив визначають лише chain-поля (adr/spec/plan/change/task).
+
 ## [3.11.0] - 2026-06-02
 
 ### Changed

package/package.json

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

package/rules/changelog/changelog.mdc

@@ -1,6 +1,6 @@
 ---
 description: CHANGELOG.md в кожному workspace, з двома моделями бази порівняння (npm і Python)
-version: '3.1'
+version: '3.2'
 alwaysApply: true
 ---
 
@@ -97,3 +97,9 @@ alwaysApply: true
 ```
 
 Секції — підмножина `### Added`, `### Changed`, `### Fixed`, `### Removed` (одна або кілька).
+
+## Post-release інваріант (гарантує CI)
+
+Перша (верхня) секція `## [version]` у `CHANGELOG.md` дорівнює полю `version` у маніфесті — але це **post-release** твердження, яке забезпечує `n-cursor release` у CI, агрегуючи change-файли (bump `version` + генерація секції + git-тег `<name>@<version>`). **Локально цю рівність руками не підтримують**: у feature-флоу `version`/`CHANGELOG.md` не чіпають, тож верхня секція може відставати від майбутньої версії — це нормально. Drift `version` поза CI (vs реєстр / vs git-база) ловить `check changelog` як заборонений ручний bump.
+
+Інструкції щодо bump `version` і редагування `CHANGELOG.md` живуть **лише** в цьому правилі — джерелі істини. Інші правила (зокрема `n-npm-module.mdc`) їй підпорядковані й власних інструкцій bump/CHANGELOG не дублюють.

package/rules/npm-module/js/package_structure.mjs

@@ -20,16 +20,15 @@
  *    test-фреймворків (`bun:test`, `node:test`, `vitest`, `@jest/globals`, `mocha`, `jest`, `ava`, …).
  *    Виняток: `*_test.rego` дозволені поруч з полісі — це конвенція conftest.
  *
- * Версія та CHANGELOG: перший заголовок `## [version]` у `npm/CHANGELOG.md` має збігатися з `version` у
- * `npm/package.json` (найсвіжіший реліз зверху). Якщо в git є незакомічені зміни під `npm/`, `version` у робочому
- * файлі має відрізнятися від `HEAD` — інакше типовий пропуск bump після правок у пакеті.
+ * Версія та CHANGELOG тут НЕ перевіряються: єдиний артефакт зміни — change-файл, а узгодженість
+ * `version`/`CHANGELOG.md` (включно з drift від ручного bump) валідує `changelog/js/consistency.mjs`
+ * за моделлю `n-changelog.mdc`. Інваріант «верхня секція CHANGELOG == package.json.version» істинний
+ * лише post-release і його гарантує `n-cursor release` у CI — локально його не підтримують руками.
  * @param {string} cwd корінь репозиторію
  */
-import { execFile } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { readFile, stat } from 'node:fs/promises'
 import { join, sep } from 'node:path'
-import { promisify } from 'node:util'
 
 import { parseSync } from 'oxc-parser'
 
@@ -43,14 +42,6 @@ import { createCheckReporter } from '../../../scripts/lib/check-reporter.mjs'
 import { loadCursorIgnorePaths } from '../../../scripts/lib/load-cursor-config.mjs'
 import { walkDir } from '../../../scripts/utils/walkDir.mjs'
 
-const execFileAsync = promisify(execFile)
-
-/** Перший заголовок релізу у Keep a Changelog (`## [1.2.3]`). */
-const CHANGELOG_FIRST_VERSION_RE = /^## \[([^\]]+)\]/m
-
-/** Поле `version` у текстовому зрізі `package.json` (для `git show HEAD:npm/package.json`). */
-const PACKAGE_JSON_VERSION_RE = /"version":\s*"([^"]+)"/u
-
 /** Файл проєкту TypeScript для emit без каталогу `src` (див. npm-module.mdc) */
 const EMIT_TYPES_CONFIG = 'npm/tsconfig.emit-types.json'
 
@@ -91,9 +82,9 @@ const GLOBSTAR_TRAILING_RE = /\/__GLOBSTAR__$/u
 
 /**
  * Чи є під `npm/src` хоча б один `.js` (рекурсивно).
+ * @param {string} cwd корінь репозиторію
  * @param {string[]} [ignorePaths] абсолютні шляхи каталогів, повністю виключених з обходу
  * @returns {Promise<boolean>} `true`, якщо знайдено хоча б один `.js`
- * @param {string} cwd корінь репозиторію
  */
 async function npmSrcTreeHasJsFile(cwd, ignorePaths = []) {
   const root = join(cwd, 'npm/src')
@@ -215,136 +206,6 @@ function checkEmitTypesConfig(passFn, failFn, cwd) {
   passFn(`${EMIT_TYPES_CONFIG} є (структуру перевіряє npx @nitra/cursor fix → npm_module.emit_types_config)`)
 }
 
-/**
- * Перевіряє npm-publish.yml workflow.
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при помилці
- * @param {string} cwd корінь репозиторію
- */
-/**
- * Чи виконано `git` у корені робочого дерева.
- * @returns {Promise<boolean>} true, якщо процес запущено в межах git work tree
- * @param {string} cwd корінь репозиторію
- */
-async function gitInsideWorkTree(cwd) {
-  try {
-    const { stdout } = await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], { encoding: 'utf8', cwd })
-    return stdout.trim() === 'true'
-  } catch {
-    return false
-  }
-}
-
-/**
- * Список незакомічених шляхів під `npm/` відносно `HEAD`.
- * @param {string} cwd корінь репозиторію
- * @returns {Promise<string[] | null>} шляхи або `null`, якщо `git` недоступний
- */
-async function gitDiffNameOnlyNpm(cwd) {
-  try {
-    const { stdout } = await execFileAsync('git', ['diff', '--name-only', 'HEAD', '--', 'npm'], {
-      encoding: 'utf8',
-      cwd
-    })
-    return stdout.trim().split('\n').filter(Boolean)
-  } catch {
-    return null
-  }
-}
-
-/**
- * Поле `version` з `npm/package.json` на заданому git-ref (`HEAD:npm/package.json`).
- * @param {string} refPath на кшталт `HEAD:npm/package.json`
- * @param {string} cwd корінь репозиторію
- * @returns {Promise<string | null>} значення поля `version` або `null`, якщо ref недоступний
- */
-async function gitShowNpmPackageVersionAt(refPath, cwd) {
-  try {
-    const { stdout } = await execFileAsync('git', ['show', refPath], { encoding: 'utf8', cwd })
-    const m = stdout.match(PACKAGE_JSON_VERSION_RE)
-    return m ? m[1] : null
-  } catch {
-    return null
-  }
-}
-
-/**
- * Версія з першого заголовка `## […]` у тексті CHANGELOG.
- * @param {string} changelogText вміст файлу CHANGELOG.md
- * @returns {string | null} версія з першої секції або `null`, якщо заголовка немає
- */
-function firstChangelogSectionVersion(changelogText) {
-  const m = changelogText.match(CHANGELOG_FIRST_VERSION_RE)
-  return m ? m[1] : null
-}
-
-/**
- * Перший реліз у CHANGELOG має збігатися з `version` у `npm/package.json`.
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при виявленому порушенні
- * @returns {Promise<void>}
- * @param {string} cwd корінь репозиторію
- */
-async function checkChangelogTopMatchesPackageVersion(passFn, failFn, cwd) {
-  if (!existsSync(join(cwd, 'npm/CHANGELOG.md')) || !existsSync(join(cwd, 'npm/package.json'))) return
-  const pkg = JSON.parse(await readFile(join(cwd, 'npm/package.json'), 'utf8'))
-  const ver = typeof pkg.version === 'string' ? pkg.version : null
-  if (!ver) {
-    failFn('npm/package.json: відсутнє поле version')
-    return
-  }
-  const cl = await readFile(join(cwd, 'npm/CHANGELOG.md'), 'utf8')
-  const first = firstChangelogSectionVersion(cl)
-  if (!first) {
-    failFn('npm/CHANGELOG.md: не знайдено жодного заголовка ## [version]')
-    return
-  }
-  if (first !== ver) {
-    failFn(
-      `npm/CHANGELOG.md: перша секція [${first}] не збігається з npm/package.json version "${ver}" ` +
-        '(зверху має бути найсвіжіший реліз і той самий номер — npm-module.mdc).'
-    )
-    return
-  }
-  passFn(`npm/CHANGELOG.md: перша секція [${first}] збігається з npm/package.json`)
-}
-
-/**
- * Незакомічені зміни під `npm/` вимагають підвищення `version` відносно `HEAD`.
- * @param {(msg: string) => void} passFn callback при успішній перевірці
- * @param {(msg: string) => void} failFn callback при виявленому порушенні
- * @returns {Promise<void>}
- * @param {string} cwd корінь репозиторію
- */
-async function checkDirtyNpmRequiresVersionBump(passFn, failFn, cwd) {
-  if (!(await gitInsideWorkTree(cwd))) {
-    passFn('npm-module: git недоступний або поза work tree — перевірку незакоміченого bump пропущено')
-    return
-  }
-  const changed = await gitDiffNameOnlyNpm(cwd)
-  if (changed === null) {
-    passFn('npm-module: git diff під npm/ недоступний — пропущено')
-    return
-  }
-  if (changed.length === 0) return
-
-  const headVer = await gitShowNpmPackageVersionAt('HEAD:npm/package.json', cwd)
-  if (headVer === null) return
-
-  const pkg = JSON.parse(await readFile(join(cwd, 'npm/package.json'), 'utf8'))
-  const cur = typeof pkg.version === 'string' ? pkg.version : null
-  if (!cur) return
-
-  if (cur === headVer) {
-    failFn(
-      `Незакомічені зміни під npm/ (${changed.join(', ')}), але "version" у npm/package.json лишився ${cur} ` +
-        '(як у HEAD). Підвищ version (+1) і додай секцію ## [нова версія] зверху CHANGELOG (npm-module.mdc).'
-    )
-    return
-  }
-  passFn(`npm/: незакомічені зміни під npm/ узгоджені з підвищенням version (${headVer} → ${cur})`)
-}
-
 /**
  * FS-existence для `npm-publish.yml` workflow. Поля workflow (`on.push.paths`,
  * `branches`, `id-token: write`, JS-DevTools/npm-publish step) валідує
@@ -614,8 +475,5 @@ export async function check(cwd = process.cwd()) {
 
   await checkPublishWorkflow(pass, fail, cwd)
 
-  await checkChangelogTopMatchesPackageVersion(pass, fail, cwd)
-  await checkDirtyNpmRequiresVersionBump(pass, fail, cwd)
-
   return reporter.getExitCode()
 }

package/rules/npm-module/npm-module.mdc

@@ -2,7 +2,7 @@
 description: Оформлення репозиторію для npm модуля
 globs: "npm/**,**/package.json,**/hk.pkl,.github/workflows/npm-publish.yml,**/tsconfig*.json"
 alwaysApply: false
-version: '1.13'
+version: '1.14'
 ---
 
 Bun monorepo: workspace **`npm/`**, кореневий **`package.json`**, **`.github/workflows/`**; опційно **`demo/`**.
@@ -55,21 +55,11 @@ bunx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly
 
 Після додавання **`hk.pkl`**: **`hk install`**.
 
-## Build версія
+## Версія та CHANGELOG
 
-Після змін у **`npm/`** обовʼязково підвищ **build**-версію в **`npm/package.json`**, але не роби зайвих підвищень: між номером у файлі й тим, що вже збережено в **git** (`HEAD`), має лишатися не більше одного кроку **+1**.
+Версію (`version` у **`npm/package.json`**) і **`npm/CHANGELOG.md`** **не редагуй вручну** — навіть для hotfix. Єдиний артефакт зміни — **change-файл** (`npx @nitra/cursor change --bump <major|minor|patch> --section <Added|Changed|Fixed|Removed> --message "<…>"`); bump `version` і генерацію секції CHANGELOG робить `n-cursor release` у CI на `main`. Будь-який ручний bump `version` поза CI завалює `check changelog` — навіть із change-файлом.
 
-У робочій копії не повинно бути більше одного незбереженого в **git** підвищення **build**-версії за раз.
-
-**Чеклист у тому ж наборі змін, що й правки під `npm/`:** `version` у **`npm/package.json`** → **+1**; зверху **`npm/CHANGELOG.md`** нова секція **`## [нова версія] - …`**; у секції лише те, що входить у цей реліз.
-
-**Антипатерн:** не дописувати нові bullet-и в уже існуючу секцію **`## [X.Y.Z]`**, якщо паралельно не піднімаєш **`version`** до нового номера й не створюєш **нову** секцію зверху. Інакше змішуються різні релізи в одному номері, а `check npm-module` / `check changelog` гірше ловлять порушення.
-
-**Підказка:** щоб не дублювати bump і бачити різницю зі збереженим деревом, перевір `git status npm/package.json` або `git diff HEAD -- npm/package.json` перед другим підвищенням у тій самій гілці / наборі змін.
-
-## CHANGELOG
-
-Найновіша версія — **перша** секція **`## [version]`** у файлі (зверху після заголовка). Вона **має збігатися** з полем **`version`** у **`npm/package.json`**.
+Повна модель (база порівняння, інверсія шляхів, формат CHANGELOG, post-release-інваріант «верхня секція CHANGELOG == `version`») — у **`n-changelog.mdc`** (джерело істини). Це правило їй підпорядковане й власних інструкцій bump/CHANGELOG не дублює.
 
 ## npm publish
 

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/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`')

package/scripts/dispatcher/trace.mjs

@@ -7,12 +7,20 @@
  * FS-доступ (`readdir`/`readFile`/`exists`) ін'єктується — тестується без диска.
  */
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
 import { cwd as processCwd } from 'node:process'
 
-/** Поля-лінки у front-matter, що утворюють ланцюг. */
+/** Поля-лінки у front-matter (порядок відображення). */
 const LINK_FIELDS = ['adr', 'spec', 'plan', 'flow', 'change', 'task']
 
+/**
+ * Інформаційні лінк-поля: показуються, але їх відсутність НЕ є розривом ланцюга.
+ * `flow` вказує на runtime-стан `.worktrees/<branch>.flow.json` — gitignored, поза
+ * `docs/`, існує лише під час задачі; у чистому checkout/CI його нема ніколи, тож
+ * рахувати його розривом — хибний сигнал. Решта полів — ланки ланцюга (breaking).
+ */
+const INFO_LINK_FIELDS = new Set(['flow'])
+
 /** Каталоги з traceable-артефактами. */
 const DIRS = ['docs/tasks', 'docs/specs', 'docs/plans', 'docs/adr']
 
@@ -52,20 +60,40 @@ function isSimpleKey(key) {
 
 /**
  * Будує аналіз: для кожного артефакту — його лінки зі статусом ok/розрив.
+ * `breaking` — чи відсутність цього лінка рве ланцюг (chain-поля) чи лише
+ * інформаційна (`flow` → runtime-стан).
  * @param {{ file: string, fm: Record<string, string | null> }[]} artifacts артефакти з front-matter
- * @param {(target: string) => boolean} exists чи існує цільовий файл лінка
- * @returns {{ file: string, kind: string | null, id: string | null, status: string | null, links: { field: string, target: string, ok: boolean }[] }[]} аналіз
+ * @param {(target: string, artifactFile: string) => boolean} resolve чи резолвиться лінк (відносно артефакту/кореня)
+ * @returns {{ file: string, kind: string | null, id: string | null, status: string | null, links: { field: string, target: string, ok: boolean, breaking: boolean }[] }[]} аналіз
  */
-export function analyze(artifacts, exists) {
+export function analyze(artifacts, resolve) {
   return artifacts.map(({ file, fm }) => ({
     file,
     kind: fm.kind ?? null,
     id: fm.id ?? null,
     status: fm.status ?? null,
-    links: LINK_FIELDS.filter(f => fm[f]).map(f => ({ field: f, target: fm[f], ok: exists(fm[f]) }))
+    links: LINK_FIELDS.filter(f => fm[f]).map(f => ({
+      field: f,
+      target: fm[f],
+      ok: resolve(fm[f], file),
+      breaking: !INFO_LINK_FIELDS.has(f)
+    }))
   }))
 }
 
+/**
+ * Чи резолвиться лінк: спершу відносно теки артефакту (конвенція доків `../specs/…`),
+ * далі fallback на root-relative (`docs/specs/…`). Обидві форми вважаються валідними.
+ * @param {string} root корінь репо
+ * @param {string} artifactFile rel-шлях артефакту (напр. `docs/plans/x.md`)
+ * @param {string} target значення лінка
+ * @param {(absPath: string) => boolean} exists перевірка існування
+ * @returns {boolean} чи знайдено цільовий файл
+ */
+function resolveLink(root, artifactFile, target, exists) {
+  return exists(join(root, dirname(artifactFile), target)) || exists(join(root, target))
+}
+
 /**
  * Текстовий рендер аналізу.
  * @param {object[]} analysis результат `analyze`
@@ -77,14 +105,24 @@ export function render(analysis) {
   for (const a of analysis) {
     lines.push(`${a.kind ?? '?'} · ${a.id ?? a.file} [${a.status ?? '—'}]`)
     for (const l of a.links) {
-      const mark = l.ok ? '→' : '✗'
-      const note = l.ok ? '' : ' (РОЗРИВ — файл відсутній)'
-      lines.push(`   ${mark} ${l.field}: ${l.target}${note}`)
+      lines.push(`   ${renderLink(l)}`)
     }
   }
   return lines.join('\n')
 }
 
+/**
+ * Рядок одного лінка: `→` ok; `✗ … (РОЗРИВ)` — нерезолвлене chain-поле;
+ * `~ … (не рве ланцюг)` — нерезолвлене інформаційне поле (`flow`, runtime-стан).
+ * @param {{ field: string, target: string, ok: boolean, breaking: boolean }} l лінк
+ * @returns {string} рядок
+ */
+function renderLink(l) {
+  if (l.ok) return `→ ${l.field}: ${l.target}`
+  if (l.breaking) return `✗ ${l.field}: ${l.target} (РОЗРИВ — файл відсутній)`
+  return `~ ${l.field}: ${l.target} (runtime-стан — не рве ланцюг)`
+}
+
 /**
  * CLI `n-cursor trace [--json]`. Повертає 1, якщо є розриви ланцюга.
  * @param {string[]} args аргументи
@@ -108,7 +146,8 @@ export function runTraceCli(args, deps = {}) {
     }
   }
 
-  const analysis = analyze(artifacts, target => exists(join(root, target)))
+  const analysis = analyze(artifacts, (target, file) => resolveLink(root, file, target, exists))
   log(args.includes('--json') ? JSON.stringify(analysis, null, 2) : render(analysis))
-  return analysis.some(a => a.links.some(l => !l.ok)) ? 1 : 0
+  // Розрив ланцюга — лише нерезолвлене chain-поле; нерезолвлений `flow` (runtime-стан) не рахуємо.
+  return analysis.some(a => a.links.some(l => l.breaking && !l.ok)) ? 1 : 0
 }