Quality Gate

scripts/quality_gate.py проверяет готовый навык перед использованием.

Markdown разбирается библиотекой markdown-it-py; её закреплённую версию подготавливает uv run --script. Зависимость нужна только компилятору: готовый навык остаётся обычными Markdown- и JSON-файлами.

Проверяется статический результат CommonMark: содержимое HTML-элементов script и style не считается текстом документа. JavaScript и CSS не исполняются; особенности фильтрации HTML конкретными просмотрщиками, включая GitHub, не моделируются.

Проверки

существует SKILL.md;
SKILL.md не длиннее заданного предела, по умолчанию 2000 слов;
есть обязательные файлы в references/;
нет явных TODO/TBD/PLACEHOLDER;
source-map.json и knowledge-manifest.json являются корректным JSON;
source_id имеет формат SHA-256 и совпадает с knowledge-manifest.source_sha256 по правилу из OUTPUT_SCHEMA.md; это проверка согласованности метаданных, не происхождения переданного source.txt;
структура сегментов и тезисов, уникальность их идентификаторов и ссылки на сегменты соответствуют OUTPUT_SCHEMA.md;
диапазоны символов и строк сегментов не выходят за пределы переданного source.txt и согласуются между собой по правилу из OUTPUT_SCHEMA.md;
каждый отдельный идентификатор seg-<число> (по правилу из OUTPUT_SCHEMA.md) в отображаемом тексте Markdown, альтернативном тексте картинки или якоре ссылки вне блоков кода и HTML-комментариев существует в карте источников;
гиперссылки с таким идентификатором в тексте, альтернативном тексте вложенной картинки или якоре ведут по корректному относительному пути в references/source-index.md этого навыка, к указанному сегменту; простые указатели без гиперссылки допустимы;
для элементов <a> в пространстве имён SVG также распознаётся устаревший атрибут xlink:href; современный href имеет приоритет, если указаны оба;
каждый тезис ссылается на существующий Markdown-файл внутри references/, где ровно один заголовок ## <claim_id> вне блоков кода и HTML-комментариев, без конфликтующего автоматического или явного HTML-якоря;
references/source-index.md существует и соответствует карте источников;
лексическое пересечение с исходником не выглядит как длинное дословное копирование.

При проверке ссылок пропускаются блоки кода с ограждением и с отступом, в том числе внутри цитат и списков. Продолжение абзаца или пункта списка с отступом остаётся обычным текстом. Проверяются и адреса ссылок, заданные отдельными определениями. Заголовки с подчёркиванием === или --- учитываются при поиске конфликтующих якорей, но не заменяют обязательный ## <claim_id>. Проверка учитывает отображаемый текст заголовка и суффиксы, занятые предыдущими заголовками.

Совпадение seg-* только в пути или параметрах URL не считается указателем источника. Например, обычная ссылка с подписью «Документация» на https://example.com/seg-999/guide не требует сегмента seg-999 в карте.

У распознанной ссылки на сегмент якорь должен точно совпадать с его идентификатором. Например, #seg-001/extra содержит отдельный seg-001, но не ведёт к его заголовку. Разделители папок в пути записывай обычным /, не %2F или %5C: кодирование разделителя меняет назначение ссылки.

Путь должен указывать на сам файл: пустые части пути и конечные . или .. отклоняются.

Создание и обновление указателя

После заполнения тезисов в source-map.json и Markdown-файлах запусти:

uv run --script scripts/quality_gate.py --source cache/jobs/<job-id>/source.txt --skill-dir dist/<skill> --write-source-index

Флаг создаёт или обновляет references/source-index.md только после успешных проверок остальных данных. Без флага скрипт ничего не меняет и требует актуальный указатель. Старые готовые навыки исправляй по сообщениям проверки, затем создавай указатель этой командой; автоматической миграции нет.

Проверка похожести

Текущая версия использует n-граммы по словам:

нормализует исходник и результат;
строит множество n-грамм исходника;
ищет самую длинную непрерывную цепочку n-грамм результата, встречающуюся в исходнике;
оценивает её длину в словах.

Это дешёвая и понятная защита от случайного копирования длинных фрагментов. Она не измеряет смысловую близость и не доказывает юридическую безопасность.

Как чинить провалы

SKILL.md too long — перенеси детали в references/.
missing required file — создай файл или поправь путь.
placeholder found — замени черновые маркеры на готовое содержание.
Ошибка карты или ссылки — исправь идентификаторы, source_segments, путь artifact или заголовок тезиса по OUTPUT_SCHEMA.md.
Отсутствующий или устаревший source-index.md — после исправления карты запусти проверку с --write-source-index.
long exact overlap — перепиши фрагмент своими словами, оставь только короткую цитату при необходимости и укажи её в source-map.json.

Когда нужен строгий режим

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

uv run --script scripts/quality_gate.py --source cache/jobs/<job-id>/source.txt --skill-dir dist/<skill> --strict

Публикация чужих коммерческих источников не считается покрытой этим скиллом.

/knowledge-compiler

referencesQUALITY_GATE.md