panopainter/docs/modernization/debt.md

Modernization Debt Log

Status: live Last updated: 2026-06-02

Every shortcut, temporary adapter, retained vendored dependency, skipped platform gate, compatibility shim, or incomplete automation path must be recorded here before it lands. Entries must be specific enough for a future agent or engineer to remove them without reconstructing context from chat.

Entry Rules

• Add an entry before merging the shortcut.
• Reference the debt id in code comments, TODOs, ADRs, or roadmap notes.
• Include an owner, reason, validation command, and removal condition.
• Do not close an entry until the removal condition is met and validated.
• Prefer deleting shortcuts over expanding this log.

Open Debt

ID	Status	Owner	Item	Reason	Validation	Removal Condition
DEBT-0001	Open	Modernization	Existing platform build files remain alongside new CMake	Required for incremental migration without losing platform coverage	Existing platform builds plus new CMake configure	Remove after all platform builds consume shared CMake targets
DEBT-0002	Open	Modernization	Vendored SDK and patched libraries retained initially	Some dependencies are SDK-only, patched, or have platform-specific binaries	Dependency inventory and platform build smoke tests	Replace with vcpkg packages or document permanent vendored status after triplet evaluation
DEBT-0003	Open	Modernization	Existing singletons remain during initial split; App::open_document, App::request_close, file-menu save actions, NodeCanvas save hotkeys, new/open/browse dirty-document workflow prompts, new-document target/resolution/overwrite decisions, save-as document file naming and overwrite decisions, save-version target decisions, export start/target naming/path decisions, pano_cli classify-open, pano_cli plan-open-route, pano_cli plan-new-document, pano_cli plan-document-file, pano_cli plan-document-version, pano_cli plan-export-start, pano_cli plan-export-target, and pano_cli simulate-app-session now consume pure pp_app_core route/session/export contracts, but document creation/loading, brush import execution, saving, and export execution still reach legacy Canvas::I/UI singletons	Avoid behavior changes while introducing component boundaries	App launch and component tests; pp_app_core_document_route_tests; pp_app_core_document_export_tests; pp_app_core_document_session_tests; pano_cli classify-open --path D:/Paint/demo.ppi; pano_cli plan-open-route --path D:/Paint/demo.ppi --unsaved; pano_cli plan-new-document --work-dir D:/Paint --name demo --resolution-index 3 --target-exists; pano_cli plan-document-file --work-dir D:/Paint --name demo --target-exists; pano_cli plan-document-version --directory D:/Paint --doc-name demo.01 --existing-path D:/Paint/demo.02.ppi; pano_cli plan-export-start --requires-license --demo; pano_cli plan-export-target --kind file --work-dir D:/Paint --doc-name demo --extension .png; pano_cli simulate-app-session --unsaved --save-intent save-dirty-version; pano_cli simulate-app-session --no-canvas; ctest --preset desktop-fast --build-config Debug	Replace singleton reaches with context/service injection at component boundaries
DEBT-0004	Open	Modernization	Android, Linux, WebGL, Apple, and AppX build files remain platform-specific until root CMake alignment reaches them	Prevent platform regressions during incremental migration; raw Windows .sln/.vcxproj files were removed on 2026-05-31 by user decision	cmake --preset windows-msvc-default; platform-specific configure/build smoke checks as each platform is migrated	Root CMake owns every platform source list and package path
DEBT-0005	Open	Modernization	Temporary local CTest harness is used before Catch2 is wired through vcpkg	vcpkg is not currently on PATH, but headless tests need to run now	ctest --preset desktop-fast --build-config Debug	Replace tests/test_harness.h tests with Catch2 tests once vcpkg toolchain/presets are validated
DEBT-0007	Open	Modernization	vcpkg.json and windows-msvc-vcpkg-headless are validated for the headless Windows component matrix, but app targets still use vendored libraries and Android/Apple triplets are not proven	Dependency migration must stay incremental while SDK/patched/vendor dependencies remain in use	$env:VCPKG_ROOT="C:\Program Files\Microsoft Visual Studio\2022\Community\VC\vcpkg"; cmake --preset windows-msvc-vcpkg-headless; ctest --preset desktop-fast-vcpkg --build-config Debug	Component targets consume vcpkg packages where reliable and desktop app, Android, and Apple triplets are validated or explicitly documented as permanent vendor exceptions
DEBT-0008	Open	Modernization	windows-msvc-default preset is used for local validation because the VS 2026 generator is not installed here	The target VS 2026 preset must remain, but this machine configures with Visual Studio 17 2022	cmake --preset windows-msvc-default; ctest --preset desktop-fast --build-config Debug	Validate windows-vs2026-x64 on a machine with Visual Studio 2026 installed and make it the default Windows validation preset
DEBT-0009	Open	Modernization	Android root CMake validation currently builds headless targets only, not APK/package variants	Platform app entrypoints still live in legacy Gradle/CMake projects and need Phase 6 alignment	powershell -ExecutionPolicy Bypass -File scripts\automation\platform-build.ps1 -Presets android-arm64	Android standard, Quest, and Focus/Wave package targets consume shared component targets and have package smoke commands
DEBT-0010	Open	Modernization	pp_document is a pure layer/frame/document/undo-history model with alpha-lock metadata, snapshot construction, per-layer frame metadata, renderer-free RGBA8 face payload storage, snapshot-embedded face-payload validation, renderer-free alpha8 selection-mask storage, PPI import/export helpers, and stroke-script-to-face-payload CLI automation, but it is not yet wired to legacy Canvas, legacy save, or legacy action commands	Keep extraction incremental while preserving app behavior	ctest --preset desktop-fast --build-config Debug; pano_cli create-document --width 64 --height 32 --layers 2; pano_cli load-project --path tests\data\projects\minimal-project.ppi; pp_document_tests; pp_document_ppi_import_tests; pp_document_ppi_export_tests; pano_cli_simulate_document_edits_smoke; pano_cli_simulate_document_export_smoke; pano_cli_save_document_project_roundtrip_smoke; pano_cli_apply_stroke_script_roundtrip_smoke; pano_cli_apply_stroke_script_rejects_tiny_canvas	Legacy document behavior is represented by pp_document tests and the app consumes it through a boundary/facade
DEBT-0011	Open	Modernization	package-smoke validates the Windows CMake app artifact only, not AppX/APK/Apple/WebGL package outputs	Platform package targets are not migrated to root CMake yet	powershell -ExecutionPolicy Bypass -File scripts\automation\package-smoke.ps1 -Preset windows-msvc-default -Configuration Debug	Package-smoke covers Windows AppX, Android APK variants, Apple bundles, and WebGL output where local toolchains are present
DEBT-0012	Open	Modernization	pp_ui_core uses vcpkg tinyxml2 on windows-msvc-vcpkg-headless, but retains pp_vendor_tinyxml2 for default and unproven platform presets	Mobile/AppX/Apple triplets and app packaging still need validation before removing the vendored fallback	ctest --preset desktop-fast-vcpkg --build-config Debug; ctest --preset desktop-fast --build-config Debug; powershell -ExecutionPolicy Bypass -File scripts\automation\platform-build.ps1 -Presets android-arm64	All supported presets consume vcpkg tinyxml2 or document a permanent vendored exception
DEBT-0013	Open	Modernization	pp_assets, pp_document, pano_cli inspect-project, pano_cli load-project, and pano_cli save-project validate the fixed PPI header, thumbnail/body byte layout, generated multi-layer/multi-frame PPI writing with explicit layer opacity/blend/alpha-lock/visibility metadata, per-layer frame durations, metadata-only and targeted dirty-face-payload save/load round-trips, layer/frame index, dirty-face descriptors, dirty-face PNG payload metadata, asset-level RGBA PNG payload decoding, pure document-to-PPI export, CLI document export automation, file-writing document export automation, stroke-script-generated document payload export, and decoded pixel attachment to pp_document, but full legacy PPI round-trip parity is not yet extracted	Full PPI save parity requires staged extraction of legacy Canvas serialization and image/layer payload handling	ctest --preset desktop-fast --build-config Debug; pp_assets_image_pixels_tests; pp_assets_ppi_header_tests; pp_document_ppi_import_tests; pp_document_ppi_export_tests; pano_cli_inspect_project_layout_smoke; pano_cli_load_project_metadata_smoke; pano_cli_save_project_roundtrip_smoke; pano_cli_save_project_payload_roundtrip_smoke; pano_cli_simulate_document_export_smoke; pano_cli_save_document_project_roundtrip_smoke; pano_cli_apply_stroke_script_roundtrip_smoke; pano_cli_apply_stroke_script_rejects_tiny_canvas	Full PPI load/save fixtures cover thumbnails, decoded layer face payloads attached to documents, frames, corrupt payloads, dirty-face payload saving, arbitrary legacy canvas payload/layout combinations, and legacy app round-trip compatibility
DEBT-0014	Open	Modernization	windows-clangcl-asan now configures as a headless Ninja/clang-cl preset and uses the release MSVC runtime required by ASan, but local builds still fail because installed clang-cl 18.1.8 is paired with VS 2026-preview STL headers that require Clang 20 or newer	Sanitizer validation should be local and repeatable, but this machine's compiler/header pairing is incompatible	cmake --fresh --preset windows-clangcl-asan; cmake --build --preset windows-clangcl-asan --target pp_foundation	Install/use Clang 20+ with the VS 2026 STL, or point the preset at a compatible VS 2022 toolchain, then make platform-build.ps1 -Presets windows-clangcl-asan pass for the headless matrix

Closed Debt

ID	Status	Owner	Item	Reason	Validation	Removal Condition
DEBT-0006	Closed	Modernization	pano_cli create-document validates and emits JSON command contracts but does not yet invoke the legacy document/app model	The document model had not been extracted from Canvas/App yet	ctest --preset desktop-fast --build-config Debug; pano_cli_create_document_smoke	Closed on 2026-05-31: command now constructs a real pp_document::CanvasDocument