1c-quality-gate

Контроль качества 1С-разработки в паре с языковой моделью. Правка .bsl или XML метаданных взводит гейт: в Claude Code сессию нельзя завершить, пока проверка не прогнана, в OpenCode плагин настойчиво возвращает агента к непроверенным правкам. Глубина считается автоматически: косметическая правка закрывается за секунды, транзакция или новый общий модуль тянут за собой полный разбор. Результат — отчёт с находками и машиночитаемый след, по которому видно, что проверено, что пропущено и почему.

English. A Claude Code and OpenCode plugin that enforces code-quality checks for 1C:Enterprise (BSL) development. Editing a BSL module or a metadata XML arms a session gate: in Claude Code a Stop hook refuses to end the session until the quality run has happened; OpenCode has no such mechanism, so the plugin keeps returning the agent to the unchecked edits instead. Depth is computed per change across three axes — volume, code archetypes, complexity — so a comment fix costs seconds while a transaction or a new common module triggers the full review. Four review loops cover static analysis and 1C development standards, architecture (SOLID and GRASP as applied to 1C), metadata XML integrity, and file hygiene. Every run emits a machine-readable evidence trail: what was checked, what was skipped, and why. Skills, reports and docs are in Russian.

Значение слов «гейт», «контур», «класс», «след» — в разделе Термины.

Как выглядит прогон

Модель правит модуль и собирается завершить работу. Stop-хук её не отпускает:

[ГЕЙТ КАЧЕСТВА 1С — ЗАВЕРШЕНИЕ ЗАБЛОКИРОВАНО]

В этой работе изменены файлы 1С (2), но Skill: quality-gate не прогонялся.

BSL (2):
  - src/cf/CommonModules/РасчётСкидок/Ext/Module.bsl
  - src/cf/Documents/ЗаказПокупателя/Ext/ObjectModule.bsl

Прогони Skill: quality-gate. Он определит глубину сам — по объёму правки,
архетипам кода и сложности — и запустит только нужные контуры.
Косметическая правка закрывается за секунды: класс C0 требует лишь гигиены файлов.

Прогон даёт отчёт: находки для человека, ниже — след для машины.

🔴 Critical  src/cf/CommonModules/РасчётСкидок/Ext/Module.bsl::ПересчитатьСтроки:142
   Запрос внутри цикла по строкам табличной части — одно обращение к БД на строку.
   Правило: #std436, bslls:QueryInLoop · измерено: 1 запрос × N строк при пороге 0
   Исправление: вынести запрос из цикла, получить строки одним пакетом и разложить
   результат в соответствие по ключу.

🟠 Major     src/cf/CommonModules/РасчётСкидок/Ext/Module.bsl::ПересчитатьСтроки:96
   ARCH-A2: ветвление вместо диспетчеризации — цепочка из 6 «ИначеЕсли» по виду скидки
   при пороге ≥4. Каждый новый вид скидки правит этот же метод.
   Целевая структура: соответствие «вид скидки → имя обработчика», обработчики —
   экспортные методы модуля; цепочка сворачивается в один вызов по имени.
   Контр-сигнал не сработал: ветки нетривиальны (12–20 строк) и растут вместе с видами.

## quality evidence

[qg scope: volume=C2, files=2, loc=+64/-11, archetypes=[query,object-event], complexity=[nesting:5], driver=archetype:query, resolved=code:L1+L2|arch:2|xml:n/a|hygiene:full, config=default]
[qg sentinel: target=v8std, id=std454, status=found]
[qg sentinel: target=bslls, id=CommonModuleInvalidType, status=found, engine=bsl-analyzer@0.2.73]
[qg applied: layer=hygiene, scope=file-encoding, ids=[qg:HYG-BOM,qg:HYG-DASH], verdict=clean]
[qg applied: layer=code, scope=query-in-loop, ids=[std436,bslls:QueryInLoop], verdict=violation:std436]
[qg applied: layer=code, scope=query-top-order, ids=[qg:QRY-TOP-WITHOUT-ORDER], verdict=clean]
[qg applied: layer=code, scope=transaction-nesting, ids=[qg:BSL-TXN-IN-HANDLER], verdict=clean]
[qg applied: layer=arch, scope=branching-dispatch, ids=[qg:ARCH-A2], verdict=violation:qg:ARCH-A2]
[qg skipped: layer=xml, reason=not_applicable]
[qg not_verified: dimension=compilation, reason=no_platform]
[qg not_verified: dimension=query-execution, reason=no_platform]

У каждой находки ключ локации путь::Метод:строка, правило (#stdNNN, код диагностики или идентификатор эвристики), измеренное значение против порога и способ исправления; у архитектурной — ещё целевая структура и проверка контр-сигнала. Уровней три: 🔴 Critical и 🟠 Major блокируют вердикт «чисто», 🟡 Minor не блокирует.

След показывает не только найденное: почему контур XML неприменим, что компилируемость тел модулей осталась непроверенной и что запрос ни разу не выполнялся. Недоступный анализатор и отсутствующий индекс кода фиксируются такими же явными записями. Гейт снимается только по корректному следу — его разбирает evidence-validator.mjs, поэтому вердикт проверяем независимо от того, что утверждает отчёт.

Зачем это нужно

Контроль качества в паре с языковой моделью отказывает не из-за незнания стандартов. Отказы дают пять механизмов.

Гейт снимается только по корректному следу. Для классов C0 и C1 допустимо снятие с письменной причиной без прогона, для C2 и C3 требуется полный прогон.

Кому адресован: разработчику 1С, работающему в паре с Claude Code или OpenCode над выгрузкой конфигурации или расширения в файлы. Плагин задаёт процедуру и критерии приёмки прогона, содержательный разбор выполняет модель по чеклистам контуров.

Когда не применяется: в проектах вне 1С хуки молчат по построению; при чтении чужого кода гейт не взводится, поскольку реагирует только на правку; при работе в конфигураторе без выгрузки исходников в файлы проверять нечего.

Что проверяется

Граница между code и arch проходит по радиусу исправления: умещается внутри тела метода — код; требует нового шва (выделение метода, перенос в другой модуль, новый экспорт, изменение «кто кого вызывает») — архитектура.

Быстрый старт

Установка

Claude Code:

/plugin marketplace add Romandredan/1c-quality-gate
/plugin install 1c-quality-gate

OpenCode — строка в opencode.json:

{
  "plugin": ["1c-quality-gate@git+https://github.com/Romandredan/1c-quality-gate.git#v3.16.0"]
}

Оба харнесса ставят один и тот же тег одного репозитория: Claude Code — через marketplace.json, OpenCode — через эту строку. Закрепляйте тег: без него OpenCode тянет текущее состояние main, и версии разъезжаются.

После установки перезапустите сессию: навыки материализуются при старте. Проверка работоспособности: /gate-status отвечает «Гейт не взведён». Отличия поведения в OpenCode — в docs/OPENCODE.md.

Обязательная зависимость одна: MCP-сервис стандартов v8std, объявленный в самом плагине и работающий по HTTP без настройки. Статический анализатор устанавливается автоматически при первом прогоне: закреплённый релиз скачивается, сверяется по SHA-256 и размещается в каталоге данных плагина. Остальное необязательно и расширяет покрытие — см. Рекомендуемый харнесс и docs/INSTALL.md.

Первый вызов

Рекомендуемый харнесс

Плагин связан с внешними инструментами по роли, а не по имени продукта: любой источник, закрывающий роль, подходит. Ни один из них, кроме v8std, не обязателен — недоступный инструмент даёт запись skipped с точной причиной, и прогон продолжается. Мощность падает, честность — нет.

Минимальная рабочая связка — Claude Code и плагин: гигиена, стандарты и архитектурные признаки без графа вызовов работают сразу. Рекомендуемая — плюс анализатор (ставится сам), lxml и индекс кода: она закрывает контур code воспроизводимым вердиктом и включает четыре архитектурных признака, которые иначе честно пропускаются.

Устройство

Четыре слоя, каждый отвечает на свой вопрос.

Два инварианта.

Профиль считается один раз, до запуска контуров. Контуры получают его готовым и не пересчитывают: иначе оси расходятся, и обоснование выбранной глубины перестаёт быть проверяемым задним числом.

Пропуск фиксируется. Контур возвращает либо applied, либо skipped с причиной. Слой, не оставивший записи, неотличим от выполненного, и это обесценивает весь механизм.

Взвод по правкам из оболочки

У команды оболочки нет аргумента «файл», поэтому модуль, записанный генератором, Set-Content или git apply, и XML, изменённый скриптом навыка правки метаданных, находятся по снимку до и после команды. До команды хук запоминает время и для каждого затронутого git-дерева — HEAD и изменённые файлы. После команды кандидатами становятся изменённые и новые файлы по git status, файлы, вернувшиеся к HEAD, и файлы коммитов, созданных во время команды; вне git каталог обходится с потолком. Взводится кандидат, у которого время изменения или смены метаданных не раньше старта команды, а файл ли это 1С, решает та же классификация, что и при правке инструментом. Затронутыми считаются рабочий каталог, корень проекта и пути из текста команды.

Два намеренных исключения защищают от ложного взвода. Игнорируемые файлы не смотрятся: выгрузка конфигурации во временный каталог — десятки тысяч модулей, которых никто не писал, а в репозиторий игнорируемое не попадает. Коммиты, существовавшие до команды, тоже не берутся: переход на ветку, pull и reset переписывают модули, но это чужой или уже проверенный код.

Цена — снимок git status до и после каждой команды: на дереве около 14 тыс. модулей и 36 тыс. XML замер дал 0,2 с до команды и 0,5 с после, на небольшом репозитории — около 0,06 с. Не видно файла, путь к которому вычислен внутри скрипта и лежит в дереве, не названном в команде, и содержимого вложенных репозиториев. Не видно и записей фоновой команды: хук «после» срабатывает в момент её запуска, поэтому модель получает предупреждение запустить команду, пишущую файлы 1С, не в фоне. Касание без изменения содержимого взводит гейт — ошибка в громкую сторону. Если git не ответил или обход упёрся в потолок, пользователь получает сообщение «не смог посмотреть», а не тишину.

Чья правка. Время изменения говорит, что файл записан, пока шла команда, но не говорит кем: в одном рабочем каталоге одновременно работают несколько сессий, пользователь и выгрузка из конфигуратора. Поэтому у каждой записи состояния есть источник и отпечаток файла — размер и время изменения на момент взвода.

Последняя строка — граница метода. Молчаливый пропуск оставил бы без проверки и то, что команда записала сама, поэтому файл взводится, а выход даётся явный: gate.mjs disown --reason "<кто записал>" <файл или каталог> снимает его с сессии и сохраняет причину в журнале снятий. Отказаться можно только от файла с источником shell: файл, который сессия хотя бы раз правила инструментом, остаётся её файлом. Какие файлы взведены по времени, показывают gate.mjs status и сообщение блокировки.

Маршрутизация знания

До v3.6.0 контур кода на каждом прогоне читал два справочника с пометкой «прогоняется всегда» (131 КБ), не оставлявшие следа ни разу за 25 боевых прогонов — разбор в docs/superpowers/specs/2026-09-07-context-routing-analysis.md. С этой версии обнаружение отделено от разбора: references/catalog/INDEX.md (генерируется из карточек) несёт только триггеры и читается всегда, полная карточка — по попаданию; проход по каталогу выполняет изолированный субагент antipattern-reader и аттестует tools/catalog.mjs, оставляя записи ai-antipatterns/platform-antipatterns в следе.

Байт обязательного чтения до первой строки кода (метод и файлы — в разделе «Результат» спецификации):

Порог C2 ≤ 190 КБ не достигнут (≈209 КБ): справочники контура архитектуры (SKILL.md, signs-map.json, checklist-architecture.md, ai-antipatterns-arch.md, patterns-in-1c.md — 76 КБ) по-прежнему читаются целиком при любом прогоне архитектуры. Их маршрутизация по карточкам (тот же приём, что применён к контуру кода) в эту версию не входила — контур arch план не задействован, задача явно не переносила его на карточки. Следующий кандидат на ту же перестройку.

Состав пакета

Оркестратор

Контуры

Правила дедупликации находок по ключу локации и шкала severity приведены в shared/routing-contract.md.

Команды, субагенты и хуки

Термины

Грамматика следа и полный перечень причин пропуска приведены в evidence-format.md.

Расчёт глубины

Три оси, считаются один раз до запуска контуров. Источник истины — tools/profile.mjs (ARCHETYPES, computeProfile): таблицы ниже описывают то же самое прозой, но профиль печатает и сверяет gate.mjs plan, а не память модели о таблицах README.

Ось 1: объём

Ось 2: архетипы кода

Архетипы образуют набор меток, а не шкалу. Расставляются механически по маркерам в диффе и путям файлов; одна правка может нести несколько меток одновременно: запрос, транзакция и блокировки, запись наборов записей, обработчик события объекта, интеграция и HTTP, права и RLS, CFE-перехват, регламентное и фоновое задание, клиент-сервер, модуль формы, асинхронный клиент, новый общий модуль, новый объект метаданных.

У каждой метки объявлен собственный минимум для контуров code и arch. Транзакция требует минимум code L2, но arch не поднимает вовсе; новый общий модуль наоборот оставляет code на L1, а arch поднимает до уровня 2. Полная таблица меток с порогами и маркерами приведена в profile-axes.md; данные, которые считает инструмент, — в tools/profile.mjs (ARCHETYPES).

Ось 3: сложность

Ось закрывает случай «строк мало, но код тяжёлый», когда архетип может не сработать вовсе. Срабатывает при вложенности от 4, длине метода свыше 120 строк, 7 и более параметрах, цепочке ветвлений от 4, рекурсии. Метрики берутся из отчёта анализатора.

Сложение осей

Базовая матрица по объёму:

глубина контура = max(по объёму, максимум минимумов по сработавшим архетипам, по сложности)

Вторая ось введена из-за асимметрии: три строки внутри транзакции опаснее трёхсот строк переименований, но транзакции нужен глубокий разбор кода, а новому общему модулю на тридцать строк нужен разбор архитектуры. Одномерным «множителем риска» это не выражается.

Отдельно фиксируется driver: что именно подняло глубину, объём, конкретный архетип или сложность. Без него вердикт виден, а его логика нет, и первое же «почему так долго на трёх строках» превращается в спор.

Понижающий модификатор называется эталонной правкой. Глубина опускается до C1 независимо от объёма при одновременном выполнении трёх условий: все фрагменты являются кальками типового эталона того же механизма с точечной адаптацией имён и полей; они уже прошли предметный верификатор с нулём ошибок; они не затрагивают транзакции, блокировки и права.

Порядок прогона

flowchart TD
    EDIT([правка .bsl или XML метаданных:<br/>инструментом правки или командой оболочки]) --> ARM["gate-arm.mjs / gate-shell.mjs:<br/>взвести гейт сессии,<br/>снять отметки проверенного"]
    ARM --> WORK[работа продолжается]
    WORK --> STOP{{"gate-check.mjs (Stop):<br/>гейт взведён?"}}
    STOP -->|нет| DONE([сессия завершается])
    STOP -->|да| HAND["основная сессия:<br/>запускает субагента gate-runner,<br/>передаёт описание работы по семи пунктам"]
    HAND --> PLAN{{"gate-runner, свежий контекст —<br/>gate.mjs run:<br/>профиль по трём осям, строка scope,<br/>инструменты плана одним вызовом, черновик следа"}}
    PLAN --> ORCH{{"quality-gate:<br/>прогоняет план, глубину поднять можно, понизить нет"}}
    ORCH --> HYG["hygiene: всегда"]
    ORCH --> CODE["code: с C1"]
    ORCH --> ARCH["arch: с C2"]
    ORCH --> XML["xml: если менялся XML"]
    ORCH --> SENT["часовой: v8std и анализатор живы?"]
    HYG --> EV[["отчёт и секция quality evidence"]]
    CODE --> EV
    ARCH --> EV
    XML --> EV
    SENT --> EV
    EV --> VAL{{"evidence-validator.mjs --gate"}}
    VAL -->|"след дефектен или часовой мёртв"| ORCH
    VAL -->|след полон| BACK["вердикт и путь к отчёту —<br/>основной сессии"]
    BACK --> REL["gate.mjs release --evidence"]
    REL --> DONE

Диаграмма иллюстративна; нормативный порядок шагов приведён в навыке quality-gate.

Последовательность одного прогона:

1. Собрать охват: gate.mjs status и git diff. Слои, уже отработавшие по этому содержимому файла, пропускаются с причиной verified_earlier. Отметку снимает любая следующая правка, поэтому переиспользование устаревшего доказательства исключено по построению.
2. gate.mjs run считает профиль по трём осям, печатает готовую строку scope (с config=...) и сам исполняет инструменты плана одним вызовом: сводка по строке на инструмент, вывод только тех, у кого находки или сбой, черновик следа из строк, напечатанных инструментами. Полный вывод, сравнение версий и индекс каталога антипаттернов уходят в каталог состояния, а не в контекст сессии. gate.mjs plan печатает те же команды без исполнения. Модель вправе поднять глубину против расчётной с записанной причиной, понизить — нет; driver фиксирует, что именно её подняло.
3. Прогнать контуры на назначенной планом глубине. Недоступный инструмент даёт skipped с точной причиной: analyzer_unavailable, rlm_unavailable, platform_unavailable и другими.
4. Проверить часового по каждому источнику, на который опирается вердикт clean: заведомо существующий стандарт через v8std, заведомо неверную фикстуру через анализатор.
5. Собрать отчёт: находки для человека, ниже секция ## quality evidence.
6. Проверить след валидатором и снять гейт командой gate.mjs release --evidence.

Слой 3, состязательный аудит, автоматически не запускается. Контуры предлагают его в отчёте при классе C3 с находками 🔴 или 🟠; запуск только после явного согласия. Методология приведена в adversarial-audit.md.

Цикл проходов

Цикл — от взвода гейта до снятия. Первый проход полный; после него сессия исправляет все открытые находки в правке, с которыми согласна, и запускает следующий проход. Проходов на цикл — три, четвёртый gate.mjs run не запускает без --decision "<кто решил и что>"; решение остаётся в журнале снятий. Сообщение пользователя начинает счёт заново.

Находки делятся по границе правки, которую печатает run (## Задето правкой): в правке — методы BSL и диапазоны строк XML, изменённые относительно HEAD; вне правки — остальное. Находки вне правки гейт не держат на любом уровне и в этом цикле не исправляются: они уходят пользователю как техдолг. 🔴 вне правки и находки, которые субагент не может оценить, попадают в раздел «Нужно решение пользователя».

При снятии release переносит остаток — открытое в правке, вне правки, требующее решения — в журнал снятий и печатает его; первое завершение после снятия показывает пользователю служебное сообщение со счётом по уровням и путём к отчёту. Почему так — разбор журналов рабочего проекта в docs/superpowers/specs/2026-10-01-gate-passes-convergence-design.md.

След проверок

Пример полного следа приведён выше, в разделе Как выглядит прогон: он показывает не только найденное, но и причину, по которой контур XML неприменим, и то, что компилируемость осталась непроверенной.

Поле config в записи scope — настройка проекта, применённая к прогону: default либо custom:<секция> с перечнем переопределённых. Строку печатает config.mjs show, и без неё гейт не снимается: «C1» в проекте с задранными порогами означает не то же, что «C1» рядом, а прогон, не заглянувший в настройку, иначе неотличим от прогона, который её учёл. Валидатор сверяет отметку с фактической настройкой — приписанное по памяти значение не пройдёт.

Проверка следа:

node "$QG/tools/evidence-validator.mjs" <файл отчёта>          # lint: только оформление
node "$QG/tools/evidence-validator.mjs" <файл отчёта> --gate   # строгий, для снятия гейта

Строгий режим требует ровно одну запись scope, хотя бы одну applied или skipped, подтверждённого часового по каждому источнику, на который опирается вердикт clean, заявленную компилируемость при полностью чистом вердикте и — если сработал архетип запроса — заявленное исполнение запроса. Грамматика и перечень причин приведены в evidence-format.md.

Проверка с инструментом заявляется только по прогону. Строку следа пишет в отчёт модель, и написанная по прочтении кода она неотличима от полученной прогоном. Поэтому инструменты печатают свою строку сами и отмечаются в журнале .claude/.state/qg-runs.jsonl, а валидатор сверяет с ним каждую запись applied, у чьей проверки инструмент есть: static-analysis, platform-api, query-alias-shadowing, query-alias-vs-nested-table, query-top-order, query-alias-reserved-word, transaction-nesting, enum-string-assign, unbounded-string-column, attribute-access, form-attribute-shadowing, dispatch-fallback, db-read-in-loop, field-transfer, batch-single-result, record-manager-read, queried-object-attributes, own-structure-check, comment-reference, mechanic-word, stale-local-calls, file-encoding, registration-check, uuid-uniqueness, structure-validation, form-binding, ai-antipatterns, platform-antipatterns, ai-antipatterns-diff (все три — tools/catalog.mjs, аттестация результата читателя; последний — признаки needs: [diff], когда --diff недоступен). Отметка должна быть не старше последней правки файлов своей сессии — прогон до правки описывает состояние, которого уже нет.

Сверяется и покрытие. В журнале лежат пути файлов, которые инструмент видел; они сопоставляются с составом правки, и прогон по одному файлу из десяти заявление обо всех десяти не закрывает. Прогоны складываются — гонять инструмент по частям законно. Непокрытый файл блокирует там, где инструмент применим к любому файлу своего расширения, и предупреждает для проверки структуры: часть служебных XML выгрузки не проверяет ни один валидатор.

Запись skipped с причиной not_applicable проверяется наравне с applied — это тоже утверждение о работе инструмента («посмотрел файлы, правило к ним не относится»). Причины вида analyzer_unavailable отметки не требуют: ставить её некому.

Что сверка не делает: она не защищает от записи, дописанной в журнал вручную. В отличие от поля config, где истина заново выводится с диска, независимого источника здесь нет — это обнаружение молчания, и не больше.

Имена проверок берутся из закрытого словаря (tools/evidence-scopes.mjs). Свободное имя проходило бы формат, но не закрывало бы ни одного требования — а выглядело бы проверкой.

Оба требования об одном и том же. Компилируемость тел BSL не проверяют ни загрузка конфигурации из файлов, ни выгрузка, ни валидаторы XML: они разбирают структуру, но тела не компилируют. Синтаксическая ошибка внутри процедуры проходит их все и проявляется только при инициализации модуля в базе. Текст запроса не проверяет и это: для анализатора, сборки и валидаторов он остаётся строковым литералом, а «Неоднозначное поле» или «Поле не найдено» всплывают при первом выполнении. Вердикт «чисто», умалчивающий об этом, закрывает вопрос фальшивой зеленью.

Меры против ложных срабатываний

Ложная находка обходится дороже пропущенной: она провоцирует переделку работающего кода, и после двух-трёх таких случаев проверку отключают целиком. Отсюда шесть конструктивных решений.

Состав проекта определяется автоматически: основная конфигурация подключается к анализу вместе с расширениями. Расширение, разобранное в одиночку, не видит библиотек, и каждое обращение к ним становится «неразрешённым вызовом». На боевых расширениях это давало треть всех находок.

Неразобранные файлы называются неразобранными, а не источником трёхсот проблем. Замечания по ним получены на обрывке синтаксического дерева и снимаются целиком.

Диагностики с высокой долей ложных на идиоматичном коде 1С отключены в гейтовом конфиге, а типографика и форматирование вынесены в отдельный дешёвый контур.

Пороги проекта и пороги гейта разделены. Анализатор запускается с конфигом из состава плагина: иначе отключённая в проекте диагностика делала бы гейт тише, и об этом никто бы не узнал.

Контр-сигнал обязателен для каждого архитектурного признака: это законная форма, в которой признак не является дефектом. Новая проверка без контр-сигнала не принимается.

Отсутствие данных не превращается в «чисто». Признаки ARCH-A1, ARCH-A7, ARCH-A9 и ARCH-A11 опираются на граф вызовов, поэтому без индекса кода уходят в skipped, а не в зелёный вердикт.

Замеры на боевом коде: docs/false-positives-cfe.md. Обоснование выбора анализатора и его ограничения: docs/analyzer-integration.md.

Файлы в проекте пользователя

<корень проекта>/
├── .1c-quality-gate.json           настройка: пороги осей, движок анализатора, архетипы, часовой
└── .claude/.state/
    ├── qg-pending.json             взведённые гейты по сессиям: источник и отпечаток файла, отметки проверенного (файл × слой), цикл — проходы и решения
    ├── qg-done.json                журнал снятий: класс, причина, охват, предупреждения валидатора, отказы от файлов, остаток находок по разделам
    ├── qg-reports/                 архив принятых отчётов: копию кладёт `gate.mjs release`
    ├── qg-runs.jsonl               журнал прогонов инструментов: чем и когда проверено на самом деле
    ├── qg-config-init.json         отметка, что настройка уже создавалась
    ├── qg-state.lock               замок записи состояния; существует, пока идёт запись
    └── qg-analyzer.toml            сгенерированный конфиг анализатора с найденным составом проекта

Отметки старта команд оболочки живут во временном каталоге системы (qg-shell/), а не в проекте: хук срабатывает на каждую команду, и в проекте вне 1С каталог состояния был бы мусором.

Корень проекта инструменты определяют одинаково: переменная CLAUDE_PROJECT_DIR, иначе подъём до .1c-quality-gate.json, иначе до .git. Пока каждый инструмент брал рабочий каталог, запуск из подкаталога давал «настройки нет» и «гейт не взведён» — оба ответа неотличимы от честных. status и отказы печатают найденный корень со способом опознания; QG_PROJECT_DIR задаёт его явно. Файлы вне корня (правки в соседнем репозитории) адресуются в состоянии и журнале одним каноническим ключом — абсолютным путём, поэтому гейт по ним снимается обычным следом.

Состояние гейта разделено по сессиям: завершение блокируется только за файлы текущей сессии, правки соседней выводятся информационной строкой. Снятие чужого гейта недопустимо, поскольку объявляет проверенной работу, которая не просматривалась, — поэтому при нескольких сессиях verify и release без --session отказывают, а не выбирают самую свежую.

В .gitignore проекта добавляются .claude/.state/ (рабочее состояние сессии) и .qg-analyzer/ (временный каталог отчёта запасного движка).

Настройка под проект

Файл заводит плагин, а не пользователь. .1c-quality-gate.json создаётся при первом взводе гейта — раньше неизвестно, что проект вообще на 1С. Секции в нём пустые, с описанием ключей внутри: проставленное умолчание закрепилось бы навсегда и пережило бы обновление плагина, поменявшее это умолчание. Удалённый файл повторно не создаётся — удаление читается как отказ.

Что действует прямо сейчас — с указанием источника каждого значения (умолчание, файл, переменная окружения):

node "$QG/tools/config.mjs" show

Эту же команду выполняет оркестратор до расчёта осей: пороги берутся из вывода, а не по памяти.

{
  "analyzer": { "engine": "bsl-analyzer", "version": "0.2.81", "required": false },
  "volume": { "c1MaxLines": 40, "c1MaxFiles": 1 },
  "complexity": { "maxNesting": 4, "maxMethodLines": 120, "maxParams": 7 },
  "archetypes": {
    "custom": [
      { "name": "exchange", "markers": ["ПланОбмена", "ОбменДанными.Загрузка"], "minCode": "L2" }
    ]
  },
  "sentinel": { "id": "std454" }
}

Приоритет: переменная окружения → файл → умолчание. Неизвестный ключ не применяется, но и не замалчивается: show называет его отдельной строкой — опечатка в имени иначе неотличима от настройки, которой нет. Полный справочник — docs/CONFIG.md.

При analyzer.required: true гейт без анализатора не снимается. По умолчанию установлено false: плагин публичный, у стороннего пользователя анализатора может не быть, и контур в этом случае пишет skipped, а прогон продолжается. В собственных проектах значение следует переключить на true. Установка, обновление и диагностика разобраны в docs/INSTALL.md.

Скрипты

Команды используют $QG, каталог установленного плагина. Переменная CLAUDE_PLUGIN_ROOT доступна хукам, но не оболочке; способ разрешить путь первой командой прогона описан в разделе «Путь к инструментам плагина» навыка quality-gate.

Механика гейта и следа:

node "$QG/tools/gate.mjs" status                                   # охват, сессии, отметки проверенного
node "$QG/tools/gate.mjs" verify --layer code <файл> [...]         # отметить слой проверенным
node "$QG/tools/gate.mjs" disown --reason "<кто записал>" <файл или каталог> [...]   # снять с сессии файл, взведённый по времени и записанный не её командой
node "$QG/tools/gate.mjs" release --evidence <файл отчёта>         # снять гейт по следу
node "$QG/tools/gate.mjs" release --evidence <файл отчёта> --critical-decision "<кто решил и что>"   # то же при находке 🔴: без записанного решения гейт не снимается
node "$QG/tools/gate.mjs" release --class C0 --reason "<почему>"   # снять без прогона (только C0 и C1)
node "$QG/tools/gate.mjs" run [--files <f> ...] [--only <имя,...>]  # профиль, scope и инструменты плана одним вызовом; черновик следа
node "$QG/tools/gate.mjs" run --session <id> --decision "<кто решил и что>"   # четвёртый проход цикла — только с записанным решением
node "$QG/tools/gate.mjs" handoff [--session <id>]                   # текст передачи проверки субагенту gate-runner — тот же, что печатает хук
node "$QG/tools/gate.mjs" plan --files <f> [<f> ...]               # то же без исполнения: профиль, scope, команды инструментов
node "$QG/tools/evidence-validator.mjs" <файл отчёта> --gate       # проверить след
node "$QG/tools/config.mjs" show                                  # действующие пороги и их источник

Проверки контуров:

node "$QG/tools/analyzer-run.mjs" --changed <файл> [...]   # статический анализ, часовой, записи следа
node "$QG/tools/analyzer-run.mjs" --sentinel               # только проверка живости анализатора
node "$QG/tools/analyzer-bootstrap.mjs" [--verify]         # установка анализатора и сверка SHA-256
node "$QG/tools/hygiene-check.mjs" <файл> [...]            # байтовая гигиена
node "$QG/tools/query-lint.mjs" <файл.bsl|.xml> [...]      # тексты запросов (включая <query> СКД и динсписки): затенение колонки, служебное слово в псевдониме, ПЕРВЫЕ N без порядка
node "$QG/tools/bsl-lint.mjs" <файл.bsl> [...]             # транзакция в обработчике; примитив в поле ссылочного типа; строковая колонка без квалификатора длины; перенос полей поштучно; пакет ради одного результата; менеджер записи для чтения; реквизиты объекта, найденного запросом; проверка состава структуры; метки задач в комментариях; слова механики из списка проекта
node "$QG/tools/rename-check.mjs" <файл.bsl> [...]         # вызов метода, объявление которого исчезло из модуля в этой правке
node "$QG/tools/catalog.mjs" index [--archetypes a,b]      # индекс триггеров каталога антипаттернов
node "$QG/tools/catalog.mjs" card qg:AI-07                 # полная карточка признака: как чинить, законные формы
node "$QG/tools/catalog.mjs" attest --result <файл.json> --files <f> [...]   # аттестация результата читателя, печатает след
node "$QG/tools/xml/orphan-check.mjs" <каталог выгрузки>   # сверка «диск ↔ состав» в обе стороны
node "$QG/tools/xml/uuid-unique.mjs" <каталог выгрузки>    # дубли UUID объектов метаданных
python "$QG/tools/xml/meta-validate.py" -Path "<путь>"     # валидаторы XML; -Path принимают все

Коды выхода: 0 чисто, 1 предупреждения или «не найдено», 2 блокирующая ошибка.

Работа над самим плагином, то же выполняет CI на каждый push:

node tests/run-tests.mjs             # тесты программных проверок
node tools/validate-package.mjs      # целостность пакета, ссылки, утечки проектных данных
node tools/gen-signs-map-md.mjs      # перегенерация signs-map.md, если менялся signs-map.json
node tools/gen-catalog-index.mjs --check   # проверить, что references/catalog/INDEX.md не устарел
node tests/recall.mjs                # полнота срабатывания читателя каталога на контрольных примерах

Структура репозитория

Версии и вклад

Версия хранится в одном месте, .claude-plugin/plugin.json, и держится синхронно с marketplace.json; расхождение обнаруживает validate-package.mjs.

Релизы помечаются аннотированными тегами vX.Y.Z, и запись плагина в маркетплейсе пиннится на тег полем source.ref: main остаётся рабочей веткой, а устанавливается только помеченное дерево. Описание релиза живёт в сообщении тега, отдельного CHANGELOG в репозитории нет.

git tag -l                             # список релизов
git tag -n99 vX.Y.Z                    # описание релиза
git log --oneline vX.Y.Z..vA.B.C       # что вошло между релизами

Порядок выпуска, нумерация и шаблон описания приведены в docs/RELEASING.md. Номер версии отвечает на вопрос «придётся ли что-то делать руками»: MAJOR — да (настройка, расположение состояния, имена инструментов и проверок, флаги CLI), MINOR — гейт стал строже или умнее в прежнем контракте. Новое блокирующее требование выходит в два шага: сначала предупреждением, ошибкой — следующим релизом, чтобы обновление не красило чужой рабочий процесс без предупреждения.

Правила добавления проверок и требования к PR приведены в CONTRIBUTING.md, инструкции для агента, работающего над самим плагином, в CLAUDE.md и AGENTS.md. Основное требование: новая проверка сопровождается двумя тестами, один подтверждает обнаружение дефекта, второй молчание на заведомо корректном коде. Для архитектурного признака дополнительно обязателен контр-сигнал. Перед PR выполняется локальный прогон node tests/run-tests.mjs и node tools/validate-package.mjs, CI должен быть зелёным.

Язык пакета русский: тела навыков, справочники и отчёты пишутся по-русски, код, команды, идентификаторы и номера стандартов остаются в оригинале.

Лицензия

Код, скрипты, чеклисты, карты соответствий и эвристики этого репозитория распространяются по MIT, см. LICENSE.

Тексты стандартов разработки 1С не воспроизводятся. Плагин публикует только ссылки и номера вида #stdNNN, а сами тексты получает во время работы через MCP-сервис v8std. Правила изложены авторами своими словами со ссылкой на номер стандарта.

Благодарности и переиспользованное

Плагин опирается на результаты других проектов. Ничто из перечисленного в пакет не входит: анализаторы скачиваются с релизов своих авторов и запускаются как внешние процессы, тексты стандартов запрашиваются по сети во время прогона. Лицензии относятся к самим этим компонентам, а не к коду плагина.

Совместимые внешние источники фактов — индекс кода rlm-tools-bsl и справочник API платформы mcp-bsl-platform-context — в пакет не входят и подключаются пользователем как отдельные MCP-серверы; связь с ними идёт по роли, а не по имени продукта.

Авторам обоих анализаторов отдельная признательность: без них контур кода остался бы набором инструкций для модели без воспроизводимого вердикта. Плагин не зеркалит их сборки и не изменяет условий их лицензий, он закрепляет версию и сверяет контрольную сумму, чтобы вердикт не менялся между прогонами.