@7n/rules 1.10.0 → 1.12.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.12.0] - 2026-07-17
+
+### Changed
+
+- Додано прапор `--path <dir>` для `n-rules lint`: звужує файловий набір per-file правил до заданої піддиректорії, лишаючи корінь прогону (root-guard, `.n-rules.json`) незмінним — на відміну від `--cwd`. Несумісний з позиційним rule/concern-фільтром; у парі з `--full` full-вісь ігнорується (без machine-wide локу).
+
+## [1.11.0] - 2026-07-17
+
+### Added
+
+- js/eslint: fix-worker.mjs з per-file циклом замість одного великого промпту на весь concern — усунення 100% timeout на драбині, виміряно на реальних lint-прогонах
+
+### Fixed
+
+- text/markdownlint: включати причину провалу markdownlint-cli2 у violation-повідомлення; js/knip: fixability=structural (LLM-ладдер завжди приречений на timeout)
+
 ## [1.10.0] - 2026-07-17
 
 ### Added

package/bin/n-rules.js

@@ -12,7 +12,9 @@
  *   `npx \@7n/rules lint`        — data-driven оркестратор lint+конформності по `rules/<id>/meta.json` (`lint: per-file|full`):
  *                                     за замовчуванням fix-by-default по дельті vs origin (лише `per-file` правила); `--full` =
  *                                     весь репо (`per-file` ∪ `full`); `--no-fix` = без мутацій/LLM (CI); позиційні
- *                                     (не-флаг) аргументи — фільтр правил конформності (мапить колишній `fix <rule>`).
+ *                                     (не-флаг) аргументи — фільтр правил конформності (мапить колишній `fix <rule>`);
+ *                                     `--path <dir>` = звузити файловий набір до піддиректорії, корінь прогону (root-guard,
+ *                                     `.n-rules.json`) лишається поточним каталогом/`--cwd`, не сумісний з rule-фільтром.
  *                                     CI = `lint --no-fix --full` (весь репо, нуль мутацій/LLM).
  *   `npx \@7n/rules skill list`     — скіли пакета без синку в проєкт
  *   `npx \@7n/rules skill taze`     — промпт на stdout
@@ -1632,7 +1634,16 @@ function printLintHelp() {
                   Один --full на машину: паралельні запуски стають у чергу
                   й бачать живий прогрес активного прогону.
   --no-fix        Лише детекція, без мутацій.
-  --cwd <path>    Робочий каталог замість поточного.
+  --cwd <path>    Робочий каталог (корінь прогону) замість поточного —
+                  root-guard, .n-rules.json і devDependencies читаються
+                  з нього.
+  --path <dir>    Звузити файловий набір до піддиректорії, лишивши корінь
+                  прогону незмінним (config/root-guard — з поточного каталогу
+                  чи --cwd). per-file правила фільтруються по файлах <dir>;
+                  full-scope правила (jscpd, cspell тощо) при спрацюванні
+                  все одно йдуть по всьому репо. Несумісний з позиційним
+                  rule/concern-фільтром; з --full full-вісь ігнорується
+                  (немає machine-wide локу).
   --verbose       Розширений вивід детекції та виправлення.
   --help, -h      Ця довідка.
 
@@ -1644,6 +1655,7 @@ function printLintHelp() {
   npx @7n/rules lint --full
   npx @7n/rules lint --no-fix eslint
   npx @7n/rules lint --cwd ./packages/foo --verbose
+  npx @7n/rules lint --path npm/scripts/lib/lint-surface --no-fix
 `)
 }
 
@@ -1717,8 +1729,29 @@ try {
         // Fix-by-default: detect → T0 → LLM-ladder (run-fix). --no-fix: лише detect.
         const cwdIdx = args.indexOf('--cwd')
         const cwdArg = cwdIdx === -1 ? cwd() : resolve(args[cwdIdx + 1])
-        const rules = args.filter((a, i) => !a.startsWith('-') && !(cwdIdx !== -1 && i === cwdIdx + 1))
-        const lintOpts = { cwd: cwdArg, full: args.includes('--full'), rules, verbose: args.includes('--verbose') }
+        // --path: на відміну від --cwd (підміняє корінь), лишає корінь/config
+        // незмінними й лише звужує файловий набір до заданої піддиректорії
+        // (той самий explicitFiles-шлях, що вже годує hook --post-tool-use/--stop).
+        const pathIdx = args.indexOf('--path')
+        const pathArg = pathIdx === -1 ? null : args[pathIdx + 1]
+        const rules = args.filter(
+          (a, i) => !a.startsWith('-') && !(cwdIdx !== -1 && i === cwdIdx + 1) && !(pathIdx !== -1 && i === pathIdx + 1)
+        )
+        if (pathArg !== null && rules.length > 0) {
+          throw new Error(
+            '--path не можна поєднувати зі scoped rule/concern фільтром (позиційні аргументи) — оберіть щось одне'
+          )
+        }
+        let pathFiles = null
+        if (pathArg !== null) {
+          const { collectPathScopedFiles } = await import('../scripts/lib/lint-surface/path-scope.mjs')
+          pathFiles = await collectPathScopedFiles(cwdArg, pathArg)
+        }
+        // --full + --path: buildPlan ігнорує full, коли передано explicitFiles (той самий
+        // шлях), тож і тут full-вісь вважаємо неактивною — інакше глобальний machine-wide
+        // лок --full брався б для швидкого scoped-прогону без причини.
+        const full = args.includes('--full') && pathArg === null
+        const lintOpts = { cwd: cwdArg, full, rules, verbose: args.includes('--verbose'), files: pathFiles }
         const noFix = args.includes('--no-fix')
         // Глобальна черга full-прогонів (spec 2026-07-03): одночасно виконується один
         // `lint --full` на машину, паралельні --full чекають лока і бачать чергу та

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/rules/js/eslint/docs/fix-worker.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: fix-worker.mjs
+resource: npm/rules/js/eslint/fix-worker.mjs
+docgen:
+  crc: 1eb9c7fc
+  model: manual
+---
+
+## Огляд
+
+Custom fix-worker `js/eslint` (перекриває дефолтний `default-worker.mjs`): замість одного `runAgentFix`-виклику з усіма порушеннями з усіх файлів concern-а — окрема агентна сесія на кожен файл, у межах спільного дедлайну rung-а. Мотивація — виміряно на реальних lint-прогонах: одна сесія, що жонглює кількома файлами одразу, стабільно впирається у timeout на всіх 4 rung-ах драбини (local-min→cloud-avg), навіть при малому обсязі порушень; та сама модель, scoped на один файл, укладається в бюджет і закриває більшість порушень.
+
+## Поведінка
+
+1. Групує вхідні `violations` за `file`; порушення без `file` ігноруються.
+2. Дедлайн — `DEADLINE_FRACTION` (0.8) від `ctx.timeoutMs`; цикл перевіряє дедлайн ПЕРЕД стартом кожного файлу і не починає новий, якщо час вичерпано.
+3. Кожен файл отримує РЕШТУ бюджету до дедлайну (не фіксований поділ `timeoutMs / files.length`) — перший (часто найважчий) файл отримує найбільше часу.
+4. На кожен файл — окремий `runAgentFix` із `targetFiles: [file]` і власним `verify` (`verifyFile`): item-scoped canonical re-detect лише цього файлу, не всього concern-а — інакше evidence-гейт хибно вважав би файл незакритим через порушення в ІНШИХ файлах.
+5. Один файл, що завершився з `error`, не обриває цикл — пропускається, наступні файли все одно обробляються в межах дедлайну.
+6. Повертає лише `touchedFiles` з успішних (`!error`) викликів; success rung-а все одно визначає whole-concern canonical re-detect runner-а (`runRung`), не цей worker.
+
+## Публічний API
+
+- `fixWorker(violations, ctx)` — контракт `FixWorkerFn`; резолвиться автоматично замість `default-worker.mjs`, бо лежить як `fix-worker.mjs` поруч із `main.mjs` concern-а.
+
+## Гарантії поведінки
+
+- Пише лише у файли з переданих `violations` (`targetFiles: [file]` на кожен виклик) — той самий semantic-collateral guard, що й у дефолтного worker-а.
+- `recordWrite` (не durable) на кожен файл: rollback-контракт незмінний — якщо після worker-а в concern-і лишилось хоч одне порушення будь-де, `runRung` відкочує ВСІ правки цього rung-а, включно з уже полагодженими файлами.

package/rules/js/eslint/docs/index.md

@@ -0,0 +1,11 @@
+---
+type: Directory Index
+title: npm/rules/js/eslint
+resource: npm/rules/js/eslint/
+---
+
+| Файл                            | Тип       |
+| ------------------------------- | --------- |
+| [fix-eslint.mjs](fix-eslint.md) | JS Module |
+| [fix-worker.mjs](fix-worker.md) | JS Module |
+| [main.mjs](main.md)             | JS Module |

package/rules/js/eslint/fix-worker.mjs

@@ -0,0 +1,99 @@
+/**
+ * fix-worker для `js/eslint`: окрема агентна сесія НА ФАЙЛ замість одного великого промпту
+ * на всі файли concern-а одразу. Дефолтний worker (`default-worker.mjs`) шле ВСІ порушення
+ * з УСІХ файлів в один `runAgentFix`-виклик — на реальних lint-прогонах (tauri-components)
+ * це давало 100% timeout на всіх 4 rung-ах драбини (local-min→cloud-avg), навіть коли
+ * порушень було лише 20-90 у 1-3 файлах: одна сесія жонглює кількома файлами одразу і не
+ * встигає в rung-таймаут. Виміряно (2026-07-17, ручний timing-експеримент поза pipeline):
+ * одна сесія, scoped на ОДИН найважчий файл (21 порушення), закрила 76% (16/21) за 91с із
+ * бюджету 120с (cloud-min) — per-file scoping вкладається, mega-prompt — ні.
+ *
+ * Rollback-контракт незмінний: `recordWrite` (не durable) на кожен файл — правки наявного
+ * стороннього коду. Якщо після worker-а `runRung`-ів canonical re-detect (whole-concern)
+ * знайде хоч одне порушення будь-де, увесь rung однаково відкотиться (S1) — той самий
+ * контракт, що й у дефолтного worker-а; батчинг підвищує ймовірність, що ЦЕЙ rung дійде
+ * до 0 порушень, а не замінює rollback-семантику.
+ *
+ * Дедлайн (`DEADLINE_FRACTION` від `ctx.timeoutMs`, той самий підхід, що й
+ * `doc-files/check/fix-worker.mjs`): цикл не стартує наступний файл, якщо дедлайн
+ * настав — worker повертає часткову роботу штатно, замість фонової сесії, що триває
+ * поверх backstop ×1.25 runner-а. Кожен файл отримує РЕШТУ бюджету до дедлайну (не
+ * фіксований `timeoutMs / files.length`) — перший (часто найважчий) файл отримує
+ * найбільше часу, а не штучно урізаний рівний шматок.
+ * @typedef {import('../../../scripts/lib/lint-surface/types.mjs').FixWorkerFn} FixWorkerFn
+ */
+import { resolve } from 'node:path'
+
+import { anchoredEnabled } from '../../../scripts/lib/lint-surface/default-worker.mjs'
+import { renderViolations } from '../../../scripts/lib/lint-surface/render.mjs'
+import { lint } from './main.mjs'
+
+/** Частка ctx.timeoutMs, після якої цикл не стартує наступний файл (запас до backstop ×1.25). */
+const DEADLINE_FRACTION = 0.8
+
+/**
+ * Item-scoped (один файл) canonical re-detect для evidence-гейта `runAgentFix` —
+ * НЕ те саме, що whole-concern `ctx.verify` з `runRung` (той перевірив би ВСІ файли
+ * concern-а й дав би хибний "не готово" навіть коли саме ЦЕЙ файл уже чистий).
+ * @param {string} cwd абсолютний корінь проєкту
+ * @param {string} ruleId id правила
+ * @param {string} concernId id concern-а
+ * @param {string} file posix-relative шлях файлу, що перевіряється
+ * @returns {Promise<{ ok: boolean, output: string }>} вердикт verify-петлі
+ */
+async function verifyFile(cwd, ruleId, concernId, file) {
+  const { violations: after } = await lint({ cwd, ruleId, concernId, files: [file] })
+  const stamped = after.map(v => ({ ...v, ruleId, concernId }))
+  return { ok: stamped.length === 0, output: renderViolations(stamped) }
+}
+
+/** @type {FixWorkerFn} */
+export async function fixWorker(violations, ctx) {
+  // lazy import — тримає detect-шлях вільним від pi/oxc (read-only --no-fix не вантажить їх).
+  const [{ runAgentFix }, { isLocalModel }, { extractContext }] = await Promise.all([
+    import('@7n/llm-lib/agent-fix'),
+    import('@7n/llm-lib/model-tiers'),
+    import('../../../scripts/utils/ast-extract.mjs')
+  ])
+
+  /** @type {Map<string, import('../../../scripts/lib/lint-surface/types.mjs').LintViolation[]>} */
+  const byFile = new Map()
+  for (const v of violations) {
+    if (!v.file) continue
+    const arr = byFile.get(v.file)
+    if (arr) arr.push(v)
+    else byFile.set(v.file, [v])
+  }
+  const files = byFile.keys().toArray()
+  if (files.length === 0) return { touchedFiles: [] }
+
+  const deadlineAt = ctx.timeoutMs ? Date.now() + Math.round(ctx.timeoutMs * DEADLINE_FRACTION) : null
+  const anchoredEdits = anchoredEnabled(ctx.model, isLocalModel)
+
+  const touchedFiles = []
+  for (const file of files) {
+    if (deadlineAt && Date.now() >= deadlineAt) break
+    const callTimeoutMs = deadlineAt ? Math.max(1000, deadlineAt - Date.now()) : ctx.timeoutMs
+
+    const res = await runAgentFix(ctx.ruleId, renderViolations(byFile.get(file)), ctx.cwd, {
+      model: ctx.model,
+      tier: ctx.tier,
+      timeoutMs: callTimeoutMs,
+      feedback: ctx.feedback ?? null,
+      caller: `fix:${ctx.ruleId}/${ctx.concernId}:${ctx.tier}:${file}`,
+      recordWrite: ctx.recordWrite,
+      chain: ctx.chain ?? null,
+      targetFiles: [file],
+      verify: () => verifyFile(ctx.cwd, ctx.ruleId, ctx.concernId, file),
+      verifyMax: ctx.verifyMax,
+      anchoredEdits,
+      deps: { astContext: p => extractContext(resolve(ctx.cwd, p)) }
+    })
+
+    // Один файл не впорався — не кидаємо, пробуємо решту в межах дедлайну; whole-concern
+    // canonical re-detect runner-а (не цей worker) визначить, чи rung закрито.
+    if (!res.error) touchedFiles.push(...(res.touchedFiles ?? []))
+  }
+
+  return { touchedFiles }
+}

package/rules/js/knip/concern.json

@@ -1,5 +1,6 @@
 {
   "$schema": "https://unpkg.com/@7n/rules/schemas/concern.json",
+  "fixability": "structural",
   "lint": {
     "scope": "full"
   }

package/rules/text/markdownlint/docs/main.md

@@ -3,38 +3,27 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/text/markdownlint/main.mjs
 docgen:
-  crc: 08324688
-  model: openai-codex/gpt-5.5
-  tier: cloud-avg
-  score: 95
-  issues: anchor-miss:(text.mdc),judge:inaccurate:0.98
-  judgeModel: openai-codex/gpt-5.4-mini
+  crc: 6aec4713
+  model: manual
 ---
 
 ## Огляд
 
-Файл забезпечує markdown-концерн для двох поверхонь: `policy` перевіряє наявність `.markdownlint-cli2.jsonc`, а `lint` запускає markdownlint-cli2 для Markdown/MDC-файлів. Він потрібен, щоб delta- та full-режими однаково застосовували правила markdownlint до релевантних файлів і повертали повідомлення з маркером ``.
+Multi-surface detector `text/markdownlint`: `policy` перевіряє наявність `.markdownlint-cli2.jsonc`, `lint` запускає сам `markdownlint-cli2` (delta — по `ctx.files`, full — за glob `**/*.md`/`**/*.mdc`) і повертає обидва результати в одному `LintResult`.
 
 ## Поведінка
 
-1. `lint` перевіряє markdown-концерн у двох площинах: наявність конфігурації markdownlint і фактичну якість Markdown-документів.
-
-2. `lint` спочатку додає до результату порушення політики, якщо в проєкті немає `.markdownlint-cli2.jsonc`.
-
-3. `lint` у delta-режимі перевіряє лише передані Markdown-файли, а у full-режимі — всі файли Markdown і MDC у робочій директорії.
-
-4. `lint` не запускає markdownlint, якщо серед цільових файлів немає Markdown-документів, і повертає лише вже зібрані порушення політики.
-
-5. `lint` приглушує прямий вивід markdownlint, щоб detector повертав уніфікований результат lint-перевірки без шуму в консолі.
-
-6. `lint` додає порушення з маркером ``, якщо markdownlint знаходить проблеми у Markdown або MDC-файлах.
-
-7. `lint` повертає спільний список порушень для policy- та lint-поверхонь, щоб markdown-концерн поводився як один цілісний detector.
+1. Policy-перевірка (`evaluatePolicyConcern`) додає порушення, якщо `.markdownlint-cli2.jsonc` відсутній.
+2. Якщо серед цільових файлів немає Markdown/MDC — `markdownlint-cli2` не запускається, повертаються лише policy-порушення.
+3. `logMessage` (banner, `Finding:`/`Found:`/`Linting:`/`Summary:` прогрес-текст) — no-op, не деталь порушення.
+4. `logError` (один готовий рядок на порушення від дефолтного форматера markdownlint-cli2: `<file>:<line>:<col> <rule> <опис> [<деталь>]`) — накопичується в масив і вбудовується у violation-повідомлення. Без цього LLM fix-worker (і non-verbose підсумок) бачив лише голе "markdownlint знайшов порушення", без файлу/рядка/правила.
+5. Ненульовий exit-код `markdownlint-cli2` → одне порушення `reason: 'markdownlint'` з накопиченою деталлю.
 
 ## Публічний API
 
-- lint — знаходить для `text.mdc` маркери повідомлень, контролює наявність policy-конфігурації та запускає markdownlint; результати обох етапів збирає в один звіт lint.
+- `lint(ctx)` — detector-контракт unified lint surface; повертає `{ violations }` (policy + lint-порушення разом).
 
 ## Гарантії поведінки
 
-- Read-only: не виконує операцій запису (ФС/БД).
+- Read-only: не пише `.markdownlint-cli2.jsonc` сам — генерація конфігу окремим T0 (не в цьому detector-і).
+- `logError`-деталь — єдине джерело причини провалу; текстові евристики за кодом виходу не використовуються.

package/rules/text/markdownlint/main.mjs

@@ -32,22 +32,30 @@ export async function lint(ctx) {
   const targets = ctx.files === undefined ? DEFAULT_MD_GLOBS : ctx.files.filter(f => MD_EXT_RE.test(f))
   if (targets.length === 0) return { violations }
 
+  // logError отримує один готовий рядок на порушення через default output formatter
+  // markdownlint-cli2 ("<file>:<line>:<col> <rule> <опис> [<деталь>]") — раніше глушився,
+  // detector повертав лише голе "щось не пройшло" без файлу/правила/причини, тож LLM
+  // fix-worker (як і non-verbose підсумок) не мав інформації, що саме виправляти
+  // (той самий патерн, що й text/run-v8r до фіксу). logMessage лишається no-op —
+  // banner/Finding/Found/Linting/Summary прогрес-текст, не деталь порушення.
+  const errorLines = []
   const code = await markdownlintCli2({
     directory: ctx.cwd,
     argv: targets,
     logMessage: () => {
-      // вивід markdownlint-cli2 глушимо — detector лише повертає код
+      // прогрес-статус markdownlint-cli2 (banner, Finding/Found/Linting/Summary) — не деталь
     },
-    logError: () => {
-      // помилки markdownlint-cli2 глушимо — detector лише повертає код
+    logError: message => {
+      errorLines.push(message)
     }
   })
   if (code !== 0) {
+    const detail = errorLines.length > 0 ? `:\n${errorLines.join('\n')}` : ''
     violations.push({
       ruleId: ctx.ruleId,
       concernId: ctx.concernId,
       reason: 'markdownlint',
-      message: 'markdownlint знайшов порушення у *.md/*.mdc (text.mdc)'
+      message: `markdownlint знайшов порушення у *.md/*.mdc (text.mdc)${detail}`
     })
   }
 

package/scripts/lib/lint-surface/docs/index.md

@@ -13,6 +13,7 @@ resource: npm/scripts/lib/lint-surface/
 | [ladder.mjs](ladder.md)                                     | JS Module |
 | [lint-lock.mjs](lint-lock.md)                               | JS Module |
 | [mt-tail.mjs](mt-tail.md)                                   | JS Module |
+| [path-scope.mjs](path-scope.md)                             | JS Module |
 | [policy-lint-adapter.mjs](policy-lint-adapter.md)           | JS Module |
 | [policy-test-step.mjs](policy-test-step.md)                 | JS Module |
 | [progress.mjs](progress.md)                                 | JS Module |

package/scripts/lib/lint-surface/docs/path-scope.md

@@ -0,0 +1,31 @@
+---
+type: JS Module
+title: path-scope.mjs
+resource: npm/scripts/lib/lint-surface/path-scope.mjs
+docgen:
+  crc: 0971e78e
+  model: openai-codex/gpt-5.4-mini
+  tier: cloud-min
+  score: 100
+  issues: judge:inaccurate:0.94
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл звужує `n-rules lint --path <dir>` до каталогу всередині вже вибраного кореня прогону, не змінюючи сам root і не підміняючи правила з `.n-rules.json`. Він збирає всі файли під заданою піддиректорією та передає їх у `buildPlan` як `explicitFiles`, тим самим шляхом, що вже живить `hook --post-tool-use`/`--stop`; per-file concerns фільтруються за цими файлами, а `full`-scope concerns запускаються при збігу glob і все одно проходять whole-repo.
+
+## Поведінка
+
+1. `collectPathScopedFiles` приймає корінь прогону та значення `--path`, звужує область lint до каталогу всередині цього кореня й не змінює сам корінь прогону.
+2. `collectPathScopedFiles` відхиляє шлях, якщо він веде поза межі кореня або не є каталогом.
+3. `collectPathScopedFiles` збирає всі файли в межах вказаного каталогу, відсікаючи виключення з кореневих ignore-налаштувань і `.gitignore`-поведінки, а порожній каталог вважає валідним порожнім результатом.
+4. `collectPathScopedFiles` повертає відсортований список шляхів відносно кореня прогону у форматі, придатному для передачі в `buildPlan` як `explicitFiles`.
+
+## Публічний API
+
+- collectPathScopedFiles — збирає posix-відносні від `cwd` шляхи всіх файлів у каталозі з `--path`, з урахуванням `.gitignore` і `.n-rules.json:ignore` у корені; порожній каталог повертає порожній набір без помилки
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/lint-surface/path-scope.mjs

@@ -0,0 +1,58 @@
+/**
+ * Резолвер explicit-files списку для `n-rules lint --path <dir>`.
+ *
+ * На відміну від `--cwd` (підміняє корінь прогону — root-guard, `.n-rules.json`,
+ * devDependencies), `--path` лишає корінь незмінним і лише звужує файловий
+ * набір: збирає всі файли під заданою піддиректорією й передає їх у
+ * `buildPlan` як `explicitFiles`, тим самим шляхом, що вже годує
+ * `hook --post-tool-use`/`--stop` (per-file concerns фільтруються по цих
+ * файлах; `full`-scope concerns запускаються при збігу glob, але самі
+ * все одно проходять whole-repo — так уже поводиться delta-режим).
+ */
+import { existsSync, statSync } from 'node:fs'
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+
+import { loadCursorIgnorePaths } from '../load-cursor-config.mjs'
+import { walkDir } from '../../utils/walkDir.mjs'
+
+/**
+ * Перевіряє, що резолвлений `--path` лежить усередині `cwd` (не traversal
+ * через `..` і не абсолютний шлях поза коренем прогону).
+ * @param {string} cwd абсолютний корінь прогону.
+ * @param {string} target абсолютний резолв значення `--path`.
+ * @returns {void}
+ */
+function assertWithinCwd(cwd, target) {
+  const rel = relative(cwd, target)
+  if (rel === '') return
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`--path має вказувати каталог усередині ${cwd} (отримано поза межами: ${target})`)
+  }
+}
+
+/**
+ * Збирає posix-відносні (від `cwd`) шляхи всіх файлів під `--path`-каталогом,
+ * поважаючи `.gitignore` і `.n-rules.json:ignore` кореня. Порожній каталог —
+ * валідний порожній результат (план виявиться порожнім), не помилка.
+ * @param {string} cwd абсолютний корінь прогону (root-guard уже пройдено).
+ * @param {string} pathArg значення `--path` (відносний або абсолютний шлях).
+ * @returns {Promise<string[]>} відсортовані posix-відносні шляхи від `cwd`.
+ */
+export async function collectPathScopedFiles(cwd, pathArg) {
+  const target = resolve(cwd, pathArg)
+  assertWithinCwd(cwd, target)
+  if (!existsSync(target) || !statSync(target).isDirectory()) {
+    throw new Error(`--path не є каталогом: ${target}`)
+  }
+  const ignorePaths = await loadCursorIgnorePaths(cwd)
+  /** @type {string[]} */
+  const out = []
+  await walkDir(
+    target,
+    abs => {
+      out.push(relative(cwd, abs).split(sep).join('/'))
+    },
+    ignorePaths
+  )
+  return out.toSorted((a, b) => a.localeCompare(b))
+}