From a523e1f542769b510a5b577ce4e4f46fd04a8e68 Mon Sep 17 00:00:00 2001 From: codex Date: Mon, 3 Aug 2026 08:12:24 +0300 Subject: [PATCH] docs: define Plant 3D 2026 migration agent contract --- AGENTS.md | 129 ++++++++++++++++++++++++++++++ Plant3D2026/P_Rec_Annot/AGENTS.md | 58 ++++++++++++++ 2 files changed, 187 insertions(+) create mode 100644 AGENTS.md create mode 100644 Plant3D2026/P_Rec_Annot/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..afd4480 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,129 @@ +# 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, например ``. 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 заменять на +``. + +## 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 выполнять: + +```powershell +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. diff --git a/Plant3D2026/P_Rec_Annot/AGENTS.md b/Plant3D2026/P_Rec_Annot/AGENTS.md new file mode 100644 index 0000000..d64d7e6 --- /dev/null +++ b/Plant3D2026/P_Rec_Annot/AGENTS.md @@ -0,0 +1,58 @@ +# AGENTS.md — P_Rec_Annot + +## Назначение и package + +`P_Rec_Annot` — приоритетный Plant 3D 2026 plugin для чтения, планирования и +последующего создания Ortho-аннотаций; это перенос активного legacy поведения +Plant 3D 2019 на .NET 8/Plant 3D 2026. + +Единственная assembly для `NETLOAD` — `PRecAnnot.Plant3D2026.dll`. +`PRecAnnot.*.dll` — internal managed dependencies, их нельзя NETLOAD по одной. +Использовать Autodesk 2026 references; Autodesk DLL не включать в bundle. + +## Commands и context + +Поддерживаемые команды: `PHP_REC_ANNOT`, `PXP-AAV`, `PXP-OA`. Все +регистрируются реальным Autodesk API, работают в Smoke/DryRun, не изменяют DWG +в этих режимах и создают одно usage event на явный вызов. + +Project status: `NotFound`, `FoundWithName`, `FoundWithoutDisplayName`, +`Ambiguous`, `Failed`. Никогда не выводить `проект '' найден`; для пустого +display name: `Plant 3D-проект открыт; отображаемое имя не определено.` +Diagnostic code: `PLANT_PROJECT_DISPLAY_NAME_EMPTY`. + +Drawing states: `Ortho`, `NotOrtho`, `Ambiguous`, `Failed`. Обычный DWG не +классифицируется как Ortho; для реального Ortho применять Autodesk API и +`OrthoDocUtils.IsValidOrthoDrawing`. + +## DryRun и determinism + +Pipeline: `Plant context → Ortho detection → sheet/view definitions → viewport +snapshots → DataLinks → Plant properties → independent DTO → deterministic +AnnotationPlan → diagnostics → no write`. + +Autodesk objects, transactions и database handles остаются в adapter layer; +Core/Application используют только независимые DTO. На неизменном fixture +повторный DryRun обязан давать тот же PlanId, counts, порядок операций и warning +codes, без side effects. PlanId не включает время, GUID, absolute path, +нестабильный ObjectId или пользовательские данные. + +## Write guard, Ribbon, tests + +Все writes проходят централизованный write guard; в Smoke/DryRun он всегда +запрещает изменения. Apply не обходится через command handler/adapter. + +Ожидаемый Ribbon путь: `Промхимпроект → Аннотации → Аннотировать`. Требуются +stable IDs, отсутствие дублей, binding к `PHP_REC_ANNOT`, устойчивость к +документам/workspace и корректный Terminate. + +Unit tests не требуют Autodesk runtime. Runtime evidence отдельно фиксирует +initialization, commands, context, Ortho, DataLinks, plan, Ribbon, DBMOD, +telemetry и shutdown. + +Bundle содержит только фактический runtime dependency graph и никогда не +содержит Autodesk DLL, PDB, test assemblies, legacy 2019 assemblies, bin/obj +или production configuration. + +Fixture: local Plant 3D 2026 project вне Git с настоящей Pipe, synthetic line +number, Ortho drawing/viewport и SHA baseline до DryRun.