@7n/rules 1.40.0 → 1.41.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [1.41.0] - 2026-07-22
+
+### Fixed
+
+- doc-files: прибрано безумовний T0 CRC-штамп для crc-mismatch (fix-check.mjs) — свіжий CRC поверх застарілого тексту назавжди маскував дрейф доки; тепер застаріла дока завжди регенерується fix-worker-ом (docgen). Guardrail: detectRefusalFiller ловить нові живі refusal-фрази локальної моделі («мені потрібен сам код», «щоб написати точну документацію», «I need the code»)
+
+## [1.40.1] - 2026-07-22
+
+### Fixed
+
+- `lint --full`: загублений `await` перед `ensureRunningInWorktree` ламав кожен прогін (у т.ч. зсередини `.worktrees/`) з `TypeError [ERR_INVALID_ARG_TYPE]`; заодно — guard проти видалення auto-created worktree при частковому провалі перенесення змін назад, і stack trace для programmer-помилок у top-level catch
+
 ## [1.40.0] - 2026-07-22
 
 ### Changed

package/bin/n-rules.js

@@ -1848,7 +1848,7 @@ try {
         // дереві задачі, worktree-ізоляція зламала б саму суть дельти) — пропускаємо.
         const needsWorktreeIsolation = full && !noFix
         const worktree = needsWorktreeIsolation
-          ? ensureRunningInWorktree(cwdArg, spawnSync, line => console.log(line), {
+          ? await ensureRunningInWorktree(cwdArg, spawnSync, line => console.log(line), {
               suffix: 'lint',
               description: 'n-rules lint --full: worktree-only full-repo run'
             })
@@ -1881,14 +1881,26 @@ try {
         } finally {
           // Лише для АВТОстворених worktree (лінт уже сидів у своєму — не наш, не чіпаємо).
           if (worktree.autoCreated) {
+            let bringBackFailed = true
             try {
-              await bringChangesBackToOriginal(runCwd, cwdArg, spawnSync, line => console.log(line))
+              const bringBackResult = await bringChangesBackToOriginal(runCwd, cwdArg, spawnSync, line =>
+                console.log(line)
+              )
+              bringBackFailed = bringBackResult.failed
             } catch (error) {
               console.log(
                 `⚠️ Перенесення змін назад провалилось: ${error instanceof Error ? error.message : String(error)}`
               )
             }
-            removeAutoCreatedWorktree(worktree.branchArg, cwdArg, spawnSync, line => console.log(line))
+            // Прибираємо worktree лише якщо перенесення точно вдалось — інакше
+            // не перенесені зміни згорять разом з деревом.
+            if (bringBackFailed) {
+              console.log(
+                `⚠️ Перенесення назад не підтверджено — worktree "${worktree.branchArg}" лишається для ручного розбору.`
+              )
+            } else {
+              removeAutoCreatedWorktree(worktree.branchArg, cwdArg, spawnSync, line => console.log(line))
+            }
           }
         }
 
@@ -1964,8 +1976,15 @@ try {
     }
   }
 } catch (error) {
+  // TypeError/RangeError/ReferenceError сигналять баг у самому коді (не навмисне
+  // user-facing повідомлення) — друкуємо stack одразу, інакше діагностика вимагає
+  // патчити node_modules вручну (як під час діагностики цього ж класу вад).
+  const isProgrammerError = error instanceof TypeError || error instanceof RangeError || error instanceof ReferenceError
   if (error instanceof ReexecHandoff) {
     process.exitCode = error.code
+  } else if (isProgrammerError && error.stack) {
+    console.error(error.stack)
+    process.exitCode = 1
   } else if (error instanceof Error && error.message) {
     console.error(error.message)
     process.exitCode = 1

package/package.json

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

package/rules/doc-files/check/docs/fix-worker.md

@@ -3,7 +3,7 @@ type: JS Module
 title: fix-worker.mjs
 resource: npm/rules/doc-files/check/fix-worker.mjs
 docgen:
-  crc: 27e4dca1
+  crc: 452ab360
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
   score: 100
   issues: judge:inaccurate:0.98
@@ -13,6 +13,8 @@ docgen:
 
 Файл забезпечує генерацію застарілих або відсутніх файлових доків за допомогою docgen-pipeline (локальна/хмарна модель) через функцію fixWorker. Кожна згенерована дока реєструється як durable-write (самодостатній кінцевий стан зі свіжим CRC), тому rollback провального rung-а її не стирає, а великий беклог сходиться за кілька прогонів (issue nitra/cursor#16). Видалення сирітських доків лишається під звичайним rollback.
 
+Інваріант конвеєра: `crc-mismatch` не закривається детермінованим T0-штампом CRC (fix-check.mjs для check свідомо відсутній) — свіжий CRC поверх старого тексту назавжди маскував би дрейф доки. Застаріла дока завжди йде через регенерацію тут; свіжий CRC зʼявляється лише разом зі щойно згенерованим вмістом (stampDoc усередині runGenerationBatch).
+
 ## Поведінка
 
 1. Викликається `fixWorker`.
@@ -26,3 +28,4 @@ docgen:
 ## Гарантії поведінки
 
 - Кожна записана дока — валідний фінальний стан (свіжий CRC; degraded теж валідна) — часткова робота не втрачається при таймауті/провалі rung-а.
+- CRC у frontmatter ніколи не оновлюється без регенерації вмісту — дрейф доки не маскується.

package/rules/doc-files/check/fix-worker.mjs

@@ -8,6 +8,12 @@
  * тож rollback провального rung-а її не стирає, і великий беклог сходиться
  * крок за кроком за кілька прогонів. Видалення сирітських док лишається під
  * звичайним rollback (ctx.recordWrite).
+ *
+ * Інваріант: `crc-mismatch` НЕ закривається детермінованим T0-штампом CRC
+ * (fix-check.mjs для check свідомо відсутній). Свіжий CRC поверх старого тексту
+ * назавжди маскує дрейф — CRC-гейт вважає доку актуальною і вона більше ніколи
+ * не регенерується. Свіжий CRC зʼявляється лише разом зі щойно згенерованим
+ * вмістом (stampDoc усередині runGenerationBatch).
  * @typedef {import('../../../scripts/lib/lint-surface/types.mjs').FixWorkerFn} FixWorkerFn
  */
 import { join } from 'node:path'

package/rules/doc-files/docgen-judge/docs/main.md

@@ -3,13 +3,13 @@ type: JS Module
 title: main.mjs
 resource: npm/rules/doc-files/docgen-judge/main.mjs
 docgen:
-  crc: ac56c24b
+  crc: 47127362
   model: omlx/gemma-4-e4b-it-OptiQ-4bit
 ---
 
 ## Огляд
 
-Огляд: Цей файл визначає інтерфейс для механізму семантичного судження якості згенерованої технічної документації за допомогою мовної моделі. Він конфігурує параметри (`JUDGE_MODEL`, `JUDGE_ENABLED`, `JUDGE_CONFIDENCE`) та надає read-only функції для ініціації судження та інтерпретації його результатів. Додатково містить детермінований пре-гейт `detectRefusalFiller` (0 токенів): курований список refusal/чат-філер фраз моделі («Я готовий писати…», «Надайте мені код…»), які структурний скорер і суддя пропускали (живий кейс: score=95 на доці з суцільним філером).
+Огляд: Цей файл визначає інтерфейс для механізму семантичного судження якості згенерованої технічної документації за допомогою мовної моделі. Він конфігурує параметри (`JUDGE_MODEL`, `JUDGE_ENABLED`, `JUDGE_CONFIDENCE`) та надає read-only функції для ініціації судження та інтерпретації його результатів. Додатково містить детермінований пре-гейт `detectRefusalFiller` (0 токенів): курований список refusal/чат-філер фраз моделі («Я готовий писати…», «Надайте мені код…», «мені/нам потрібен сам код/файл/вміст», «щоб написати точну документацію», «I need the code»), які структурний скорер і суддя пропускали (живі кейси: score=95 на доці з суцільним філером; 2026-07-21 — «Щоб написати точну документацію, мені потрібен сам код…» злите прямо в тіло доки).
 
 Поведінка:
 JUDGE_MODEL — конфігурує LLM, яка використовується для семантичного судження якості документації.

package/rules/doc-files/docgen-judge/main.mjs

@@ -35,9 +35,11 @@ const VERDICTS = new Set(['accurate', 'generic', 'inaccurate'])
  * Детермінований пре-гейт (0 токенів) ПЕРЕД LLM-суддею: чат-філер/refusal локальної
  * моделі замість документації. Живий кейс: дока зі score=95, де секції — суцільне
  * «Я готовий писати поведінкову документацію… Надайте мені код» (gemma) — судді
- * структура здалась валідною. Курований безпечний список (перша особа/імператив до
- * користувача не трапляються у нормальній поведінковій доці); без `\b` — кирилиця
- * не ASCII-`\w`, JS-межі слова не спрацьовують.
+ * структура здалась валідною. Другий живий кейс (2026-07-21, робота над storybook):
+ * модель злила «Щоб написати точну документацію, мені потрібен сам код…» прямо в
+ * тіло доки — жоден зі старих патернів не збігався. Курований безпечний список
+ * (перша особа/імператив до користувача не трапляються у нормальній поведінковій
+ * доці); без `\b` — кирилиця не ASCII-`\w`, JS-межі слова не спрацьовують.
  */
 const REFUSAL_FILLER_RES = [
   /я готов(?:ий|а)/iu,
@@ -47,8 +49,12 @@ const REFUSAL_FILLER_RES = [
   /не можу\s+(?:згенерувати|створити|написати)/iu,
   /чекаю на\s+(?:код|файл|вміст)/iu,
   /давайте почнемо/iu,
+  // живий кейс 2026-07-21: «Щоб написати точну документацію, мені потрібен сам код…»
+  /(?:мені|нам)\s+(?:потрібен|потрібно|потрібна|потрібні)\s+(?:сам(?:ий|е)?\s+)?(?:код|файл|вміст|джерел)/iu,
+  /щоб написати\s+(?:точну|повну|якісну|детальну)\s+документацію/iu,
   /as an ai(?: language)? model/iu,
   /i(?:['’]m| am)\s+(?:ready to|unable to)/iu,
+  /i need\s+(?:the\s+)?(?:source\s+)?(?:code|file)/iu,
   /please provide(?: the| me)?\s+(?:code|file|source)/iu
 ]
 

package/rules/doc-files/main.mdc

@@ -30,8 +30,12 @@ unified lint surface (spec `docs/specs/2026-06-29-unified-lint-surface.md`) і
 
 Алгоритм детекту (кандидати, ignore-дерево, CRC, реверс-мапінг доки→джерело) — у
 `docgen-scan/main.mjs` / `docgen-crc/main.mjs` / `docgen-ignore/main.mjs`, детектор — у
-`check/main.mjs` (`lint(ctx)`), fix — у `check/fix-check.mjs` (T0) і `check/fix-worker.mjs`
-(LLM); тут — лише людинозрозумілий контракт, без дублювання логіки.
+`check/main.mjs` (`lint(ctx)`), fix — лише `check/fix-worker.mjs` (LLM-регенерація); тут —
+лише людинозрозумілий контракт, без дублювання логіки.
+
+T0-штампу CRC для `crc-mismatch` **немає навмисно**: свіжий CRC поверх старого тексту
+назавжди маскує дрейф (CRC-гейт вважає доку актуальною і вона більше не регенерується).
+Свіжий CRC пише лише генерація разом із новим вмістом.
 
 ## Hook'и
 

package/rules/doc-files/check/docs/fix-check.md

@@ -1,28 +0,0 @@
----
-type: JS Module
-title: fix-check.mjs
-resource: npm/rules/doc-files/check/fix-check.mjs
-docgen:
-  crc: 9a1d9107
-  model: omlx/gemma-4-e4b-it-OptiQ-4bit
-  tier: local-min
-  score: 100
-  issues: judge:inaccurate:0.97
-  judgeModel: openai-codex/gpt-5.4-mini
----
-
-## Огляд
-
-Файл реалізує детерміноване оновлення CRC-штампів у документації, що спрацьовує після виявлення розбіжності `crc-mismatch`. Механізм автоматично оновлює метадані документації, щоб фіксувати відповідність між зміненими джерелами та вже існуючим, незміненим контентом. Це забезпечує точну валідацію метаданих системи.
-
-## Поведінка
-
-1.  Перевіряється наявність вказівок на розбіжність CRC у документації.
-2.  Для документації, яка відповідає критеріям розбіжності CRC, але є цілісною, виконується детерміноване оновлення CRC в метаданих.
-3.  Операція включає аналіз якості документації, ініційована з використанням відповідних моделей.
-4.  Оновлена документація записується у файл, ідентифікований шляхом до документації, що відповідає розбіжності.
-5.  Повертається булеве значення, що вказує на те, чи було внесено зміни у документацію.
-
-## Гарантії поведінки
-
-- (специфічних машинно-виведених гарантій немає)

package/rules/doc-files/check/fix-check.mjs

@@ -1,45 +0,0 @@
-/**
- * T0-autofix doc-files/check — детермінований CRC-stamp для `crc-mismatch` доків
- * (джерело змінилось, але дока актуальна → лише оновити CRC у frontmatter, без LLM).
- * `missing`/`degraded`/`orphaned-doc` лишаються worker-у (генерація/очистка).
- *
- * Unified lint surface: structured violations; запускається ПЕРЕД fix-worker-ом.
- */
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-
-/** @type {import('../../../scripts/lib/lint-surface/types.mjs').T0Pattern[]} */
-export const patterns = [
-  {
-    id: 'doc-files-stamp-crc',
-    test: violations => violations.some(v => v.reason === 'crc-mismatch'),
-    apply: async (violations, ctx) => {
-      const { scanForDocFiles } = await import('../docgen-scan/main.mjs')
-      const { crc32, readDocModel, readDocQuality, stampDoc } = await import('../docgen-crc/main.mjs')
-      const { cwd } = ctx
-      /** @type {string[]} */
-      const touchedFiles = []
-
-      const staleFiles = scanForDocFiles(cwd).filter(f => f.stale && f.reason === 'crc-mismatch')
-      for (const file of staleFiles) {
-        const sourceAbs = join(cwd, file.sourcePath)
-        const docAbs = join(cwd, file.docPath)
-        if (!existsSync(docAbs)) continue // missing → worker, не T0
-        const { score, issues, judgeModel } = readDocQuality(docAbs)
-        const quality = score === null ? null : { score, issues, judge: judgeModel ? { model: judgeModel } : undefined }
-        const crc = crc32(readFileSync(sourceAbs))
-        ctx.recordWrite?.(docAbs)
-        mkdirSync(dirname(docAbs), { recursive: true })
-        writeFileSync(
-          docAbs,
-          stampDoc(readFileSync(docAbs, 'utf8'), file.sourcePath, crc, quality, readDocModel(docAbs))
-        )
-        touchedFiles.push(docAbs)
-      }
-
-      return touchedFiles.length > 0
-        ? { touchedFiles, message: `stamped CRC: ${touchedFiles.length} доки(ів)` }
-        : { touchedFiles: [] }
-    }
-  }
-]