autodesk/AGENTS.md

AGENTS.md

Назначение проекта

Этот репозиторий содержит аудит, архитектуру, исходный код, тесты, runtime evidence и документацию миграции корпоративной экосистемы Autodesk AutoCAD Plant 3D 2019 на Autodesk AutoCAD Plant 3D 2026.

Конечная цель — функционально эквивалентная рабочая схема Plant 3D 2026: корпоративный Launcher, локальная доставка и активация пакетов, managed плагины, команды, Ribbon, Plant project integration, DataLinks, Ortho, аннотации, обновление, диагностика и rollback. Миграция не считается завершённой после успешной компиляции: необходима runtime-проверка реальных сценариев в Plant 3D 2026.

Связанные репозитории

• основной Autodesk-репозиторий: C:\dev\autodesk;
• Launcher Next: C:\dev\launcher-next;
• legacy launcher (read-only): C:\dev\launcher\git, C:\dev\p_serv_starter;
• legacy P_Rec_Annot (read-only): C:\dev\autodesk\link\P_Rec_Annot\v1.0.4\repo.

Legacy и deployed-файлы нельзя изменять без отдельного прямого задания.

Целевая платформа и принцип миграции

• Autodesk AutoCAD Plant 3D 2026, series R25.1, Windows x64, .NET 8;
• использовать реальные Autodesk 2026 managed assemblies;
• managed package загружается локально, не напрямую с UNC;
• Autodesk DLL нельзя коммитить, помещать в package/fixture или публиковать.

Переносится функциональное поведение, а не историческая структура файлов. Не воспроизводить без отдельного доказательства 20 последовательных NETLOAD, legacy LISP bootstrap, OrthoLoader.dll, загрузку с сети или прежние workaround. Предпочтительная цепочка:

Launcher Next → versioned local package → один managed entry assembly → internal dependencies → commands and Ribbon.

Статус legacy-команд

Ни одна активная команда Plant 3D 2019 не исчезает молча. Для каждой команды фиксируется ровно один статус: IMPLEMENTED, RUNTIME_VERIFIED, REPLACED_WITH_NATIVE, RETIRED_APPROVED или BLOCKED_WITH_REASON. Aliases сохраняются, пока их удаление не утверждено отдельно.

Runtime уровни

Smoke проверяет assembly load, регистрацию команд, Plant context, Ribbon, отсутствие необработанных исключений и отсутствие записи в DWG.

DryRun проверяет реальные Plant data, Ortho/sheet/view definitions, DataLinks, Plant objects, детерминированный план и отсутствие записи в DWG/project DB.

Apply разрешается только отдельным явным заданием: write guard, ограниченная DWG transaction, тестовая копия проекта, baseline, rollback/UNDO, duplicate protection и runtime evidence обязательны. Apply нельзя включать только локальной конфигурацией.

Runtime важнее предположений

Build и unit tests не доказывают Autodesk integration. Для RUNTIME_VERIFIED необходимы фактические результаты: команда, module path, DBMOD, Ribbon, DataLinks, Ortho status, telemetry и состояние файлов после закрытия. Не выдумывать UI evidence: использовать null, NOT VERIFIED или BLOCKED WITH REASON.

На тестовой машине реальный Plant 3D запуск разрешён, если он входит в задачу и есть test branch, локальный fixture, пройденные build/tests, rollback и нет production deploy. Не создавать искусственный review-gate перед Process.Start. Остановка допустима лишь после завершения доступной части работы и при конкретном внешнем blocker: установка, ОС, права, Autodesk runtime, fixture или необходимость production-данных.

Test fixtures и отсутствие записи

Fixtures создаются вне Git, например <TEST_FIXTURE_ROOT>. Ortho fixture — настоящий Plant project с Pipe, DataLinks row, line group, Ortho drawing, Ortho viewport и source-model connection; обычный AutoCAD viewport не годится. Production DWG/project использовать нельзя без прямого разрешения.

Нельзя коммитить DWG, DCF, Project.xml с runtime-data, project DB, Ortho generated files или реальные engineering values.

Для Smoke/DryRun проверять DBMOD до/после, SHA-256 содержательных project files, отсутствие непредусмотренных transactions/DCF/project-metadata writes. LastWriteTime недостаточен. Отделять служебные Plant cache/session files от содержательных данных.

Ribbon, механика и evidence

Ribbon — часть продукта: проверять tab, panel, button, command binding, stable IDs, отсутствие дубликатов при документах/workspace/reinitialization. Команда может быть отдельно рабочей, но plugin slice не завершён без Ribbon evidence или отдельного UI defect.

Документировать каждую runtime-цепочку: component/project/class/method, input/output, Autodesk transaction mode, writes, telemetry, failure code и rollback action. Документация соответствует фактическому коду.

Evidence содержит только проверенные значения. Не добавлять username, permit, полный environment, real project paths/line numbers/ObjectId/RowId/properties, полные logs, local manifest или startup scripts. Путь fixture заменять на <TEST_FIXTURE_ROOT>.

Warnings и Git

Известный MSB3277 WindowsBase 4.0.0.0/8.0.0.0 допустим только при полном совпадении с ранее зафиксированным warning. Новые warnings исследовать; не подавлять NoWarn без причины.

Запрещены force push, amend/rebase опубликованной истории, push binaries, изменение неизвестного remote и production deployment из test branch. Перед commit выполнять:

git diff --check
git status --short
git diff --cached --check

Не смешивать Launcher defect, plugin defect, runtime evidence и unrelated formatting в одном commit.

Definition of Done

Срез завершён, когда реализованы код, build/tests, валидный package и требуемый runtime-сценарий; записаны фактические результаты; выполнен rollback; fixture и production изолированы; механика документирована; ветка опубликована обычным push.

Общая карта проекта

Каноническая общая карта проекта находится в Google Drive: https://drive.google.com/drive/folders/1avnR0V8q7y5pfWRYwB6LPBEEyfpN7PpV. Локальная синхронизированная копия, если она доступна, определяется только переменной среды PHIM_PLANT3D_PROJECT_MAP_ROOT; её путь не хардкодить.

Перед работой над архитектурой, миграцией или runtime-сценарием обязательно прочитать доступные индекс/обзор карты, целевую архитектуру и migration status, индекс runtime evidence, а также записи карты для затрагиваемых Launcher и P_Rec_Annot. Затем сверить их с локальными AGENTS.md, релевантными tracked документами, текущим кодом и тестами.

Источники истины имеют следующий приоритет: фактическое runtime evidence; текущий код, tests и tracked configuration на проверенном Git HEAD; tracked документация репозитория; общая карта проекта. Внешняя карта описывает и связывает работу, но не является build/runtime dependency и не переопределяет текущий код или runtime evidence.

Проверять свежесть каждой используемой записи карты по фактическим git rev-parse HEAD, ветке и привязанному runtime evidence. Если карта или её локальная копия недоступна, фиксировать PROJECT_MAP_UNAVAILABLE; если зафиксированные commit/runtime status не совпадают с фактическими — PROJECT_MAP_STALE. Эти статусы не разрешают выдумывать evidence: продолжать по доступным локальным источникам и явно сообщать расхождение.

Системные инварианты сохраняются: Launcher доставляет versioned local package с одним managed entry assembly и без Autodesk DLL; P_Rec_Annot подтверждает реальное Plant/Ortho/DataLinks поведение runtime evidence, а не только build или tests. После изменения архитектуры либо runtime-статуса в отчёте указывать конкретные документы общей карты, которые требуют обновления (архитектура, статус миграции, evidence index и запись затронутой подсистемы); не заявлять, что они уже обновлены, без фактического изменения.