round-trip-yaml

name	round-trip-yaml
description	Диагностирует полный metadata round-trip (XML -> модель -> YAML -> модель -> XML) и показывает single/triage diff'ы без создания reproducer.

round-trip-yaml — диагностика полного round-trip

Перед диагностикой metadata round-trip обязательно прочитай:

1. .agents/knowledge/metadata/INDEX.md
2. .agents/knowledge/metadata/sources-of-truth.md
3. .agents/knowledge/metadata/round-trip-cycle.md
4. .agents/knowledge/metadata/yaml-contract.md

Что делает скилл

Скилл запускает полный цикл:

XML -> модель -> YAML -> модель -> XML

На выходе он показывает XML diff'ы, появившиеся после nkdk import <xml-dir> <tmp-yaml-dir>, nkdk sync <tmp-yaml-dir> <tmp-xml-dir> --reference <xml-dir> и полной замены активного XML-каталога результатом временного XML-каталога.

У скилла два режима:

1. Single — показывает один diff-файл. Без явного выбора берётся первый по алфавиту diff найденного каталога.
2. Triage-пачка — показывает несколько diff-файлов для обзорного анализа.

Скилл только диагностирует. Он не создаёт ветки, slug, фикстуры, тесты, планы исправления, коммиты и PR.

Жёсткие инварианты

• Triage-пачка только информирует. В triage-режиме AI показывает список diff'ов, вероятные модули, вероятные файлы кода, категории, описания и фрагменты diff.
• Single тоже только информирует. Single-режим показывает один полный diff и краткий разбор, но не начинает reproducer workflow.
• Чистое рабочее дерево nkdk-core. Если git status не чистый — стоп, попросить пользователя.
• Временный YAML-каталог очищается перед прогоном. Старые YAML-файлы и миграции не должны влиять на новый результат.
• Временный YAML-каталог остаётся после прогона. Он нужен для диагностики YAML-слоя.
• XML-репо после прогона остаётся с diff'ами. Не откатывай XML-репо после диагностики: diff является результатом анализа.
• Не писать новые правила fromXML/toXML/fromYAML/toYAML. Скилл ничего не исправляет.
• Не запускать полный pnpm test. Это диагностический skill.

Запуск round-trip

Вызови ./.agents/skills/round-trip-yaml/round-trip.sh из корня nkdk-core.

Скрипт:

1. читает NKDK_XML_REPO (обязательная), NKDK_XML_DIR (опциональная) и NKDK_ROUND_TRIP_YAML_DIR (опциональная) из .env;
2. проверяет, что рабочее дерево nkdk-core чистое;
3. проверяет, что NKDK_XML_REPO является git-репозиторием;
4. определяет каталоги запуска;
5. перед каждым прогоном делает git restore . в XML-репо;
6. перед каждым прогоном удаляет временный YAML-каталог для активного XML-каталога;
7. перед каждым прогоном очищает временный XML-каталог;
8. запускает nkdk import <xml-dir> <tmp-yaml-dir>;
9. запускает nkdk sync <tmp-yaml-dir> <tmp-xml-dir> --reference <xml-dir>;
10. после успешного sync копирует reference-only файлы, которые не являются частью YAML-договора, из активного XML-каталога во временный XML-каталог;
11. полностью заменяет активный XML-каталог содержимым временного XML-каталога;
12. собирает XML diff'ы через git diff;
13. если после каталога появился хотя бы один diff — останавливается на этом каталоге и дальше не смотрит, если не указан --all-configs.

Если скрипт написал === Round-trip чистый: диффов нет === — стоп, нечего анализировать.

Если скрипт упал на guard'е dirty-tree — попроси пользователя сохранить/откатить правки. Не запускай git stash, git restore, git clean сам.

Каталог YAML

По умолчанию временный YAML-каталог создаётся в ${TMPDIR:-/tmp}/round-trip-yaml/<config>.

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

NKDK_ROUND_TRIP_YAML_DIR=/Users/nikita/git/erp_nkdk

При запуске нескольких конфигураций через --all-configs каждая конфигурация получает подпапку внутри NKDK_ROUND_TRIP_YAML_DIR, чтобы результаты не перетирали друг друга.

Временный XML-каталог

Для экспорта YAML обратно в XML скрипт использует временный XML-каталог ${TMPDIR:-/tmp}/round-trip-yaml-xml/<config>.

Перед sync каталог очищается. Активный XML-каталог передаётся в sync только как --reference: старые XML-файлы не копируются во временный XML-каталог. Результат после успешного sync полностью заменяет активный XML-каталог, поэтому любые файлы, которые не были восстановлены из YAML, становятся удалениями в git diff. Сам временный XML-каталог не считается диагностическим результатом; анализировать нужно diff в XML-репо и сохраненный YAML-каталог.

Исключение: reference-only файлы, которые намеренно не входят в YAML-договор, копируются из активного XML-каталога во временный XML-каталог после sync и до замены активного каталога. Сейчас это Ext/ParentConfigurations.bin и Ext/ParentConfigurations/*.cf.

Single-режим

Команды:

./.agents/skills/round-trip-yaml/round-trip.sh
./.agents/skills/round-trip-yaml/round-trip.sh --diff-index 3

После запуска сформируй краткий разбор:

XML-файл: <абсолютный локальный путь из SELECTED_XML_FILE_ABS>
XML-каталог: <значение ACTIVE_XML_DIR>
YAML-каталог: <значение YAML_DIR>
Diff: <SELECTED_DIFF_FILE>
Вероятный модуль: packages/core/metadata/<...> или неизвестно
Вероятный код: packages/core/metadata/<...>/rules.ts или неизвестно
Категория: потеря пустого тега / порядок XML-узлов / лишний default / потеря атрибута / потеря xsi:type / потеря id или ссылки / YAML-default / YAML-исключение / неизвестно
Описание: <что изменилось при полном round-trip>
Diff:
<релевантный фрагмент или полный diff, если он короткий>
Сомнения: <почему модуль или причина неочевидны, если есть сомнения>

Triage-пачка

Используй этот режим, когда пользователь просит показать несколько ошибок для анализа: «покажи следующие 5 ошибок», «дай пачку с 6-й», «покажи 10 diff'ов».

Команды:

./.agents/skills/round-trip-yaml/round-trip.sh --triage --batch-size 5
./.agents/skills/round-trip-yaml/round-trip.sh --triage --batch-size 5 --start-index 6
./.agents/skills/round-trip-yaml/round-trip.sh --triage --all-configs --batch-size 20

После запуска сформируй краткий список. Каждый пункт должен содержать:

1. <относительный XML-путь из diff>
   XML-файл: <абсолютный локальный путь из XML_FILE_ABS>
   XML-каталог: <значение ACTIVE_XML_DIR>
   YAML-каталог: <значение YAML_DIR>
   Вероятный модуль: packages/core/metadata/<...> или неизвестно
   Вероятный код: packages/core/metadata/<...>/rules.ts или неизвестно
   Категория: потеря пустого тега / порядок XML-узлов / лишний default / потеря атрибута / потеря xsi:type / потеря id или ссылки / YAML-default / YAML-исключение / неизвестно
   Описание: <что изменилось при полном round-trip>
   Diff:
   <короткий релевантный фрагмент>
   Сомнения: <почему модуль или причина неочевидны, если есть сомнения>

Правила triage-ответа:

• XML-файл всегда бери из XML_FILE_ABS. Если путь абсолютный и файл существует локально, оформи его кликабельной ссылкой.
• YAML-каталог всегда бери из YAML_DIR.
• Для определения вероятного модуля и кода можно читать packages/core/metadata/**/rules.ts, types.ts, fromYAML.test.ts, toYAML.test.ts, fromXML.test.ts, toXML.test.ts.
• Показывай diff-фрагмент как источник истины.
• Если несколько пунктов похожи на одну категорию, отметь связь, но не объединяй пункты.
• Не создавай ветку, slug, фикстуры, тесты и план исправления. После списка остановись и жди, какую проблему пользователь захочет разобрать отдельно.

Тупиковые ситуации

Остановись и спроси пользователя, если:

• nkdk import падает;
• nkdk sync падает;
• один diff содержит несколько независимых причин и краткая классификация будет вводить в заблуждение;
• невозможно понять, расхождение появилось из-за XML-слоя или YAML-слоя.

Политика коммитов

Скилл не коммитит, не пушит, не создаёт PR, не запускает тесты и не исправляет код.