@nitra/cursor 3.11.0 → 3.13.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [3.13.0] - 2026-06-02
+
+### Changed
+
+- k8s hasura_configmap: розширено перелік обов'язкових env у ConfigMap Hasura-Deployment — додатково до HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS="true" тепер вимагаються HASURA_GRAPHQL_ENABLE_RELAY="false", HASURA_GRAPHQL_ENABLE_TELEMETRY="false", HASURA_GRAPHQL_ENABLED_LOG_TYPES="startup,http-log" (точний рядок) і HASURA_GRAPHQL_DISABLE_EVENTING (ключ обов'язковий, значення довільне, за замовчуванням "true")
+
+## [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.13.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/k8s/js/manifests.mjs

@@ -2349,47 +2349,17 @@ export function isHasuraDeploymentManifest(manifest) {
 }
 
 /**
- * Обов'язковий ключ у **`data`** ConfigMap для Hasura-Deployment (узгоджено з k8s.mdc).
- */
-export const HASURA_REMOTE_SCHEMA_PERMISSIONS_KEY = 'HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS'
-
-/**
- * Чи значення поля `data.<key>` у ConfigMap читається як логічне **true**.
- * ConfigMap у Kubernetes тримає значення як рядки, але в YAML часто пишуть без лапок —
- * тому приймаємо і булевий **true**, і рядок **"true"** (без регістрової залежності).
- * @param {unknown} v значення з `data[HASURA_REMOTE_SCHEMA_PERMISSIONS_KEY]`
- * @returns {boolean} true, якщо значення — `true` або рядок `'true'`
- */
-function isConfigMapValueTrue(v) {
-  if (v === true) return true
-  if (typeof v === 'string' && v.trim().toLowerCase() === 'true') return true
-  return false
-}
-
-/**
- * Чи порушує ConfigMap вимогу щодо **`HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS: "true"`** (k8s.mdc).
- * Перевірка застосовна, коли в тому ж каталозі є Hasura-Deployment (див. `isHasuraDeploymentManifest`).
- * @param {unknown} manifest корінь YAML-документа ConfigMap
- * @returns {string | null} текст порушення або null, якщо не ConfigMap / ключ є і значення `true`
- */
-export function hasuraConfigMapRemoteSchemaPermissionsViolation(manifest) {
-  if (manifest === null || manifest === undefined || typeof manifest !== 'object' || Array.isArray(manifest))
-    return null
-  const rec = /** @type {Record<string, unknown>} */ (manifest)
-  if (rec.kind !== 'ConfigMap') return null
-  const data = rec.data
-  if (data === null || data === undefined || typeof data !== 'object' || Array.isArray(data)) {
-    return `data.${HASURA_REMOTE_SCHEMA_PERMISSIONS_KEY}: додай ключ зі значенням "true" (Deployment з hasura/graphql-engine — див. k8s.mdc)`
-  }
-  const d = /** @type {Record<string, unknown>} */ (data)
-  if (!Object.hasOwn(d, HASURA_REMOTE_SCHEMA_PERMISSIONS_KEY)) {
-    return `data.${HASURA_REMOTE_SCHEMA_PERMISSIONS_KEY}: додай ключ зі значенням "true" (Deployment з hasura/graphql-engine — див. k8s.mdc)`
-  }
-  if (!isConfigMapValueTrue(d[HASURA_REMOTE_SCHEMA_PERMISSIONS_KEY])) {
-    return `data.${HASURA_REMOTE_SCHEMA_PERMISSIONS_KEY}: значення має бути "true" (зараз: ${JSON.stringify(d[HASURA_REMOTE_SCHEMA_PERMISSIONS_KEY])}) (див. k8s.mdc)`
-  }
-  return null
-}
+ * Обов'язкові env-ключі у **`data`** ConfigMap для Hasura-Deployment (узгоджено з
+ * rego-пакетом `k8s.hasura_configmap` та k8s.mdc). Лише для людиночитного pass-повідомлення —
+ * авторитетна пер-документна валідація (наявність ключів і значення) живе в rego.
+ */
+export const HASURA_REQUIRED_ENV_KEYS = [
+  'HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS',
+  'HASURA_GRAPHQL_ENABLE_RELAY',
+  'HASURA_GRAPHQL_ENABLE_TELEMETRY',
+  'HASURA_GRAPHQL_ENABLED_LOG_TYPES',
+  'HASURA_GRAPHQL_DISABLE_EVENTING'
+]
 
 const K8S_YAML_EXT_RE = /\.ya?ml$/iu
 
@@ -3676,7 +3646,10 @@ async function validateConfigMapNameMatchesDeployment(root, yamlFilesAbs, fail,
 
 /**
  * Для кожного `k8s/base/configmap.yaml`, у каталозі якого поруч є Hasura-Deployment,
- * вимагає у `data` ключ **`HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS`** зі значенням **`"true"`** (k8s.mdc).
+ * вимагає у `data` обов'язкові env-ключі (`HASURA_REQUIRED_ENV_KEYS`) з очікуваними
+ * значеннями (`HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS="true"`,
+ * `HASURA_GRAPHQL_ENABLE_RELAY="false"`, `HASURA_GRAPHQL_ENABLE_TELEMETRY="false"`,
+ * `HASURA_GRAPHQL_ENABLED_LOG_TYPES="startup,http-log"`, `HASURA_GRAPHQL_DISABLE_EVENTING` — будь-яке) (k8s.mdc).
  * @param {string} root корінь репозиторію
  * @param {string[]} yamlFilesAbs yaml під k8s
  * @param {(msg: string) => void} fail callback при помилці
@@ -3688,8 +3661,8 @@ async function validateHasuraConfigMapRemoteSchemaPermissions(root, yamlFilesAbs
     return CONFIGMAP_BASE_PATH_RE.test(`/${rel}`) || rel === 'k8s/base/configmap.yaml'
   })
   // JS gating: відберемо ConfigMap-файли, у каталозі яких поруч є Hasura-Deployment.
-  // Per-document валідація `data.HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS == "true"`
-  // — у rego-пакеті `k8s.hasura_configmap`.
+  // Per-document валідація обов'язкових `data.HASURA_GRAPHQL_*` env — у rego-пакеті
+  // `k8s.hasura_configmap`.
   const paired = []
   for (const cmAbs of cmFiles) {
     const deployment = await findDeploymentDocInDir(dirname(cmAbs))
@@ -3708,7 +3681,7 @@ async function validateHasuraConfigMapRemoteSchemaPermissions(root, yamlFilesAbs
     fail(`${rel}: ${v.message}`)
   }
   if (violations.length === 0) {
-    passFn(`Hasura-ConfigMap (${paired.length}) відповідає ${HASURA_REMOTE_SCHEMA_PERMISSIONS_KEY}="true" (rego)`)
+    passFn(`Hasura-ConfigMap (${paired.length}) містить обов'язкові env [${HASURA_REQUIRED_ENV_KEYS.join(', ')}] (rego)`)
   }
 }
 

package/rules/k8s/k8s.mdc

@@ -297,11 +297,23 @@ spec:
 
 ## ConfigMap для Hasura-Deployment
 
-Якщо в `k8s/base/` поруч із **`configmap.yaml`** є **Deployment** з образом **`hasura/graphql-engine`**, у `data` ConfigMap **обов'язково** має бути ключ **`HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS`** зі значенням **`"true"`**. Точні умови перевірки — **`rules/k8s/fix.mjs`**.
+Якщо в `k8s/base/` поруч із **`configmap.yaml`** є **Deployment** з образом **`hasura/graphql-engine`**, у `data` ConfigMap **обов'язково** мають бути env-ключі:
+
+- **`HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS`** зі значенням **`"true"`**;
+- **`HASURA_GRAPHQL_ENABLE_RELAY`** зі значенням **`"false"`**;
+- **`HASURA_GRAPHQL_ENABLE_TELEMETRY`** зі значенням **`"false"`**;
+- **`HASURA_GRAPHQL_ENABLED_LOG_TYPES`** зі значенням **`"startup,http-log"`** (точний рядок);
+- **`HASURA_GRAPHQL_DISABLE_EVENTING`** — ключ обов'язковий, значення довільне (за замовчуванням **`"true"`**).
+
+Точні умови перевірки — rego-пакет **`k8s.hasura_configmap`** (cross-file прив'язка ConfigMap↔Deployment — у `rules/k8s/js/manifests.mjs`).
 
 ```yaml
 data:
   HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS: 'true'
+  HASURA_GRAPHQL_ENABLE_RELAY: 'false'
+  HASURA_GRAPHQL_ENABLE_TELEMETRY: 'false'
+  HASURA_GRAPHQL_ENABLED_LOG_TYPES: 'startup,http-log'
+  HASURA_GRAPHQL_DISABLE_EVENTING: 'true'
 ```
 
 ## Kustomize: структура каталогів (`base` / overlays)

package/rules/k8s/policy/hasura_configmap/hasura_configmap.rego

@@ -1,18 +1,30 @@
 # Порт перевірки ConfigMap для Hasura-Deployment з
 # `npm/scripts/rules/k8s/fix.mjs` (k8s.mdc): у ConfigMap, що сусідствує з
-# Hasura-Deployment, у `data` обов'язково має бути ключ
-# `HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS` зі значенням `"true"`.
+# Hasura-Deployment, у `data` обов'язково мають бути env-ключі зі списку
+# `required_env` з очікуваними значеннями:
+#   "HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS" → "true"
+#   "HASURA_GRAPHQL_ENABLE_RELAY"                      → "false"
+#   "HASURA_GRAPHQL_ENABLE_TELEMETRY"                  → "false"
+#   "HASURA_GRAPHQL_ENABLED_LOG_TYPES"                 → "startup,http-log" (точний рядок)
+#   "HASURA_GRAPHQL_DISABLE_EVENTING"                  → null (ключ обов'язковий,
+#       значення довільне; за замовчуванням рекомендовано "true")
+#
+# Семантика очікуваного значення у `required_env`:
+#   "true"  — має читатись як логічне true (boolean true або рядок "true", case-insensitive);
+#   "false" — має читатись як логічне false (boolean false або рядок "false", case-insensitive);
+#   null    — ключ обов'язковий, значення довільне (за замовчуванням "true");
+#   інший рядок — значення має точно дорівнювати рядку (exact match).
 #
 # Запуск (локально, лише для ConfigMap у каталозі з Hasura-Deployment):
 #   conftest test path/to/k8s/.../configmap.yaml \
 #     -p npm/policy/k8s/hasura_configmap \
 #     --namespace k8s.hasura_configmap
 #
-# Прив'язка ConfigMap-Deployment cross-file — у JS (`rules/k8s/fix.mjs`:
+# Прив'язка ConfigMap-Deployment cross-file — у JS (`rules/k8s/js/manifests.mjs`:
 # `validateHasuraConfigMapRemoteSchemaPermissions` шукає Hasura-Deployment
 # у тому ж dir-у і викликає conftest з цією намеспейс лише для відповідних
-# ConfigMap-ів). JS authoritative (`hasuraConfigMapRemoteSchemaPermissionsViolation`,
-# константа `HASURA_REMOTE_SCHEMA_PERMISSIONS_KEY`).
+# ConfigMap-ів). Rego authoritative для пер-документної валідації; JS лишає
+# лише cross-file orchestration.
 #
 # Структура каталогу збігається зі шляхом пакету (regal: directory-package-mismatch).
 # Конвенція проєкту — `import rego.v1` + multi-value `deny contains msg if { … }`.
@@ -20,45 +32,82 @@ package k8s.hasura_configmap
 
 import rego.v1
 
-# Обов'язковий ключ у `data` (узгоджено з `rules/k8s/fix.mjs`).
-required_key := "HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS"
+# Обов'язкові env-ключі у `data` (узгоджено з `rules/k8s/js/manifests.mjs` та k8s.mdc).
+# Значення — очікуваний стан ключа (семантика — у шапці файлу).
+required_env := {
+	"HASURA_GRAPHQL_ENABLE_REMOTE_SCHEMA_PERMISSIONS": "true",
+	"HASURA_GRAPHQL_ENABLE_RELAY": "false",
+	"HASURA_GRAPHQL_ENABLE_TELEMETRY": "false",
+	"HASURA_GRAPHQL_ENABLED_LOG_TYPES": "startup,http-log",
+	"HASURA_GRAPHQL_DISABLE_EVENTING": null,
+}
+
+# Множина "boolean-подібних" очікувань — для них значення читається як логічне,
+# а не звіряється точним рядком.
+bool_expected := {"true", "false"}
+
+# Підказка про очікуване значення для повідомлення про відсутній ключ.
+expected_hint(null) := "(значення довільне, за замовчуванням \"true\")"
 
-key_missing_template := concat(" ", [
-	"data.%s: додай ключ зі значенням \"true\"",
-	"(Deployment з hasura/graphql-engine — k8s.mdc)",
-])
+expected_hint(expected) := sprintf("зі значенням \"%s\"", [expected]) if is_string(expected)
 
-key_value_wrong_template := concat(" ", ["data.%s: значення має бути \"true\" (зараз: %v) (k8s.mdc)"])
+key_value_wrong_template := concat(" ", ["data.%s: значення має бути \"%s\" (зараз: %v) (k8s.mdc)"])
+
+# Ключ відсутній: `data` не об'єкт або в ньому немає обов'язкового ключа.
+deny contains msg if {
+	input.kind == "ConfigMap"
+	some key, expected in required_env
+	not key_present(key)
+	msg := sprintf(
+		"data.%s: додай ключ %s (Deployment з hasura/graphql-engine — k8s.mdc)",
+		[key, expected_hint(expected)],
+	)
+}
 
+# Очікуване "true", а значення не читається як логічне true.
 deny contains msg if {
 	input.kind == "ConfigMap"
-	not is_object(object.get(input, "data", null))
-	msg := sprintf(key_missing_template, [required_key])
+	d := object.get(input, "data", null)
+	is_object(d)
+	some key, expected in required_env
+	expected == "true"
+	key in object.keys(d)
+	not is_value_true(d[key])
+	msg := sprintf(key_value_wrong_template, [key, "true", d[key]])
 }
 
+# Очікуване "false", а значення не читається як логічне false.
 deny contains msg if {
 	input.kind == "ConfigMap"
 	d := object.get(input, "data", null)
 	is_object(d)
-	not key_present(d)
-	msg := sprintf(key_missing_template, [required_key])
+	some key, expected in required_env
+	expected == "false"
+	key in object.keys(d)
+	not is_value_false(d[key])
+	msg := sprintf(key_value_wrong_template, [key, "false", d[key]])
 }
 
+# Очікуване — точний рядок (не "true"/"false"/null), а значення не збігається.
 deny contains msg if {
 	input.kind == "ConfigMap"
 	d := object.get(input, "data", null)
 	is_object(d)
-	key_present(d)
-	value := d[required_key]
-	not is_value_true(value)
-	msg := sprintf(key_value_wrong_template, [required_key, value])
+	some key, expected in required_env
+	is_string(expected)
+	not expected in bool_expected
+	key in object.keys(d)
+	d[key] != expected
+	msg := sprintf(key_value_wrong_template, [key, expected, d[key]])
 }
 
-key_present(d) if {
-	required_key in object.keys(d)
+key_present(key) if {
+	d := object.get(input, "data", null)
+	is_object(d)
+	key in object.keys(d)
 }
 
-# Значення вважається "true", якщо це boolean true або рядок "true"
+# Значення вважається "true"/"false", якщо це відповідний boolean або рядок
 # (case-insensitive). ConfigMap у Kubernetes тримає рядки, але YAML без лапок
 # дає boolean — приймаємо обидва варіанти.
 is_value_true(true)
@@ -67,3 +116,10 @@ is_value_true(v) if {
 	is_string(v)
 	lower(trim_space(v)) == "true"
 }
+
+is_value_false(false)
+
+is_value_false(v) if {
+	is_string(v)
+	lower(trim_space(v)) == "false"
+}

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
 }