@7n/rules 1.0.0

package/scripts/lib/lint-surface/docs/codegen-opa-wrapper.md

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: codegen-opa-wrapper.mjs
+resource: npm/scripts/lib/lint-surface/codegen-opa-wrapper.mjs
+docgen:
+  crc: 10226c5a
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Хелпери відрізняють застарілий згенерований `main.mjs` від ручного escape-hatch-файлу та визначають, чи `concern.json` містить конкретні файлові цілі для прямої оцінки policy-concern-а. Файл існує, щоб підтримати перехід policy-concern-ів на оцінку напряму з `concern.json` без обов’язкового generated `main.mjs`.
+
+## Поведінка
+
+- `isGeneratedFile` визначає, чи є файл застарілим згенерованим артефактом, щоб відрізняти його від ручного `main.mjs` для custom-detector-ів.
+- `hasResolvableFiles` визначає, чи опис файлів у `concern.json` вказує на конкретні цілі для прямої оцінки policy-concern-а.
+
+## Публічний API
+
+- isGeneratedFile — розпізнає файли, створені автоматично, щоб не оцінювати їх як ручний код; спирається на `concern.json`.
+- hasResolvableFiles — визначає, чи `policy.files` у concern можна звести до конкретних цілей через одиночний файл або glob-обхід; concern без таких цілей має виконуватись через parent-концерн або вважатись неповним для прямої оцінки.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/lint-surface/docs/collateral-veto.md

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: collateral-veto.mjs
+resource: npm/scripts/lib/lint-surface/collateral-veto.mjs
+docgen:
+  crc: 16d3ef02
+---
+
+## Огляд
+
+Semantic-collateral veto для verdict-фази fix-pipeline (spec pi-fix-engine-migration §12, addendum 2026-07-05). Закриває клас collateral слабких локальних моделей: «виправляючи» правило, модель робить семантичну правку у сторонньому файлі, яка не порушує жодного правила й тому проходить canonical re-detect (кейс App.vue: хардкод версії з коментарем «we simulate it being available» замість виклику `getVersion`).
+
+## Поведінка
+
+1. `findCollateralEdits` порівнює список змінених наявних файлів rung-а (`snapshot.modifiedExisting()`) із target-set порушення (`violations[].file ∪ item.files`) і повертає правки поза target-set.
+2. Нові файли до veto не входять — легітимний клас (scaffold, доки поряд із кодом); їх покриває re-check зачеплених файлів і rollback.
+3. Порожній target-set (whole-repo концерни без `file` у violations) → veto незастосовний: свідомий fail-open, повертається порожній масив.
+4. Усі шляхи realpath-нормалізуються (`realpathBestEffort`, той самий патерн, що у write-guard llm-lib) — знімає symlink-розбіжності macOS (`/tmp` → `/private/tmp`); caller relativize-ить результати від так само нормалізованого cwd.
+
+## Публічний API
+
+- `findCollateralEdits({ modifiedExisting, targetFiles, cwd })` — нормалізовані абсолютні шляхи відхилених правок; порожньо — collateral немає або target-set невідомий.
+- `realpathBestEffort(p)` — realpath з найкращих зусиль (наявний файл → повний realpath; неіснуючий → realpath батьківської теки + basename; інакше — як є).
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Ніколи не кидає: помилки realpath ігноруються з поверненням шляху як є.

package/scripts/lib/lint-surface/docs/default-worker.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: default-worker.mjs
+resource: npm/scripts/lib/lint-surface/default-worker.mjs
+docgen:
+  crc: c5ac8bf6
+  model: openai-codex/gpt-5.5
+---
+
+## Огляд
+
+Файл надає дефолтний LLM fix-worker для unified lint surface: `fixWorker` є адаптером до `runAgentFix` під контракт `fixWorker → { touchedFiles, telemetry? }`. Він існує як запасний обробник для concern-ів без власного `fix-worker.mjs`, повертає central pipeline-у змінені файли й опційну telemetry та не пише самостійно у ФС/БД. Записи LLM-процесу проходять через central write-guard як `onCapture = ctx.recordWrite`, щоб `pre-image` потрапляв у central snapshot до запису, а rollback міг відкочувати ці правки. Worker виконує один attempt, а успіх визначає повторний canonical re-detect runner-а.
+
+## Поведінка
+
+1. `fixWorker` приймає набір lint-порушень і контекст виправлення як дефолтний LLM-обробник для unified lint surface.
+
+2. Перетворює знайдені порушення на текстове завдання для LLM, щоб агент отримав зрозумілий опис проблем, які треба виправити; додатково збирає target-set порушення (унікальні `violations[].file`) і передає його як `targetFiles` у промпт — перший шар semantic-collateral guard (§12, addendum 2026-07-05), verdict-veto runner-а звіряє фактичні правки з тим самим набором.
+
+3. Запускає Pi-агента для внесення правок за правилом, concern-ом, робочою текою, вибраною моделлю, tier-ом і доступним feedback; прокидає per-tier `ctx.timeoutMs` (ADR 260620-0556) у `runAgentFix opts.timeoutMs`, щоб зависла LLM-сесія переривалась зсередини, а не блокувала lint; прокидає також evidence-гейт (`ctx.verify`/`ctx.verifyMax`, Фаза A1 run-harness) — провал canonical-перевірки інʼєктиться фідбеком у ту саму pi-сесію замість одразу нового рунга; anchored-edits профіль (Фаза A2) керується env `N_LLM_FIX_ANCHORED` (`1` — усі тири, `cloud` — лише не-local моделі, `0` — вимкнено); дефолт `cloud` за bench A/B 2026-07-11 (docs/specs/2026-07-11-anchored-verify-bench-results.md).
+
+4. Передає механізм фіксації записів у central pipeline, щоб write-guard зберігав pre-image до зміни файлів і rollback rung-а міг відкочувати також LLM-правки.
+
+5. Трактує один запуск агента як один attempt: сам `fixWorker` не визначає остаточний успіх виправлення, бо це робить canonical re-detect runner після повторної перевірки.
+
+6. Якщо агент повертає помилку, `fixWorker` зупиняє виконання помилкою, щоб pipeline не вважав attempt успішним.
+
+7. Повертає список змінених файлів і, за наявності, telemetry для подальшої обробки central pipeline-ом.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,38 @@
+---
+type: JS Module
+title: detect.mjs
+resource: npm/scripts/lib/lint-surface/detect.mjs
+docgen:
+  crc: 6080123e
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 90
+  issues: internal-name:evaluatePolicyConcern,judge:inaccurate:0.92
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл виконує detect-крок unified lint surface для одного concern-detector-а: запускає detector read-only, спирається на `concern.json` і повертає нормалізований `LintResult`. `runConcernDetector` є публічним entrypoint для цього запуску, а `DetectorError` уніфікує технічні збої detector-а й невалідні результати як інфраструктурний failure лінту. Тут немає LLM, autofix чи мутацій дерева.
+
+## Поведінка
+
+- `DetectorError` позначає збій detector-а або невалідний результат як помилку інфраструктури лінту, щоб unified lint surface міг завершитись із технічним failure.
+- `runConcernDetector` запускає один concern-detector у read-only режимі, обирає policy-оцінювання за `concern.json` або ручний detector, нормалізує результат до єдиного формату й перетворює аномалії на `DetectorError`.
+
+## Публічний API
+
+- DetectorError — позначає збій detector-а або непридатний результат; такий стан завершує виконання з exit 2.
+- runConcernDetector — запускає detector для одного concern-а, приводить відповідь до очікуваного формату й перетворює будь-яку аномалію на `DetectorError`.
+
+Код спирається на конфіг `concern.json`.
+
+Чисті policy-concern-и на основі rego/template виконуються напряму через `evaluatePolicyConcern` з даних `concern.json`; генерований `main.mjs` для них не потрібен.
+
+Ручний не-`@generated` `main.mjs` є escape-hatch і завжди має пріоритет над policy-оцінкою.
+
+Concern-и без policy і без `main.mjs` вважаються помилкою конфігурації.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,27 @@
+---
+type: Directory Index
+title: npm/scripts/lib/lint-surface
+resource: npm/scripts/lib/lint-surface/
+---
+
+| Файл                                                        | Тип       |
+| ----------------------------------------------------------- | --------- |
+| [codegen-opa-wrapper.mjs](codegen-opa-wrapper.md)           | JS Module |
+| [collateral-veto.mjs](collateral-veto.md)                   | JS Module |
+| [default-worker.mjs](default-worker.md)                     | JS Module |
+| [detect.mjs](detect.md)                                     | JS Module |
+| [ladder.mjs](ladder.md)                                     | JS Module |
+| [lint-lock.mjs](lint-lock.md)                               | JS Module |
+| [mt-run-node.mjs](mt-run-node.md)                           | JS Module |
+| [mt-tail.mjs](mt-tail.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 |
+| [render.mjs](render.md)                                     | JS Module |
+| [run-detectors.mjs](run-detectors.md)                       | JS Module |
+| [run-fix.mjs](run-fix.md)                                   | JS Module |
+| [snapshot.mjs](snapshot.md)                                 | JS Module |
+| [tier-sampling-bench.mjs](tier-sampling-bench.md)           | JS Module |
+| [tier-sampling-experiment.mjs](tier-sampling-experiment.md) | JS Module |
+| [types.mjs](types.md)                                       | JS Module |
+| [violation-reporter.mjs](violation-reporter.md)             | JS Module |

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

@@ -0,0 +1,33 @@
+---
+type: JS Module
+title: ladder.mjs
+resource: npm/scripts/lib/lint-surface/ladder.mjs
+docgen:
+  crc: a5e45f08
+  model: openai-codex/gpt-5.5
+  score: 100
+  issues: judge:inaccurate:0.97
+---
+
+## Огляд
+
+Файл визначає чисті правила tier-ladder для central fix-pipeline: `DEFAULT_MAX_AVG`, `buildLadder`, `classifyFixError` і `decideAfterFailure` будують доступний ланцюжок рівнів виправлення від локального до cloud-avg, класифікують причину невдачі та вирішують подальшу ескалацію. Він потрібен, щоб central fix-pipeline мав єдину поведінку ескалації за `2026-06-19-fix-escalation-cascade` і `2026-06-29-unified-lint-surface §Tier Ladder`, без залежності від старого `orchestrator.mjs`, який видаляється на cutover.
+
+## Поведінка
+
+- `DEFAULT_MAX_AVG` задає типовий ліміт звернень до середнього cloud-рівня за один прогін, щоб ескалація не витрачала надмірно дорогий ресурс.
+- `buildLadder` формує послідовність рівнів виправлення від локального мінімального до cloud-avg і відкидає недоступні рівні без моделі.
+- Кожен rung несе `timeoutMs` — per-tier таймаут виклику (ADR 260620-0556): локальні рівні 45s, хмарні 120s; override без зміни коду — env `N_LOCAL_FIX_TIMEOUT_MS` / `N_CLOUD_FIX_TIMEOUT_MS` (мс на ОДИН rung відповідного класу; невалідне значення → дефолт). Runner прокидає його worker-у через `FixContext`, щоб зависла LLM-сесія переривалась (runner додатково тримає backstop ×1.25), а ladder рухався далі. Це робочий важіль для повільної локальної моделі чи великої черги batch-концерну (doc-files ріже беклог під цей ліміт м'яким дедлайном).
+- `classifyFixError` визначає характер помилки виправлення: системна причина, транспортний збій або якісна невдача агента.
+- `decideAfterFailure` вирішує, чи продовжувати ескалацію після невдалого рівня, чи пропустити локальну модель, чи зупинити процес.
+
+## Публічний API
+
+- DEFAULT_MAX_AVG — задає стандартну межу звернень до cloud-avg за один прогін, щоб кілька concerns не витратили avg-бюджет.
+- buildLadder — формує ladder з доступних тирів і прибирає rung-и без заданої моделі.
+- classifyFixError — відносить збій worker-а до systemic, transport або quality; агентний backstop-timeout трактує як quality, щоб ladder перейшов до сильнішого rung-а.
+- decideAfterFailure — визначає, що робити після невдалого rung-а: зупинити ladder або пропустити поточну модель.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

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

@@ -0,0 +1,47 @@
+---
+type: JS Module
+title: lint-lock.mjs
+resource: npm/scripts/lib/lint-surface/lint-lock.mjs
+docgen:
+  crc: 23bf1b2c
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл серіалізує лише довгі machine-wide запуски `n-rules lint --full`, щоб на машині одночасно виконувався щонайбільше один full-прогін. Delta, scoped і `--no-fix` запуски не беруть глобальний лок і не стають у цю чергу.
+
+Активний full-прогін записує власника лока в `owner.json` і публікує живий стан у `progress.json`, щоб процеси в очікуванні бачили поточного виконавця та прогрес. Процеси в черзі реєструються у `queue/<enqueuedAt>-<pid>.json`, що дає видимий список очікування й позицію кожного запуску.
+
+Дедуплікація спирається на fingerprint і TTL у механіці лока, а не на файли стану. За неможливості безпечно дочекатися черги запуск завершується fail-closed, щоб не допустити мовчазного паралельного full-прогону.
+
+## Поведінка
+
+- `GLOBAL_CACHE_DIR` задає спільне machine-wide місце стану для черги full-лінту, включно з `owner.json` і `progress.json`.
+
+- `lintLockFingerprint` формує ключ дедуплікації для full-лінту з урахуванням стану дерева й варіанта запуску; повертає порожнє значення, коли безпечно дедуплікувати неможливо.
+
+- `createProgressPublisher` публікує throttled-знімки прогресу активного full-прогону в `progress.json`, щоб процеси в черзі бачили живий стан без зайвого навантаження на диск.
+
+- `renderWaitLine` створює однорядковий статус очікування з позицією в черзі, поточним власником лока з `owner.json`, прогресом із `progress.json` і рештою очікувачів.
+
+- `withGlobalLintLock` серіалізує лише `--full` запуски лінту через глобальну чергу, а короткі дельта/scoped/`--no-fix` запуски пропускає одразу; при timeout завершується fail-closed, щоб не допустити паралельний full-прогін.
+
+## Публічний API
+
+- GLOBAL_CACHE_DIR — зберігає спільний machine-wide стан лока й черги для всіх repo та worktree; спирається на owner.json і progress.json.
+- lintLockFingerprint — формує ключ для TTL-дедуплікації за станом робочого дерева та режимом запуску lint; повертає null поза git-repo або коли --cwd відрізняється від process cwd, щоб не прив’язати прогін до чужого дерева.
+- createProgressPublisher — публікує прогрес активного lint-прогону в progress.json, щоб процеси в черзі бачили актуальний progress bar власника лока.
+- renderWaitLine — показує стан очікування в черзі: позицію процесу, поточного власника з pid і текою, його прогрес та інші queued процеси.
+- withGlobalLintLock — запускає full lint під глобальним локом і чергою; delta, scoped та --no-fix прогони стартують одразу без очікування.
+
+## Гарантії поведінки
+
+- У кожен момент на машині виконується щонайбільше один `lint --full`; запуски в черзі стартують у порядку постановки.
+- Файлові операції стану (реєстрація в черзі, публікація прогресу, читання чужих записів) — best-effort: їх збій не валить прогін, лише зменшує видимість; записи мертвих PID прибираються при читанні списку.
+- Таймаут очікування черги — виняток (fail-closed), а не мовчазний паралельний запуск.
+- Ідентичний повторний `--full` на незміненому дереві дедуплікується за fingerprint у межах TTL (exit 0 без повторної роботи); поза git-репо чи при `--cwd` не на процесний cwd дедуплікація вимикається, черга лишається.

package/scripts/lib/lint-surface/docs/mt-run-node.md

@@ -0,0 +1,37 @@
+---
+type: JS Module
+title: mt-run-node.mjs
+resource: npm/scripts/lib/lint-surface/mt-run-node.mjs
+docgen:
+  crc: 01c3876b
+  model: openai-codex/gpt-5.4-mini
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей файл є executor-містом для fix-вузла MT у pi-harness: MT-runner (`@7n/mt#29`) спавнить цю команду замість вбудованого Claude-шляху для actor=agent вузлів. `argv[0]` і `MT_NODE_DIR` вказують на директорію вузла з `task.md` та `a.md`, `MT_WORKTREE` задає дерево, у якому застосовуються зміни, а `MT_MODEL_TIER` дублює `a.md` у значеннях `MIM|AVG|MAX`. Команда повертає stdout у форматі JSON `{"applied","touchedFiles"}`; `exit 0` означає, що MT сам запускає `## Check` і синтезує fact, а ненульовий exit означає `failed-run`. Її роль — виконати лише застосування змін у межах канонів тирів `omlx/pi-тири llm-lib`, тоді як claim/lease, worktree-ізоляція, budget/timeout, `## Check` і publish залишаються на стороні MT.
+
+## Поведінка
+
+- `parseNodeContract` — дістає з `task.md` правило з `## Check`, список target-файлів з `## Inputs` і текст задачі з `## Task`.
+- `resolveTierLabel` — перетворює `MT_MODEL_TIER` у tier-label для `llm-lib`, а невідоме або порожнє значення зводить до `avg`.
+- `buildViolationText` — формує текст порушення для agent-fix із задачі та, за наявності, додає перелік target-файлів; canonical-check лишається за `## Check`.
+- `runNode` — читає `task.md`, парсить контракт вузла, підбирає tier і запускає виправлення в заданому worktree через інʼєкований або стандартний fix.
+- `runNodeCli` — бере `node-dir` з argv або `MT_NODE_DIR`, запускає обробку вузла, друкує JSON зі станом виконання та повертає код завершення без пробросу винятків назовні.
+- `recordNodeFixTelemetry` — успішний фікс із реальними правками пише запис `oldText→newText` у глобальний distillation-стор (Фаза C): MT-вузли живлять той самий крос-репо корпус маховика T0, що й інлайн-драбина; best-effort, лише applied без error.
+
+## Публічний API
+
+- parseNodeContract — дістає з `task.md` контракт вузла й перетворює його на придатний для виконання опис.
+- resolveTierLabel — зв’язує `MT model_tier` із міткою `llm-lib`; для невідомого або порожнього значення підставляє `avg`.
+- buildViolationText — формує текст порушення для агента на основі контракту вузла, без повторного визначення канонічної перевірки `## Check`.
+- runNode — запускає один MT-вузол: читає контракт, готує виправлення нашим harness у worktree та повертає результат.
+- runNodeCli — запускає `node_executor` як CLI: бере `node-dir` з `argv[0]`, використовує `MT_WORKTREE` і `MT_MODEL_TIER`, виводить у stdout JSON з `applied` і `touchedFiles`, а кодом завершення показує успіх або помилку екзекутора.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

package/scripts/lib/lint-surface/docs/mt-tail.md

@@ -0,0 +1,41 @@
+---
+type: JS Module
+title: mt-tail.mjs
+resource: npm/scripts/lib/lint-surface/mt-tail.mjs
+docgen:
+  crc: a84afa7f
+  model: openai-codex/gpt-5.4-mini
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл матеріалізує lint-хвіст у пласкі root-level MT-вузли `mt/<node>/task.md` і `a.md` без composite-плану й `spawn-approve`, щоб окремі fix-правки далі виконував orchestrator MT за контрактом `graph.md` з `Task`, `Done when` і `Check`. Ядро модулю охоплює кластеризацію, сигнатуру вузла та формування `buildTaskMd`, `buildCheckCommand` і `buildAgentFlag`, а конфіг, на який він спирається, — `.mt.json`. Єдиний гейт — onboarded-репо (наявність `.mt.json`, перевіряє `mtPreflight`); якщо MT недоступний, він працює fail-open і повертає `{ materialized: false }`, не валячи lint. Широкі фікси (кількість target-файлів від порога `N_LINT_MT_AUDIT_FILES`, дефолт 4, або whole-repo) отримують `audit: required` — collateral-контроль штатним MT-аудитом (Фаза C); вузькі — `optional`.
+
+## Поведінка
+
+- `clusterTail` — групує порушення в окремі fix-одиниці за правилом і concern та збирає список пов’язаних файлів.
+- `fixNodeSignature` — будує стабільну коротку сигнатуру кластера для відтворюваного імені вузла.
+- `fixNodeName` — формує канонічну назву root-level MT-вузла для fix-роботи.
+- `buildCheckCommand` — описує команду перевірки, яка підтверджує, що порушення правила зникли.
+- `buildTaskMd` — створює вміст `task.md` для fix-вузла з описом задачі, умовою готовності, командою перевірки та списком target-файлів.
+- `buildAgentFlag` — створює вміст `a.md`, який позначає вузол як виконуваний агентом і задає `model_tier`.
+- `mtPreflight` — перевіряє, чи репо має `.mt.json` і чи доступний MT CLI.
+- `materializeTail` — перетворює lint-хвіст на MT-вузли; якщо MT недоступний, лише логує причину й повертає `materialized: false`, не валячи lint.
+
+## Публічний API
+
+- clusterTail — зводить хвостові порушення в fix-одиниці за парою `rule × concern`.
+- fixNodeSignature — дає стабільний підпис кластера, щоб той самий хвіст завжди мапився на той самий вузол.
+- fixNodeName — формує root-level імʼя fix-вузла в `mt/` у kebab-safe форматі.
+- buildCheckCommand — створює `## Check` для вузла: повторно знаходить правило, а `exit 0` означає, що порушення вже зникло.
+- buildTaskMd — генерує канонічний `task.md` для fix-вузла за контрактом `graph.md`; час не вставляє, `budgetSec` може бути заданий окремо.
+- buildAgentFlag — пише прапор `a.md`, який позначає агента-виконавця; tier перетворює на `model_tier`.
+- mtPreflight — перевіряє, чи є MT CLI+addon і чи репо вже onboarded через `.mt.json`.
+- ensureNodeExecutor — гарантує, що `.mt.json` задає `node_executor` = наша команда (B2), щоб вузли виконувались нашим harness, а не Claude-шляхом MT; ідемпотентно, не перезаписує наявне налаштування.
+- materializeTail — перетворює хвіст порушень на MT fix-вузли; якщо MT недоступний, не валить lint і повертає `{ materialized: false }`.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

package/scripts/lib/lint-surface/docs/policy-lint-adapter.md

@@ -0,0 +1,44 @@
+---
+type: JS Module
+title: policy-lint-adapter.mjs
+resource: npm/scripts/lib/lint-surface/policy-lint-adapter.mjs
+docgen:
+  crc: c25338e7
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 80
+  issues: internal-name:resolveTargetFiles,internal-name:runConftestBatch,judge:inaccurate:0.97
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+`evaluatePolicyConcern` перетворює policy-поверхню concern-а — Rego через conftest або `template deep-subset` — на уніфікований `LintResult` зі структурованими violations. Існує як adapter для generated detector-а: generated `main.mjs` policy-concern-а викликає саме цю функцію згідно зі spec `2026-06-29 §Policy Codegen`.
+
+Переоформлює перевірену логіку `run-rule.mjs` у результат detector-а, не дублюючи її: використовує ту саму поведінку вибору файлів через `resolveTargetFiles`, виконання conftest через `runConftestBatch` і template-перевірок через `template-checks`, щоб policy-рушії повертали сумісний `LintResult`.
+
+## Поведінка
+
+1. `evaluatePolicyConcern` приймає опис policy-concern-а й повертає уніфікований результат лінту зі списком порушень для подальшої обробки generated detector-ом.
+
+2. Спочатку визначає цільові файли concern-а відносно робочого каталогу, щоб застосувати policy лише до релевантної поверхні правила.
+
+3. Якщо цільових файлів немає, а concern очікує обовʼязковий single-файл, додає порушення про відсутній policy-файл із повідомленням за замовчуванням або з переданим override-повідомленням.
+
+4. Якщо цільових файлів немає і файл не є обовʼязковим single-target, повертає порожній список порушень, бо перевіряти нічого.
+
+5. Для template-перевірки читає template-очікування concern-а. Якщо очікування не задані, повертає поточний результат без порушень.
+
+6. Для кожного target-файлу в template-режимі порівнює фактичний вміст із declarative template-очікуваннями: обовʼязковими фрагментами, заборонами та вимогами на наявність. Кожну невідповідність оформлює як `policy-template-mismatch`.
+
+7. Для Rego-перевірки запускає policy concern-а через conftest-поверхню та передає доступні template-дані як супровідний контекст, щоб зберегти поведінку існуючої policy-логіки.
+
+8. Кожен deny-результат Rego оформлює як `policy-deny` із повідомленням policy та, якщо доступно, відносним шляхом до файла-порушника.
+
+9. Усі порушення мають однакову структуру з rule, concern, reason, message і severity `error`, щоб різні рушії policy повертали сумісний `LintResult`.
+
+10. Шляхи файлів у порушеннях нормалізуються до відносного POSIX-вигляду, щоб звіти були стабільними між платформами.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/lint-surface/docs/policy-test-step.md

@@ -0,0 +1,43 @@
+---
+type: JS Module
+title: policy-test-step.mjs
+resource: npm/scripts/lib/lint-surface/policy-test-step.mjs
+docgen:
+  crc: dcfe003c
+  model: openai-codex/gpt-5.5
+  tier: cloud-avg
+  score: 100
+  issues: judge:inaccurate:0.96
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Файл запускає unit-тести для policy-concern-ів із `policy.engine: 'rego'` у `concern.json`, щоб `<concern>_test.rego` перевіряв саме source-validation concern перед policy codegen/evaluate. Він read-only знаходить релевантні concern-и, виконує `conftest verify`, перехоплює помилки без винятків назовні, а падіння тестів нормалізує в lint-порушення з причиною `rego-unit-test-failed`.
+
+## Поведінка
+
+1. `runPolicyUnitTests` знаходить у каталозі правил policy-concern-и з `policy.engine: 'rego'` у `concern.json` і наявними unit-тестами для цього concern-а.
+
+2. Для кожного знайденого rego-concern-а запускає policy unit-tests через `conftest verify` по каталогу concern-а.
+
+3. Якщо `conftest` недоступний, завершує перевірку fail-safe як пропущену без створення порушень.
+
+4. Якщо unit-tests проходять успішно, повертає порожній список порушень для відповідного concern-а.
+
+5. Якщо unit-tests падають, перетворює кожен failure на lint-порушення з причиною `rego-unit-test-failed`, прив’язкою до тестового файлу concern-а та severity `error`.
+
+6. Підтримує обмеження перевірки вибраними rule-id, щоб delta-lint запускав unit-tests лише для релевантних змін.
+
+7. Повертає сукупний результат: знайдені порушення, ознаку пропущеного запуску та кількість реально виконаних прогонів.
+
+8. Не змінює файлову систему чи зовнішній стан; працює як read-only етап перед policy codegen/evaluate.
+
+## Публічний API
+
+- runPolicyUnitTests — запускає unit-тести policy для всіх або вибраних rego-concern-ів, спираючись на конфігурацію concern.json.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).
+- Перехоплює помилки і не пропускає винятків назовні (fail-safe).

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

@@ -0,0 +1,28 @@
+---
+type: JS Module
+title: progress.mjs
+resource: npm/scripts/lib/lint-surface/progress.mjs
+docgen:
+  crc: c442f348
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей модуль надає спільний ProgressReporter для unified lint surface, що реалізує гібридний механізм відображення прогресу довгих процесів, згідно з каноном scripts.mdc. Репортер керує відображенням монотонного бару для концернів (з відомим загальним лімітом) та тикера для відстеження знайдених і виправлених порушень. Поведінка відображення залежить від середовища: у TTY використовується однорядковий бар, що інтерактивно оновлюється через cli-progress MultiBar, тоді як у не-TTY середовищах (CI, hooks, пайпи) вивід зведення доповнюється до кожного обробленого елемента без використання ANSI-кодів. Лічильники відображають кількість знайдених порушень у порядку, що не приховує нові виявлені порушення, а збільшує лічильник `found`. Основні функції для роботи з репортером — renderProgressLine та createProgressReporter.
+
+## Поведінка
+
+- `renderProgressLine` створює єдиний текстовий рядок, що відображає стан прогресу (завершено/загалом), шкалу та поточні підсумки знайдених і виправлених порушень; той самий формат використовує черга `lint --full` для показу прогресу активного прогону.
+- `createProgressReporter` створює об'єкт-репортер, який керує відображенням прогресу тривалих процесів: у TTY — інтерактивний однорядковий бар, у не-TTY — append-рядки зведення (їх можна вимкнути `appendInNonTTY: false`); кожна зміна стану додатково публікується через опційний колбек `onUpdate`.
+
+## Публічний API
+
+renderProgressLine — відображає один рядок стану прогресу, що використовується як універсальний формат для самого репортера та для відображення чергової роботи іншого процесу.
+createProgressReporter — генерує об'єкт репортера, отримуючи вхідну загальну кількість елементів для обробки.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)

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

@@ -0,0 +1,29 @@
+---
+type: JS Module
+title: render.mjs
+resource: npm/scripts/lib/lint-surface/render.mjs
+docgen:
+  crc: 932ebe4d
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.94
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Єдиний рендерер уніфікованої поверхні лінтингу. Він агрегує та форматує вихідні дані (`LintResult`), отримані від детекторів. Це забезпечує однаковий візуальний вигляд повідомлень про порушення, незалежно від того, який консерн їх виявив, та є централізованою точкою для відображення звітів. Також він може генерувати список технічної інформації, якщо вона була надана.
+
+## Поведінка
+
+renderViolations збирає порушення, групує їх за ID правила та зосередження, а потім формує згрупований текстовий звіт про кожен випадок.
+renderDiagnostics формує текстовий список технічної інформації про діагностики, якщо вона надана.
+
+## Публічний API
+
+renderViolations — відображає порушення, згруповані за типом проблеми, повертає вміст для подальшого відображення.
+renderDiagnostics — відображає технічні деталі, якщо встановлено режим детального виведення.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/lint-surface/docs/run-detectors.md

@@ -0,0 +1,32 @@
+---
+type: JS Module
+title: run-detectors.mjs
+resource: npm/scripts/lib/lint-surface/run-detectors.mjs
+docgen:
+  crc: 984cc5be
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+  issues: judge:inaccurate:0.98
+  judgeModel: openai-codex/gpt-5.4-mini
+---
+
+## Огляд
+
+Цей файл є детектором для уніфікованої поверхні лінту, який сканує код без внесення змін. Він виконує процес вибору області перевірки (`scope-selection`), збирає всі виявлені порушення (`normalized violations`) для кожного аспекту (`concern`) відповідно до конфігурації `.n-rules.json`. Цей компонент працює у режимі `Detect-only`, тобто він не вносить жодних мутацій і не використовує LLM. Порушення передаються до пайплайну виправлення (Fix-pipeline) для подальшої обробки.
+
+## Поведінка
+
+Поведінка
+DEFAULT_RULES_DIR визначає шлях до стандартної директорії з правилами.
+buildDetectPlan створює впорядкований план прогону лінтера, збираючи всі відповідні концерни та визначаючи область їх сканування.
+detectAll виконує прохід лінтера у режим детекції, збираючи всі виявлені порушення та повертаючи код виходу.
+
+## Публічний API
+
+* DEFAULT_RULES_DIR — Містить набір стандартних правил для перевірок.
+* buildDetectPlan — Створює план виконання перевірок, охоплюючи визначені області.
+* detectAll — Виконує повний прохід пошуку проблем і повертає всі виявлені порушення та код виходу.
+
+## Гарантії поведінки
+
+- Read-only: не виконує операцій запису (ФС/БД).

package/scripts/lib/lint-surface/docs/run-fix.md

@@ -0,0 +1,33 @@
+---
+type: JS Module
+title: run-fix.mjs
+resource: npm/scripts/lib/lint-surface/run-fix.mjs
+docgen:
+  crc: d26e2efc
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+---
+
+## Огляд
+
+Цей файл реалізує уніфіковану поверхню для фіксації порушень лінтування (unified lint surface) відповідно до специфікації `2026-06-29 §Fix Role / §Tier Ladder`. Він керує послідовним процесом виявлення та усунення проблем, який складається з етапів: виявлення → (очищення/збереження) → Т0 (перманентне виправлення) → знімок S1 → повторне виявлення → (очищення/збереження) → цикл `ladder[відновлення S1 → worker → виявлення]*` (до вичерпання) → (вичерпання/відкат S1). Публічна функція `fixConcern` відповідає за індивідуальне виправлення певного компонента, а `runFixPipeline` ініціює весь комплексне виконання пайплайну. Ролі є чітко розподілені: `detector` лише виявляє, тоді як `T0` та `worker` здійснюють зміни. Успішне завершення визначається виключно канонічним повторним виявленням.
+
+## Поведінка
+
+Поведінка:
+fixConcern застосовує детерміновані патерни (T0), а потім, якщо це можливо, послідовно виконує ланцюжок фікс-операцій (ladder) для виявлення та усунення порушень певного concern-а.
+runFixPipeline керує повним циклом виправлення: він детектирує всі порушення, застосовує виправлення для кожного знайденого concern-а через `fixConcern`, і виводить фінальний звіт про нездоланні порушення.
+Per-tier timeout (ADR 260620-0556): кожен rung передає worker-у свій `timeoutMs` через `FixContext` (шлях до `runAgentFix opts.timeoutMs`, який abort-ить LLM-сесію), а сам виклик worker-а додатково огорнутий backstop-гонкою ×1.25 від `rung.timeoutMs` — worker, що ігнорує таймаут (зокрема зависла cloud-SSE), фейлить rung помилкою `fix timeout …` замість блокувати lint назавжди; така помилка класифікується як quality і ladder ескалює далі.
+Semantic-collateral veto (spec pi-fix-engine-migration §12, addendum 2026-07-05): clean-вердикт rung-а не приймається, якщо rung змінив наявні файли поза target-set порушення (`violations[].file ∪ item.files`, звірка через `collateral-veto.mjs` за `snapshot.modifiedExisting()`); наслідок — rollback S1, `🚫`-лог, feedback наступному rung-у й телеметрія `kind:"collateral-veto"` у глобальний llm-trace. Нові файли дозволені; порожній target-set → veto незастосовний (fail-open).
+Evidence-гейт рунга (Фаза A1 run-harness, спека 2026-07-11): кожен rung отримує у `FixContext` `verify` — item-scoped canonical re-detect (той самий детектор, що й фінальний вердикт), і `verifyMax` per tier (local — 1, cloud — 2); worker прокидає їх у `runAgentFix`, де провал verify інʼєктиться фідбеком у ту саму pi-сесію. Зовнішній canonical re-detect після worker-а лишається єдиним вердиктом рунга; помилка детектора всередині verify ковтається у `{ok:false}` — зовнішній detect кине її штатно.
+Durable-write-и (issue nitra/cursor#16): worker отримує у `FixContext` поруч із `recordWrite` опційний `recordDurableWrite` — для записів, кожен з яких є самодостатнім кінцевим станом (doc-files: дока зі свіжим CRC). Такі файли переживають rollback провального rung-а і не входять у collateral-veto: частковий прогрес великого батчу не стирається, canonical re-detect наступного rung-а/прогону рахує лише те, що реально лишилось.
+MT-tail (Фаза B, спека 2026-07-11): коли лишився невиправлений хвіст (worst=1), `renderRemaining` повертає зібрані порушення, і вони матеріалізуються у вузли MT-графа через `materializeTail` (mt-tail.mjs). Єдиний гейт — onboarded-репо (наявність `.mt.json`); fail-open: MT недоступний або будь-яка помилка → лог, lint не падає.
+Distillation-телеметрія (Фаза C, §13 pi-migration): успішний agentic-рунг (canonical clean, без veto, з реальними правками у worker telemetry) пише запис `oldText→newText` у глобальний стор (`recordFixTelemetry`, `~/.n-rules/telemetry/<rule>/open/`) — корпус для маховика дистиляції T0. Best-effort; T0/ручні фікси не пишуться.
+
+## Публічний API
+
+fixConcern — Виконує один етап перевірки у конвеєрі (T0 → S1 → ladder) та повідомляє про результат закриття цієї перевірки.
+runFixPipeline — Запускає повний цикл виправлення: ідентифікує всі проблеми, виправляє кожну, що не пройшла перевірку, і завершує роботу.
+
+## Гарантії поведінки
+
+- Сам не редагує кодові файли (мутації роблять T0/worker); пише лише телеметрію collateral-veto у глобальний llm-trace (best-effort, ніколи не валить прогін).

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

@@ -0,0 +1,30 @@
+---
+type: JS Module
+title: snapshot.mjs
+resource: npm/scripts/lib/lint-surface/snapshot.mjs
+docgen:
+  crc: 4a2fab06
+  model: omlx/gemma-4-e4b-it-OptiQ-4bit
+  score: 100
+---
+
+## Огляд
+
+Централізований знімок попереднього образу (pre-image snapshot) та механізм відкату (rollback) забезпечують функціональність фікс-пайплайну відповідно до специфікації spec 2026-06-29, §Tier Ladder. Відкат відновлює попередній стан файлів, але не видаляє ті, що відсутні у знімку. Операції виконуються послідовно для кожного окремого concern-а, гарантуючи, що стан кожного concern-а базується на успішних змінах попередніх concern-ів. До запису в tracker.record ПЕРЕД мутацією забезпечується фіксація попереднього образу для кожного потенційно зміненого файлу. Окремо підтримуються durable-write-и — самодостатні кінцеві стани (напр. файлові доки зі свіжим CRC), які rollback не чіпає.
+
+## Поведінка
+
+1. Створюється об'єкт-трекер попереднього стану. Цей трекер фіксує вихідний стан файлів, які можуть бути змінені в процесі виправлення.
+2. Для фіксації стану файлу використовується механізм `record`, який зберігає вміст файлу або маркер відсутності, якщо файл на момент фіксації не існував.
+3. Механізм `recordDurable` позначає шлях як durable: запис у такий файл — самодостатній кінцевий стан, тож rollback його не відновлює й не видаляє, а semantic-collateral veto його не враховує. Це дозволяє batch-worker-ам (doc-files) зберігати частковий прогрес після провалу/таймауту rung-а — беклог сходиться за кілька прогонів (issue nitra/cursor#16).
+4. Після виконання змін, трекеру викликається `rollback`. Цей метод відновлює вміст усіх зафіксованих файлів (крім durable-позначених), а файли, які відсутні на момент фіксації, видаляє.
+5. Щоб отримати список усіх файлів, чий попередній стан був зафіксований або які позначені durable, використовується метод `touched`.
+6. Метод `modifiedExisting` повертає наявні на момент S1 файли, чий поточний вміст відрізняється від pre-image (видалення наявного файлу теж вважається зміною) — вхід semantic-collateral veto; нові файли та durable-шляхи до результату не входять.
+
+## Публічний API
+
+- createSnapshot — створює фіксацію стану (snapshot S1) з порожнім набором попередніх зображень.
+
+## Гарантії поведінки
+
+- (специфічних машинно-виведених гарантій немає)